List Clustered Hash Table Keys (QcstListCHTKeys) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Connection handle | Input | Char(16) |
| 4 | Key selection information | Input | Void(*) |
| 5 | Key selection information size | Input | Binary(4) |
| 6 | Key selection information format | Input | Char(8) |
| 7 | Error code | I/O | Void(*) |
Service Program: QCSTCHT
Default Public Authority: *USE
Threadsafe: Yes
The List Clustered Hash Table Keys (QcstListCHTKeys) API generates a list of keys and descriptive information about the entries stored in the clustered hash table specified by the connection handle parameter. The generated list is placed in the specified user space and replaces any existing list. There is no special authority needed to retrieve a list of the keys. The list can include some of the following:
- All entries
- Entries which are in conflict between clustered hash table domain nodes
- Entries which are owned by a specific user
- Entries which were last stored by a specific user
Restrictions:
- A connection must have been established with the clustered hash table server.
- When this API is called, the clustered hash table server must be active on the requesting node.
- This API must be run under the same job that issued the Connect Clustered Hash Table (QcstConnectCHT) API.
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The name of the *USRSPC object that is to receive the generated list. The first 10 characters contain the user space object name, and the second 10 characters contain the name of the library where the user space is located. No special values are supported for library name, for example, QTEMP, *CURLIB, or *LIBL. The user space cannot be in an independent auxiliary storage pool.
- Format name
- INPUT; CHAR(8)
The format of the information returned for each key in the clustered hash table. Possible values are:
CHTL0100 Clustered Hash Table Keys For more information, see CHTL0100 Format.
- Connection handle
- INPUT; CHAR(10)
This is an active connection handle for the clustered hash table server. It is obtained by calling the Connect Clustered Hash Table (QcstConnectCHT) API.
- Key selection information
- INPUT; CHAR(*)
The information that determines the keys to be listed. The format of this information is described in CHTI0100 Format.
- Key selection information size
- INPUT; BINARY(4)
The size in bytes of the key selection information parameter. If the size is greater than the length of the key selection information format, it must be padded with zeroes.
- Key selection information format
- INPUT; CHAR(8)
The format of the key selection information parameter. Possible values are:
CHTI0100 The specific information identifying the keys to be listed. For more information, see CHTI0100 Format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Generated Lists
The clustered hash table key list consists of:
- A user space
- A generic header
- An input parameter section
- A header section
- A list data section:
- CHTL0100 format
For details about the user area and generic header, see User spaces. For detailed descriptions of the fields in the list returned, see Field Descriptions.
The completion code in the generic header should be checked to determine if the API completed successfully. When you retrieve list entry information from a user space, you must use the length of entry information returned associated with each entry returned. If you do not use the length of entry information the result may not be valid.
Input Parameter Section
An exact copy of the parameters coded in the call to the API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(16) | Connection handle |
| 44 | 2C | CHAR(8) | Key selection information format |
| 52 | 34 | BINARY(4) | Key selection information size |
| 56 | 38 | BINARY(4) | Entry status requested |
| 60 | 3C | CHAR(10) | Storing user profile requested |
| 70 | 46 | CHAR(10) | Owning user profile requested |
Header Section
Global information about the clustered hash table keys.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Authorization list name |
| 10 | A | CHAR(2) | Reserved |
CHTL0100 Format
General information about the clustered hash table keys. Detailed information about a key can be obtained by using the Retrieve Clustered Hash Table Entry (QcstRetrieveCHTEntry) API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of entry information returned |
| 4 | 4 | BINARY(4) | Offset to key |
| 8 | 8 | BINARY(4) | Length of key |
| 12 | C | BINARY(4) | Entry status |
| 16 | 10 | BINARY(4) | Authority access level |
| 20 | 14 | CHAR(10) | Storing user profile |
| 30 | 1E | CHAR(10) | Owning user profile |
| 40 | 28 | CHAR(*) | Key |
CHTI0100 Format
The following table shows the format of the key selection information parameter for the CHTI0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Entry status requested |
| 4 | 4 | CHAR(10) | Storing user profile requested |
| 14 | E | CHAR(10) | Owning user profile requested |
Field Descriptions
Authority access level. This field describes who is allowed to retrieve and update the entry associated with this key. Valid special values are:
| 0 | The user profile that owns the entry and a user with *ALLOBJ authority is allowed to retrieve and update the entry associated with this key. |
| 1 | Any user can retrieve and update the entry associated with this key. |
Authorization list name. This is the name of the authorization list specified when the cluster hash table server was started. Valid special values are:
| *NONE | No authorization list was specified. |
Connection handle. This is an active connection handle for the clustered hash table server. It is obtained by calling the Connect Clustered Hash Table (QcstConnectCHT) API.
Entry status. Indicates whether the entry is in conflict or not. An entry is in conflict if it is not the same on all nodes in the clustered hash table domain. A potential cause of an entry marked in conflict is the clustered hash table domain nodes were not communicating and the information associated with the key was updated from more than one cluster partition. For additional details on cluster node partitions, see Partition errors. To resolve an entry in conflict, use the Store Clustered Hash Table Entry (QcstStoreCHTEntry) API to update the entry to the correct value. The possible values are:
| 0 | Entry is not in conflict in the clustered hash table. |
| 1 | Entry is in conflict in the clustered hash table. |
Entry status requested. Specifies the entry status to use when returning the list of keys. The possible values are:
| 0 | Entries which are not in conflict will be returned. |
| 1 | Entries which are in conflict will be returned. |
| -1 | All entries will be returned regardless of status. This is the default value. |
Format name. The content and format of the information returned for each clustered hash table key. The value must be set to CHTL0100.
Key. A key stored in the clustered hash table.
Length of key. The length of the key stored in the clustered hash table.
Length of entry information returned. The total length of the entry information returned for the key. This value is used to increment to the next key in the list.
Offset to key. The bytes from the beginning of the entry to the Key field.
Owning user profile. The user profile that owns the entry associated with this key.
Owning user profile requested. Specifies the owning user profile to use when returning the list of keys. The owning user profile is the user profile that originally stored the entry. Valid special values for this field are:
| *ALL | Returns the keys in the clustered hash table for all owners. This special value must be left justified. This is the default value. |
Reserved. This field will contain hexadecimal zeroes.
Storing user profile. The user profile that last stored the entry associated with this key.
Storing user profile requested.Specifies the storing user profile to use when returning the list of keys. The storing user profile is the user profile that last stored the entry. Valid special values for this field are:
| *ALL | Returns the keys in the clustered hash table for all user profiles. This special value must be left justified. This is the default value. |
User space library name. The name of the library that contains the user space.
User space name. The name of the user space that receives the list.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9810 E | Library &1 not found. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| CPFBB4D E | Cluster Resource Services cannot process the request. |
| CPFBD09 E | Clustered hash table server &1 not active or not responding. |
| CPFBD0A E | Clustered hash table server &1 internal error. |
| CPFBD0B E | Connection handle not active. |
API introduced: V5R2
[ Back to top | Cluster APIs | APIs by category ]