Choosing Menu Maps
When designing an application, the developer must decide whether to use system-designed or user-defined menu maps. The system-defined menu provides a standard format for the information that is provided by the developer during the definition of the functions and responses of the application in an ADSA session. If a format other than the standard format is desired, the user-defined menu map is used. For example, use the user-defined menu map when the you want to redefine certain literal fields on the map or to supply site-specific headers.
idmscu19
When designing an application, the developer must decide whether to use system-designed or user-defined menu maps. The system-defined menu provides a standard format for the information that is provided by the developer during the definition of the functions and responses of the application in an ADSA session. If a format other than the standard format is desired, the user-defined menu map is used. For example, use the user-defined menu map when the you want to redefine certain literal fields on the map or to supply site-specific headers.
System-Defined Menu Maps
If the menu map is to be system-defined, the designer has the option of using one of the following menu formats:
- Short description menu map (ADSOMUR1)-- The menu screen that lists 30 valid menu responses per page; a short (12-byte) textual description is displayed for each response.
- Long description menu map (ADSOMUR2)-- The menu screen that lists 15 valid menu responses per page; a long (28-byte) textual description is displayed for each response name.
- Signon menu map (ADSOMSON)-- The menu screen that requires a DC/UCF validation of user ID and password before the menu request can be processed. The standard signon menu map can have 12 valid menu response names per page with 28 bytes of descriptive text displayed for each.
If none of the menu formats meet the needs of the user, the system-defined menu map can be altered by the user. Otherwise, a new menu (designated as a menu/dialog function) can be formatted. Information about both methods of creating user-defined maps follows.
User-Defined Menu Maps
Altering Map Methods
When user-specific modifications to the existing system-defined menu maps are necessary, designers can alter the menu maps by using either of the following techniques:
- Reformatting and regenerating the standard system-defined menu
- Designing a menu/dialog (that is, a menu map that is part of a menu/dialog function)
Each of these methods is discussed in the following sections.
Reformat the System-Defined Menu
The existing system-designed menu map can be reformatted and regenerated, retaining the same name. This method has the advantage of allowing the developer to use the standard menu function rather than designing and using a menu/dialog function.
To reformat the system menu
- Obtain the source for the map being used (that is, ASDSOMUR1, ADSOMUR2, or ADSOMSON) from the source data sets created when the distribution tape was installed. The maps are stored as members under their own names.
- Use the batch mapping compiler to store the source in the dictionary.
- Use the online mapping facility to modify and regenerate the menu map.
Regenerating the System-Defined Menu
When regenerating a menu map with the online mapping facility, the following rules must be observed:
- ADSO-APPLICATION-MENU-RECORD is a required map record. Optionally, the menu can map to more records, but it must always map to the .hw ADSO--APPLICATION--MENU--RECORD.
- The menu must contain the same number of responses per page as the number of responses for the selected map (that is, 30 for ADSOMUR1, 15 for ADSOMUR2, or 12 for ADSOMSON).
- The AMR-RESPONSE field of the .hw ADSO--APPLICATION--MENU--RECORD record is a required field. The first response name on the map must map to the first occurrence of AMR-RESPONSE. Each subsequent response name must map to the next corresponding occurrence.
- The AMR-USER-ID and AMR-PASSWORD fields of the .hw ADSO--APPLICATION--MENU--RECORD are required on a signon menu map. The user ID data field must map to AMR-USER-ID, and the password data field must map to AMR-PASSWORD.
- All other fields on the .hw ADSO--APPLICATION--MENU--RECORD are optional. The map data fields that are used must be associated with the appropriate fields on the record. For example, heading data must map to AMR-HEADING.
- If the AMR-KEY field is used, this field appears as a single byte (the AID byte) in the .hw ADSO--APPLICATION--MENU--RECORD. The AMR-KEY field is associated with a code table (ADSOAIDM) that translates the AID byte to more easily readable characters. For example, 1 translates to PF1 and percentage translates to PA1.
For more information about using the online mapping facility to regenerate a map, see Mapping Facility.
Design a Menu/Dialog
The user has the option of designing and generating an entirely new menu with the online mapping facility. This map must be defined as a menu/dialog function of the application.
To design a menu/dialog function
- Design and generate the map using the online mapping facility. Observe the following rules when generating the map:
- ADSO-APPLICATION-MENU-RECORD must be one of the records that is associated with the map.
- The AMR-RESPONSE field is required for all menus. The number of required occurrences depends on the number of responses per page (to a maximum of 50) specified on the ADSA Menu Specification screen. The first response name on the map must map to the first occurrence of AMR-RESPONSE. Each subsequent occurrence must map to the next corresponding occurrence of AMR-RESPONSE.
- The AMR-USER-ID and AMR-PASSWORD fields are required for signon maps. The user ID data field must map to AMR-USER-ID, and the password data field must map to AMR-PASSWORD.
- All other fields on the .hw ADSO--APPLICATION--MENU--RECORD are optional. The map data fields that are used must be associated with the appropriate fields on the record. For example, heading data must map to AMR-HEADING.
- Add the process source to the dictionary in an IDD session. The dialog that is associated with the menu does not have to include any process code, although the choice of a menu/dialog function suggests that some processing is intended.
- Compile the dialog in an ADSC session, associating the map and any processes with the dialog using the ADSC Dialog Definition screen. Note that the dialog must be compiled to include the map before the application can be executed at run time.
- Define the dialog as a menu/dialog function for the application.
An installation can develop standard map templates and the associated boilerplate code for site-specific menu/dialogs. When a menu is needed, programmers can obtain a copy of the template/boilerplate, fill in the appropriate fields and the edit/code tables that are needed for those fields, and submit it to the data administrator for approval.