Display Help (QUHDSPH) API


  Required Parameter Group:

1 Help identifier array Input Char(*)
2 Number of help identifiers Input Binary(4)
3 Help type Input Array(2) of Binary(4)
4 Full display title Input Char(55)
5 Qualified search index object name Input Char(20)
6 Display type Input Char(1)
7 Upper-left corner Input Array(2) of Binary(4)
8 Lower-right corner Input Array(2) of Binary(4)
9 Cursor location Input Array(2) of Binary(4)
10 Error code I/O Char(*)

  Optional Parameter Group:

11 Help bookshelf name Input Char(8)
12 Border attribute Input Array(2) of Char(1)
13 Border characters Input Array(8) of Char(1)

  Default Public Authority: *USE

  Threadsafe: No

The Display Help (QUHDSPH) API displays help information. The help can be either contextual or extended. It can be formatted as a full display or in a window.

Contextual help provides information about a single item, such as the field on which the user's cursor is positioned when help is requested. Extended help provides help for all the items on the display; it contains all contextual help items and can contain additional information as well. A window is an area on the display that is treated as a separate display. Windows have visible boundaries and appear to overlay the display from which they are requested.

You can use the QUHDSPH API to handle Help key processing in applications written in data description specifications (DDS) or user-defined data streams (UDDS). You do not need it to handle help requests in applications that use record-level DDS display files with DDS help keywords to present panels because the DDS help keywords handle all help requests.

You do not need to use this API to display help for applications written using panel groups to present panels, because the UIM handles all help requests.


Authorities and Locks

Library Authority
*READ
Search Index Object Authority
*USE
Search Index Object Library Authority
*READ
Search Index Object Lock
*SHRRD
Panel Group Authority
*USE
Panel Group Lock
*SHRRD

Required Parameter Group

Help identifier array
INPUT; CHAR(*)

An array of the help identifiers to display. The list can contain up to 2000 items. Each item has two parts:

Qualified help panel group name
CHAR(20)

The panel group (*PNLGRP) object that contains the help module to display, and the library in which it is located. (A panel group is an object with an object type of *PNLGRP. It contains display panels, print panels, or help modules.)

The first 10 characters contain the panel group object name, and the second 10 characters contain the library name. You can use these special values for the library name:

*CURLIB The job's current library
*LIBL The library list

Help module name
CHAR(32)

The name specified on the NAME attribute of a :HELP. tag in the panel group object. The name must be specified using uppercase, alphabetic characters.

Number of help identifiers
INPUT; BINARY(4)

The number of help identifiers in the help identifier array parameter. The number must be between 1 and 2000.

Help type
INPUT; ARRAY(2) of BINARY(4)

Whether this is a request to display extended or contextual help, and which help identifiers to display for the latter. For contextual help, only a subset of the help identifiers in the help identifier array parameter is initially displayed, and a function key is enabled to display extended help. Extended help includes all help identifiers in the help identifier array parameter, including those used in contextual help.

This parameter is a 2-element array of BINARY(4) values. Both elements are used as indexes into the help identifier array. The array elements are:

  1. The first help identifier to display for contextual help. The value must be greater than or equal to 1, and less than or equal to the number of help identifiers in the help identifier array.
  2. The last help identifier to display for contextual help. The value must be greater than or equal to the value specified in the first element of this parameter, and less than or equal to the number of help identifiers in the help identifier array.

To display extended help, set the value of the first array element to 1 and the value of the second array element to the value specified in the number of help identifiers parameter.

Full display title
INPUT; CHAR(55)

The default title to use if the help is shown in a full display and if no title is found in the help panel group object.

Qualified search index object name
INPUT; CHAR(20)

The search index (*SCHIDX) object that can be accessed from the help display, and the library in which it is located. The first 10 characters contain the search index object name, and the second 10 characters contain the library name.

You can use the following special value for this parameter:

*NONE The search index function is not made available for this help request. The library name must be blank.

You can use the following special values for the library name:

*CURLIB The job's current library
*LIBL The library list

Note: The qualified search index object name must be *NONE if the help bookshelf name is something other than *NONE.

Display type
INPUT; CHAR(1)

Whether the help information is displayed in a full screen or a window. You must use one of the following values:

Y The help is displayed in a full screen.
N The help can be displayed in a window, depending on the user option (USROPT) value of the user profile.

Upper-left corner
INPUT; ARRAY(2) of BINARY(4)

The upper-left corner of the area on the display for which help is requested. If the help is displayed in a window, the window is adjacent to the area identified, if possible. The array elements are:


Lower-right corner
INPUT; ARRAY(2) of BINARY(4)

The lower-right corner of the area on the display for which help is requested. If the help is displayed in a window, the window is adjacent to the area identified, if possible. The array elements are:


Cursor location
INPUT; ARRAY(2) of BINARY(4)

The position of the cursor when help is requested. If the help is displayed in a window, this cursor position is used by the UIM to decide the position and size of the window. The array elements are the row number of the cursor position and the column number of the cursor position.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Optional Parameter Group

Help bookshelf name
INPUT; CHAR(8)

This parameter is no longer supported and any value entered will be ignored.

Border attribute
INPUT; ARRAY(2) of CHAR(1)

The border attributes of the pop-up window in which the help may be displayed. The two array elements are:

Border attributes

Hex Value Color Display Monochrome Display
X'01' Green Normal
X'02' Green
Reverse		 Reverse Image
X'03' White High Intensity
X'04' Green
Reverse		 High Intensity Reverse
X'05' Green
Underscore		 Underscore
X'06' Green Underscore
Reverse		 Underscore
Reverse
X'07' White
Underscore		 High Intensity
Underscore
X'08' Nondisplay Nondisplay
X'09' Red Blink
X'0A' Red
Reverse		 Blink
Reverse
X'0B' Red
Blink		 Blink
High Intensity
X'0C' Red
Blink
Reverse		 Blink
High Intensity
Reverse
X'0D' Red
Underscore		 Blink
Underscore
X'0E' Red
Underscore
Reverse		 Blink
Underscore
Reverse
X'0F' Red
Blink
Underscore		 Blink
Underscore
High Intensity
X'10' Turquoise
Column Separator		 Column Separator
X'11' Turquoise
Column Separator
Reverse Image		 Column Separator
Reverse Image
X'12' Yellow
Column Separator		 Column Separator
High Intensity
X'13' Yellow
Column Separator
Reverse Image		 Column Separator
High Intensity
Reverse Image
X'14' Turquoise
Column Separator
Underscore		 Column Separator
Underscore
X'15' Turquoise
Column Separator
Reverse Image
Underscore		 Column Separator
Reverse Image
Underscore
X'16' Yellow
Column Separator
Underscore		 Column Separator
Underscore
X'17' Pink Blink
Column Separator
X'18' Pink
Reverse Image		 Blink
Column Separator
Reverse Image
X'19' Blue Blink
Column Separator
High Intensity
X'1A' Blue
Reverse Image		 Blink
Column Separator
High Intensity
Reverse Image
X'1B' Pink
Underscore		 Blink
Column Separator
Underscore
X'1C' Pink
Reverse Image
Underscore		 Blink
Column Separator
Reverse Image
Underscore
X'1D' Blue
Underscore		 Blink
Column Separator
High Intensity
Underscore

Border characters
INPUT; ARRAY(8) of CHAR(1)

The border characters that define the pop-up window in which the help may be displayed. The eight array characters are:

  1. The character to define the top left corner.
  2. The character to define the top margin.
  3. The character to define the top right corner.
  4. The character to define the left margin.
  5. The character to define the right margin.
  6. The character to define the bottom left corner.
  7. The character to define the bottom margin.
  8. The character to define the bottom right corner.

The help window would look like this:

            12222222222223
            4            5
            4            5
            4            5
            67777777777778

When using the default values, the border would look like this:

            ..............
            :            :
            :            :
            :            :
            :............:

Error Messages

Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
CPF6A24 E Parameter &1 not passed correctly.
CPF6A25 E Return code length of &1 not valid.
CPF6Exx E All CPF6Exx messages could be signalled. xx is from 01 to FF.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R1

[ Back to top | User Interface Manager APIs | APIs by category ]