Retrieve Clustered Hash Table Entry (QcstRetrieveCHTEntry) API
Required Parameter Group:
| 1 | Receiver variable | Output | Void(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Connection handle | Input | Char(16) |
| 4 | Format name | Input | Char(8) |
| 5 | Length of key | Input | Binary(4) |
| 6 | Key | Input | Char(*) |
| 7 | Error code | I/O | Void(*) |
Service Program: QCSTCHT
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Clustered Hash Table Entry (QcstRetrieveCHTEntry) API retrieves
an entry from the clustered hash table specified by the connection handle
parameter. The entry to be retrieved is identified by the key parameter. If the
entry exists, is not expired and the requesting user is authorized, the
information will be returned in the receiver parameter in the selected
format.
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
- Entry Authority Access Level (for restricted entries)
- *ALLOBJ or owner of the entry
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 of the parameter correctly. As a result, the API returns only the information 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 the 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.
- Connection handle
- INPUT; CHAR(16)
This is an active connection handle for the clustered hash table server. It is obtained by calling the Connect Clustered Hash Table (QcstConnectCHT) API.
- Format name
- INPUT; CHAR(8)
The content and format of the information that is returned. The possible format names are as follows:
CHTR0100 Entry information. For more information, see CHTR0100 Format.
- Length of key
- INPUT; BINARY(4)
The length of the key of the entry to be retrieved. This must be 16 bytes.
- Key
- INPUT; Char(*)
The key of the entry to be retrieved.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
CHTR0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to data |
| 12 | C | BINARY(4) | Length of data |
| 16 | 10 | BINARY(4) | Entry status |
| 20 | 14 | BINARY(4) | Authority access level |
| 24 | 18 | CHAR(10) | Owning user profile |
| 34 | 22 | CHAR(10) | Storing user profile |
| 44 | 2C | CHAR(*) | Data |
Field Descriptions
Authority access level. This field describes who is allowed to retrieve and update the entry. 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. |
| 1 | Any user can retrieve and update the entry associated with this key. |
Bytes available. The number of bytes of information available to be returned to the user.
Bytes returned. The number of bytes of information returned to the user.
Data. The data associated with the specified key.
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 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. The entry was marked in conflict when the cluster partition was merged together. For additional details on cluster node partitions, see Partition errors. The entry is not the same on all nodes in the clustered hash table domain. 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. |
Length of data. Length of the data associated with the specified key.
Offset to data. The offset from the beginning of the structure to the Data field.
Owning user profile. The user profile that originally stored the entry associated with this key.
Storing user profile. The user profile that last stored the
entry associated with this key.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of receiver variable not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| CPFBB4D E | Cluster Resource Services cannot process the request. |
| CPFBD06 E | Key not found in clustered hash table &1. |
| CPFBD07 E | User profile &1 not authorized to clustered hash table entry. |
| 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 ]