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:

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.
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:

The row number of the upper-left corner
The column number of the upper-left corner

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:

The row number of the lower-right corner
The column number of the lower-right corner

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:

The border attribute for a monochrome display. The default for a monochrome display is normal.
The border attribute for a color display. The default for a color display is blue.

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:

The character to define the top left corner.
The character to define the top margin.
The character to define the top right corner.
The character to define the left margin.
The character to define the right margin.
The character to define the bottom left corner.
The character to define the bottom margin.
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

Top | User Interface Manager (UIM) APIs | APIs by category