# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# DEFAULT MENU FILE Clause (Menu)

> 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

#1
    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 (" ").

#2
    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.

# DELAY Subclause (Optional ENTRIES)

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

# ENTRIES Clause (Menu)

> Defines an entry as a menu entry or a task entry. A menu entry displays a menu when users select the entry. A task entry runs a task.

## Format

## Parameters

> ### entry-name

> The name that ADU puts on the left side of the menu to identify the entry. You must create an entry name for each entry in a menu. Each entry name can be up to 10 characters long, including letters and numbers. The entry name must begin with a letter. A colon (:) separates an entry name from the subclauses that describe it.

> You can put entry names in quotation marks (" ") to display the entry name as you typed it, with uppercase letters displayed in uppercase, and lowercase letters in lowercase. Do not include embedded spaces, periods, or tab characters in an entry name contained in quotation marks.

> If you do not put an entry in quotation marks (" "), ACMS displays the entry name in uppercase letters. Typing the entry name in either uppercase or lowercase letters does not affect the way ACMS displays an entry name not contained in quotation marks.

> ### required-subclause

> Defines an entry as a menu (MENU subclause) or as a task (TASK subclause). You must include either the MENU or the TASK subclause for each entry you define with the ENTRIES clause.

> ### optional-subclause

> Allows you to include descriptive text in menus, and control WAIT and DELAY screen display characteristics for task entries:
> - TEXT is the optional subclause you use to describe characteristics for entries in a menu definition.
> - DELAY specifies that 3 seconds will elapse when a task ends before a menu is redisplayed.
> - WAIT sends a message to the terminal screen indicating that the user must press `[Return]` to have ACMS clear the screen and redisplay the menu.

> DELAY and WAIT subclauses are valid for task entries only.

## Clause Default

> You must include at least one ENTRIES clause and define at least one entry in every menu definition. This clause is required.

## Notes

> Insert a colon between the entry name and the first subclause for the task. The colon separates the entry name from the subclauses that describe it.

> After putting all the subclauses for an entry in your definition file, begin the description of the next entry by typing another entry name. Follow the entry name with a colon and the subclauses for that entry.

> The order of entry names in the menu definition is the order in which ACMS displays them on the menu.

> You can use more than one ENTRIES clause in the same menu definition. If necessary, ACMS separates the menus into many screens for each menu definition.

> You can use an entry name only once for each menu.

## Example

    ENTRIES ARE
      ADD     :  TASK EMPLOYEE IN PERSONNEL;
                 TEXT IS "Add New Employee";
                 DELAY;
      EDITOR  :  TASK EDIT IN PERSONNEL;
                 TEXT IS "Edit Memos";
                 WAIT;
    END ENTRIES;
    END DEFINITION;

> The entry names in this example are ADD and EDITOR. Both begin with a letter and contain fewer than 10 characters. Follow each entry name with a colon and the subclauses for that entry. The keywords END DEFINITION complete the menu definition.

# HEADER Clause (Menu)

> Defines the title of a menu.

## Format

> HEADER IS string [ ,string ] ;

## Parameter

> ### string

> The text of the menu title. The title can have up to two lines of text. If you include only one line for the header, enclose the text in quotation marks (" ") and end the line with a semicolon (;). If you have a two-line title, enclose the text for the first line in quotation marks (" ") and end it with a comma (,). Put quotation marks (" ") around the second line of the two-line title and end it with a semicolon (;).

## Clause Default

> ADU leaves the title lines blank. This clause is optional.

## Notes

> You do not need to fill spaces to the right of a header line.

> Center a title by including spaces before the text of the title. Put the spaces and the title in quotation marks.

> Do not use tabs or other nonprinting characters.

##

### Examples

#1
    HEADER "        ACMS EMPLOYEE SAMPLE APPLICATION";
    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;

> In this example, the single-line title is in quotation marks (" "). The clause ends with a semicolon. The keyword IS is optional.

#2

    HEADER IS "              A C M S",
              "    EMPLOYEE  SAMPLE  APPLICATION";
    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;

> This example has a two-line header. Put both lines of the title in quotation marks (" "). The first line ends with a comma, and the second line ends with a semicolon.

# MENU Subclause (Required ENTRIES)

> Defines an entry as a menu and points to the CDD location of the definition for that menu.

## Format

> MENU IS menu-path-name ;

## Parameter

> ### menu-path-name

> The CDD path name of a menu definition. This definition describes the menu ACMS displays when users select the entry.

## Clause Default

> You must include this subclause or the TASK subclause for each menu entry you define.

## Note

> Do not name a menu that has been used higher in the same menu tree. If you do, the BUILD command goes into an infinite loop.

##

### Examples

#1
    ENTRIES ARE
     ADMIN :
           MENU IS DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE.ACMS_ADMIN_MENU;
           TEXT IS "Administrative Application Menu";
     DEPART :
           MENU IS DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE.ACMS_DEPART_MENU;
           TEXT IS "Department Application Menu";
    END ENTRIES;
    END DEFINITION;

> Each entry in this example points to a menu located in the dictionary. A menu path name defines the location of the menu definitions that display the menu when users select the entry. Both MENU subclauses include complete path names.

#2
    ENTRIES ARE
      ADMIN  :   MENU IS ACMS_ADMIN_MENU;
                 TEXT IS "Administrative Application Menu";
      DEPART :   MENU IS ACMS_DEPART_MENU;
                 TEXT IS "Department Application Menu";
    END ENTRIES;
    END DEFINITION;

> If you use the ADU SET DEFAULT command or the DCL DEFINE command to assign the logical CDD$DEFAULT to the default directory DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE, you can use just the relative path names ACMS_ADMIN_MENU and ACMS_DEPART_MENU instead of the full CDD path names.

# REQUEST Clause (Menu)

> Identifies the TDMS request that defines the menu layout.

## Format

> REQUEST IS request-name [ WITH number ENTRIES PER SCREEN ] ;

## Parameters

> ### request-name

> The given name of the TDMS request that supplies the menu ACMS displays. This is the name of the request in the request library definition. It is not a CDD path name.

> ### number

> Identifies the number of entries the TDMS request contains.

## Clause Default

> ACMS supplies the default menu request MENU_REQUEST. If you omit the WITH number ENTRIES PER SCREEN portion of the REQUEST clause, the default is WITH 16 ENTRIES PER SCREEN. This clause is optional.

## Note

> Use the REQUEST clause to specify that TDMS is to be used to display a menu.

> Compaq ACMS for OpenVMS Writing Applications has information about using the REQUEST clause.

## Example

    REQUEST IS MENU_REQUEST;

> In this example, the TDMS request that supplies the menus for the application is MENU_REQUEST.

# TASK Subclause (Required ENTRIES)

> Names the task ACMS runs when a user selects the entry from a menu.

## Format

> TASK IS task-name [ IN application-spec ] ;

## Parameters

> ### task-name

> The name of the task in the application database. If the task is defined with the TASK ATTRIBUTES clause in the application definition, the task name must be the one used in that definition. If the task is not defined in an application, the task name must be the one used in the task group definition. The task name can be up to 31 characters, consisting of letters, numbers, and underscores. Begin the task name with any of these characters except a number. Do not put the task name in quotation marks (" ").

> ### application-spec

> See Section 6.1 for information about application specifications.

## Clause Default

> You must include this subclause or the MENU subclause for each menu entry you define.

## Notes

> If you include the application specification in the DEFAULT APPLICATION clause, you do not have to include it with the TASK subclause.

> In the TASK subclause, you can include an application specification that is different from the one you used in the DEFAULT APPLICATION clause. If you do, the assignment you make with the TASK subclause overrides the application specification you include with the DEFAULT APPLICATION clause.

##

### Examples

#1
    ENTRY IS
      EMPLOYEE  :  TASK IS  EMPLOYEE IN EMPLYAPP;
                   TEXT IS "Create Employee Database";
    END ENTRY;
    END DEFINITION;

> This example defines the task entry EMPLOYEE and includes the application name EMPLYAPP.

#2
    DEFAULT APPLICATION IS ACPERSON;
    ENTRY IS
      UTILITY  :  TASK IS UTILITY;
                  TEXT IS "Display Utility Menu";
    END ENTRY;
    END DEFINITION;

> This example uses the DEFAULT APPLICATION clause to name the application ACPERSON. You then can omit the reference to the application name from the TASK subclause.

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

> This example shows a menu definition including a remote task from the EMPLOYEE menu definition on node MAGPIE. The SCHEDULE entry is a task named REVIEW_SCHEDULE in the Personnel application running on the node RAVEN. The EMPLOYEE entry is a task named EMPLOYEE in the Employee application running on the same node as the menu definition.

#4
    HEADER IS   "                    EMPLOYEE MENU";
    ENTRIES ARE
      SCHEDULE : TASK IS REVIEW_SCHEDULE
                   IN "REALLY_LONG_APPLICATION_LOGICAL_NAME::PERSONNEL";
      EMPLOYEE : TASK IS LIST_EMPLOYEE IN EMPLOYEE;
    END ENTRIES;
    END DEFINITION;

> This example shows the use of logical names in a menu definition, including a remote task, from the EMPLOYEE menu definition on the node MAGPIE. The SCHEDULE entry is a task named REVIEW_SCHEDULE in the Personnel application running on the node defined by the logical name REALLY_LONG_APPLICATION_LOGICAL_NAME. OpenVMS translates this logical name as RAVEN. Because the logical name is longer than 31 characters, the entire application specification is enclosed in quotation marks. The EMPLOYEE entry is a task named EMPLOYEE in the Employee application running on the same node as the menu definition.

# TEXT Subclause (Optional ENTRIES)

> Provides descriptive text that ACMS displays with a menu or task entry.

## Format

> TEXT IS description-string ;

## Parameter

> ### description-string

> The text describing the entry. You can use up to 50 characters in this description. Enclose the text in quotation marks (" ").

## Clause Default

> ACMS leaves the text field to the right of the entry name blank. This subclause is optional.

## Note

> Do not use tabs in a text string.

##

### Examples

#1
    ENTRIES ARE
      ADMIN :
            MENU IS DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE.ACMS_ADMIN_MENU;
            TEXT IS "Administrative Application Menu";
      DEPART :
            MENU IS DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE.ACMS_DEPART_MENU;
            TEXT IS "Department Application Menu";
    END ENTRIES;
    END DEFINITION;

> Both entries in this example use the TEXT subclause. The descriptive information is in quotation marks (" "). Each TEXT subclause ends with a semicolon.

#2
    ENTRIES ARE
      ADMIN   :  MENU IS ACMS$SAMPLE.ACMS_ADMIN_MENU;
      DEPART  :  MENU IS ACMS$SAMPLE.ACMS_DEPART_MENU;
                 TEXT IS "Department Application Menu";
    END ENTRIES;
    END DEFINITION;

> By default, ADU leaves the field next to the ADMIN menu entry blank. Only the DEPART menu entry has an entry description.

# WAIT Subclause (Optional ENTRIES)

> Controls whether or not ACMS prompts a terminal user to press `[Return]` after a task entry completes and before clearing the screen and displaying the ACMS menu.

## Format

> [ NO ] WAIT ;

## Clause Default

> If you do not set the WAIT attribute in the 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 WAIT 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 menu entry.

> This subclause differs from the DELAY subclause, which controls whether or not ACMS waits 3 seconds before redisplaying 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 WAIT and DELAY clauses specified in a menu definition.

## Example

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

> The EMPLOYEE task entry in this example uses a WAIT subclause. When the entry finishes running, ACMS displays a message on the terminal screen prompting users to press `[Return]` to clear the terminal and display the previous menu.

Previous | Next | Contents | Index