Retrieve Clustered Hash Table Entry (QcstRetrieveCHTEntry) API

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

Field Descriptions

Authority access level. This field describes who is allowed to retrieve and update the entry. Valid special values are:

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:

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