Don't let the amount of code in this article discourage you. The bulk of the code needs to be keyed only once for inclusion in all future menus. In fact, any personalization you can add to the modules presented saves you time with each subsequent menu you create.
Brief: V2R2M0 has made available a new kind of menu: UIM. As this article reveals, UIM menus give so much additional functionality (and at such a low price) that there's very little reason for not using them. Take some time to read this article and try out the sample menu; it will be an eye-opener- guaranteed!
The August 1992 issue of MC contained an article of mine titled "Creating Program-style Menus." In it, I described how to design and code your own menus-not the easy SDA-generated menus, but the more difficult *PGM menus. Now that V2R2 is here, there's yet another way of creating menus that totally bypasses SDA and programs: using User Interface Manager (UIM) panel groups. This article shows you how easy this process can be.
UIM menus are far superior to any other kind. They give you automatic rolling, automatic support for command prompting (F4), automatic retrieval of previously entered commands (F9) and conditional availability of function keys and menu options; and the result adheres to the Common User Access (CUA) interface standards of SAA.
Panel Groups and UIM
A lot has changed since the UIM was first introduced in V2R1M0. Panel group objects (*PNLGRP) have existed for a long time, but it wasn't until V2R1M0 came along that programmers like us could create our own. The source code for panel groups is written in UIM, a special language that at first only allowed the creation of help panel groups for application programs and commands. For more information, see my article "Jazz Up Help With UIM" in the January 1992 issue of MC.
V2R2M0 extended UIM's horizons-now UIM can be used to create menus that have the look and feel of OS/400 menus (they even roll automatically and include the "More..." or "Bottom" indicators as appropriate). You can also use UIM to create panel groups that are used by interactive application programs, instead of using display files. That, however, is material for another article.
UIM Source for a Menu
UIM source sure doesn't look simple at first, but you'll get used to its strangeness the same way you got used to DDS, CL and RPG-by doing it over and over.
You begin by creating a source physical file (IBM's default source file is QMNUSRC) to contain the menu's source code. The members for menu source must have a type of MENU (not MNU, which is different).
UIM source is filled with UIM tags. Each tag makes up a statement, so you may want to think of these tags as UIM's equivalent of RPG op codes or the commands in a CL program. Tags always begin with a colon (:) and end with a period (.). In the vast majority of cases, the colon must be placed in column 1 of the source record-which prevents indenting the statements. Comments must have a period followed by an asterisk (.*) beginning in column 1 of the source record; the rest of the record can have anything you want. Blank statements can be used to make your source member more readable.
1 shows a stripped-down, simplified version of a typical UIM menu source member. All UIM source members must begin with a PNLGRP (panel group) tag and end with an EPNLGRP (end panel group) tag. Within it, UIM menu source must have three major areas, which I have blocked off in three boxes:
Figure 1 shows a stripped-down, simplified version of a typical UIM menu source member. All UIM source members must begin with a PNLGRP (panel group) tag and end with an EPNLGRP (end panel group) tag. Within it, UIM menu source must have three major areas, which I have blocked off in three boxes:
o Header. The header contains the copyright notice, a definition for a Z- variable containing the menu name (ZMENU), and the definition of function keys available on the menu. A Z-variable is a kind of reserved word in UIM, like UDATE and PAGE in RPG.
o Body of menu. The body is delimited by a PANEL and EPANEL tag pair. Within it, there's an embedded block delimited by a MENU and EMENU tag pair. The PANEL tag defines the panel to be presented to the user when he runs the GO command to access the menu. The MENU tag defines the menu area within the panel, which begins on line 3 with "Select one of the following" and includes a definition of all menu options. After the MENU/EMENU block ends, we define the command line (or lack thereof) before closing the panel definition with EPANEL.
o Help block. All UIM menus must have help defined for their function keys, for the menu itself, and for each menu option. The help text is delimited by a HELP and EHELP (end help) tag pair.
Importing Source
Fortunately, the UIM compiler allows for copying chunks of source code from other source members at the time of compilation, the way the RPG compiler allows copies with /COPY. In UIM, however, you use the .IM (import) compiler directive; unlike the RPG /COPY, it allows multiple levels of include directives, making it easier to design modular code. Notice that .IM is not a UIM tag-it doesn't start with a colon-but a compiler directive. You must not confuse it with the IMPORT UIM tag either, because IMPORT performs another function altogether.
Using this technique, I've built several import source modules that take the pain out of creating UIM menus. These eight import modules, individually illustrated in Figures 2-9, comprise some of the more repetitive, standardized components you'll encounter in constructing a menu. By using them, you won't have to produce the majority of the source each time you create a menu. After a preliminary outline of the modules, we'll examine each one more closely as we proceed to construct a menu.
Each module is actually a separate member in the source file you use for your UIM menus. I've selected an at sign (@) as the prefix, so that all the modules will sort together in PDM listings-I could have chosen any valid source member name. The source members are:
o @HEADER: It contains the PNLGRP UIM tag, the copyright notice, and a declaration for variable ZMENU, which is used later. See 2. You can follow this module with definitions for your own variables and conditions.
o @HEADER: It contains the PNLGRP UIM tag, the copyright notice, and a declaration for variable ZMENU, which is used later. See Figure 2. You can follow this module with definitions for your own variables and conditions.
o @STDKEYS: It contains the definition for the standard function keys, such as F3, F4, F12 and Page Up. See 3. You can follow this module with the definition for your own function keys. Then you must include an EKEYL (end key list) UIM tag.
o @STDKEYS: It contains the definition for the standard function keys, such as F3, F4, F12 and Page Up. See Figure 3. You can follow this module with the definition for your own function keys. Then you must include an EKEYL (end key list) UIM tag.
o @TITLE: It contains the beginning of the PANEL UIM tag, ready for you to type the title of the menu immediately underneath. See 4.
o @TITLE: It contains the beginning of the PANEL UIM tag, ready for you to type the title of the menu immediately underneath. See Figure 4.
o @OPTIONS: It contains the MENU and TOPINST UIM tags. See 5. You must follow the @OPTIONS import module with the MENUI (menu item) UIM tags, describing each menu option.
o @OPTIONS: It contains the MENU and TOPINST UIM tags. See Figure 5. You must follow the @OPTIONS import module with the MENUI (menu item) UIM tags, describing each menu option.
o @CMDLONG, @CMDSHORT and @NOCMD: These modules contain the EMENU tag, the definition of the command line (long, short, or none) and the EPANEL tag. See Figures 6, 7 and 8. You can use only one of these in a menu.
o @HELP: It defines the help modules for the function keys and a generic help module named MENU/NOHELP (which displays "Help information is not available at this time"), and starts the help module MENU/HELP, which is the help module for the entire menu (not for a particular option). See 9. You must finish this module yourself, close it with an EHELP tag, and continue designing the help modules for each menu option you want to support with help instructions. Then you must close the source member with an EPNLGRP tag.
o @HELP: It defines the help modules for the function keys and a generic help module named MENU/NOHELP (which displays "Help information is not available at this time"), and starts the help module MENU/HELP, which is the help module for the entire menu (not for a particular option). See Figure 9. You must finish this module yourself, close it with an EHELP tag, and continue designing the help modules for each menu option you want to support with help instructions. Then you must close the source member with an EPNLGRP tag.
Let's Build a Menu
To show you how easy it is to create a UIM menu, I'll design a UIM menu. 10 contains the entire source for menu XEM006MN. I'll briefly describe each part in turn. Don't be concerned if you don't understand something-I'll explain everything in full detail as we progress.
To show you how easy it is to create a UIM menu, I'll design a UIM menu. Figure 10 contains the entire source for menu XEM006MN. I'll briefly describe each part in turn. Don't be concerned if you don't understand something-I'll explain everything in full detail as we progress.
The first line after the compile instruction comments imports the @HEADER module. Then I define variable ZLMTCPB, which automatically contains *YES, *NO or *PARTIAL, depending on the current user profile's limited capability attribute. Two conditions are defined after that: F13F16OK and NOLMTCPB. Conditions are described in detail in "Z-Variables and Conditions," the sidebar accompanying this article.
Now we import @STDKEYS, which defines the standard function keys you expect to have available in a menu (F3, F4, F12 and Page Down, to name a few). Since we want this menu to allow for F13 and F16 as well, we add them after @STDKEYS, closing the key list definition with an EKEYL tag.
The @TITLE module is imported next, immediately followed by the title of the menu, which UIM will automatically center on line 1, in high intensity. Next, we import @OPTIONS and begin defining each menu option as we see fit. For the purposes of illustration, we'll define four options:
1. Display a user profile. This option activates the prompter for the Display User Profile (DSPUSRPRF) command.
2. Display a device description. It activates the prompter for the Display Device Description (DSPDEVD) command.
4. Display the job log. It runs the Display Job Log (DSPJOBLOG) command without prompting.
6. Go to the Command Entry panel, if the user doesn't have limited capabilities in his user profile.
Notice that there are no options 3 or 5. This is not a mistake. You'll see why we've skipped them when you compile and display the menu.
Now we import @CMDLONG to define a long command line (two physical lines long), then import @HELP to start the help definition block. Immediately after the @HELP import statement, I retype the menu title and key in the help text that will be displayed when the user presses the Help key at the command line, without having entered anything. The EHELP tag ends this help module.
Finally, we define three other help modules for F13 (SUPPORT), for F16 (MAINMENU) and for option 1 (MENU/ OPTION). Then EPNLGRP ends the entire panel group. Although we're defining help for one menu option only, in a "real-life" menu you'd want to define help for all options.
Compiling Our Menu
To compile the menu, execute the Create Menu (CRTMNU) command as shown at the top of 10. The TYPE parameter must have the value *UIM to specify that this is to be a UIM menu. The SRCFILE parameter must contain the qualified name of the source file; the xxx represents the name of the library you have selected-any library will do.
To compile the menu, execute the Create Menu (CRTMNU) command as shown at the top of Figure 10. The TYPE parameter must have the value *UIM to specify that this is to be a UIM menu. The SRCFILE parameter must contain the qualified name of the source file; the xxx represents the name of the library you have selected-any library will do.
The INCFILE names the source file that contains the modules we're importing ("including") with the .IM compiler directive. This parameter defaults to *SRCFILE, meaning that the compiler is to look for the modules in the source file specified in the SRCFILE parameter. If you keep your include modules elsewhere, you must override the default value.
Finally, the PRDLIB parameter says that, while the menu is displayed, library xxx will become the product library in the job's library list. This places library xxx between the system portion of the library list and the current library (if existent). It gives you the convenience of having library xxx automatically available to whatever programs or commands are executed by selecting option numbers-or run from the command line.
11 shows what the menu looks like. To display the menu, use the GO command.
Figure 11 shows what the menu looks like. To display the menu, use the GO command.
Details in Depth
In learning new techniques, it always helps when you fully understand the concepts behind the techniques. Learning by rote has never been my favorite approach; I always want to know why things are the way they are. If you are like me, keep reading. If not, you can stop reading-you already have enough material to start building UIM menus on your own.
Let's review, in detail, each statement of the UIM source. As I explain each line, it will help you to study the figures so you can follow the explanation more accurately.
Also keep in mind that, although I have broken up the source in "include modules," you do not have to. I've done it to make it easier to build UIM menus. If you don't feel comfortable with this approach, you can repeat the entire source in each menu source member.
The @HEADER Module
First, let's address the @HEADER module (2). The PNLGRP (panel group) tag is required. All UIM source members must have one at the very beginning. I have included a SCHIDX keyword, so that the default search index (QHSS1) is available to the user while displaying help. If you include a SCHIDX keyword, the user will be able to press F11 to access the search index specified. You can create your own search index and use it instead of QHSS1.
First, let's address the @HEADER module (Figure 2). The PNLGRP (panel group) tag is required. All UIM source members must have one at the very beginning. I have included a SCHIDX keyword, so that the default search index (QHSS1) is available to the user while displaying help. If you include a SCHIDX keyword, the user will be able to press F11 to access the search index specified. You can create your own search index and use it instead of QHSS1.
The COPYR (copyright) tag is optional. COPYR lets you code a copyright notice of your own, which appears in high intensity at the bottom of the menu when the menu is accessed with the GO command. Of course, you can use COPYR for other things besides copyright notices; for example, you may want to give the user a special warning such as "This menu is for Data Processing use only."
At the end of @HEADER is a VAR (variable declaration) tag to define a Z- variable named ZMENU. As mentioned earlier, Z-variables are reserved variable names (such as UDATE and PAGE in RPG) because they have special meanings. ZMENU, in particular, always contains the name of the menu-XEM006MN, in our case. This variable is used later to display the name of the menu in the upper- left corner of the screen, in blue.
Define Your Own Conditions
If you look at 10 now, you'll see that I have inserted a VAR tag and two COND tags below the .IM @HEADER line. These lines are optional. The VAR tag declares variable ZLMTCPB to the panel group. This variable is used in the second COND tag to determine if the user displaying this menu has limited capabilities. As the EXPR keyword states, we compare ZLMTCPB against "*NO". If they're equal, the condition is true-that's why it's named NOLMTCPB. I'll use this condition after the @OPTIONS module in the menu source to determine whether to allow the user to select option 6.
If you look at Figure 10 now, you'll see that I have inserted a VAR tag and two COND tags below the .IM @HEADER line. These lines are optional. The VAR tag declares variable ZLMTCPB to the panel group. This variable is used in the second COND tag to determine if the user displaying this menu has limited capabilities. As the EXPR keyword states, we compare ZLMTCPB against "*NO". If they're equal, the condition is true-that's why it's named NOLMTCPB. I'll use this condition after the @OPTIONS module in the menu source to determine whether to allow the user to select option 6.
Similarly, the first COND statement checks to see if the user has a security classification of *SYSOPR (system operator) or higher. This condition will be used to determine whether to allow the user to press F13 or F16. Again, you'll see that later.
By the same token, you can define your own additional variables and conditions in this space. Check the sidebar for more information about Z-variables and conditions you can code.
The @STDKEYS Module
The @STDKEYS module (3) describes the function keys that are to be available to the user while the menu is displayed. Not all function keys are described-only those that have become standard, such as Enter or F3 to exit. To start the function key definition, we need a KEYL (key list) tag. KEYL defines a set of function keys-and the set must have a name, which we specify with the NAME keyword. The HELP keyword points to the help module that will be displayed when the user presses the Help key to display help for the function keys.
The @STDKEYS module (Figure 3) describes the function keys that are to be available to the user while the menu is displayed. Not all function keys are described-only those that have become standard, such as Enter or F3 to exit. To start the function key definition, we need a KEYL (key list) tag. KEYL defines a set of function keys-and the set must have a name, which we specify with the NAME keyword. The HELP keyword points to the help module that will be displayed when the user presses the Help key to display help for the function keys.
Each KEYI (key item) tag describes one function key. All function keys have preset names, such as F1, F3 and HOME, which you must specify in the KEY keyword. Again, the HELP keyword specifies the help module the user can reach to find out more about a particular function key. The ACTION keyword tells UIM what to do when the function key is pressed.
If you look at the KEYI tag for the F1 key, you'll see ACTION=HELP. The word HELP has a preset meaning, directing UIM to display help. In essence, the F1 key will work like the HELP key-which complies with the CUA standards for SAA. A complete list of actions (referred to as "dialog commands") can be found in Appendix B of the IBM manual referenced at the end of this article.
Now look at the KEYI tag for the F3 key, it has VARUPD=NO. This keyword specifies whether dialog variables are to be updated when the user presses the function key. Since the only dialog variable is ZMENU and that's a reserved variable, VARUPD=NO seems redundant and ineffectual because ZMENU can't be updated. However, the UIM compiler issues a warning message if VARUPD=NO is omitted when the ACTION keyword contains CANCEL or EXIT, as in the case of the F3 or F12 key. By including VARUPD=NO, I eliminate the warning message.
Immediately after the period that ends the KEYI tag for the F3 key, there's text that reads "F3=Exit." This is what shows up at the bottom of the menu. If you replace this text with "Fred was here," the menu shows that instead. This text is not required. If you don't enter any text, the function key is undocumented but still works. F1, for example, is undocumented.
The KEYI tag for F4 shows ACTION=PROMPT (to activate the command prompter). F9 shows an action of RETRIEVE (which retrieves commands previously entered). These actions (PROMPT and RETRIEVE) are automatically supported by UIM menus- you don't have to code anything to make them work, except specify them as actions for function keys, as we've done. This alone makes UIM menus far superior to SDA-generated menus and program-style menus.
Any More Keys?
I have included in the @STDKEYS module all the standard function keys, but you can add your own (such as F6=WRKSPLF and F7=WRKSBMJOB).
The @STDKEYS module starts the key list with the KEYL tag, but it has no closing EKEYL tag. You must supply it in your menu source member yourself, below the .IM @STDKEYS line. This gives you a chance to insert definitions for more keys you may want to use in a particular menu. To add keys, insert the necessary KEYI tags between the .IM @STDKEYS line and the EKEYL tag. I'm doing this in my sample menu (10).
The @STDKEYS module starts the key list with the KEYL tag, but it has no closing EKEYL tag. You must supply it in your menu source member yourself, below the .IM @STDKEYS line. This gives you a chance to insert definitions for more keys you may want to use in a particular menu. To add keys, insert the necessary KEYI tags between the .IM @STDKEYS line and the EKEYL tag. I'm doing this in my sample menu (Figure 10).
The KEYI tag for the F13 key shows an action of MENU SUPPORT. This is an order to display OS/400's SUPPORT menu if the user presses F13. But notice the presence of COND=F13F16OK. As we saw earlier, this is the name of a condition we declared with the COND tag, to check that the user has a classification of *SYSOPR or higher. What happens here, then, is that the F13 key will be available only if the current user is *SYSOPR or higher. UIM checks the user class when the menu is activated. If the user is not *SYSOPR or higher, UIM won't display the caption "F13=User support" and will issue an error message if the user presses F13. The KEYI tag for F16 works the same way for the AS/400 Main menu.
The @TITLE Module
The @TITLE module (4) is included next. It contains only the PANEL tag, which begins the definition of the body of the menu. PANEL describes a complete screen panel, which can be divided into several areas. In the case of a menu, there's only one area defined with the MENU tag within the @OPTIONS module.
The @TITLE module (Figure 4) is included next. It contains only the PANEL tag, which begins the definition of the body of the menu. PANEL describes a complete screen panel, which can be divided into several areas. In the case of a menu, there's only one area defined with the MENU tag within the @OPTIONS module.
Notice the KEYL keyword, pointing to the key list (named MENUKEYS) we defined in the @STDKEYS module. In UIM, you must supply names for just about everything, and then refer to everything by name. The set of function keys we defined received the name MENUKEYS, so now we link this set to the PANEL tag. In non-menu panel groups, you can have more than one set of function keys and more than one panel definition.
The ENTER keyword indicates what to do if the user presses the Enter key without input. In our case, we're directing UIM to display message CPD9817 ("Type option number or command") from message file QCPFMSG. The PANELID keyword specifies what to display as the identifier for this panel (which always appears in blue at the top-left corner). Since we've specified ZMENU, the menu name appears there. Lastly, the TOPSEP=SYSNAM keyword specifies that the system name is to be used as a separator at the top of the panel-meaning that the system name will appear on the menu to the right on the line after the menu title.
There's one more item to the PANEL tag, not included in the @TITLE module. It's the actual title of the menu, which UIM automatically centers at the top of the screen, in high intensity. As you can see in 10, the title appears as text immediately after the .IM compiler directive. This effectively places the menu title (Sample Menu) immediately after the PANEL tag, completing its syntax and forcing "Sample Menu" as the title of the menu.
There's one more item to the PANEL tag, not included in the @TITLE module. It's the actual title of the menu, which UIM automatically centers at the top of the screen, in high intensity. As you can see in Figure 10, the title appears as text immediately after the .IM compiler directive. This effectively places the menu title (Sample Menu) immediately after the PANEL tag, completing its syntax and forcing "Sample Menu" as the title of the menu.
The @OPTIONS Module
Now go to 5. The MENU tag defines a menu area within the panel. It seems redundant but it's a requirement in UIM. The definition of the menu area continues until UIM finds an EMENU (end menu) tag. Between the two, you use MENUI (menu item) tags to define each option of the menu.
Now go to Figure 5. The MENU tag defines a menu area within the panel. It seems redundant but it's a requirement in UIM. The definition of the menu area continues until UIM finds an EMENU (end menu) tag. Between the two, you use MENUI (menu item) tags to define each option of the menu.
The DEPTH='*' keyword indicates that the menu area will have as many lines as are left after allocating space for the title, function keys, command line, message line, and so on. Alternatively, you can supply a specific number of lines, but this is hardly a benefit. SCROLL=YES is what makes this a rolling menu-meaning that the menu will accept the Roll (or Page) keys to display more options. That's all it takes to create a rolling menu using UIM!
The BOTSEP (bottom separator) keyword indicates what to use at the bottom of the menu area to separate it from the command line. I've chosen SPACE, which simply leaves a blank line. This avoids clutter and conforms with CUA. You could have chosen RULE (a solid line of underlined spaces) or NONE (no separator).
The TOPINST (top instructions) tag lets you key in a brief instruction message to be displayed on top of the menu options. I've decided to keep things CUA- compliant, so I specify the lame "Select one of the following:".
The Menu Options
Since each menu has different options, it doesn't make sense to place their definitions in an include member. This forces us to define the options in the menu source member itself (see 10). Each option must have its own MENUI tag.
Since each menu has different options, it doesn't make sense to place their definitions in an include member. This forces us to define the options in the menu source member itself (see Figure 10). Each option must have its own MENUI tag.
The OPTION keyword identifies the option by number. You can use numbers between 1 and 999. If you leave a gap between consecutive option numbers (such as in 10 which has no option 3), UIM leaves a blank line to evidence the gap.
The OPTION keyword identifies the option by number. You can use numbers between 1 and 999. If you leave a gap between consecutive option numbers (such as in Figure 10 which has no option 3), UIM leaves a blank line to evidence the gap.
The ACTION keyword tells UIM what to do when the user selects the option by number. In all four options shown in 10, the action is to execute a command (as indicated by the CMD word). The name of the command must follow. Options 1 and 2 have the command name prefixed by a question mark, indicating that the command should be prompted for. Options 4 and 6 don't have a question mark, so the command is executed directly. Other valid actions are EXIT and CANCEL (as if the user had pressed F3 or F12, respectively) and MENU, to go to another menu, as in 'MENU XYZ.'
The ACTION keyword tells UIM what to do when the user selects the option by number. In all four options shown in Figure 10, the action is to execute a command (as indicated by the CMD word). The name of the command must follow. Options 1 and 2 have the command name prefixed by a question mark, indicating that the command should be prompted for. Options 4 and 6 don't have a question mark, so the command is executed directly. Other valid actions are EXIT and CANCEL (as if the user had pressed F3 or F12, respectively) and MENU, to go to another menu, as in 'MENU XYZ.'
The HELP keyword identifies a help module to be displayed when the user presses the Help key after typing in an option number. This help module should describe the purpose of the option selected.
Pay special attention to the MENUI tag for option 6. It contains a COND keyword which conditions the availability of this option according to the condition named NOLMTCPB-which was defined much earlier. NOLMTCPB checks to see if the user displaying the menu doesn't have limited capabilities. If he doesn't, the condition is true-so option 6 becomes available. I'm conditioning option 6 because it displays the Command Entry panel, a dangerous place for a user with limited capabilities to be.
Command Line or Option Line?
One of the thorniest questions you must face is whether to give your menus a command line. It's impossible to give you a straight answer because too much depends on the specifics of your installation, the level of system security you need, and so forth. Only you can make this decision. UIM gives you the tools to provide a command line in your menus, or simply an option line (an input field long enough to enter an option number).
If you want to give your menu a command line, use the @CMDLONG or @CMDSHORT include module (depending on the desired length for the command line). Otherwise, you must use the @NOCMD module to include an option line. All menus must have either a command line or an option line.
The three modules (Figures 6, 7 and 8) are almost identical. They start with an EMENU tag, closing the menu area definition that was started with the MENU tag (found in the @OPTIONS module). Then follows a CMDLINE (command line) tag for the @CMDLONG and @CMDSHORT modules or an OPTLINE (option line) tag for the @NOCMD module. Finally, there's an EPANEL tag, to close the PANEL tag we opened in the @TITLE module.
The CMDLINE tag sports a SIZE keyword which specifies the length of the command line. LONG means two physical lines, while SHORT means only one.
The @NOCMD module causes UIM to place a very short field at the bottom of the screen, where the user types in the option number selected. This input field is just long enough to fit the highest-numbered option in the menu. For example, if the highest-numbered option is 12, the field accepts a maximum of two characters.
The @HELP Module
The @HELP module (9) contains several help modules for the basic components of a UIM menu: primarily function keys. At the end of @HELP, there is a module named MENU/NOHELP which you can use when you don't have the time or inclination to write help for each menu option. As 10 illustrates, I've done precisely that for options 2, 4 and 6. @HELP also contains the opening HELP tag for the help module that displays help text for the entire menu-which is displayed when the user presses the Help key without any input, with the cursor positioned at the command or option line.
The @HELP module (Figure 9) contains several help modules for the basic components of a UIM menu: primarily function keys. At the end of @HELP, there is a module named MENU/NOHELP which you can use when you don't have the time or inclination to write help for each menu option. As Figure 10 illustrates, I've done precisely that for options 2, 4 and 6. @HELP also contains the opening HELP tag for the help module that displays help text for the entire menu-which is displayed when the user presses the Help key without any input, with the cursor positioned at the command or option line.
Each help module contained in @HELP begins with a HELP tag and ends with an EHELP (end help) tag. Describing the meaning and purpose of each help module tag is beyond the scope of this article; you should refer to "Jazz Up Help With UIM" in the January 1992 issue of MC. This article contains a fair amount of information about building help modules. Of course, additional information can be found in the book listed as a reference at the end of this article.
Adding Help Modules and Finishing Up
@HELP ends by opening the MENU/HELP help module, as mentioned above. As you can see in 10, you need to type the text for this help module, close it with an EHELP tag, and continue with the help modules for each menu option. Remember that, in UIM, defining help for function keys and menu options is mandatory. If you don't want to define help for something, use the MENU/NOHELP help module.
@HELP ends by opening the MENU/HELP help module, as mentioned above. As you can see in Figure 10, you need to type the text for this help module, close it with an EHELP tag, and continue with the help modules for each menu option. Remember that, in UIM, defining help for function keys and menu options is mandatory. If you don't want to define help for something, use the MENU/NOHELP help module.
When all help modules are written in the menu source member, the only item left is to close the panel group with the EPNLGRP (end panel group) tag, as the last line in 10 illustrates.
When all help modules are written in the menu source member, the only item left is to close the panel group with the EPNLGRP (end panel group) tag, as the last line in Figure 10 illustrates.
A Simple Map for You
I have prepared a map for you, to simplify the process of creating UIM menus if you utilize the include modules provided in this article. It tells you what you must code in the menu source member, spelling out the main points and presenting the options available. The map is in 12 (see page 35).
I have prepared a map for you, to simplify the process of creating UIM menus if you utilize the include modules provided in this article. It tells you what you must code in the menu source member, spelling out the main points and presenting the options available. The map is in Figure 12 (see page 35).
I'll bet that you never thought creating rolling menus was so simple. When I started programming on the AS/400, SDA disappointed me because it wouldn't handle rolling menus. I then created my own menu system in PL/I, too complicated to even begin to describe. Program-style menus solve some of the problems, but not all. Only UIM takes care of everything, including:
o Automatic rolling
o Automatic support for F4=Prompt and F9=Retrieve
o Conditioning function keys and options
o Adherence to CUA standards
What more can you ask for? UIM menus are hot and I, for one, will no longer use any other kind.
Ernie Malaga is a senior technical editor at Midrange Computing.
Reference Guide to Programming Application and Help Displays (SC41-0011-01, CD-ROM QBKA7901).
SIDEBAR:
Z-Variables and Conditions
Z-Variables
Z-variables are reserved variables, predefined to UIM the way UDATE and PAGE are predefined to RPG. All Z-variables have names beginning with the letter Z. Of all available Z-variables, only a few can be effectively used in UIM menus:
ZDBCS-Contains either '1' or '0.' It's '1' if the job is currently in double- byte character set (DBCS) mode. It's '0' otherwise.
ZJOB-Contains the 10-character name of the display station.
ZJOBNBR-Contains the 6-character number of the current job.
ZLMTCPB-Contains '*NO,' '*YES' or '*PARTIAL,' depending on the current user's limited capabilities attribute. This attribute is part of the user profile and can be changed with the Change User Profile (CHGUSRPRF) command.
ZMENU-Contains the 10-character name of the menu.
ZMNULIB-Contains the 10-character name of the library in which the menu resides.
ZSYSNAM-Contains the 8-character name of the system.
ZUSER-Contains the 10-character name of the current user.
ZS36ENV-Contains either '1' or '0.' It's '1' if the job is running in the S/36 Environment. It's '0' otherwise.
Conditions
Conditions are defined at the beginning of the panel group with the COND UIM tag. All conditions must have a name. Conditions can then be used to condition the availability of function keys or menu options by simply adding the COND keyword to the KEYI or MENUI tags, respectively, referencing the condition by its name.
To define a condition, use the COND tag with at least a NAME keyword (to give it a name) and an EXPR keyword (which holds a logical expression, defining the condition itself).
The EXPR keyword can contain more than one logical expression, joined with *ANDs and *ORs, or reversed with *NOTs-just like in CL. Each logical expression can be either:
o A comparison between two values (two variables or a variable and a literal).
o A CHKOBJ function to check the existence of an object and/or the necessary authority the user has to that object-similar to the Check Object (CHKOBJ) command in CL programs.
o A CHKUSRCLS function to check if the current user has a specific user class or higher user class.
Examples of conditions:
:cond name=fileok
expr='CHKOBJ("MYLIB/CUSTOMER", "*FILE")'.
This condition checks for existence of file CUSTOMER in MYLIB. If it exists,
the condition is true.
:cond name=fileok
expr='CHKOBJ("MYLIB/CUSTOMER", '*FILE',
"*CHANGE")'.
Same as before, except that the user must have *CHANGE authority to the file. If the file doesn't exist or the user doesn't have *CHANGE authority to it, the condition is false.
:cond name=nolib
expr='*NOT(CHKOBJ("MYLIB", "*LIB"))'.
This condition checks that library MYLIB doesn't exist.
:cond name=dspok
expr='ZJOB = "DSP01" *OR ZJOB = "DSP02"'.
This condition is satisfied if the menu is displayed at display station DSP01
or DSP02.
:cond name=security
expr='CHKUSRCLS("*SECADM")'.
Finally, this condition is true if the user displaying the menu has a classification of *SECADM or *SECOFR.
Create IBM-Style Rolling Menus with UIM
Figure 1 Skeleton Source for UIM Menu
:pnlgrp ...
:copyr.1993 ABC Consulting, Inc.
:var name=zmenu.
:keyl name=menukeys
help=keyl.
:keyi key=F3
help=exit
action='exit set'
varupd=no.
F3=Exit
:keyi ...
:keyi ...
:ekeyl.
:panel name=...
Menu Title
:menu ...
:topinst.Select one of the following:
:menui option=1
action='cmd dsplib qtemp'
help='menu/option1'.
Display QTEMP library
:menui ...
:menui ...
:emenu.
:cmdline size=long.
Selection or command
:epanel.
:help ...
:ehelp.
:help ...
:ehelp.
:epnlgrp.
Create IBM-Style Rolling Menus with UIM
Figure 2 @HEADER Import Module
:pnlgrp schidx=qhss1.
.*
:copyr.
(c) Copyright 2001 ABC Consulting, Inc. All rights reserved.
.*
:var name=zmenu.
Create IBM-Style Rolling Menus with UIM
Figure 3 @STDKEYS Import Module
:keyl name=menukeys
help=keyl.
:keyi key=F1
help=helpf1
action=help.
:keyi key=F3
help=exit
action='exit set'
varupd=no.
F3=Exit
:keyi key=F4
help=prompt
action=prompt.
F4=Prompt
:keyi key=F9
help=retrieve
action=retrieve.
F9=Retrieve
:keyi key=F12
help=cancel
action='cancel set'
varupd=no.
F12=Cancel
:keyi key=enter
help=enter
action=enter.
:keyi key=help
help=help
action=help.
:keyi key=home
help=home
action=home.
:keyi key=pagedown
help=pagedown
action=pagedown.
:keyi key=pageup
help=pageup
action=pageup.
:keyi key=print
help=print
action=print.
Create IBM-Style Rolling Menus with UIM
Figure 4 @TITLE Import Module
:panel name=mnupnl
help='menu/help'
keyl=menukeys
enter='msg cpd9817 qcpfmsg'
panelid=zmenu
topsep=sysnam.
Create IBM-Style Rolling Menus with UIM
Figure 5 @OPTIONS Import Module
:menu depth='*'
scroll=yes
botsep=space.
:topinst.Select one of the following:
Create IBM-Style Rolling Menus with UIM
Figure 6 @CMDLONG Import Module
:emenu.
.*
:cmdline size=long.
Selection or command
.*
:epanel.
Create IBM-Style Rolling Menus with UIM
Figure 7 @CMDSHORT Import Module
:emenu.
.*
:cmdline size=short.
Selection or command
.*
:epanel.
Create IBM-Style Rolling Menus with UIM
Figure 8 @NOCMD Import Module
:emenu.
.*
:optline.
Selection
.*
:epanel.
Create IBM-Style Rolling Menus with UIM
Figure 9 @HELP Import Module
:help name=keyl.
Function Keys - Help
:xh3.Function keys
:ehelp.
.*
:help name=helpf1.
:parml.
:pt.F1=Help
:pd.
Provides additional information about using the display or a
specific field on the display.
:eparml.
:ehelp.
.*
:help name=exit.
:parml.
:pt.F3=Exit
:pd.
Ends the current task and returns to the display from which the
task was started.
:eparml.
:ehelp.
.*
:help name=prompt.
:parml.
:pt.F4=Prompt
:pd.
Provides assistance in entering or selecting a command.
:eparml.
:ehelp.
.*
:help name=retrieve.
:parml.
:pt.F9=Retrieve
:pd.
Displays the last command you entered on the command line and
any parameters you included. Pressing this key once, shows the
last command you ran. Pressing this key twice, shows the
command you ran before that and so on.
:eparml.
:ehelp.
.*
:help name=cancel.
:parml.
:pt.F12=Cancel
:pd.
Returns to the previous menu or display.
:eparml.
:ehelp.
.*
:help name=enter.
:parml.
:pt.Enter
:pd.
Submits information on the display for processing.
:eparml.
:ehelp.
.*
:help name=help.
:parml.
:pt.Help
:pd.
Provides additional information about using the display.
:eparml.
:ehelp.
.*
:help name=home.
:parml.
:pt.Home
:pd.
Goes to the menu that was shown after you signed on the system.
This menu is either the initial menu defined in your user
profile or the menu you requested from the Sign-On display.
:eparml.
:ehelp.
.*
:help name=pagedown.
:parml.
:pt.Page Down (Roll Up)
:pd.
Moves forward to show additional information for this display.
:eparml.
:ehelp.
.*
:help name=pageup.
:parml.
:pt.Page Up (Roll Down)
:pd.
Moves backward to show additional information for this display.
:eparml.
:ehelp.
.*
:help name=print.
:parml.
:pt.Print
:pd.
Prints information currently shown on the display.
:eparml.
:ehelp.
.*
:help name='menu/nohelp'.
No Help Available
:p.
Help information is not available at this time.
:ehelp.
.*
:help name='menu/help'.
Create IBM-Style Rolling Menus with UIM
Figure 10 Source for Menu XEM006MN
.im @header
.*
:var name=zlmtcpb.
.*
:cond name=F13F16ok
expr='CHKUSRCLS("*SYSOPR")'.
:cond name=nolmtcpb
expr='zlmtcpb = "*NO"'.
.*
.im @stdkeys
:keyi key=F13
cond=F13F16ok
help=support
action='menu support'.
F13=User support
:keyi key=F16
cond=F13F16ok
help=mainmenu
action='menu qsys/main'.
F16=AS/400 Main menu
:ekeyl.
.*
.im @title
Sample Menu
.*
.im @options
:menui option=1
action='cmd ?dspusrprf'
help='menu/option1'.
Display a user profile
.*
:menui option=2
action='cmd ?dspdevd'
help='menu/nohelp'.
Display a device description
.*
:menui option=4
action='cmd dspjoblog'
help='menu/nohelp'.
Display the job log
.*
:menui option=6
cond=nolmtcpb
action='cmd call qcmd'
help='menu/nohelp'.
Go to command entry panel
.*
.im @cmdlong
.*
.im @help
Sample Menu
:p.
Help information for entire menu goes here.
:ehelp.
.*
:help name=support.
:parml.
:pt.F13=User support
:pd.
Shows a menu with several types of assistance available. Select
this option to access online education, Q & A database, search
index, and additional help topics.
:eparml.
:ehelp.
.*
:help name=mainmenu.
:parml.
:pt.F16=AS/400 Main menu
:pd.
Takes you to the system main menu.
:eparml.
:ehelp.
.*
:help name='menu/option1'.
Option 1 - Help
:xh3.Option 1. Display a user profile
:p.
Select this option to display full information about a user
profile. You must be authorized to display user profiles to
select this option.
:ehelp.
.*
:epnlgrp.
Create IBM-Style Rolling Menus with UIM
Figure 11 Menu XEM006MN
XEM006MN Sample Menu
System: MC PGMR
Select one of the following:
1. Display a user profile
2. Display a device description
4. Display the job log
6. Go to command entry panel
Bottom
Selection or command
===> ____________________________________________________________
____________________________________________________________
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F13=User support
F16=AS/400 Main menu
(c) Copyright 2001 ABC Consulting, Inc.
Create IBM-Style Rolling Menus with UIM
Figure 12 Road Map to Create UIM Menu Source
Begin
|
Start SEU, making sure that the
source member type is MENU.
|
.IM @HEADER Add VAR and COND
as needed
|
.IM @STDKEYS Add KEY1
as needed
|
.IM @ TITLE
(Title of Menu goes here)
|
.IM @ OPTIONS Describe each
option with MENUI.
|
.IM @ CMDLONG .IM @ CMDSHORT .IM @ NOCMD
|
.IM @ HELP
Continue menu-level
help module EHELP
|
Help modules for
each option
|
END
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online