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:


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 ]