Retrieve Help Text (QUHRHLPT) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Help identifiers to be retrieved | Input | Array(*) of (*) |
| 5 | Number of help identifiers | Input | Binary(4) |
| 6 | Help identifier text | Output | Char(*) |
| 7 | Length of help identifier text | Input | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Help Text (QUHRHLPT) API lets you generate an Extensible Markup Language (XML) source listing of the help identifiers in a panel group or menu object. The QUHRHLPT API returns the XML source in UTF-8 (CCSID 1208). You can use the QUHRHLPT API to generate XML source representing the help text as defined in help identifiers in UIM panel groups or menus.
The QUHRHLPT API returns information in one format.
Special consideration: The text for the UIM LINK tag will be displayed, but there will be no link generated in the XML source.
Authorities and Locks
- Help Panel Group/Menu Authority
- *READ
- Help Panel Group/Menu Library Authority
- *EXECUTE
- Imported Help Panel Group Authority
- *READ
- Imported Help Panel Group Library Authority
- *EXECUTE
Required Parameter Group
- Receiver variable
- INPUT; CHAR(*)
The variable that is to receive the information requested. For the format of the structure, see Format of the Receiver Variable.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may be unpredictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the information returned for the help identifiers that are requested. The following format name must be used:
RHLP0100 For details about the formats, see Format of the Receiver Variable.
- Help identifiers to be retrieved
- INPUT; Array(*) of (*)
An array of help identifiers to be formatted. The list can contain up to 2000 items. For the format of the structure, see Format of Help Identifiers to Be Retrieved.
- Number of help identifiers
- INPUT; BINARY(4)
The number of help identifer names passed in on the help identifiers to be retrieved parameter.
- Help identifier text
- OUTPUT; Char(*)
The variable that is to receive the generated Xml output. The information returned potentially could be very large. In this case, a user space with the auto-extendable attribute set may act as a better choice for a receiver variable. For further information about using a user space, see User spaces. For the format of the structure, see Format of Help Identifier Text. If the variable is not large enough, no data may be returned.
- Length of help identifier text
- INPUT; BINARY(4)
The length of the help identifier text parameter. If the length specified is larger than the size of the parameter, the results may be undesirable. The minimum length is 8 bytes.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Format of the Receiver Variable
The receiver variable contains:
- A header section
- A list data section
For detailed descriptions of each field in the header section, see Field Descriptions.
RHLP0100
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(8) | Format name |
| 16 | 10 | BINARY(4) | Offset to help identifiers |
| 20 | 14 | BINARY(4) | Number of entries |
| 24 | 18 | BINARY(4) | Size of each entry |
| * | * | CHAR(*) | Help identifiers |
Help Identifier Entries
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(32) | Help identifier name |
| 32 | 20 | CHAR(10) | Object name |
| 42 | 2A | CHAR(10) | Object library name |
| 52 | 34 | CHAR(10) | Object type |
| 62 | 3E | CHAR(1) | Help identifier found |
| 63 | 3F | CHAR(96) | Help identifier anchor name |
| 167 | A7 | CHAR(33) | Reserved |
Field Descriptions
Bytes available. The number of bytes of information available to be returned.
Bytes returned. The number of bytes of information returned.
Format name. The format name that was passed to this API.
Help identifier anchor name. The name of the anchor within the help document.
Help identifier found. A one-character field indicating the status of the help ID when the caller selects the help identifiers to be retrieved. The possible values are:
| 0 | Not found due to incorrect name |
| 1 | Help identifier found |
| 2 | Object access failure; see joblog for details |
If none of the requested help identifiers are found, the API will also signal a CPF6E3B escape message.
Help identifier name. The name specified on the NAME attribute of a :HELP. tag in the panel group or menu object.
Number of entries. The number of entries being returned in the list data section.
Object library name. The library containing the panel group or menu object in which the help identifier was found.
Object name. A 10-character name used to identify the panel group or menu object in which the help identifier was found.
Object type. The type of the object in which the help identifier was found.
Offset to help identifiers. The offset from the start of the receiver variable to the first help identifier.
Reserved. An ignored field.
Size of each entry. The size of each entry in bytes in the list data section.
Format of Help Identifiers to Be Retrieved
The following information is accepted as input. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(32) | Help identifier name |
| 32 | 20 | CHAR(10) | Object name |
| 42 | 2A | CHAR(10) | Object library name |
| 52 | 34 | CHAR(10) | Object type |
| 62 | 3E | CHAR(18) | Reserved |
Field Descriptions
Help identifier name. The name specified on the NAME attribute of a :HELP. tag in the panel group or menu object. The name must be specified using uppercase, alphabetic characters.
Object library name. The library containing the panel group or menu object in which the help identifier was found. As input, this value must be in uppercase letters. You can use these special values for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
Object name. A 10-character name used to identify the panel group or menu object in which the help identifier was found. As input, this value must be in uppercase letters.
Object type. The type of the object in which the help identifier was found. This value must be *PNLGRP or *MENU.
Reserved. This field should be set to blanks.
Format of the Help Identifier Text
The following is a description of the data in the help identifier text parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| * | * | Char(*) | Data |
Field Descriptions
Bytes available. The number of bytes of information available to be returned.
Bytes returned. The number of bytes of information returned.
Data. The UIM online help formatted in Xml. This information contains:
- A document header section
- Xml-formatted tags
- A document footer section
Each formatted help identifier contains a <div> tag representing the help identifier being formatted, such as:
- <div> <a name="FSDIR.CRTDIR"></a>
- (Xml-formatted help text is contained here)
- </div>
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C20 E | Error found by program &1. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of receiver variable not valid. |
| CPF3C31 D | Object type &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF9801 D | Object &2 in library &3 not found. |
| CPF9802 D | Not authorized to object &2 in &3. |
| CPF6E3B E | Help information is not available. |
| CPF9803 D | Cannot allocate object &2 in library &3. |
| CPF9804 D | Object &2 in library &3 damaged. |
| CPF9810 D | Library &1 not found. |
| CPF9820 D | Not authorized to use library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R1
[ Back to top | User Interface Manager APIs | APIs by category ]