Brief: V2R3 delivers some great news for those responsible for programming help text. Instead of defining help areas by specific screen coordinates, you can now define a help area by referencing a field name or constant. With this new method, changes to a display record no longer require redefinition of the help area.
Help text is nothing more than information (usually presented through a window) about a user's display. To be effective, the help text should be relevant to the area of the display on which a user is working. For example, a user looking at the OS/400 Work with Spooled Files screen might not be sure how to interpret the information he sees. He can position the cursor to the item he doesn't understand and press the Help key. Instantly, a window pops up with information describing that item. We refer to the ability to present help information related to a specific item or area as context-sensitive or contextual help.
Contextual help support is one of the most important capabilities you can add to your application to improve user productivity and assistance. It can dramatically decrease the amount of time and effort required for a user to obtain information about your application.
But, prior to V2R3, creating this type of help support was a tedious process. You had to define a rectangular area of the screen by using screen coordinates (the upper-left row and column and the lower-right row and column). Subsequent changes to the display file could easily cause the coordinates of the help area to change. If you weren't careful, your contextual help quickly became out of context help, leaving the user confused.
With V2R3, IBM adds the ability to define a help area by referencing a field or constant. The area occupied by the field or constant becomes the help area.
This significant change in definition eliminates (for the most part) the need to determine and maintain screen coordinates. Not only does this simplify the implementation of contextual help; but more importantly, it allows the help area to follow the field or constant wherever it may go. Subsequent changes to the location or size of the field or constant won't affect the associated help area.
This article describes how to implement help support using the new DDS technique. It takes you through a sample programming session using IBM's Screen Design Aid (SDA), which I consider the tool of choice for working with display files. But, if you choose, you can use SEU to create the DDS specifications directly. (The article includes the DDS source member for the display file.)
You'll find that adding help support to your display files couldn't be much easier.
Help Text
Before you can add help text support to your own display files, the help text must already exist. Although it's not the main purpose of this article, I'll briefly describe how to create help text. You can use any one of three methods to create help text: DDS display records, OfficeVision documents and User Interface Manager (UIM) panel groups.
Each method has advantages and disadvantages. (For more information on choosing between the methods, see IBM's Guide to Programming Application and Help Displays.) I use UIM panel groups in this article because they offer so many features the other two methods don't. For example, they:
o Provide access to InfoSeeker. o Provide Hypertext links. o Allow you to create help for user-written commands. o Display help text in windows. o Allow printing of help information. o Support double-byte character set (DBCS) online help information.
Panel groups offer flexibility and power. At the same time, they are relatively simple to create and maintain; and, since UIM ships with OS/400, there is no additional cost.
Panel Groups and Help Text
Panel groups are AS/400 objects (type *PNLGRP) that contain information to be displayed when help is activated (usually by pressing F1). You create a panel group object from a panel group source member, much like you create a *FILE object from a DDS source member. The panel group source member is made up of modules, each representing information to be displayed. A module is to a panel group as a record is to a display file.
Panel group source is described through the tag-based UIM language. Every statement starts with a tag to identify its purpose. For example, the :HELP NAME tag assigns a name to a module to be used as help text. UIM is, for the most part, a free-format language you can create with almost any editor since no prompt formats are required. This means the help text doesn't have to be created on the AS/400 with SEU; any user with a PC could potentially create it.
The general format of a panel group source member is illustrated in 1. The three highlighted blocks of code represent the three help text modules. Each help module begins with a :HELP NAME tag and ends with an :EHELP tag.
The general format of a panel group source member is illustrated in Figure 1. The three highlighted blocks of code represent the three help text modules. Each help module begins with a :HELP NAME tag and ends with an :EHELP tag.
The first module, extended help text, is a special module used to present general information about an associated screen (OS/400 refers to this as extended help). Any time a user presses the help key without the cursor positioned in a specific help area, extended help information is displayed.
The remaining modules present help text for specific portions of a display record. These modules present context-sensitive help information. In other words, if a user presses the Help key while working in a particular area of a screen, the system displays information related to the item on which he is currently working. For example, the credit limit module in 1 (:HELP NAME=CRDLMTHLP) can be displayed if the user presses the Help key when his cursor is in the credit limit field as illustrated in 2.
The remaining modules present help text for specific portions of a display record. These modules present context-sensitive help information. In other words, if a user presses the Help key while working in a particular area of a screen, the system displays information related to the item on which he is currently working. For example, the credit limit module in Figure 1 (:HELP NAME=CRDLMTHLP) can be displayed if the user presses the Help key when his cursor is in the credit limit field as illustrated in Figure 2.
When you use panel groups to define help text, you automatically give users access to extended help from within any contextual help module. For example, if the system displays contextual help for a user, he could select the extended help function (F2) to display general help text. When extended help is requested, all other help modules found in the panel group are also displayed, allowing the user to scroll through general and specific information at the same time.
Adding Application Help with SDA
So now you've got a brief lesson on help-text definition under your belt. Before you continue, you should key the source code in 1 and create the panel group with the instructions given at the beginning of the source member. (Panel group source members are normally stored in a source file called QPNLSRC.) You should also create the display file (XRS002DF) illustrated in 3. Just key the nonhighlighted sections of code. (The highlighted sections represent the help support specifications you'll add momentarily.)
So now you've got a brief lesson on help-text definition under your belt. Before you continue, you should key the source code in Figure 1 and create the panel group with the instructions given at the beginning of the source member. (Panel group source members are normally stored in a source file called QPNLSRC.) You should also create the display file (XRS002DF) illustrated in Figure 3. Just key the nonhighlighted sections of code. (The highlighted sections represent the help support specifications you'll add momentarily.)
Assuming you have created the panel group and the display file, you can proceed to add the help support with SDA using three basic steps.
1. Activate help support and define general help for the display file. 2. Assign help identification to the constants. 3. Link the help areas (field names and constants) to the help text modules.
Using SDA to assign help support requires the same three steps no matter where your help text is stored (DDS, OfficeVision documents or panel groups).
Activating Help
After you have created the display file, go to the Work with Display Records panel of SDA and activate the file-level keywords function (F14). You'll be presented with the Select File Keywords panel. Place a Y in the Indicator keywords, Help keywords and Alternate keywords options and press Enter. The Define Indicator Keyword panel appears.
Key the HELP keyword in the first blank entry in the Keyword column and press Enter. The Select Help Keywords panel appears. By default, SDA assumes you'll be working with DDS display records or OfficeVision documents. Since the technique presented here uses a panel group instead, you'll need to press F9 to select the HLPPNLGRP keyword. An alternate Select Help Keywords screen appears, as illustrated in 4. Fill out the display as shown in the figure. The meaning of each value used here is as follows:
Key the HELP keyword in the first blank entry in the Keyword column and press Enter. The Select Help Keywords panel appears. By default, SDA assumes you'll be working with DDS display records or OfficeVision documents. Since the technique presented here uses a panel group instead, you'll need to press F9 to select the HLPPNLGRP keyword. An alternate Select Help Keywords screen appears, as illustrated in Figure 4. Fill out the display as shown in the figure. The meaning of each value used here is as follows:
o The Y next to the HLPPNLGRP keyword indicates that the help text is contained in a panel group.
o The help module name is the name of the panel group module that contains the extended help text for the display file. Here you use the name CRLRCDEH (credit limit record extended help). This is the first module defined in 1.
o The help module name is the name of the panel group module that contains the extended help text for the display file. Here you use the name CRLRCDEH (credit limit record extended help). This is the first module defined in Figure 1.
o The panel group name is XRS002PG.
o The help title is a default title, displayed if there is no help title in the panel group or if the panel group doesn't exist. Since a help title would normally exist in the panel group, this default title wouldn't be displayed in most cases, but it is required.
After you complete the Select Help Keywords panel, press Enter and the Define Alternate Keywords panel appears. Here you indicate the use of an alternate Help key by placing a Y next to the ALTHELP keyword. The associated input field for ALTHELP enables you to specify which key to use as an alternate. If you leave the field blank, the F1 key (CA01) is assigned as the alternate. Since you want the F1 key to be the alternate, leave the key assignment field blank.
The keywords generated by the previous steps are shown in 3 as the first group of highlighted statements labeled A. As you can see, four keywords have been created: HLPTITLE, HLPPNLGRP, ALTHELP and HELP.
The keywords generated by the previous steps are shown in Figure 3 as the first group of highlighted statements labeled A. As you can see, four keywords have been created: HLPTITLE, HLPPNLGRP, ALTHELP and HELP.
Assigning Help Identification
As mentioned earlier, the significance of the V2R3 DDS help enhancements is the fact that you can define help areas by field names and constants. Defining help areas by fields only requires that you link the field name by reference to a help text panel (document or record). This process will be described in the next section.
Defining help area for constants isn't quite as easy since you don't have anything like a field name to reference. You need to assign a help identifier to the constant with the new HLPID keyword. This keyword simply assigns a number (in a range from 1-999) to a constant. Then you can link the help identifier to the help text. Let's take a look at as-signing help identifiers to constants with SDA.
From the SDA Work with Display Records panel, select the Design image option (12) for our display record, CRLRCD. On the editing work screen, place an asterisk (*) preceding the "Customer name . . . ." constant to add field-level keywords. Press Enter to obtain the Select Field Keywords panel. Place a Y in the "General keywords" prompt and press Enter. The Select General Keywords panel appears. Assign a number (in this case, 1) to the HLPID keyword as shown in 5, and press Enter twice to return to the edit work screen.
From the SDA Work with Display Records panel, select the Design image option (12) for our display record, CRLRCD. On the editing work screen, place an asterisk (*) preceding the "Customer name . . . ." constant to add field-level keywords. Press Enter to obtain the Select Field Keywords panel. Place a Y in the "General keywords" prompt and press Enter. The Select General Keywords panel appears. Assign a number (in this case, 1) to the HLPID keyword as shown in Figure 5, and press Enter twice to return to the edit work screen.
Now repeat the above procedure for the "Credit limit . . . ." constant-only this time, use number 2 as the HLPID. That's it for assigning help identifiers to constants. The highlighted specifications labeled C and D in 3 illustrate the HLPID keywords generated by SDA. The constants for which you want help text support are now ready to be linked to the panel group modules. The linking process is the same for fields and constants.
Now repeat the above procedure for the "Credit limit . . . ." constant-only this time, use number 2 as the HLPID. That's it for assigning help identifiers to constants. The highlighted specifications labeled C and D in Figure 3 illustrate the HLPID keywords generated by SDA. The constants for which you want help text support are now ready to be linked to the panel group modules. The linking process is the same for fields and constants.
Linking Help Text
With SDA, you'll define four cursor-sensitive help areas that will present the appropriate help text if the user presses the Help key. You'll use the same help text for the constants that precede the NAME and CRDLMT fields in the sample display file. The four areas to define are:
1. The customer NAME field. 2. The customer name constant to the left of the NAME field. 3. The CRDLMT field. 4. The credit limit constant to the left of the CRDLMT field.
Go to the SDA Work with Display Records panel and use the Select keywords option (8) for the CRLRCD record. You'll be presented with the Select Record Keywords panel. Place a Y in the "Application help" prompt and press Enter. When the Define Application Help panel appears, enter the values as illustrated in 6. The meaning of each value is as follows:
Go to the SDA Work with Display Records panel and use the Select keywords option (8) for the CRLRCD record. You'll be presented with the Select Record Keywords panel. Place a Y in the "Application help" prompt and press Enter. When the Define Application Help panel appears, enter the values as illustrated in Figure 6. The meaning of each value is as follows:
o The Y next to the HLPPNLGRP keyword indicates that the help text is contained in a panel group.
o The help module name is the name of the panel group module that contains the help text for the help area you are about to define. Here you use the help module name called NAMEHLP (the second module defined in 1).
o The help module name is the name of the panel group module that contains the help text for the help area you are about to define. Here you use the help module name called NAMEHLP (the second module defined in Figure 1).
o The panel group name is XRS002PG.
o The Y in HLPARA tells SDA that you want to define a help area.
Now press Enter to get to the Define Help Area panel. All you need to do here is place a field name of NAME in the field prompt under "Help for field," as illustrated in 7.
Now press Enter to get to the Define Help Area panel. All you need to do here is place a field name of NAME in the field prompt under "Help for field," as illustrated in Figure 7.
When you press Enter this time, you return to the Define Application Help panel. Here you define the next help area, the customer name constant to the left of the customer NAME field. To define this help area, key a 2 in the "Next help number" prompt at the top of the screen. The next help number is merely a sequential number assigned for each help specification that you define.
Once you complete the "Next help number" prompt, a new, blank Define Application Help panel appears. Fill out the screen as shown in 8. The values you supply here are exactly the same as in 6, except this time you need to place a Y next to the Help Text Excluded (HLPEXCLD) keyword. You need the HLPEXCLD keyword because you're using the same help module for the NAME field and the customer name constant. Extended help displays all help modules referenced in the display file. Therefore, when you reference the same help module more than once in the same display file (which happens in the example here), extended help will display the same information twice unless you specify HLPEXCLD. So, on subsequent references to the same help module, you should use the HLPEXCLD keyword.
Once you complete the "Next help number" prompt, a new, blank Define Application Help panel appears. Fill out the screen as shown in Figure 8. The values you supply here are exactly the same as in Figure 6, except this time you need to place a Y next to the Help Text Excluded (HLPEXCLD) keyword. You need the HLPEXCLD keyword because you're using the same help module for the NAME field and the customer name constant. Extended help displays all help modules referenced in the display file. Therefore, when you reference the same help module more than once in the same display file (which happens in the example here), extended help will display the same information twice unless you specify HLPEXCLD. So, on subsequent references to the same help module, you should use the HLPEXCLD keyword.
Now, press Enter to get the Define Help Area panel. Place a 1 in the "Identifier" prompt under Help for constant at the bottom of the screen. You may remember that 1 is the HLPID assigned to the customer name constant earlier.
Repeat the above procedure for the remaining two help areas, to assign help text to the CRDLMT field and the credit limit constant. Increment the next help number by one for each assignment. Reference help module name CRDLMTHLP for the CRDLMT field and help identifier 2 for the credit limit constant.
The result of the work you've done on this section is the help specifications in your display record that link help modules to fields and constants. These specifications are highlighted in 3 and labeled as B.
The result of the work you've done on this section is the help specifications in your display record that link help modules to fields and constants. These specifications are highlighted in Figure 3 and labeled as B.
Just Do It!
You should have learned three things in this article. With the new ability to define help areas by field name and constant references, contextual help support is easy to implement and maintain; using SDA is a simple way to add the support; and help text is easy to create with UIM. Delivering an application with help support enhances your user's ability to work with your applications. So, just do it!
Richard Shaler is a senior technical editor at Midrange Computing.
References DDS Reference (SC41-9620, CD-ROM QBKA7402). Guide to Programming Application and Help Displays (SC41-0011, CD-ROM QBKA7902). SDA User's Guide and Reference (SC09-1340, CD-ROM QBKA0802).
Simplify Contextual Help Development
Figure 1 UIM Panel Group Help Text
.*=============================================================== .* To create: .* .* CRTPNLGRP PNLGRP(XXX/XRS002PG) SRCFILE(XXX/QPNLSRC) .* .*=============================================================== :PNLGRP. .*=============================================================== .* Extended help text .*=============================================================== :HELP NAME='CRLRCDEH'. Customer Credit Limit Entry - Help :P. Use this panel for entering new the credit limit for a customer. :EHELP. .*=============================================================== .* Help text for customer name .*=============================================================== :HELP NAME='NAMEHLP'. Customer Name - Help :XH3.Customer name :P. Customer name corresponding to the requested customer number :EHELP. .*=============================================================== .* Help text for credit limit .*=============================================================== :HELP NAME='CRDLMTHLP'. Customer Credit Limit - Help :XH3.Customer Credit Limit :P. Enter the credit limit for this customer :EHELP. .*=============================================================== :EPNLGRP. .*===============================================================
Simplify Contextual Help Development
Figure 2 Customer Credit Limit Entry Record (CRLRCD)
Customer Credit Limit Entry Enter customer credit limit, press Enter. Customer name . . . . ABC Company Credit limit . . . . .00 ................................................................ : Customer Credit Limit - Help : : : : Enter the credit limit for this customer : : Bottom : : F2=Extended help F3=Exit help F10=Move to top : : F12=Cancel F13=Information Assistant F14=Print help : : : :..............................................................: F3=Exit F12=Cancel
Simplify Contextual Help Development
Figure 3 Final DDS for Sample Display File
A*=============================================================== A* To create: A* A* CRTDSPF FILE(XXX/XRS002DF) SRCFILE(XXX/QDDSSRC) A* A*=============================================================== A*. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 A DSPSIZ(24 80 *DS3) A HLPTITLE('Customer Credit - A Limit Entry - Help') A HLPPNLGRP(CRLRCDEH XRS002PG) A ALTHELP A HELP A CA03(03) A CA12(03) A R CRLRCD A H HLPPNLGRP(NAMEHLP XRS002PG) A HLPARA(*FLD NAME) A H HLPPNLGRP(NAMEHLP XRS002PG) A HLPEXCLD A HLPARA(*CNST 001) A H HLPPNLGRP(CRDLMTHLP XRS002PG) A HLPARA(*FLD CRDLMT) A H HLPPNLGRP(CRDLMTHLP XRS002PG) A HLPEXCLD A HLPARA(*CNST 002) A 1 27'Customer Credit Limit Entry' A DSPATR(HI) A 3 2'Enter customer credit limit, - A press Enter.' A COLOR(BLU) A 5 4'Customer name . . . .' A HLPID(001) A NAME 35A O 5 27 A 7 4'Credit limit . . . .' A HLPID(002) A CRDLMT 9Y 2B 7 27EDTCDE(1) A 23 2'F3=Exit' A COLOR(BLU) A 23 13'F12=Cancel' A COLOR(BLU) A*. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7
Simplify Contextual Help Development
Figure 4 Defining Help for the Display File
Select Help Keywords Member . . . : DDS001DF Type choices, press Enter. Keyword Help text in UIM panel group HLPPNLGRP Y Y=Yes Indicators . . . . . . . . ___ ___ ___ Help module name . . . . . CRLRCDEH Name Panel group name . . . . . XRS002PG Name Library . . . . . . . . __________ Name, *LIBL, *CURLIB Enable search index . . . . HLPSCHIDX _ Y=Yes Search index object . . . __________ Name Library . . . . . . . . __________ Name, *LIBL, *CURLIB Full screen help text . . . HLPFULL _ Y=Yes Help title . . . . . . . . . HLPTITLE Y Y=Yes Customer Credit Limit Entry - Help F3=Exit F9=Select HLPRCD or HLPDOC keyword F12=Cancel
Simplify Contextual Help Development
Figure 5 Assignment of Help Identification to a Constant
Select General Keywords Constant . . . : Customer name . . . . Length . . . . : 21 Row . . . : 5 Column . . . : 4 Type parameters and choices, press Enter. Keyword Text or Value More ALIAS ______________________________ INDTXT __ __________________________________________________ _ DFT __________________________________________________ HLPID 1 Keyword Y=Yes Indicators/+
Simplify Contextual Help Development
Figure 6 Defining Application Help
Define Application Help Record . . . : CRLRCD Help number . . . . . . . . : 1 of 1 Next help number . . . . . . Number Type choices, press Enter. Keyword Help text in UIM panel group HLPPNLGRP Y Y=Yes Indicators . . . . . . . . ___ ___ ___ Help module name . . . . . NAMEHLP Panel group . . . . . . . XRS002PG Name Library . . . . . . . . __________ Name, *LIBL, *CURLIB Help text excluded . . . . . HLPEXCLD _ Y=Yes Indicators . . . . . . . . ___ ___ ___ Help boundary . . . . . . . HLPBDY _ Y=Yes Indicators . . . . . . . . ___ ___ ___ Change help area . . . . . . HLPARA Y Y=Yes F3=Exit F9=Select HLPRCD or HLPDOC keyword More... F12=Cancel
Simplify Contextual Help Development
Figure 7 Defining the Help Area
Define Help Area Record . . . . . . . : CRLRCD Keyword . . . . . . . : HLPARA Help number . . . . . : 1 of 1 Type choices, press Enter. Row/column boundaries . . . . . . . From __ ___ Number To __ ___ Number -OR- Entire record is one area . . . . . *RCD _ Y=Yes -OR- Secondary help only . . . . . . . . *NONE _ Y=Yes -OR- Help for field . . . . . . . . . . *FLD Field . . . . . . . . . . . . . . NAME Name Choice . . . . . . . . . . . . . __ 1-99 -OR- Help for constant . . . . . . . . . *CNST Identifer . . . . . . . . . . . . ___ 1-999 F3=Exit F12=Cancel
Simplify Contextual Help Development
Figure 8 Excluding the Help Module from Extended Help
Define Application Help Record . . . : RCD001 Help number . . . . . . . . : 2 of 4 Next help number . . . . . . ___ Number Type choices, press Enter. Keyword Help text in UIM panel group HLPPNLGRP Y Y=Yes Indicators . . . . . . . . ___ ___ ___ Help module name . . . . . NAMEHLP Panel group . . . . . . . XRS002PG Name Library . . . . . . . . __________ Name, *LIBL, *CURLIB Help text excluded . . . . . HLPEXCLD Y Y=Yes Indicators . . . . . . . . ___ ___ ___ Help boundary . . . . . . . HLPBDY _ Y=Yes Indicators . . . . . . . . ___ ___ ___ Change help area . . . . . . HLPARA Y Y=Yes F3=Exit F9=Select HLPRCD or HLPDOC keyword More... F12=Cancel
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