| Previous | Contents | Index |
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.
B.1 Modifying the Menu Format Using ACMS
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:
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.
B.2 Modifying the ACMS Menu Using TDMS Requests
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:
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.
B.2.1 Getting the ACMS Menu Request and Form
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:
$ DMU DMU> SET DEF CDD$TOP.MENU_REQUESTS DMU> RESTORE SYS$SYSTEM:ACMSREQ.BAK DMU> EXIT |
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.
| Definition Name | Description |
|---|---|
| BLANK_FORM <CDD$FORM> | Form used to reset the screen. Do not change this definition. |
| CLEAR_SCREEN <CDD$REQUEST> | Request used to reset the screen. Do not change this definition. |
| COMD_CONTROL_RECORD <CDD$RECORD> | Record used for control information for command menu. |
| COMD_ENTRY_RECORD <CDD$RECORD> | Record used for entry information for command menu. |
| COMD_FORM <CDD$FORM> | Form used for command menu. |
| COMD_HEADER_RECORD <CDD$RECORD> | Record used for header of command menu. |
| COMD_REQUEST <CDD$REQUEST> | Request used for command menu. |
| COMD_SELECTION_RECORD <CDD$RECORD> | Record used for selection string typed after Command: prompt. |
| EXIT_REQUEST <CDD$REQUEST> | Request used to do a $EXIT from menu. |
| EXPERT_COMD_FORM <CDD$FORM> | Form used for command prompt when no command menu displayed. |
| EXPERT_MENU_FORM <CDD$FORM> | Form used for selection prompt when no selection menu displayed. |
| HCOMD_FORM <CDD$FORM> | Help form for command menu. |
| HMENU_FORM <CDD$FORM> | Help form for selection menu. |
| MENU_CONTROL_RECORD <CDD$RECORD> | Record used for control information for selection menu. |
| MENU_ENTRY_RECORD <CDD$RECORD> | Record used for entry information for selection menu. |
| MENU_FORM <CDD$FORM> | Form used for selection menu. |
| MENU_HEADER_RECORD <CDD$RECORD> | Record used for header of selection menu. |
| MENU_LIBR <CDD$REQUEST_LIBRARY> | ACMSREQ.RLB definition. |
| MENU_REQUEST <CDD$REQUEST> | Request used for selection menu. |
| MENU_SELECTION_RECORD <CDD$RECORD> | Record used for selection string typed after Selection: prompt. |
| RESET_SCREEN <CDD$REQUEST> | Request used to reset the screen. Do not change this definition. |
You can then use the TDMS utilities to change the MENU_FORM or MENU_REQUEST definitions to suit your needs.
Do not, under any conditions, change the BLANK_FORM, CLEAR_SCREEN, or RESET_SCREEN definitions. |
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:
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.
B.2.3 Forms, Records, and Keypad Used by the 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:
There are four records in the ACMS menu request. Example B-2 shows the definitions for the MENU_HEADER_RECORD.
| Example B-2 Definition for ACMS Menu Header Record |
|---|
DEFINE RECORD MENU_HEADER_RECORD
DESCRIPTION IS /* RECORD FOR THE DEFAULT ACMS MENU HEADER INFO */.
MENU_HEADER_RECORD STRUCTURE.
NUMBER_OF_ENTRIES DATATYPE UNSIGNED LONGWORD.
MENU_PATH DATATYPE TEXT 70.
MENU_HEADER_1 DATATYPE TEXT 80.
MENU_HEADER_2 DATATYPE TEXT 80.
END MENU_HEADER_RECORD STRUCTURE.
END 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.
| Example B-3 Definition for Menu Entry Record |
|---|
DEFINE RECORD MENU_ENTRY_RECORD
DESCRIPTION IS /* RECORD FOR THE DEFAULT ACMS MENU ENTRY INFO */.
MENU_ENTRY_RECORD STRUCTURE.
LINE STRUCTURE OCCURS 16 TIMES.
ENTRY_NUMBER DATATYPE TEXT 2.
ENTRY_KEY DATATYPE TEXT 10.
ENTRY_FLAG DATATYPE TEXT 1.
ENTRY_TEXT DATATYPE TEXT 50.
END LINE STRUCTURE.
END MENU_ENTRY_RECORD STRUCTURE.
END 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.
| Example B-4 Definition for Menu Control |
|---|
DEFINE RECORD MENU_CONTROL_RECORD
DESCRIPTION IS /* RECORD FOR THE DEFAULT ACMS MENU CONTROL INFO */.
MENU_CONTROL_RECORD STRUCTURE.
CTL_EXPERT_MENU DATATYPE TEXT 1.
CTL_NEW_ENTRIES DATATYPE TEXT 1.
CTL_MULTI_PAGE DATATYPE TEXT 1.
CTL_LAST_PAGE DATATYPE TEXT 1.
END MENU_CONTROL_RECORD STRUCTURE.
END MENU_CONTROL_RECORD.
|
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.
| Example B-5 Definition for Menu Selection Record |
|---|
DEFINE RECORD MENU_SELECTION_RECORD
DESCRIPTION IS /* RECORD FOR THE DEFAULT ACMS MENU SELECTION */.
MENU_SELECTION_RECORD STRUCTURE.
VARIANTS.
VARIANT.
SELECTION_STRING DATATYPE TEXT 255.
END VARIANT.
VARIANT.
SELECTION_STRING_1 DATATYPE TEXT 69.
! Must match size of selection_string_1 field in MENU_FORM
SELECTION_STRING_2 DATATYPE TEXT 186.
! Should calculate as 255 - <size of selection_string_1>
END VARIANT.
END VARIANTS.
END MENU_SELECTION_RECORD STRUCTURE.
END MENU_SELECTION_RECORD.
|
This record consists of a single field, into which the request moves the selection string. The variant for this field lets the request move the two lines of the selection input field separately.
The second part of the menu request contains instructions that TDMS
performs when ACMS calls the request. The next section explains these
instructions.
B.2.4 Instructions Performed by TDMS When ACMS Calls a 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 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.
| Previous | Next | Contents | Index |