Although ACMS supports several presentation services, ACMS supports DECforms as its primary presentation service. DECforms provides such features as FIMS compliance, device-class independence, storage of form context between exchanges, input verification (values, ranges, and types), and escape routines.

6.4.1 DECforms Concepts

DECforms architecture provides a full separation of form from function. This separation allows you to write an application program (the function) without being concerned with the intricacies of the user interface (the form) for that program.

Normally, the term form means a document with blanks for the insertion of information. In DECforms, however, the form is a specification that may govern the complete user interface to an application program. The form specification completely describes all terminal screen interactions, the data that is transferred to and from the screen, and any display processing that takes place.

A panel consists of the information and images that are physically displayed on the user's terminal screen. A panel is composed of such items as fixed background information (literals), fields (blanks for insertion of information), attributes, function key control, and customized help messages.

You can partition the display into rectangular areas called viewports by specifying viewport declarations within the form definition. You can adjust the viewport to any size and locate it anywhere on the display (such that viewports overlap one another). For a panel to be visible, it must be associated with a viewport.

Figure 6-3 illustrates the concept of specifying panel declarations and viewport declarations within the DECforms form definition. You specify a viewport name within each panel declaration. By doing this, you map each panel to a specific viewport. At run time, each panel appears on the terminal screen within its viewport.

Figure 6-3 Panels and Viewports

The DECforms Form Manager is the run-time component that provides the interface between the terminal display and an ACMS application. The Form Manager controls panel display, user input, and data transfer between the form and ACMS. A DECforms form is loaded by the Form Manager at execution time under the direction of an ACMS application program.

ACMS begins a session with DECforms when an ACMS application program first references the form. The syntax that references the form is contained in the ACMS task definition.

In DECforms, the form record is a structure that controls data transfer between ACMS and the form. The form record identifies which form data items (variables associated with the form) are to be returned to ACMS.

Figure 6-4 shows the interaction between DECforms and ACMS when ACMS requests information from DECforms.

Figure 6-4 DECforms Interaction with ACMS

The following steps are the sequence of events that occur when ACMS requests information from DECforms:

1. To request information, ACMS calls the Form Manager with a RECEIVE or TRANSCEIVE call. In that call, ACMS performs the following operations:
   1. Tells the Form Manager the name of the form needed to collect data.
   2. Tells the Form Manager the record identifier being received.
   3. Gives the Form Manager the ACMS workspaces used to transfer data.
2. The Form Manager displays a panel on the user's terminal screen. The displayed panel is specified in the form that ACMS names in its RECEIVE or TRANSCEIVE call to DECforms.
3. The Form Manager accepts input from the user's terminal.
4. The Form Manager uses the form record to store the user's input data in the appropriate form data items.
5. The Form Manager completes the request by returning data to the ACMS workspaces.

Resource managers (RMs) are the software products that store and manage the data accessed by ACMS applications. A resource manager controls shared access to a set of recoverable resources, such as a database.

All Compaq's resource managers provide access to recoverable data. Step procedures can access the following resource managers either locally or remotely:

• Rdb database management system
• DBMS database management system
• RMS file management system
• ACMS queuing facility

Compaq's resource managers are not an integral part of the TP system, but are instead under the control of the operating system (OS). This OS control of resource managers permits database sharing among TP and non-TP applications, decision support systems, and remote nodes requesting data.

ACMS supports Rdb as its primary database management system. For Rdb conceptual information, refer to the Rdb documentation.

For the sake of simplicity, this tutorial application uses an RMS master file to store and retrieve records. RMS is an OpenVMS-supplied file management system that supports sequential, relative, or indexed files. The initialization procedure in this tutorial creates the RMS file (EMPLOYEE.DAT) when you run the application for the first time.

6.5.2 ACMS Interaction with a Resource Manager

To access a database, ACMS interacts with a procedure server process. The procedure server process, in turn, interacts with the resource manager of the database. As shown in Figure 6-5, processing steps call step procedures (user-written subroutines) to handle interactions with the resource managers of databases or files.

ACMS uses a procedure server process for executing a procedure. When starting a processing step, ACMS allocates a procedure server process to execute the procedure in that step. The procedure server process remains allocated to the task for the duration of one or more processing steps in the task.

In an update task, you need at least one exchange step to prompt the user for a key value, and another to display the requested record for modification. You need one processing step to retrieve the record from the database, and another to write the record back to the database with the user's changes. Figure 6-5 shows the interactions among ACMS, the procedure server, and the resource manager to execute a simple update task.

Figure 6-5 A Resource Manager Interacting with ACMS

The following steps are the sequence of events that executes the update task:

1. An exchange step calls the Form Manager (not shown) to display a panel on which the user can supply a key value (for example, an employee number).
2. A processing step calls procedure 1, which in turn retrieves an employee record from the database through its resource manager. The record retrieved matches the employee number that the user entered.
3. An exchange step calls the Form Manager to display a panel with the information contained in the employee record. The user can modify this information (for example, change the employee's address).
4. A processing step calls procedure 2, which in turn writes the modified employee record to the database.

For a full picture of the ACMS execution flow that includes the Form Manager's role in exchange steps, refer to Figure 6-1.

6.6 Defining Fields and Records in CDD

The CDD dictionary system provides a central storage repository for shareable data definitions. CDD is an active dictionary system that provides the user interface known as CDO (Common Dictionary Operator).

The dictionary contains metadata (descriptions of data) in the form of dictionary definitions. The most commonly used dictionary definitions are fields, records, and databases.

A field definition describes the data that can be stored in a specific field in your application. Field definitions typically include information such as data type and size. The tutorial application defines the following fields: employee number, name, street address, city, state, and zip code.

A record definition typically consists of a grouping of field definitions. The tutorial application defines a record named EMPLOYEE_INFO_RECORD, which contains a group of field definitions corresponding to the preceding fields.

This tutorial application creates your personal CDD dictionary. It also sets up your default CDD directory so that all your definitions are located there automatically. By setting a default CDD directory, the tutorial application can identify EMPLOYEE_INFO_RECORD by its name alone (without having to use its full path name).

This chapter describes in step-by-step detail how to write the Data Entry Task using ACMS, DECforms, and CDD definitions. Before you begin, check the prerequisites for this tutorial listed in Section 6.1.

7.1 Defining a CDD Environment

This tutorial application requires you to create a personal CDD directory. You then need to define this directory to be your default CDD directory, so that all your definitions are located there automatically.

Your system manager can help you decide where to locate your CDD directory by choosing one of the following alternatives:

• Create your personal subdirectory under CDD$COMPATIBILITY (a system logical that on most systems points to the system dictionary directory SYS$COMMON:[CDDPLUS]).
• Or, define a directory in your own account to be your dictionary (for example, USER$1:[JONES.CDD]).

The directory used as your CDD dictionary in this tutorial is represented by the placeholder disk:[cdd_directory]. When this specification appears on subsequent pages, you are required to enter the disk name and directory name where your CDD dictionary is located (for example, USER$1:[JONES.CDD]).

If your system manager determines that you should define a dictionary in your own OpenVMS account, you must first create a subdirectory for this purpose (for example, a subdirectory named CDD in an account such as USER$1:[JONES]). For example:

$ CREATE/DIRECTORY [JONES.CDD]

This subdirectory must remain dedicated to your CDD dictionary; CDD stores its files there. Do not store your source files or any other OpenVMS files in this directory.

To set up your personal CDD directory, follow these steps:

1. Enter the CDD Dictionary Operator Utility by issuing the following command:

   $ DICTIONARY OPERATOR CDO>

   
   CDD responds by displaying the CDO> prompt.

2. This step is required only if you are creating a CDD dictionary in your own OpenVMS account. (If you are attaching your personal CDD directory to the system dictionary, CDD$COMPATIBILITY, skip this step). Note that the following command line ends with a period:

   CDO> DEFINE DICTIONARY disk:[cdd_directory]. CDO>

   
   For cdd_directory, substitute the name of the directory that you created as your CDD dictionary (for example, [JONES.CDD]).

3. Set your default directory to the directory that will be your CDD directory:

   CDO> SET DEFAULT disk:[cdd_directory] CDO>

   
   Issue the SHOW DEFAULT command to verify this:

   CDO> SHOW DEFAULT disk:[cdd_directory] CDO>

4. Create a CDD subdirectory to use as your personal directory. Substitute your directory name for d_name in this example and elsewhere in this manual (for example PJ_DICTIONARY). Note that this command line ends with a period:

   CDO> DEFINE DIRECTORY disk:[cdd_directory]d_name. CDO>

   
   A dictionary directory is a named section of a dictionary that you use to hold your field and record definitions. Issue the DIRECTORY command to check that the subdirectory you created is listed in your anchor directory:

   CDO> DIRECTORY

   
   CDO displays the contents of disk:[cdd_directory]; your personal subdirectory (dictionary) is listed as a directory.

   Directory disk:[cdd_directory] . . . d_name DIRECTORY CDO>

5. Exit from CDO:

   CDO> EXIT $

6. Using a text editor, edit your login command file to define the logical name CDD$DEFAULT. The CDO uses this logical name to set your default CDD directory whenever you invoke CDO. Also, to enter CDO more quickly, define a symbol for the DICTIONARY OPERATOR command. Add the following lines to your login command file:

   $ DEFINE CDD$DEFAULT disk:[cdd_directory]d_name $ CDO :== DICTIONARY OPERATOR

   
   Save your login command file and exit the editor.

7. Issue the following commands to execute your edited login command file and to make sure that your default directory is set correctly:

   $ @LOGIN.COM $ CDO CDO> SHOW DEFAULT CDD$DEFAULT = disk:[cdd_directory]d_name CDO>

8. Exit from CDO:

   CDO> EXIT $

In this chapter, you create your first source files: CDD files, DECforms files, ACMS files, and COBOL files. The easiest way to manage these files is to create them all in the same OpenVMS directory.

This manual assumes that you are using your default OpenVMS directory (udisk:[uname]) to hold your source files. In this manual, udisk represents your OpenVMS disk name, and uname represents your OpenVMS directory name (for example, USER$1:[JONES]). Make sure that you are located in your default OpenVMS directory when you create a source file.

To define fields and records in your CDD dictionary, follow these steps:

1. Using a text editor, create a source file, EMPLOYEE_FIELDS.CDO, in your OpenVMS default directory. (All source files are available on line, if you choose to copy them instead of typing them yourself. See Appendix B for their location.) Type in your field definitions as follows:

   DEFINE FIELD EMPL_NUMBER DATATYPE TEXT SIZE 10. DEFINE FIELD EMPL_NAME DATATYPE TEXT SIZE 30. DEFINE FIELD EMPL_STREET_ADDRESS DATATYPE TEXT SIZE 30. DEFINE FIELD EMPL_CITY DATATYPE TEXT SIZE 20. DEFINE FIELD EMPL_STATE DATATYPE TEXT SIZE 2. DEFINE FIELD EMPL_ZIP_CODE DATATYPE TEXT SIZE 10.

   
   Because input records of this format are eventually filled in with alphabetic and numeric data typed at the terminal, the data type of all the fields is TEXT, which can be either alphabetic or numeric. In a more complex application, you would probably use other data types such as NUMERIC. The SIZE information specifies the maximum number of characters that the value of a field can have.
   Save this file and exit the editor.

2. Execute the source file to place these field definitions in your dictionary:

   $ CDO CDO> @EMPLOYEE_FIELDS CDO>

   
   If you do not have the necessary privileges to define an object in CDO, or if you have not turned on your privileges (with the SET PROCESS/PRIV=xxxx command), you receive an "insufficient privileges" message here. If so, see your system manager about required privileges.
   To check that a field is in your CDD directory, you can issue the SHOW FIELD command. For example:

   CDO> SHOW FIELD EMPL_NUMBER Definition of field EMPL_NUMBER | Datatype text size is 10 characters CDO>

3. Exit from CDO. Create a source file named EMPLOYEE_INFO_RECORD.CDO. Type the following lines:

   DEFINE RECORD EMPLOYEE_INFO_RECORD. EMPL_NUMBER. EMPL_NAME. EMPL_STREET_ADDRESS. EMPL_CITY. EMPL_STATE. EMPL_ZIP_CODE. END RECORD.

   
   Save this file and exit the editor.

4. Execute the source file:

   $ CDO CDO> @EMPLOYEE_INFO_RECORD CDO>

   
   Issue the SHOW RECORD command to check that your record is accurate:

   CDO> SHOW RECORD EMPLOYEE_INFO_RECORD Definition of record EMPLOYEE_INFO_RECORD | Contains field EMPL_NUMBER | Contains field EMPL_NAME | Contains field EMPL_STREET_ADDRESS | Contains field EMPL_CITY | Contains field EMPL_STATE | Contains field EMPL_ZIP_CODE CDO>

   
   You can display the data type and length of each field in the record by using the /FULL qualifier after the SHOW RECORD command.
   To display a list of all fields and records in your default CDD directory, issue the DIRECTORY command:

   CDO> DIRECTORY Directory disk:[cdd_directory]d_name EMPLOYEE_INFO_RECORD;1 RECORD EMPL_CITY;1 FIELD EMPL_NAME;1 FIELD EMPL_NUMBER;1 FIELD EMPL_STATE;1 FIELD EMPL_STREET_ADDRESS;1 FIELD EMPL_ZIP_CODE;1 FIELD CDO>

5. Exit from CDO. Create a source file named EMPLOYEE_INFO_WKSP.CDO. Type the following lines:

   DEFINE RECORD EMPLOYEE_INFO_WKSP. EMPL_NUMBER. EMPL_NAME. EMPL_STREET_ADDRESS. EMPL_CITY. EMPL_STATE. EMPL_ZIP_CODE. END RECORD.

   
   Save this file and exit the editor.

6. Enter the EMPLOYEE_INFO_WKSP definition in CDD by executing the source file:

   $ CDO CDO> @EMPLOYEE_INFO_WKSP CDO>

7. Exit from CDO.

The easiest way to design DECforms panels in a form is to use the DECforms Panel Editor in the Form Development Environment (FDE). The definition of the panel that you create is automatically stored in a form source file with the file type of .IFDL (Independent Form Description Language).

7.3.1 Creating a Basic Form

To enter FDE and create a basic form and source file, follow these steps:

1. Edit your login command file to define a symbol for the FORMS DEVELOP command:

   $ FDE :== FORMS DEVELOP

   
   Save your login command file and exit the editor.

2. Execute your edited login command file:

   $ @LOGIN.COM

3. Enter the FDE symbol to enter the DECforms interactive environment:

   $ FDE

   
   If the DECforms system starts successfully, the system prompts you for a file name. However, if DECforms does not recognize your device type, the system responds that this operation must be done with a 100, 200, or 300 series terminal. In this case, issue the SET TERMINAL/INQUIRE command at the dollar ($) prompt and repeat this step.

4. Type the name EMPLOYEE_INFO_FORM at the prompt:

   _Input_File: EMPLOYEE_INFO_FORM

   
   After you enter your form name, DECforms displays two messages:

   Form Development Environment starting... Creating a new form file called: UDISK:[UNAME]EMPLOYEE_INFO_FORM.FORM

   
   DECforms then displays a screen that prompts you to accept a default layout for your panel (see Figure 7-1).

   Note If you copied the online IFDL source files to your default directory before starting this tutorial, DECforms translates the existing IFDL file here and loads the resulting FORM file. It displays the Main Menu instead of Figure 7-1. In this case, use the arrow keys to choose the Exit option and press [Select]. Proceed to Section 7.3.4, step 2.

   Figure 7-1 DECforms LAYOUT Screen

   ---

   
   On DECforms screens, use the arrow keys to move the cursor among the options that are displayed. Then press [Select] to register your choice of options.
5. Press [Select] to accept the default of Yes, because the example in this tutorial uses just one layout for all types of terminals and users. DECforms next displays the FDE Main Menu, shown in Figure 7-2.

   Figure 7-2 FDE Main Menu

   ---

   
6. Using the arrow keys, move the cursor to the EXIT option. Then press [Select]. DECforms saves all the entries you made and then displays the following messages notifying you that your form has been saved in a form source file and in a binary file:

   IFDL saved in file: UDISK:[UNAME]EMPLOYEE_INFO_FORM.IFDL;1. Form saved in file: UDISK:[UNAME]EMPLOYEE_INFO_FORM.FORM;1.

   
   You have now created a basic form.

7. Enter the TYPE command and your IFDL source file name to display the IFDL source file:

   $ TYPE EMPLOYEE_INFO_FORM.IFDL

   
   In the form source file, DECforms places IFDL statements that identify the form and the layout selected. By selecting the default layout, you cause DECforms to create the following lines:

   Form EMPLOYEE_INFO_FORM <FF> Layout VT_LAYOUT Device Terminal Type %VT100 End Device Size 24 Lines by 80 Columns End Layout End Form

To make your form useful, create a panel that produces a display on the terminal screen. The next section contains instructions for doing this.