HLPARA (Help Area) keyword for display files

You use this help-specification-level keyword to define a rectangular area on the display.

If the cursor is located in this area when you press the Help key, the online help information specified for that help (H) specification (on a HLPDOC, HLPPNLGRP, or HLPRCD keyword) is displayed.

The format of the keyword is:

HLPARA(top-line left-position bottom-line right-position)
or
HLPARA(*RCD)
or
HLPARA(*NONE)
or
HLPARA(*FLD field-name [choice-number])
or
HLPARA(*CNST help-identifier)

Observe the following rules when the line and position values are specified as parameters:

The line and position values must be within the display size.
If you do not specify HLPARA for a secondary display size, the HLPARA of the primary display size is used if it is valid for the secondary display size. HLPARA(*NONE) is used if the HLPARA of the primary display size is not valid for the secondary display size.
The top line must not exceed the bottom line and the left position must not exceed the right position.
If you specify the SLNO(n) keyword on the record, the top-line and bottom-line values are adjusted, and any errors are diagnosed at creation time. If you specify the SLNO(*VAR) keyword on the record, the top line and bottom line are adjusted at processing time.

The special value *RCD indicates that the help area is the area of the record containing the H specification. This area includes all display positions in every line occupied by the record.

HLPARA(*RCD) is not valid for subfile control (SFLCTL) or user-defined (USRDFN) record formats.

If you specify HLPARA(*RCD) on an H specification, the record format containing the H specification must contain at least one displayable field for the primary display size. Hidden (H in position 38), message (M in position 38), and program-to-system (P in position 38) fields and fields that specify a SFLPGMQ or SFLMSGKEY keyword are not displayable.

The special value *NONE indicates that no help area is associated with the help information defined on this H specification. If the help information is defined using the UIM (HLPPNLGRP keyword), it is not displayed as item-specific help when the Help key is pressed, but might be displayed as extended help. If the help information is defined using DDS (HLPRCD keyword), it is not displayed as primary help when the Help key is pressed, but it might be displayed as secondary help when the Page Up or Page Down key is pressed on another help display. The *NONE value is not useful when the help information is defined in a document (HLPDOC keyword), because this information will never be displayed when the Help key is pressed.

The special value *FLD indicates that the help area is the area of a field. If the field occupies only one line, the help area consists of the first and last characters of the line and all the characters in between.

If the field wraps from one line to another, the help area consists of the entire length of all lines in the field. For example, if a field starts on line 3, position 4 and ends on line 5, position 10, the help area starts in line 3, position 1 and ends in line 5, position 80.

If the field is a choice or a continued-entry field, the help area consists of the rectangular area occupied by the choice or continued-entry field.

The field-name parameter specifies the name of the field for which the help area is defined. The field must exist in the record containing the H specification.

If the choice-number parameter is specified, the help area is the area of the choice within the field specified. When a choice number is specified, the field name must be the name of a menu-bar field or a selection field, and the choice number you specify must also be specified on a MNUBARCHC or CHOICE keyword for that field. Valid values for the choice number are positive integers greater than 0 and less than 100.

The *CNST special value indicates that the help area is the area of a constant field. This area includes the beginning and ending attribute bytes of the field.

The help-id parameter is a number that identifies the constant field for which this help area is defined. The constant field must exist in the record containing the H specification, and it must have the HLPID keyword specified with the same help-identifier.

You must specify at least one HLPARA keyword on an H specification. When you specify multiple HLPARA keywords for each H specification, you must use display size conditioning.

Help areas can overlap when multiple H specifications are specified on a record. When multiple H specifications are specified, the first H specification with both of the following characteristics is used:

The help area specified on the HLPARA keyword contains the current cursor location.
The option indicator on the HLPRCD, HLPPNLGRP, or HLPDOC keyword was in effect when the application record was written to the display.

The following rules apply to H specifications:

An H in position 17 denotes the start of an H specification. The H specification must be located in the DDS after the record-level keywords and before the first field in that record.
Each H specification must have exactly one HLPRCD, HLPPNLGRP, or HLPDOC keyword, up to one HLPBDY or HLPEXCLD keyword, and at least one HLPARA keyword.
The end of the H specification is denoted by another H in position 17 or the first field.
You cannot use H specifications in subfile (SFL keyword) record formats. H specifications are not allowed in subfile control formats associated with message subfiles (SFLMSGRCD keyword).

Option indicators are not valid for this keyword.

Example 1

The following example shows how to specify the HLPARA keyword:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A                                      HELP
     A                                      HLPRCD(DFTHELP)
     A          R RECORD1
     A          H                           HLPARA(1 5 3 15)
     A                                      HLPDOC(FLDHELP DOC1 FOLDER1)
     A
     A          H                           HLPARA(*RCD)
     A                                      HLPRCD(HELPRCD1)
     A
     A          H                           HLPARA(*NONE)
     A                                      HLPRCD(HELPRCD2)
     A            FIELD1        10A     2  5
     A            FIELD2        40A    10 10
     A

In this example, the HLPARA keyword on the first H specification indicates that the area from line 1, position 5 to line 3, position 15 is to be associated with the online help information document DOC1. If the cursor is located in this area when the Help key is pressed, document DOC1 is displayed beginning at label FLDHELP.

The HLPARA keyword on the second H specification indicates that the area occupied by RECORD1 (lines 2 through 10) is to be associated with the online help information record HELPRCD1. If the cursor is located anywhere on lines 2 through 10 (outside the area defined by the first H specification) when the Help key is pressed, record HELPRCD1 is displayed.

The HLPARA keyword on the third H specification indicates that no area is to be associated with the online help information HELPRCD2. HELPRCD2 can only be displayed by pressing the Page Up or Page Down key from a online help information display.

Example 2

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A                                      HELP HLPRCD(DFTHELP)
     A          R RECORD
     A          H                           HLPARA(*FLD F1 1)
     A                                      HLPRCD(UNDOHLP HLPLIB/HLPFILE)
     A          H                           HLPARA(*FLD F1 2)
     A                                      HLPRCD(MARKHLP HLPLIB/HLPFILE)
     A          H                           HLPARA(*FLD F1 3)
     A                                      HLPRCD(COPYHLP HLPLIB/HLPFILE)
     A          H                           HLPARA(*FLD F2)
     A                                      HLPRCD(F2HLP HLPLIB/HLPFILE)
     A          H                           HLPARA(*CNST 1)
     A                                      HLPRCD(TITLEHLP HLPLIB/HLPFILE)
     A                                  1 37'Title' HLPID(1)
     A            F1             2Y 0B 10  2SNGCHCFLD
     A                                      CHOICE(1 'Choice 1')
     A  01                                  CHOICE(2 'Choice 2')
     A                                      CHOICE(3 'Choice 3')
     A            F2            10A  B 10 30
     A

The HLPARA keyword on the first three H specifications indicates the areas occupied by Choice 1, Choice 2, and Choice 3, which are to be associated with online help information. If Choice 2 is turned off so that Choice 3 moves up one line, the help area for Choice 3 automatically moves with the choice.

The HLPARA keyword specified on the 4th H specification indicates the area of F2 to be associated with online help information. This area is line 10, from position 29 through position 40.

The HLPARA keyword specified on the 5th H specification indicates the area of the constant title to be associated with online help information. This area is line 1, from position 36 through position 42.