HP OpenVMS Systems Documentation

Menu definitions describe the contents of ACMS menus, which are screen displays of entries that users can select. Users can select task entries that do the work of an application, or menu entries that display other menus with their own entries. You can create a menu hierarchy similar to the directory structure on your OpenVMS system.

This chapter explains the clauses you use to write menu definitions. A menu definition describes the menu title and the names and descriptions of menu entries. Table 6-1 names and briefly describes each of these clauses.

The ENTRIES clause is the only required menu clause. It includes a required subclause specifying whether an entry is a task or menu entry. It can also include optional subclauses for displaying descriptive text and controlling screen display characteristics. Figure 6-1 shows the menu definition syntax.

Figure 6-1 Menu Definition Syntax

Example 6-1 shows a sample menu definition.

HEADER IS "               EXAMPLE OF",
          "             ACMS MENU DEFINITION";
DEFAULT APPLICATION IS PERSONNEL;
ENTRIES ARE
  ADD     :  TASK IS ADD_EMPLOYEE;
             TEXT IS "Add New Employee Record";
  CHANGE  :  TASK IS CHANGE_EMPLOYEE;
             TEXT IS "Change Employee Record";
  DISPLAY :  MENU IS DISPLAY_MENU;
             TEXT IS "Menu of Tasks to Display Information";
END ENTRIES;
END DEFINITION;

This menu defines three entries. ADD and CHANGE are task entries. When selected, they run the tasks identified by the task names ADD_EMPLOYEE and CHANGE_EMPLOYEE. You must define these names in a task group definition. DISPLAY is a menu entry that displays another menu selected by a user. DISPLAY_MENU is the CDD path name of the menu definition that describes the menu you want to display. Each entry includes descriptive text.

ENTRIES clauses define each entry in a menu definition. You begin a set of ENTRIES clauses with the keywords ENTRIES ARE and end it with the keywords END ENTRIES. ENTRIES subclauses define the characteristics of each entry.

To define the characteristics of a set of entries, specify each entry name, a colon (:), and the entry's subclauses. The ENTRIES clause includes the following types of subclauses:

• Required subclauses define whether the entry displays a menu (MENU subclause) or runs a task (TASK subclause) when a terminal user selects the entry. Specify only one of these subclauses for each entry.
• Optional subclauses define descriptive text (TEXT subclause) and WAIT or DELAY screen display characteristics.

Several ADU clauses include an application specification parameter. For example, in the DEFAULT APPLICATION clause, you must specify the name of the application to be the default when the terminal user logs on to ACMS.

The syntax for the application specification parameter is:

The elements of the application specification parameter are:

• File-name
  The name of the application database file created by the BUILD APPLICATION command. The file must have .ADB as the file type. You cannot specify the file type or version number. You also cannot specify a device or directory name. The .ADB file must be located on the device and directory pointed to by the logical ACMS$DIRECTORY.
  File names can have up to 39 characters, including letters, digits, hyphens (-), underscores (_), and dollar signs ($). If you have more than 31 characters in the file name, you must enclose the application specification in quotation marks, either single (') or double (").
• Node-name
  The name of a valid DECnet node. The node name cannot include an access control string.
• Logical-node-name
  A logical name whose equivalence string is the name of a valid DECnet node. The logical node name cannot include an access control string. ACMS follows the OpenVMS conventions for translating logical names, including use of interative translation and search lists.
  A logical name can have up to 255 characters. If the logical name exceeds 31 characters, enclose the application specification in quotation marks, either single (') or double (").
• Logical-appl-name
  A logical name whose equivalence string consists of either of the following:
  • The name of an application database (.ADB) file.
  • A valid DECnet node name, followed by two colons (::), followed by the name of an application database file, for example, NODE1::PAYROLL.
  
  The file name that the logical application name points to must conform to the rules listed previously for application file names.
  A logical name can have up to 255 characters. If the logical name exceeds 31 characters, enclose the application specification in quotation marks, either single (') or double (").

Logical names must be accessible to the ACMS command process (CP), so define them as system logical names. See OpenVMS DCL Dictionary for information on logical names and file names.

The application you specify can be located on the same node as the terminal user, or on a remote node with the terminal user located on a separate front-end processor. When the application exists on the same node as the user, the application specification consists of the name of the application database file. That file must be located in the directory pointed to by the logical ACMS$DIRECTORY. The logical definition for ACMS$DIRECTORY includes both a device name and a directory name.

For a distributed application, where the application is located on a remote node, specify both the application database file name and the name of the remote node. The device and directory names are taken from the ACMS$DIRECTORY logical on the remote node.

Use logical application names whenever possible to specify the application database file. If the application is moved to another node, you only need to change the logical name definition to reflect the new configuration. For example, if the file name is hardcoded in the menu definition, the menu database must be rebuilt whenever the node changes.

Frequently, sites develop and test applications on a single node system. Then, when they put the application into production, they distribute the front-end processing to one node and place the application on a more powerful system. Using a logical application specification means only one change to the code is required when a new configuration is set up.

The following are examples of application specifications:

• PAYROLL
  The application database file is PAYROLL.ADB. The node where the application resides is the same node where terminal users log on to access the application.
• "HOURLY_PAYROLL_MAPLE_VALLEY_BRANCH"
  HOURLY_PAYROLL_MAPLE_VALLEY_BRANCH.ADB is the application database file. Quotation marks are required because the file name exceeds 31 characters.
• SANFRN::PAYROLL
  The application database file is PAYROLL.ADB. The application is located on node SANFRN.
• SAN_FRANCISCO::PAYROLL
  The application database file is PAYROLL.ADB. The node where the application resides is defined by the logical name SAN_FRANCISCO.
• SAN_FRANCISCO_SALARIED_PAYROLL
  SAN_FRANCISCO_SALARIED_PAYROLL is a logical application name that points to the application database file SF_SAL_PAYROLL.ADB. The node where the application resides is included in the logical name definition.
• "SAN_FRANCISCO_BAY_AREA_SALARIED_PAYROLL"
  SAN_FRANCISCO_BAY_AREA_SALARIED_PAYROLL is a logical application name that points to the application database file SFBA_SAL_PAYROLL.ADB. The node where the application resides is included in the logical name definition. Quotation marks are required because the logical name exceeds 31 characters.

ACMS supports applications distributed across a network. A menu can include 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.

For example, suppose the ACMS Sample Applications Personnel and Employee run on an OpenVMS Cluster with two nodes, RAVEN and MAGPIE. The Personnel application runs on the node RAVEN; Employee runs on MAGPIE. Some tasks from the Employee application on MAGPIE are needed by users on RAVEN. 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.

One way to distribute a task remotely is to include the name of the remote node in the application specification in the menu definition. Example 6-2 provides an example of a menu entry for a task of a remote node.

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

The EMPLOYEE menu definition is on node MAGPIE. The HEADER clause lists the descriptive text at the top of the menu. The ENTRIES clause lists the choices displayed on the menu. The first entry, SCHEDULE, 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.

Example 6-2 hardcoded a node name in a menu definition. See Section 6.1 for information about other methods of accessing remote applications that are more flexible than hardcoding.

Lets you customize your DECforms menu by sending up to five control text items to the form.

Format

Parameters

string

A 5- to 25-character identifier that the ACMS command process passes to DECforms, instructing DECforms to execute corresponding control text responses. You can specify up to five control text items; each item must be five characters long. If you send multiple control text items, do not separate them with spaces or commas.

quoted-string

A 5- to 25-character identifier, within quotation marks, that instructs the DECforms to execute corresponding control text responses. Use a quoted string if your string contains any nonalphanumeric characters.

number

Identifies the number of entries that appear on the terminal screen.

Clause Default

The CONTROL TEXT clause is optional. If you do not use it in your menu definition, and your application uses DECforms, your menu appears in the standard DECforms format with 16 entries for each screen.

Notes

You can use the CONTROL TEXT clause to change menu attributes such as background color, highlighted fields, and blinking fields. For each control text item that you name, define a corresponding control text response in your IFDL (Independent Form Description Language) source file in the form.

You cannot specify both CONTROL TEXT and REQUEST clauses in the same menu definition.

Example

SEND CONTROL TEXT IS COLORLIGHT
       WITH 10 ENTRIES PER SCREEN;
      

This example passes two control text items, COLOR and LIGHT, to DECforms where two corresponding control text responses define the menu's background color and highlighted fields. This example also changes the number of entries for each screen from the default of 16 to 10.

Defines the application specification that ACMS uses as the default for TASK entries, unless you name a different application database file with the TASK subclause.

Format

DEFAULT APPLICATION IS application-spec ;

Parameter

application-spec

See Section 6.1 for information about application specifications.

Clause Default

If you omit the DEFAULT APPLICATION clause, you must specify the application in each TASK subclause in the menu definition. This clause is optional.

Notes

Include the application specification in the DEFAULT APPLICATION clause rather than in TASK subclauses. Changing the application specification in the DEFAULT APPLICATION clause is easier than changing each entry that uses that application specification.

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

Examples

DEFAULT APPLICATION IS EMPLOYEE;
ENTRIES ARE
  ADD    :  TASK IS ADD_EMPLOYEE;
            TEXT IS "Add Employee Information";
  CHANGE :  TASK IS CHANGE_EMPLOYEE;
            TEXT IS "Change Employee Information";
END ENTRIES;
END DEFINITION;
      

In this example, the default application is EMPLOYEE. You do not need to include the application for each entry in the ENTRIES clause. Only if a task entry belongs to another application do you need to name another application name with the TASK subclause.

The application specification EMPLOYEE in the DEFAULT APPLICATION clause includes no node name, indicating that the application EMPLOYEE is resident on the same node as the menu definition. This is the default.

DEFAULT APPLICATION IS RAVEN::DEPART;
ENTRIES ARE
  ADD    :  TASK IS ADD_EMPLOYEE;
            TEXT IS "Add Employee Information";
  CHANGE :  TASK IS CHANGE_EMPLOYEE IN EMPLOYEE;
            TEXT IS "Change Employee Information";
END ENTRIES;
END DEFINITION;
      

In this example, the default application database DEPART runs on the remote node RAVEN, so the application specification includes the node name followed by two colons followed by the application file name. Because the ADD task entry includes no application name, ADD takes the default application. The CHANGE task, however, belongs to a different application, Employee, in the database file EMPLOYEE.ADB on the same node as the menu definition. The assignment you make for the CHANGE task overrides the default for that task.

DEFAULT APPLICATION IS
           "LONG_LOGICAL_NAME_FOR_APPLICATION_NODE::EMPLOYEE";
ENTRIES ARE
  ADD    :  TASK IS ADD_EMPLOYEE;
            TEXT IS "Add Employee Information";
  CHANGE :  TASK IS CHANGE_EMPLOYEE;
            TEXT IS "Change Employee Information";
END ENTRIES;
END DEFINITION;

      

In this example, the default application database file is:

LONG_LOGICAL_NAME_FOR_APPLICATION_NODE::EMPLOYEE.

LONG_LOGICAL_NAME_FOR_APPLICATION_NODE is defined as RAVEN, so OpenVMS translates the application specification as RAVEN::EMPLOYEE. Because the logical name is longer than 31 characters, the application specification is enclosed in quotation marks.

Defines the menu database file that ACMS uses as the default when it builds a menu tree. ACMS builds the menu tree when you use the BUILD command and includes the specified menu as the top menu in the tree.

Format

DEFAULT MENU FILE IS menu-database-file ;

Parameter

menu-database-file

The file specification of the menu database file that you create when you build a menu definition. It can be either an identifier or a quoted string. If the menu database file specification contains any characters not allowed for an identifier, or the file specification exceeds 31 characters, enclose the file specification in quotation marks (" "). ADU assigns the default file type .MDB. If you do not include a device or directory with the menu database file specification, ADU searches your current default device and directory by default.

Clause Default

This clause is optional. Any menu database file assignment you make in the BUILD command overrides any you make with the DEFAULT MENU FILE clause in a menu definition. When you do not include the DEFAULT MENU FILE clause in a menu definition, ADU uses the file specification you include with the BUILD command for the menu database file. If you do not name a menu database file when you build a menu, and you do not name a database file with the DEFAULT MENU FILE clause, ADU derives the database file specification from the given name of the menu. It uses the full given name, including dollar signs ($) and underscores (_), for the default database file name.

Examples

DEFAULT MENU FILE IS "DISPLAY.MDB";
DEFAULT APPLICATION IS DEPART;
ENTRIES ARE
  ADD    :  TASK IS ADD_EMPLOYEE;
            TEXT IS "Add Employee Information";
  CHANGE :  TASK IS CHANGE_EMPLOYEE IN EMPLOYEE;
            TEXT IS "Change Employee Information";
END ENTRIES;
END DEFINITION;
      

ADU uses the menu database file that you name with the DEFAULT MENU FILE clause to store the binary version of a CDD menu definition. If you include a device designation, a directory specification, or a file type, you must enclose the file specification in quotation marks (" ").

MENU FILE DISPLAY;
DEFAULT APPLICATION IS DEPART;
ENTRIES ARE
  ADD    :  TASK IS ADD_EMPLOYEE;
            TEXT IS "Add Employee Information";
  CHANGE :  TASK IS CHANGE_EMPLOYEE;
            TEXT IS "Change Employee Information";
END ENTRIES;
END DEFINITION;
      

ACMS assigns the default file type .MDB if you omit the file type in your file specification. When you include only the file name, you do not need to use quotation marks (" "). To shorten the clause, leave out the keywords DEFAULT and IS.

Controls whether or not ACMS waits 3 seconds after a task entry stops running before clearing the screen and displaying the ACMS menu.

Format

[ NO ] DELAY ;

Clause Default

If you do not set the delay attribute in an ENTRIES clause, ACMS uses the setting you assign in the application or task group definition. If you do not make an assignment there, ACMS uses the NO DELAY default. This subclause is optional.

Notes

DELAY and WAIT subclauses are valid for task entries only.

When you use the WAIT subclause, you cannot specify a DELAY subclause for the same task entry.

The DELAY subclause always delays clearing the screen for 3 seconds. You cannot change the time of the delay.

This subclause differs from the WAIT subclause, which requires users to press [Return] to have ACMS redisplay the menu.

The WAIT and DELAY subclauses determine how quickly ACMS returns user control to a menu when a task ends. For example, if a user runs a task that displays the time of day with the SHOW TIME command, by default ACMS displays the time, but then immediately clears the screen and returns the user to the menu. Both subclauses let you delay the time interval between the task ending and the selection menu redisplay.

WAIT and DELAY subclauses specified for a task in a task, task group, or application definition are overridden by menu definition WAIT and DELAY clauses.

Example

ENTRIES ARE
  EMPLOYEE  :  TASK IS EMPLOYEE IN EMPYAPP;
               TEXT IS "Create Employee Database";
               DELAY;
END ENTRIES;
END DEFINITION;
      

The EMPLOYEE task entry in this example uses a DELAY subclause. When the entry finishes running, ACMS waits 3 seconds before clearing the screen and displaying the ACMS menu.