Creating help text using UIM

Thanks to UIM, User Interface Manager, designing help for your DDS display files is very simple. UIM has been used by IBM for their screens, menus, and help panels since the launch of the AS400, it was not until V2R1, 1991, that it was made available to programmers to create their own help panels. The "language" itself is easy to become familiar with and its compile listings are some of the easiest to decipher on IBM i.

In this post I am going to show how to create UIM help panels that can be used in DDS display files, and in a second post how to add the various DDS keywords to your Display file source code to use the UIM help panels.

Let me start with the basics. If you use the IBM convention for source files, help panel groups should be placed in the source file QPNLSRC. Personally, I put all my source members for each library in one source file. The source type for Panel Groups is PNLGRP. Over the years I have come to conclusion that it is best to create one help panel group per application, rather than one per display file. Most of the fields in any application will be shown in multiple display files, and by using one help panel group I can use the same help text in multiple display files. As the help is external to the display files, I can change the panel group without having to recompile the display file.

Work with Members Using PDM File . . . . . . DEVSRC Library . . . . MYLIB Opt Member Type Text TESTHELP PNLGRP Help text

All UIM source statements start with a tag. Many tags can come in pairs, reminiscent of HTML, one to begin and one at the end. Tags start with a colon ( : ), and end with a period/dot ( . ).

A comment line starts with a period/dot followed by an asterisk ( .* ). Every panel's first "active" statement must be :PNLGRP. and end with an :EPNLGRP., comment lines may be placed before or after these tags.

All statements start in the first column of the source member.

• PNLGRP/EPNLGRP - Start and end of the panel group (source member)
• HELP/EHELP - Start and end of a section of help text
• Hx - Start and end of extended heading
• P - Paragraph
• HPx/EHPx - Start and end of highlighting
• UL/EUL - Start and end of an unordered list
• OL/EOL - Start and end of an ordered list
• SL/ESL - Start and end of a simple list
• LI - List item
• LINK/ELINK - Start and end of a link

There are other UIM tags that can be used in help panel groups. I am not going to list them here, but refer you to the link to the IBM documentation at the bottom of this post.

 

PNLGRP/EPNLGRP - Panel group start and end

All panel groups mist start with a PNLGRP and end with a matching EPNLGRP. These must occur only once in the source member.

As I mentioned earlier all tags start with a colon ( : ), and end with a period/dot ( . ).

...+... 1 ...+... 2 ...+... 3 ... *************** Beginning of data 01 :PNLGRP. .******************************** .******************************** 02 :EPNLGRP.

 

HELP/EHELP - Help sections

A help panel group can contain one of more help sections.

01 :PNLGRP. .*************************** 02 :HELP NAME='FIRST_EXAMPLE'. 03 First example. 04 :EHELP. .*************************** 05 :HELP NAME='SECOND_EXAMPLE'. 06 Second example. 07 :EHELP. .*************************** 08 :EPNLGRP.

Line 1: The panel group must start with a PNLGRP tag.

Line 2: This is the first section of help text, and it needs a name so that I can define it in the DDS of the display file.

Line 3: This is the heading that will be shown at the top of the help panel when it is displayed.

Line 4: End of the section of help text.

Lines 5 – 7: A second section of help text.

Line 8: The panel group must end with a EPNLGRP tag.

 

Hx - Headings

There are four levels of heading:

• H1 - Centered, highlighted/bold, and underlined
• H2 - Left justified, highlighted/bold, and underlined
• H3 - Left justified, highlighted/bold, and not underlined
• H4 - Left justified, not highlighted/bold, and underlined

01 :HELP NAME='FIRST_EXAMPLE'. 02 First example - Headings. 03 :XH1.Heading 1 04 :XH2.Heading 2 05 :XH3.Heading 3 06 :XH4.Heading 4 07 :EHELP.

There is no matching closing tag.

Click on image to see a larger version

 

P - Paragraph

The help text I want to display needs to be entered after a paragraph tag.

01 :HELP NAME='SECOND_EXAMPLE'. 02 Second example - Paragraphs. 03 :H1.Paragraphs 04 :P.This is my first paragraph. 05 :P.I have another paragraph here! 06 :EHELP.

There is no matching closing tag.

Click on image to see a larger version

 

HPx/EHPx - Highlighting

The codes for highlighting a section of text must be included within a paragraph. This is a tag that need to be closed with an ending tag. There are nine types of highlighting.

• HP1/EHP1 - Underlined
• HP2/EHP2 - Highlighted/bold
• HP3/EHP3 - Highlighted/bold and underlined
• HP4/EHP4 - Normal text
• HP5/EHP5 - Reverse image
• HP6/EHP6 - Reverse image and underlined
• HP7/EHP7 - Reverse image and highlighted/bold
• HP8/EHP8 - Reverse image and highlighted/bold (appears to be same as HP7)
• HP9/EHP9 - Reverse image (appears to be same as HP5)

01 :HELP NAME='THIRD_EXAMPLE'. 02 Third example - Highlighting. 03 :H1.Highlighting 04 :P.Highlighting occurs within a paragraph. 05 :P.:HP1.Highlighting 1:EHP1. 06 :P.:HP2.Highlighting 2:EHP2. 07 :P.:HP3.Highlighting 3:EHP3. 08 :P.:HP4.Highlighting 4:EHP4. 09 :P.:HP5.Highlighting 5:EHP5. 10 :P.:HP6.Highlighting 6:EHP6. 11 :P.:HP7.Highlighting 7:EHP7. 12 :P.:HP8.Highlighting 8:EHP8. 13 :P.:HP9.Highlighting 9:EHP9. 14 :EHELP.

Click on images to see a larger version

 

UL/EUL - Unordered list

If I wanted to display a list of valid values it is easier on the eye if the items are displayed in a list, rather than separate paragraphs. If I want that list to be prefix with a bullet I use the unordered list. The UL tag is used to indicate that an unordered list is starting, see line 5 below. Each item within the list is prefixed with a list item tag, LI, lines 6 – 8. After the last list item the listed needs to be ended with a EUL tag, line 9.

Line 4 gives an example of how a paragraph can be "overflowed" onto a second line of source code.

01 :HELP NAME='FOURTH_EXAMPLE'. 02 Fourth example - Unordered list. 03 :H1.Unordered list 04 :P.An unordered list looks better than multiple paragraphs. 05 :UL. 06 :LI.One 07 :LI.Two 08 :LI.Three 09 :EUL. 10 :EHELP.

Click on image to see a larger version

 

OL/EOL - Ordered list

The difference between an unordered and an ordered list is that the ordered list items are numbered. The tag for starting an ordered list is OL, see line 5 below. The list items use the LI tag, as they do the in the unordered list. The ordered list is closed with the EOL tag, line 9.

01 :HELP NAME='FIFTH_EXAMPLE'. 02 Fifth example - Ordered list. 03 :H1.Ordered list 04 :P.An ordered list gives each item a number. 05 :OL. 06 :LI.One 07 :LI.Two 08 :LI.Three 09 :EOL. 10 :EHELP.

Click on image to see a larger version

 

SL/ESL - Simple list

List items within a simple list do not have a prefixing character, like the other two types of lists, and are indented like the other types of list's items. The items in simple list are separated with a blank line. The SL, line 5 below, and the ESL, line 9, are used to designate that the list will be a simple list.

01 :HELP NAME='SIXTH_EXAMPLE'. 02 Sixth example - Simple list. 03 :H1.Ordered list 04 :P.An simple list has no character at start of the line before the list item's text. 05 :SL. 06 :LI.One 07 :LI.Two 08 :LI.Three 09 :ESL. 10 :EHELP.

Click on images to see a larger version

 

LINK/ELINK - Link

The link tag creates a link to another section of help text, which can be within the same panel group or another. All links start with the LINK tag which includes a PERFORM statement defining where the link will go to. Line 6 shows a link within the same panel group, and line 9 shows a link to another panel group. Link text follows, and the link is closed with the ELINK tag.

01 :HELP NAME='SEVENTH_EXAMPLE'. 02 Seventh example - Link. 03 :H1.Link 04 :P.Here is a link to another section of 05 help text 06 :LINK PERFORM='DSPHELP FIRST_EXAMPLE'. 07 first example:ELINK., and here is a second 08 link 09 :LINK PERFORM='DSPHELP SECOND_UIM OTHER_UIM'. 10 second example:ELINK.. 11 :EHELP.

Click on image to see a larger version

Links are displayed as underlined and yellow. To visit the linked help section I position my cursor on the link text and press the Enter key. Notice how there is a blank character before the link text, this indicates if the link has been visited or not. In the image below the greater than symbol ( > ) shows that I have visited the first link.

Click on image to see a larger version

 

I can test how my panel groups will look without having to add them to a display file by creating my own program to use an IBM API.

The next step is how to add DDS to my display file so that it will display the help text.

 

The best documentation I can find for the UIM tags is the Application Display Programming manual for 7.5, which is a PDF file you can view on the IBM website here (not been updated since IBM i 6.1).

 

This article was written for IBM i 7.3, and should work for earlier releases too.