Store Clustered Hash Table Entry (QcstStoreCHTEntry) API

The Store Clustered Hash Table Entry (QcstStoreCHTEntry) API stores an entry in the clustered hash table identified by the connection handle.

The storage for the entry is not persistent. Not persistent means the storage for the entry is only known to the clustered hash table server on the local node and only available until the clustered hash table server is ended.

This request to store an entry is replicated to other nodes in the clustered hash table domain. The clustered hash table domain was defined using the STRCHTSVR command. Control will not be returned until the entry is stored in the clustered hash table on all active nodes in the clustered hash table domain.

There is no encrypting of the information that is replicated and stored in the clustered hash table.

When an entry is stored, a time to live value is specified. The entry can become expired, when the time to live value has expired. Expired entries will be removed when processing various functions. For example, when adding another cluster node to the domain of an existing clustered hash table server. The existing entries, if any, are replicated to the added cluster hash table domain node. Expired entries are removed from the clustered hash table during this process.

The user that originally stores the entry will be the owner of the entry. The owning user profile will be used in determining authorization to an entry.

Information stored in the clustered hash table is associated with a key. The key can be generated using the Generate Clustered Hash Table Key (QcstGenerateCHTKey) API or the user can generate their own.

An entry in the clustered hash table can be stored with restricted access. This provides the ability to restrict who is allowed to retrieve and update an entry. See authority access level field description for details on entry level authority.

Duplicate keys are not supported. An entry associated with an existing key can be updated if the requesting user is the owner of the entry or is authorized to the entry. See authority access level field description for details on entry level authority.

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.
• A partition can occur when communication is lost between the cluster nodes defined in the clustered hash table domain. For additional details on cluster node partitions, see Partition errors. The following are the recommendations if the clustered hash table domain is partitioned:
  • Updating the entry associated with an existing key should be restricted to one cluster partition. When the cluster version is 3 or greater, conflicts in the entry found when the cluster merges partitions will be resolved by selecting the entry from the clustered hash table domain node that was last updated. If it is indeterminate which clustered hash table domain node last updated the entry, all clustered hash table domain nodes will mark the entry in conflict. To resolve an entry in conflict use store to update the entry to the correct information.
  • Unique keys can be added from any cluster partition. However, Cluster Resource Services does not guarantee keys are unique between cluster partition. Managing unique keys across cluster partitions is the users responsibility.
  • When the current cluster version is 2 and merging cluster partitions, conflicts in the entry are not checked. Only unique keys between the cluster partitions will be replicated. For more information on the current cluster version see Cluster Version.
• This API must be run under the same job that issued the Connect Clustered Hash Table (QcstConnectCHT) API.

Authorities and Locks

Authority to update existing entry (for restricted entries)

*ALLOBJ or owner of the entry

Required Parameter Group

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.

Store entry description

INPUT; CHAR(*)

Detailed information for the store request. For more information, see CHTS0100 Format.

Format name

INPUT; Char(8)

The content and format of the information that is stored. The possible format names are as follows:

CHTS0100

Entry description. For more information, see CHTS0100 Format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

CHTS0100 Format

Field Descriptions

Authority access level. This field describes who is allowed to retrieve and update the entry associated with this key. This field must be 0 if the current cluster version is 2. For more information about the current cluster version, see Cluster Version. Valid special values are:

Data. The data to be associated with the specified key.

Key. The key that will be associated with the entry. A unique key can be generated by using the Generate Clustered Hash Table Key (QcstGenerateCHTKey) API. If the key already exists, the update option field determines the action.

Length of key. The length in bytes of the Key field. This value must be 16.

Length of data. The length in bytes of the Data field. This length can be from 1 to 61000.

Length of additional fields. The length in bytes of the additional fields. This field must be zero.

Offset to data. The bytes from the beginning of this parameter to the Data field.

Offset to key. The bytes from the beginning of this parameter to the Key field.

Offset to additional fields. The bytes from the beginning of this parameter to the Additional fields. This field must be zero.

Time to live. The time (in minutes) that the entry will be allowed to remain in the clustered hash table before expiring. This value can be 1 to 525600 (minutes in one year). A value of -1 can be specified to indicate the entry will never expire.

Update option. The action used when the specified key already exists. This field must be 0 if the current cluster version is 2. For more information about the current cluster version, see Cluster Version. This value is only for the given store request. Valid special values for this field are:

Error Messages