The first step in creating a menu definition is to enter a title for the menu. The HEADER clause lets you create either a 1-line or 2-line title. ACMS displays the title at the top of a menu screen. By default, ACMS leaves the lines at the top of a screen blank. However, it is a good idea to include a title for each menu so your users always know where they are working within the menu structure.

To define a menu title, type the HEADER clause in your source file, putting quotation marks around the title. For example:

HEADER IS " PERSONNEL MENU";

You center the title by including spaces before the text of the title, inside the quotation marks. End the clause with a semicolon (;). If you include a second line in a HEADERS clause, end the first line with a comma (,) and end the second line with a semicolon (;). For example:

HEADER IS " HISTORY AND SALARY MENU", " FOR PERSONNEL APPLICATION";

You use the ENTRIES clause to name the entries on a menu and to describe characteristics of each entry. The ENTRIES clause is the only required clause in the menu definition. The descriptions of an entry include the entry name, entry description, and the type of entry.

The ENTRIES clause begins with the keywords ENTRIES ARE and ends with END ENTRIES. Entry names can be up to 10 characters long and should describe the task or menu that they name. An entry name can be enclosed in quotation marks. If your entry name is a quoted string, do not include spaces, tabs, or periods in the name. A colon (:) separates an entry name from the subclauses that define the entry. For example:

HEADER IS " PERSONNEL MENU"; ENTRIES ARE REVIEW : UTILITY: END ENTRIES; END DEFINITION;

You can define two types of entries in a menu definition: tasks and menus. If you define an entry as a task and a user who has access to it selects that entry, ACMS runs that task. When you define an entry as a menu, and a user selects that entry, ACMS displays another menu. You use either the TASK or MENU subclause in the ENTRIES clause to indicate the type of entry. Every ENTRIES clause must include at least one TASK or MENU subclause.

12.2.3 Naming Menus

You use the MENU subclause to define every menu entry on a menu. In the menu subclause, you include the keywords MENU IS and the CDD path name of the definition for the menu you want to display. For example:

HEADER IS " PERSONNEL MENU"; ENTRIES ARE REVIEW : MENU IS EXAMPLES_DEFINITIONS.REVIEW_MENU; UTILITY : MENU IS EXAMPLES_DEFINITIONS.UTILITY_MENU; END ENTRIES; END DEFINITION;

In this example, the REVIEW entry is a menu whose definition is in the CDD directory EXAMPLES_DEFINITIONS. The menu is named REVIEW_MENU. The second entry in the menu definition is UTILITY. This entry is also a menu that would be found in the CDD directory EXAMPLES_DEFINITIONS. The menu is named UTILITY_MENU.

Both entries in the menu definition are menus. Tasks and menus can be named on the same menus or on different ones. Naming tasks is very similar to naming menus.

12.2.4 Naming Tasks on a Menu

You use the TASK subclause to define every task entry on a menu. In the TASK subclause, you include the keywords TASK IS, the name of the task in the application database, and the application specification of the application database file that contains the task. For a more complete discussion of application specifications, see Section 12.2.7.

If the task is defined with the TASK ATTRIBUTES clause in the application definition, the task name must be the one used in the ATTRIBUTES clause. If the task is not defined in the application definition, the task name must be the one used in the task group definition.

For the application database file name, include only the file name, not a device, directory, or file type specification. For example:

HEADER IS " REVIEW MENU"; ENTRIES ARE SCHEDULE : TASK IS REVIEW_SCHEDULE IN PERSONNEL; HISTORY : TASK IS REVIEW_HISTORY IN PERSONNEL; END ENTRIES; END DEFINITION;

In this example, the HISTORY entry is a task named REVIEW_HISTORY in the Personnel application. The SCHEDULE entry is a task named
REVIEW_SCHEDULE, running in the Personnel application.

12.2.5 Specifying WAIT or DELAY Action

You can specify the WAIT/DELAY attribute on tasks in the menu definition. The WAIT/DELAY attribute causes the Command Process (CP) to wait or delay before displaying the menu. The WAIT/DELAY attribute specified in the menu definition overrides the WAIT/DELAY value specified for the task in the application database.

HEADER IS " REVIEW MENU"; ENTRIES ARE HISTORY : TASK IS REVIEW_HISTORY IN PERSONNEL; DELAY; SCHEDULE : TASK IS REVIEW_SCHEDULE IN PERSONNEL; WAIT; END ENTRIES; END DEFINITION;

In this example, the WAIT command causes the CP to wait until the user signals to continue, and the DELAY command causes the CP to wait 3 seconds. This section describes how to create short descriptions of tasks and menus that are displayed with the entry on an ACMS menu.

The TEXT subclause lets you create a short description of an entry that is displayed on an ACMS menu. By default, ACMS does not include descriptive text on the screen. However, it is a good idea to include descriptive text for each task and menu in your application to help users identify the item they are selecting, rather than relying just on the name of a selection.

To include descriptive text on a menu, use the TEXT IS subclause, followed by the text itself. The text can be up to 50 characters long, must be enclosed in quotation marks and must end with a semicolon (;). For example:

HEADER IS " REVIEW MENU"; ENTRIES ARE HISTORY : TASK IS REVIEW_HISTORY IN PERSONNEL; TEXT IS "Display Review Histories"; SCHEDULE : TASK IS REVIEW_SCHEDULE IN PERSONNEL; TEXT IS "Display Review Schedules"; END ENTRIES; END DEFINITION;

For each task on the Review Menu, descriptive text is included to the right of the task selection. Figure 12-3 shows the menu created by the Review Menu definition.

Figure 12-3 The Review Menu

So far, every menu definition shown in this chapter has named the application for each individual task or menu. The next section explains the menu definition clause that allows you to avoid this repetition.

12.2.6 Naming Default Application Files

It is not necessary to name the application for every task and menu in a menu definition. Instead, you can assign a default application specification in a menu definition. ADU uses the application specification by default when you build the application.

The DEFAULT APPLICATION clause includes the keywords DEFAULT APPLICATION IS and the application specification. When you use the DEFAULT APPLICATION clause, the application name should not include the device, directory, or file type specification. For example, the menu definition for the Review Menu includes a default application name:

DEFAULT APPLICATION IS PERSONNEL; HEADER IS " REVIEW MENU"; ENTRIES ARE SCHEDULE : TASK IS REVIEW_SCHEDULE; TEXT IS "Display Review Schedules"; HISTORY : TASK IS REVIEW_HISTORY; TEXT IS "Display Review Histories"; END ENTRIES; END DEFINITION;

In this example, Personnel is the default application specification for the application. The TASK subclauses in the definition do not need to specify the application.

The application specification that you assign in the TASK subclause overrides the one that you assign with the DEFAULT APPLICATION clause.

12.2.7 Application Specifications and Remote Tasks

You can select a task running in an application on another node in a distributed environment, whether that environment is a local area network, wide area network, or OpenVMS Cluster system. There are two methods for selecting a task in a distributed environment:

• You can use a logical name for the node name or for the application name. Using a logical name means that you do not need to rebuild the application if the application node changes for some reason. For a more complete discussion of remote tasks and application specifications, see Compaq ACMS for OpenVMS ADU Reference Manual.
• In your menu definition you can also specify the node that the application is on. If the application and the task are on the same node, the application specification consists of the application name. If the application is on a remote node, the application specification consists of the node name followed by two colons (::) followed by the application name.
  Using the example of two applications, Personnel and Employee, suppose the department using these applications has an OpenVMS Cluster with two nodes, RAVEN and MAGPIE. The Personnel application runs on the node RAVEN; Employee runs on MAGPIE. Rather than duplicate tasks from the Employee application for users on RAVEN, you can provide remote access to Personnel tasks on RAVEN for users on MAGPIE using the menu definition. Example 12-2 shows the menu definition for the node MAGPIE.

Example 12-2 Example of a Menu with a Remote Task

HEADER IS " EMPLOYEE MENU"; ENTRIES ARE SCHEDULE : TASK IS REVIEW_SCHEDULE IN RAVEN::PERSONNEL; EMPLOYEE : TASK IS EMPLOYEE IN EMPLOYEE; END ENTRIES; END DEFINITION;

Remember that the EMPLOYEE menu definition is on MAGPIE. The SCHEDULE entry is a task named REVIEW_SCHEDULE, in the Personnel application running on node RAVEN. The EMPLOYEE entry is the task named EMPLOYEE in the Employee application on node MAGPIE. The SCHEDULE entry provides remote access to the task named REVIEW_SCHEDULE in the Personnel application on RAVEN.

12.2.8 Naming Default Menu Files

You can assign a default menu database file specification in a menu definition. If you specify a file specification, the Application Definition Utility (ADU) uses the name by default for the menu database created when you build a menu tree.

The DEFAULT MENU FILE clause includes the keywords DEFAULT MENU FILE and the name you assign to the database file. If the file name you assign to the database file does not fit the specifications for an ACMS identifier, enclose the name in quotation marks. By default, ADU assigns the file type .MDB to the menu database file. If you do not include a device or directory specification for the file, ADU uses your current device and directory. For example:

DEFAULT APPLICATION IS PERSONNEL; DEFAULT MENU FILE IS "PERSONNEL.MDB"; HEADER IS " PERSONNEL MENU"; ENTRIES ARE REVIEW : MENU IS EXAMPLES_DEFINITIONS.REVIEW_MENU; TEXT IS "Review Menu"; UTILITY : MENU IS EXAMPLES_DEFINITIONS.UTILITY_MENU; TEXT IS "Utility Menu"; END ENTRIES; END DEFINITION;

In this example, the default menu file is PERSONNEL.MDB in the current default device and directory. When you build this menu, ACMS creates a menu database called PERSONNEL.MDB.

A menu database file assignment you make with the BUILD command overrides an assignment you make with the DEFAULT MENU FILE clause. If you do not include a file specification for the menu database with the BUILD command, ADU uses the menu database file name assigned with the DEFAULT MENU FILE clause in the menu definition. If you do not name a menu database file either with the BUILD command or in the menu definition, ADU derives the file name from the full CDD given name of the menu definition, including dollar signs and underscores.

ADU ignores the DEFAULT MENU FILE clause if the clause is in any menu definition other than the menu definition specified in the BUILD command. For more information on how ADU derives the menu database file name from a CDD path name, see Compaq ACMS for OpenVMS ADU Reference Manual.

12.2.9 Defining a Menu Forms Product

ACMS uses either DECforms or TDMS to display menus for users. In cases where DECforms or TDMS is not available (if it is not installed on the system, or the user is logged in to an unsupported terminal), ACMS uses OpenVMS QIOs to prompt the user to enter a selection.

If DECforms or TDMS is available, ACMS uses the following information, in the order specified, to determine which forms product will be used to display the menu:

1. If the MDB was built using ACMS Version 3.0 or lower, TDMS will be used.
2. You can choose to customize your menu by specifying the REQUEST IS clause for TDMS or the CONTROL TEXT IS clause for DECforms. If one of these clauses is specified in the menu definition, the corresponding forms product will be used. (See Appendix A and Appendix B for specific information on customizing ACMS menus displayed by DECforms or TDMS.)
3. You can define the logical ACMS$DEFAULT_MENU_FORMS_PRODUCT to be TDMS or DECforms. This logical forces the forms product for all users in the CP.
4. If DECforms is installed on the system, it will be used to display the menu. Otherwise, TDMS will be used.

Figure 12-4 is a diagram of the decisions ACMS makes in selecting DECforms or TDMS to display an ACMS menu.

Figure 12-4 ACMS Menu Choices

If you need to modify the standard ACMS menu format, an advantage to using DECforms is that you do not need to make modifications in both the menu request and in the menu definition. You can make all your changes in the menu form source (.IFDL) file. (See Appendix A for information about customizing DECforms menus.)

To use DECforms to display menus for versions of ACMS prior to ACMS Version 3.1, you must rebuild MDBs.

If you remove TDMS from your system, ACMS does not automatically use DECforms for menus displayed by the CP. Unless you rebuild your MDB, the task submitter sees only a selection prompt. After rebuilding your MDB, you can use DECforms to display menus.

If you want to use two identical menus, one using DECforms and another using TDMS, in your application, you must build two separate MDBs. You can, however, use DECforms for one menu and TDMS for another menu in the same menu tree.

Following are explanations of how to select DECforms or TDMS as a menu forms product in a menu definition or in a logical:

• Selecting a menu displayed by TDMS in a menu definition
  If your ACMS application requires a menu format different from the ACMS menu format displayed by TDMS, you can use TDMS to modify the menu format. However, this requires a thorough knowledge of TDMS. See Appendix B for more information on how to modify ACMS menus using TDMS.
  To specify a TDMS menu, you must include the REQUEST IS clause in your menu definition. In the REQUEST IS clause, you must include the given name of the request you want ACMS to use for that menu. This given name is not the CDD path name of the request but, rather, the name by which the request is listed in the request library definition. For example:

  HEADER IS " PERSONNEL MENU"; REQUEST IS PERSONNEL_MENU_REQUEST WITH 12 ENTRIES PER SCREEN; DEFAULT APPLICATION IS PERSONNEL; ENTRIES ARE REVIEW : MENU IS EXAMPLES_DEFINITIONS.REVIEW_MENU; TEXT IS "Review Menu"; UTILITY : MENU IS EXAMPLES_DEFINITIONS.UTILITY_MENU; TEXT IS "Utility Menu"; END ENTRIES; END DEFINITION;

  
  In this example, the REQUEST clause names the TDMS request PERSONNEL_MENU_REQUEST for the menu format. This definition must be in the request library, ACMSREQ.RLB, which is used by ACMS for displaying menus.
  The definition also specifies that the Personnel request display 12 entries per screen. The number in the ENTRIES PER SCREEN phrase must correspond to the number of form fields to which the request writes entry information. The default number of entries for each screen is 16. If you want more or fewer than 16 entries on each screen, you must use the WITH ENTRIES PER SCREEN phrase to define the number of entries. You must also define a request to handle that number of entries.
  If you are not customizing the menu format and you want to use TDMS only to display the menu, specify the request name provided by ACMS:

  REQUEST IS MENU_REQUEST;

• Selecting a menu displayed by DECforms in a menu definition
  If your ACMS application requires a menu format different from the ACMS menu format displayed by DECforms, you can use DECforms to modify the menu format. However, this requires a thorough knowledge of DECforms forms source files. See Appendix A for more information on how to modify ACMS menus using DECforms.
  To specify a DECforms menu that you have customized, you must include the CONTROL TEXT IS clause in your menu definition. In the CONTROL TEXT IS clause, you must include a five-character control text item. In the menu form source (IFDL) file, you must define a control text response with the same name. In the menu definition, for example, you enter the CONTROL TEXT IS clause, followed by a one- to five-character string:

  HEADER IS " PERSONNEL MENU"; CONTROL TEXT IS "MYMNU"; DEFAULT APPLICATION IS PERSONNEL; ENTRIES ARE REVIEW : MENU IS EXAMPLES_DEFINITIONS.REVIEW_MENU; TEXT IS "Review Menu"; UTILITY : MENU IS EXAMPLES_DEFINITIONS.UTILITY_MENU; TEXT IS "Utility Menu"; END ENTRIES; END DEFINITION;

  
  In this example, the CONTROL TEXT IS clause names the control text item MYMNU.
  You must enter a reference to MYMNU in the form menu source file; for example:

  Control Text Response "MYMNU" Activate MY_PANEL End Response

  
  In this example, the control text response identifies the control text item MYMNU and directs DECforms to display the customized menu panel MY_PANEL to terminal users.
  The default number of entries on each screen of menus displayed by DECforms is 16. With menus displayed by DECforms, you specify a different number of entries per screen in the menu form source file. (Appendix A contains instructions for customizing menus displayed by DECforms.)
  If you are not customizing the menu format and you want to use DECforms only to display the menu, specify the control text response provided by ACMS:

  CONTROL TEXT IS "DFMENU";

• Selecting a forms product by defining a Logical
  If you do not use a REQUEST IS or a CONTROL TEXT IS clause in a menu definition to specify a customized menu displayed by TDMS or DECforms, ACMS attempts to translate this logical:

  ACMS$DEFAULT_MENU_FORMS_PRODUCT

  
  You can define this logical to be either TDMS or DECforms and thus specify a forms product for all users on the CP. For example:

  $ DEFINE/SYSTEM ACMS$DEFAULT_MENU_FORMS_PRODUCT TDMS $ DEFINE/SYSTEM ACMS$DEFAULT_MENU_FORMS_PRODUCT DECFORMS

  
  This logical name should be defined before you start ACMS. To change the value of the logical after you have started ACMS, stop and restart the ACMS terminal subsystem.

You use the ADU CREATE or REPLACE command to store menu definitions in CDD. After you store a definition in CDD, you use the ADU BUILD command to create a database from the definition that ACMS uses at run time.

As explained in Chapter 1, processing definitions can be simpler if a REPLACE command is included in the source definition file. Include a REPLACE command at the top of each menu source definition file. For example, the command for the Personnel menu is:

REPLACE MENU PERSONNEL_MENU/LOG/LIST

With the REPLACE command in each source file, type the at sign (@) command and the name of each menu definition source file in response to the ADU> prompt:

$ ADU ADU> @PERSMEN1.MDF

%ACMSCDU-S-MENREPLAC, Menu UDISK:[CDDPLUS]EXAMPLES_DEFINITIONS.PERSONNEL_MENU replaced ADU>

The errors you can get when replacing menu definitions are explained in the online error message documentation contained in the file SYS$HELP:ACMSADU.MEM. If you get an error, correct the definition and use ADU to process it again.

Once the corrected definition is stored in CDD, you can use the BUILD command to create menu databases. The BUILD command includes:

• The MENU keyword.
• The CDD relative or full path name of the menu definition of the top-level menu of your menu tree.
• A menu database file specification (optional). If you do not provide a file name, and if the top-level menu definition does not contain a DEFAULT MENU FILE clause, ADU creates one from the full CDD path name including dollar signs and underscores, and the .MDB file type.

Use the BUILD command to produce menu databases. You need to build only the top menu in an application. The other menus are built automatically at the same time. To build the top menu, enter the BUILD command:

ADU> BUILD MENU PERSONNEL_MENU PERSMEN1.MDB/LOG

%ACMSCDU-I-MENUNAME, Menu named 'REVIEW' %ACMSCDU-I-LODMENNAM, Loading menu %ACMSCDU-I-MENPTHLOD, Menu CDD object 'UDISK:[CDDPLUS]EXAMPLES_DEFINITIONS.REVIEW_MENU' loaded %ACMSCDU-I-PROCMENU, Processing menu 'REVIEW_MENU' %ACMSCDU-I-PROCTASK, Processing task 'REVIEW_SCHEDULE' %ACMSCDU-I-PROCTASK, Processing task 'REVIEW_HISTORY' %ACMSCDU-I-MENUNAME, Menu named 'UTILITY' %ACMSCDU-I-LODMENNAM, Loading menu %ACMSCDU-I-MENPTHLOD, Menu CDD object 'CDD$TOP.EXAMPLES_DEFINITIONS.UTILITY_MENU' loaded %ACMSCDU-I-PROCMENU, Processing menu 'UTILITY_MENU' %ACMSCDU-I-PROCTASK, Processing task 'EDIT' %ACMSCDU-I-PROCTASK, Processing task 'DATR' %ACMSCDU-I-WRITEMDB, Writing MDB -ACMSCDU-I-BYTESWRIT, 1336 bytes (3 blocks)

This command produces a menu database file, PERSMEN1.MDB, containing the run-time version of all three menu definitions.

All submenus in the menu tree must exist in CDD before the BUILD MENU command can complete successfully.