Retrieve Category List (QTARCGYL) API
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Category List (QTARCGYL) API retrieves a list of the categories currently defined on the system.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The content and format of the information being returned.
The RCGY0100 format must be used for the category list information. See RCGY0100 Format to view the information returned for this format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
RCGY0100 Format
The following table shows the information that is returned for the RCGY0100 format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to category list |
| 12 | C | BINARY(4) | Number of category list entries |
| 16 | 10 | BINARY(4) | Length of category list entry |
| CHAR(*) | Category list | ||
Category list
The list of categories that are currently defined for the system. Each category entry has the following format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Category Name |
| 10 | A | CHAR(8) | Category System |
Field Descriptions
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Category name. The name of the defined category.
Category system.The name of the system owning the defined category. This field is blank for categories that are not owned by a specific system.
Length of category list entry. This field is set to the length, in bytes, of a single category list entry. A value of zero is returned if the category list is not available.
Number of category list entries. The number of category list entries returned. A value of zero is returned if the category list is not available.
Offset to category list. The offset, in bytes, to the category list. A value of zero is returned if the category list is not available.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF6708 E | Command ended due to error. |
| CPF67E4 E | Library device function not successful. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R3
[ Back to top | Backup and Recovery APIs | APIs by category ]