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:

• ENABLE---When a form is accessed in a task for the first time
• DISABLE---When you exit from ACMS
• CANCEL---When you use the DCL commands ACMS/CANCEL USER, ACMS/CANCEL TASK, or [Ctrl/Y] to cancel a task

You make calls to the remaining three external requests in the EXCHANGE step of an ACMS task definition:

• SEND
  Use the SEND call in a task definition when you want to send data to the form.
• RECEIVE
  Use the RECEIVE call in a task definition to receive data from the form.
• TRANSCEIVE
  Use the TRANSCEIVE call to send data to and receive data from the form.

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.

• Control text responses
  You can use control text responses to send information to DECforms (such as display directions) or to collect information from DECforms (such as status information about the completion of a SEND, RECEIVE, or TRANSCEIVE operation).
  Refer to DECforms IFDL Reference Manual for more information about control text responses.
• External responses
  After it processes control text responses, DECforms processes other responses that you enter in the form source (IFDL) file. If you do not declare responses in the IFDL file, the DECforms performs certain default actions for each call to an external request. Default actions are detailed in DECforms Programmer's Reference Manual.
  To alter the default actions of DECforms or to direct DECforms to take certain actions if there are no defaults, you must enter external responses in the form source IFDL file.
  Refer to DECforms IFDL Reference Manual for more information on declaring external responses.
• Response steps
  A response step is an instruction to DECforms to alter the processing of an external request. Enter response steps in the form source IFDL file.
  DECforms Guide to Commands and Utilities contains a table of response steps, and DECforms Programmer's Reference Manual describes each response step in detail.
  An example of a response step is DISPLAY, which causes the named panels on the terminal screen to display.
• Accept responses
  Enter accept responses in the form source IFDL file to determine what DECforms does during user input. The four types of accept responses are ENTRY, EXIT, FUNCTION, and VALIDATION.
  Refer to DECforms Programmer's Reference Manual for more information about accept responses.
• Internal responses
  An internal response is one that is called from another response. You can use internal responses for any action that is called for repeatedly in a form. For example, you might want to direct DECforms to display a message each time a user enters the last item in a list.

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

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:

• Link escape unit objects with form objects. For example:

  $ LINK/SHARE EMPLOYEE_INFO_FORM.OBJ, EMPLOYEE_ESC_UNIT.OBJ

• Link escape unit objects into a separate image. For example:

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

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

• Linking escape units with the form objects
  You can make escape units available to the Command Process (CP) agent by linking them into the same image as the form. An advantage of this method is that, if your system uses distributed processing, the escape units are automatically cached, along with the form files, to the remote submitter node.
  By using this method, however, you allow application code from a remote system to execute in a privileged environment on your system. But if the remote application node and the local submitter node are in a common security domain, this may not be a concern.
  To avoid the possible security problem of executing escape units that are linked with the forms shareable image, ACMS, by default, does not execute these escape units. To execute them, you must define the following system-level logical:

  ACMS$ESC_RTN_IN_FORM

  
  If the value of this logical is set to T, t, Y, y, or l, then ACMS allows these escape units to run. If this logical is not defined or has another value, ACMS does not execute the escape units.

• Linking escape units in a separate image
  You can also link escape units in their own shareable image. You then need to make that image available to the CP agent by defining the following logical name:

  FORMS$IMAGE

  
  If there are more than one escape unit image, you can make the logical a search list of all images. For the CP agent supplied by ACMS, this logical must be in either the system group name table or the system name table. (Refer to the DECforms documentation for more information about defining this logical.)
  If you use the FORMS$IMAGE logical to specify escape unit images, these escape units can be shared by all of the applications that the CP agent references. However, sometimes the different applications may have the same escape unit name for different functions. To settle this possible naming conflict, ACMS provides an additional system-level logical name:

  ACMS$ESC_RTN_<node>_<application>

  
  You can use this logical to define an escape unit image for a particular application on a particular node. If the application uses more than one image, this logical can be a search list. When you use this logical name on a system where the NODE_NAME parameter is not defined in ACMSGEN, you must omit the <node> part from the logical name. Therefore, the system-level logical name looks like:

  ACMS$ESC_RTN_<application>

  
  If you do not define either of these logicals, or if the specified logical is not on the search list, DECforms then uses the FORMS$IMAGE logical.

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

• Making escape units available to the CP agent
• Protecting privileged agents that execute escape units

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:

• Rename the new form file.
• Change the definition of the logical name for the form file to point to the new file specification.
• Stop and restart the application.

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:

• The file name of the image must be unique. The OpenVMS image activator keeps track of images by file name only. Therefore, forms image file names must be unique, even if they are located in different directories or on different devices.
• Avoid defining the file name of a forms image file as a logical. The OpenVMS image activator attempts to perform a logical translation of the file name. However, it is recommended that you do not define the file name of a forms image file to be a logical because this can cause problems with the ACMS management of the forms file. If you do define the file name of a forms image file to be a logical, the logical name must refer to a valid form file. Otherwise, ACMS generates the following error message when a task tries to access the forms image file:

  An error was returned from a DECforms request %FORMS-F-INVFHDSIZ, invalid form header size.

  
  The file name of the ACMS menu is ACMS_MENU. If you define ACMS_MENU as a logical, it must refer to a forms image file that contains a valid form for the ACMS menu. Otherwise, the CP does not let users sign in to ACMS.

DECforms user interface features include the following:

• [Ctrl/Z] or [F10] to exit from a DECforms menu
  As part of DECforms design, [Ctrl/Z] can be defined so that it functions the same as the EXIT command does. When a user presses [Ctrl/Z] or [F10] for a DECforms menu selection, the CP handles it like an EXIT command, and the user exits out of ACMS.
• Cursor repositioning
  In ACMS, a user can press [PF2] and then the UP/DOWN arrow keys to move the cursor up and down among the entries. If the user presses [Return], the CP handles it just as if the user had typed the number of the item.
• Line recall selection
  In ACMS, a user can press the UP/DOWN arrow keys to recall a selected line backward or forward just like the OpenVMS command line recall function.

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.