Adding UIM help to the Display file

Having created a UIM help panel group I need to add the code to my Display file's DDS so that the help will be displayed. This post is going to use the UIM panel group that was created in my previous post to demonstrate, in simple terms, how to do this. I have designed a very simple display file to only include what I think is the minimum needed for it to work.

Most people have no idea where to find the Help key in their 5250 emulation client, therefore, as per SAA CUA standards I always define F1 as an alternate help key. I define the alternate help key in the file level keywords, top before the first record format definition, of the display file.

Rather than use SDA I find it easier to enter this source code using a source code editor, for example SEU. Therefore, I will be describing how to add this code as if I am using a source code editor.

AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++++++ 01 A DSPSIZ(24 80 *DS3) 02 A HELP 03 A ALTHELP(CA01) 04 A HLPPNLGRP('START' HELP_UIM) 05 A HLPTITLE('Example display file') 06 A HLPFULL

Line 2: I activate the Help key with the HELP function. You never know someone may know where their help key is.

Line 3: This is where I define F1 as the alternate help key. Notice that I have defined the key indicator to be command attention, CA01.

Lines 4 – 6: Are optional.

Line 4: I will describe the HLPPNLGRP function later. This is the help text that will be displayed at the beginning of the Extended Help. Defined at the file level this help text will be displayed at the start of the Extended Help for all the record formats within this display file. If I do not want this for all record formats I define this function in the record format. It cannot be defined in both places.

Line 5: This is the title that will be used at the top of the Extended Help, and works the same way as the HELPPNLGRP function on line 4

Line 6: The presence of the HLPFULL function will make the help text display on the full screen, not in a pop up window. If this function is absent the help will be displayed as defined in the User Options parameter, USROPT, of my user profile.

I am not going to show all the code for the record format within this display file, just the parts to do with the definition of the help text. The rest of the record format, the definition of the fields, is irrelevant as defining the help is not dependent upon the types of the fields.

07 A R SCREEN 08 A HLPCLR 09 A* HLPTITLE('Example rcd format') 10 A H HLPPNLGRP('FIRST_EXAMPLE' + HELP_UIM) 11 A HLPARA(*FLD Z1) 12 A H HLPPNLGRP('SECOND_EXAMPLE' + HELP_UIM) 13 A HLPARA(3 10 3 15) 14 A H HLPPNLGRP('THIRD_EXAMPLE' + HELP_UIM) 15 A HLPARA(*FLD Z3) 16 A H HLPPNLGRP('FOURTH_EXAMPLE' + HELP_UIM) 17 A HLPARA(*FLD Z4) 18 A H HLPPNLGRP('FIFTH_EXAMPLE' + HELP_UIM) 19 A HLPARA(*FLD Z5) 20 A H HLPPNLGRP('SIXTH_EXAMPLE' + HELP_UIM) 21 A HLPARA(*FLD Z6) 22 A H HLPPNLGRP('SEVENTH_EXAMPLE' + HELP_UIM) 23 A HLPARA(*FLD Z7A) 24 A H HLPPNLGRP('SEVENTH_EXAMPLE' + HELP_UIM) 25 A HLPARA(*FLD Z7B) 26 A HLPEXCLD 27 A H HLPPNLGRP('NOT_EXIST' HELP_UIM) 28 A HLPARA(*FLD Z8)

Line 7: Record format name.

Line 8: HLPCLR when used at the record format level clears any active help specifications.

Line 9: I can define the HLPTITLE at the record format level as well as in the file level. As in this example I gave it at the file level I have commented out this line.

Lines 10 and 11: Here is the first definition for help. The H is in the 17th column, which is the same place the R is placed for the definition of the record format name. The HLPPNLGRP function defines the name of the help section in the UIM panel group. It needs to be given with the name of the help section first, followed by the name of the UIM panel group. As the panel group HELP_UIM is in my library list I do not have to give the library name with name of the panel group.

The HLPARA keyword comes in three flavors.

AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++++++ A1 A H HLPPNLGRP('FIELD_1' HELP_UIM) A2 A HLPARA(3 2 3 4) B1 A H HLPPNLGRP('FIELD_2' HELP_UIM) B2 A HLPARA(*FLD Z1) C1 A H HLPPNLGRP('RCDFMT_1' HELP_UIM) C2 A HLPARA(*RCD)

Line A2: HLPARA(3 2 3 4) - Defines the help for an area of the record format. This help will be displayed in the area from the third row/second column to the third row/fourth column.

Line B2: HLPARA(*FLD Z1) - Defines the help for the field Z1. I prefer this method because if I move Z1 to another part of the display I do not have to change the HLPARA, which I would have to if I had defined it using the previous way.

Line C2: HLPARA(*RCD) - Defines the help text for the entire record format, except where help has been defined using the two previous methods.

OK, back to the DDS source code for all the help definitions in the record format SCREEN. The rest of all this source code, lines 12 – 28, are the same as line 10 and 11, just defining the help for various fields or areas of the screen, except…

Line 26: HLPEXCLD excludes the line from appearing in the Extended Help. In this example I have same help defined for fields Z1 and Z2. When the Extended Help is displayed I only want this help displayed once, not twice.

Lines 27 and 28: There is no help called NOT_EXIST, therefore, if the field Z8, is "helped" a help screen like this is displayed.

Click on image to see a larger version

When I see this I find I have misspelled the help name in the DDS.

So, what is Extended Help?

In the help panel I can see F2=Extended help. If I press F2 all of the help for that record format is displayed in the order the help specifications are placed in the record format's source code, not the order of the fields. The screen below is shown in full screen mode, as I added the HLPFULL function to the display file's source.

Click on image to see a larger version

The error message "Help information is incomplete" is displayed as the help called NOT_EXIST is not present in the help panel group.

Help can only be shown when it is defined in the record format that is displayed using EXFMT. With a subfile, SFL, it is the subfile control, SFLCTL, that is EXFMT, therefore, the help for the subfile has to be placed in the subfile control record. As the subfile's fields are not defined in the control record format I have to define the area upon which this subfile field will be displayed.

A H HLPPNLGRP(INV_NBR ORDHELP) A HLPARA(06 010 22 017)

One last recommendation I would make is to display F1=Help with the other function keys on any display file/record format you have added help to. This alerts the people using the display file that help is available to them. If you don't people will not know it is there.

F1=Help F3=Exit F4=Prompt

 

You can learn more about this from the IBM website:

• HLPARA - Help area
• HLPCLR - Help clear
• HLPEXCLD - Help exclude
• HLPPNLGRP - Help panel group
• HLPTITLE - Help title

 

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