Display Help (QUHDSPH) API

Required Parameter Group:

Help identifier array

Input

Char(*)

Number of help identifiers

Input

Binary(4)

Help type

Input

Array(2) of Binary(4)

Full display title

Input

Char(55)

Qualified search index object name

Input

Char(20)

Display type

Input

Char(1)

Upper-left corner

Input

Array(2) of Binary(4)

Lower-right corner

Input

Array(2) of Binary(4)

Cursor location

Input

Array(2) of Binary(4)

Error code

I/O

Char(*)

Optional Parameter Group:

Help bookshelf name

Input

Char(8)

Border attribute

Input

Array(2) of Char(1)

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:

The help is displayed in a full screen.

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

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

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