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.
6.1 Application Specifications
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.
6.2 Writing Menu Definitions for Distributed Applications
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.
| Example 6-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; |
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.
CONTROL TEXT Clause (Menu)
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.
DEFAULT APPLICATION Clause (Menu)
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
| #1 |
|---|
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.
| #2 |
|---|
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.
| #3 |
|---|
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.
| Previous | Next | Contents | Index |