Wednesday, February 1, 2017

Creating help text using UIM

uim panel group help

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.

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.

6 comments:

  1. That is the easiest to follow explanation of UIM I've seen. It was a good refresher; how often do you create help text. Thanks

    ReplyDelete
    Replies
    1. Thank you for the feedback. I am glad to hear that it is the easiest explanation you have found.

      Delete
  2. Top article Simon!
    Jan

    ReplyDelete
  3. Great Job Simon. Help text is very lacking when developers are coding but the users love it.

    Hoss

    ReplyDelete

To prevent "comment spam" all comments are moderated.
Learn about this website's comments policy here.

Some people have reported that they cannot post a comment using certain computers and browsers. If this is you feel free to use the Contact Form to send me the comment and I will post it for you, please include the title of the post so I know which one to post the comment to.