HP OpenVMS Systems Documentation

Compaq ACMS for OpenVMSWriting Applications

Changing the standard ACMS menu requires the full TDMS kit; do not
attempt to make changes in the menu unless you are thoroughly familiar
with TDMS. Errors in the TDMS requests and records that ACMS uses for
menu work can produce fatal exceptions that cause other parts of the
ACMS system to fail; avoid changing the ACMS menu format except when
there is a serious need.
This appendix also describes how to disable the SELECT command, which
gives the user the ability to select a task by application name and
task name from the ACMS Command Menu. Disabling the SELECT command does
not require using TDMS.

There are two ways to revise the ACMS menu format without changing the
default format. First, you can include OpenVMS images that use option
lists or menus in your application. For an example of a task that
includes an option list, see the Employee task of the ACMS Sample
Application. Second, when you set up a menu using ADU, you can make a
number of choices in the menu format that ACMS supplies. For example,
you can define the text that appears at the top of the menu. You define
the entries that are displayed on the screen and the descriptive text
for these entries.

By using the HEADER, DEFAULT APPLICATION, and ENTRIES clauses (and the
subclauses under ENTRIES), you can change what is displayed on the
menu. The format of the menu, however, is the same from menu to menu:

The two lines of header text are the top two lines of the screen.

Each page of the menu can contain up to 16 entries.

Each entry line consists of a number, a keyword, a task/menu flag,
and descriptive text.

The Selection: prompt displays on the third line from the bottom.

The bottom line is used for all messages except "Press
<RET> for more" and "Press <RET> for first
page". These messages are displayed on the line above the
selection prompt.

You can change some parts of this format just by changing the form
definition that ACMS uses. For example, you can change the Selection:
prompt or the location of the "Press <RET> ..." message
lines by changing the menu form. Other changes can require you to
change the TDMS request that displays the menu form. The rest of this
appendix explains how to use TDMS requests to modify the ACMS menu
format.

To modify the default ACMS menu format, you need to change the TDMS
request that displays the menu form. For example, if you want to change
the number of entries that can appear on a menu, you must change the
menu request.

To change the menu request, you must either modify the menu request
supplied by ACMS or create a new menu request in order to add or delete
fields:

If you modify the ACMS menu request and keep the same name for it,
you must also rebuild the ACMS menu request library. All menus on the
ACMS system then use the new menu format. You must rebuild the ACMS
menu request library if you either change the ACMS-supplied menu or add
your own.

If you are creating a new menu request, you must name the request
in a REQUEST clause in all menu definitions that use the new request.
Make sure the number of entries in the request is the same as the
number in the ENTRIES PER SCREEN phrase in the menu definition.
Next, add the new request to the MENU_LIBR request library
definition. Then rebuild MENU_LIBR to create a new version of the
ACMSREQ.RLB request library file that includes the new request.

The only way to change the number of entry lines on an ACMS menu is to
change the menu request. Whenever a menu definition includes fewer
entries than there are entry lines in the menu request, only the
entries for that menu are displayed. The remaining entry lines are
filled with spaces by TDMS.

To create a new menu request, either you can create a copy of the ACMS
menu request or you can create entirely new request and form
definitions. To modify the ACMS menu request, load the contents of the
SYS$SYSTEM:ACMSREQ.BAK file into a CDD directory:

In this example, the contents of the ACMSREQ.BAK file are stored in the
CDD directory MENU_REQUESTS, directly below CDD$TOP. Be sure that the
directory you use is in the CDD before you use the RESTORE command.

If the ACMSREQ.BAK file is not in the directory pointed to by the
SYS$SYSTEM logical name, you can get it from the ACMS distribution kit
by reinstalling ACMS.

Table B-1 lists the definitions that the RESTORE command loads into
the CDD.

If you are changing only the appearance of the menu without changing
the number of entries, the only definition you need to modify is the
MENU_FORM definition. By modifying only the form definition, you can
change:

The background text that displays on the menu. The only background
text on the ACMS-supplied form is the Selection: prompt. You can change
this prompt or add background text to the form if you wish.

The location of the selection input field.

The location of the header text output fields.

The location of the entry output fields. However, they must still
be indexed fields, and there must be 16 fields in the form's indexed
array.

For an explanation of how to modify TDMS form definitions, see
VAX TDMS Forms Manual.

Use the name MENU_FORM if you want all menus in the ACMS system to use
the new form. In this case, you do not have to change the menu request.
However, you must store the new MENU_FORM in the same CDD directory as
the menu request and then rebuild the request library, as explained in
Section B.2.8.

If you are changing only the menu form, be sure to use the same field
names as MENU_FORM uses. Do not delete any input or output fields from
the form. Keep their type and size the same as in the MENU_FORM
definition.

If you want to change any other characteristics of the ACMS menu
format, you must modify the existing ACMS menu request or create a new
ACMS menu request.

The menu request has two parts. The first part identifies the forms,
records, and keypad used by the request. The second part contains the
instructions that TDMS performs when ACMS calls the request.
Example B-1 shows the definition for MENU_REQUEST.

Example B-1 MENU_REQUEST Definition

CREATE REQUEST MENU_REQUEST
RECORD IS MENU_HEADER_RECORD;
RECORD IS MENU_ENTRY_RECORD;
RECORD IS MENU_CONTROL_RECORD;
RECORD IS MENU_SELECTION_RECORD;
FORM IS MENU_FORM;
FORM IS EXPERT_MENU_FORM;
KEYPAD IS NUMERIC;
CONTROL FIELD IS CTL_EXPERT_MENU
"T":
USE FORM EXPERT_MENU_FORM;
DEFAULT FIELD SELECTION_STRING_1;
DEFAULT FIELD SELECTION_STRING_2;
INPUT SELECTION_STRING_1 TO SELECTION_STRING_1;
INPUT SELECTION_STRING_2 TO SELECTION_STRING_2;
NOMATCH:
CONTROL FIELD IS CTL_NEW_ENTRIES
"T":
DISPLAY FORM MENU_FORM;
OUTPUT MENU_HEADER_1 TO MENU_HEADER_1;
OUTPUT MENU_HEADER_2 TO MENU_HEADER_2;
CONTROL FIELD IS ENTRY_FLAG [1 TO 16]
" ":
WAIT;
NOMATCH:
OUTPUT ENTRY_NUMBER [%LINE] TO ENTRY_NUMBER [%LINE];
OUTPUT ENTRY_KEY [%LINE] TO ENTRY_KEY [%LINE];
OUTPUT ENTRY_FLAG [%LINE] TO ENTRY_FLAG [%LINE];
OUTPUT ENTRY_TEXT [%LINE] TO ENTRY_TEXT [%LINE];
END CONTROL FIELD;
CONTROL FIELD IS CTL_MULTI_PAGE
"T":
CONTROL FIELD IS CTL_LAST_PAGE
"T":
OUTPUT " ....... Press <RET> for first page ......."
to MENU_MORE;
NOMATCH:
OUTPUT " ....... Press <RET> for more ......."
to MENU_MORE;
END CONTROL FIELD;
END CONTROL FIELD;
INPUT SELECTION_STRING_1 TO SELECTION_STRING_1;
INPUT SELECTION_STRING_2 TO SELECTION_STRING_2;
NOMATCH:
USE FORM MENU_FORM;
DEFAULT FIELD SELECTION_STRING_1;
DEFAULT FIELD SELECTION_STRING_2;
INPUT SELECTION_STRING_1 TO SELECTION_STRING_1;
INPUT SELECTION_STRING_2 TO SELECTION_STRING_2;
END CONTROL FIELD;
END CONTROL FIELD;
END DEFINITION;

The ACMS menu request uses two forms:

MENU_FORM is the complete ACMS menu, which includes 16 entries, a
2-line menu header, the Selection: prompt, and a 2-line selection input
field.

EXPERT_MENU_FORM contains the Selection: prompt and the 2-line
selection input field; this form is for users who want to select tasks
without seeing menus.

There are four records in the ACMS menu request. Example B-2 shows
the definitions for the MENU_HEADER_RECORD.

ACMS uses the NUMBER_OF_ENTRIES field to pass to the request the number
of entries in the MENU_ENTRY_RECORD record. It takes this value from
the user's menu database, using the value assigned in the ENTRIES PER
SCREEN clause in the definition for the menu.

ACMS uses the two menu header fields to pass the menu header, or title,
to the request. It takes this text from the HEADER clause of the menu
definition.

The default ACMS menu does not use the MENU_PATH field of this record.
The menu path is the sequence of menus, identified by keyword, that the
user followed in reaching the current menu; ACMS maintains this
information. A request can use this field to display the user's current
location in the menu tree.

Example B-3 shows the CDD definition for the second record used by
the request, MENU_ENTRY_RECORD.

ACMS uses MENU_ENTRY_RECORD to pass the number, keyword, identifying
flag, and descriptive text to the request. It derives all this
information for each entry from the menu database. The number for an
entry is derived from the sequence in which the entry occurs in the
ENTRIES clause of the definition. The keyword is derived from the name
used for the entry in the ENTRIES clause; the text is taken from the
TEXT subclause for the entry. The flag field contains one of two
values: T (for tasks) or M (for menus).

Example B-4 shows MENU_CONTROL_RECORD, the third record used by the
request.

The information in the menu control record does not come directly from
the menu database. Rather, it is information that ACMS maintains for
each user and for the user's current menu. The value of CTL_EXPERT_MENU
determines whether the user sees the complete ACMS menu, in which case
the field is set to F (False), or sees only the selection prompt, in
which case the field is set to T (True). The initial value is set from
the user definition file (ACMSUDF.DAT). Each time the user types in the
terminal user MENU or NOMENU command, that field is updated.

ACMS uses the MULTI_PAGE and LAST_PAGE fields in the record to tell the
request whether more menu entries are available than would fit on a
single screen. It uses the NEW_ENTRIES field to tell the request
whether the entries to be displayed differ from the entries last
displayed.

Example B-5 shows MENU_SELECTION_RECORD, the final record used by the
request.

A menu request must include the forms, records, and keypad it uses, as
well as the instructions that TDMS performs when ACMS calls the
request. This section explains the instructions that the request
contains.

The second part of the menu request begins with the "CONTROL FIELD
IS CTL_EXPERT_MENU" instruction. Although this part of the request
is complex because of its control fields, the work it does is always
the same:

The request displays either a complete menu or the selection
prompt only.

After the user has typed in a selection keyword or number (and,
optionally, a selection string) and pressed [Return], the
request moves that information to the menu selection record.

The request uses the value passed in the CTL_EXPERT_MENU field to
determine whether to display the complete menu or only the expert menu.
This control field is the first TDMS looks at; if the CTL_EXPERT_MENU
field is set to T, the request displays the expert menu, enters the
selection in the menu selection record, and ends. These statements,
taken from the menu request, perform those operations:

CONTROL FIELD IS CTL_EXPERT_MENU
"T" : USE FORM EXPERT_MENU_FORM;
DEFAULT FIELD SELECTION_STRING_1;
DEFAULT FIELD SELECTION_STRING_2;
INPUT SELECTION_STRING_1 TO SELECTION_STRING_1;
INPUT SELECTION_STRING_2 TO SELECTION_STRING_2;
...
END CONTROL FIELD;

If the CTL_EXPERT_MENU field is not set to T, the request then checks
whether the entries to be displayed are the same ones as the last
entries the user saw. If the value of the CTL_NEW_ENTRIES field of the
control record is set to a value other than T, then the menu is the
same as the last one. In this case, the request displays the last menu,
accepts the selection string, and ends. The following statements, taken
from the menu request, show this second way you can write the request:

CONTROL FIELD IS CTL_EXPERT_MENU
...
NOMATCH:
CONTROL FIELD IS CTL_NEW_ENTRIES
...
NOMATCH:
USE FORM MENU_FORM;
DEFAULT FIELD SELECTION_STRING_1;
DEFAULT FIELD SELECTION_STRING_2;
INPUT SELECTION_STRING_1 TO SELECTION_STRING_1;
INPUT SELECTION_STRING_2 TO SELECTION_STRING_2;
END CONTROL FIELD;
END CONTROL FIELD;
END DEFINITION;

If the menu to be displayed does contain new entries, then ACMS has set
the value of CTL_NEW_ENTRIES to T. In this case, the request displays
the menu form and outputs the menu header. The request then begins
displaying the entries to the indexed fields on the menu form. This
work is done by the statements in the conditional instruction that
begins "CONTROL FIELD IS ENTRY_FLAG". As long as there is an
entry, which the request checks by looking at one of the fields to be
displayed, the request continues to produce the entry information. As
soon as there are no more entries, or when the request has displayed
the sixteenth entry, the request stops displaying entries.

Before accepting the selection information from the user, the request
checks the CTL_MULTI_PAGE field to see if there are more entries than
fit on one screen. If so, ACMS sets the value of that field to T. If
not, then the request does not display a message; there is an implicit
NOMATCH in this control field. The request then accepts input from the
user and ends.

The statements that follow show this third sequence of operations:

CONTROL FIELD IS CTL_EXPERT_MENU
...
NOMATCH:
CONTROL FIELD IS CTL_NEW_ENTRIES
"T" :
DISPLAY FORM MENU_FORM;
OUTPUT MENU_HEADER_1 TO MENU_HEADER_1;
OUTPUT MENU_HEADER_2 TO MENU_HEADER_2;
CONTROL FIELD IS ENTRY_FLAG [1 TO 16]
" " :
WAIT;
NOMATCH :
OUTPUT ENTRY_NUMBER [%LINE] TO ENTRY_NUMBER [%LINE];
OUTPUT ENTRY_KEY [%LINE] TO ENTRY_KEY [%LINE];
OUTPUT ENTRY_FLAG [%LINE] TO ENTRY_FLAG [%LINE];
OUTPUT ENTRY_TEXT [%LINE] TO ENTRY_TEXT [%LINE];
END CONTROL FIELD;
CONTROL FIELD IS CTL_MULTI_PAGE
...
END CONTROL FIELD;
INPUT SELECTION_STRING_1 TO SELECTION_STRING_1;
INPUT SELECTION_STRING_2 TO SELECTION_STRING_2;
...
END CONTROL FIELD;
END CONTROL FIELD;
END DEFINITION;

If there are more than 16 entries, which is the default number of
entries for each screen, then the request tests the CTL_LAST_PAGE field
to determine whether or not this is the last page of the menu displayed
to the user. ACMS indicates the last page of the menu by setting the
CTL_LAST_PAGE field to T. If it is the last page, the request displays
the message "Press <RET> for first page". If it is not
the last page of the menu, the request outputs the message "Press
<RET> for more". It then accepts the selection from the user
and ends.

The statements that follow show this fourth sequence of operations:

CONTROL FIELD IS CTL_EXPERT_MENU
...
NOMATCH:
CONTROL FIELD IS CTL_NEW_ENTRIES
"T" :
DISPLAY FORM MENU_FORM;
OUTPUT MENU_HEADER_1 TO MENU_HEADER_1;
OUTPUT MENU_HEADER_2 TO MENU_HEADER_2;
CONTROL FIELD IS ENTRY_FLAG [1 TO 16]
" " :
WAIT;
NOMATCH :
OUTPUT ENTRY_NUMBER [%LINE] TO ENTRY_NUMBER [%LINE];
OUTPUT ENTRY_KEY [%LINE] TO ENTRY_KEY [%LINE];
OUTPUT ENTRY_FLAG [%LINE] TO ENTRY_FLAG [%LINE];
OUTPUT ENTRY_TEXT [%LINE] TO ENTRY_TEXT [%LINE];
END CONTROL FIELD;
CONTROL FIELD IS CTL_MULTI_PAGE
"T" :
CONTROL FIELD IS CTL_LAST_PAGE
"T":
CONTROL FIELD IS CTL_LAST_PAGE
"T":
OUTPUT " ....... Press <RET> for first page ......."
to MENU_MORE;
NOMATCH:
OUTPUT " ....... Press <RET> for more ......."
to MENU_MORE;
END CONTROL FIELD;
END CONTROL FIELD;
INPUT SELECTION_STRING_1 TO SELECTION_STRING_1;
INPUT SELECTION_STRING_2 TO SELECTION_STRING_2;
...
END CONTROL FIELD;
END CONTROL FIELD;
END DEFINITION;

The complexity of the ACMS menu request can provide several significant
performance benefits. The instruction CONTROL FIELD IS ENTRY_FLAG
ensures that the request performs an output mapping only when there is
an entry to be displayed. Using USE FORM rather than DISPLAY FORM in
the CONTROL FIELD IS CTL_NEW_ENTRIES instruction ensures that the
request does not repaint the screen if a user selects an invalid
selection. Removing these instructions simplifies the request but
decreases ACMS performance.