Store Clustered Hash Table Entry (QcstStoreCHTEntry) API
Required Parameter Group:
1 | Connection handle | Input | Char(16) |
2 | Store description | Input | Void(*) |
3 | Format name | Input | Char(8) |
4 | Error code | I/O | Void(*) |
Service Program: QCSTCHT
Default Public Authority: *USE
Threadsafe: Yes
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 by using the Start Clustered Hash Table Server (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 by 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
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Offset to key |
4 | 4 | BINARY(4) | Length of key |
8 | 8 | BINARY(4) | Offset to data |
12 | C | BINARY(4) | Length of data |
16 | 10 | BINARY(4) | Offset to additional fields |
20 | 14 | BINARY(4) | Length of additional fields |
24 | 18 | BINARY(4) | Update option |
28 | 1C | BINARY(4) | Authority access level |
32 | 20 | BINARY(4) | Time to live |
* | * | CHAR(*) | Key |
* | * | CHAR(*) | Data |
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:
0 | The owning user profile or 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. |
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:
0 | Do not allow updating the entry associated with the specified key. If the specified key already exists in the clustered hash table an error will be issued. The behavior for this option will vary if the current cluster version is 2. The uniqueness of the key may not always be detected. To ensure uniqueness, use the Generate Clustered Hash Table Key (QcstGenerateCHTKey) API to generate a unique key for each store request when the current cluster version is 2. |
1 | Allow updating the entry associated with the specified key if the specified key already exists and the requesting user is authorized to update the information. See the authority access level field for details on authorization to update an entry. |
Error Messages
Message ID | Error Message Text |
---|---|
CPF3C1D E | Length specified in parameter &1 not valid. |
CPF3C19 E | Error occured with receiver variable specified. |
CPF3C1E E | Required parameter &1 omitted. |
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. |
CPFBB5F E | Field value within structure is not valid. |
CPFBB70 E | Request &1 not compatible with current cluster version. |
CPFBD07 E | User profile &1 not authorized to clustered hash table entry. |
CPFBD08 E | Key already exists in clustered hash table &1. |
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 ]