510 lines
17 KiB
HTML
510 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>Store Clustered Hash Table Entry ( QcstStoreCHTEntry) API</title>
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- qctStoreElement.htm created by Vicki Morey on Wed Dec 6 2000 -->
|
|
<!-- Edited by Kersten Oct 2001 -->
|
|
<!-- End Header Records -->
|
|
<!-- -->
|
|
<!-- -->
|
|
<!-- -->
|
|
<!-- Begin Developer Note ========================================== -->
|
|
<!-- NOTE: If you are adding, changing, or removing ANY requirements -->
|
|
<!-- for this API chance are good that the GUI code need to change -->
|
|
<!-- also. The Cluster GUI code is built on top of this API and it -->
|
|
<!-- does a certain amount of explicit and implicit validation -->
|
|
<!-- checking of user data prior to the API call being made. Please -->
|
|
<!-- have the Cluster GUI developer check the -->
|
|
<!--/as400/v5r4m0.guix/cur/cmvc/java.pgm/ugcl.guix/com/ibm/as400/opnav/ugcl/ClGuiActionsManager.java/ClGuiActionsManager.java -->
|
|
<!-- part to determine if any Cluster GUI code changes are needed. -->
|
|
<!-- End Developer Note -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<!--Java sync-link-->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>Store Clustered Hash Table Entry (QcstStoreCHTEntry) API</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="TOP" width="10%">1</td>
|
|
<td align="LEFT" valign="TOP" width="50%">Connection handle</td>
|
|
<td align="LEFT" valign="TOP" width="20%">Input</td>
|
|
<td align="LEFT" valign="TOP" width="20%">Char(16)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="TOP">2</td>
|
|
<td align="LEFT" valign="TOP">Store description</td>
|
|
<td align="LEFT" valign="TOP">Input</td>
|
|
<td align="LEFT" valign="TOP">Void(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="TOP">3</td>
|
|
<td align="LEFT" valign="TOP">Format name</td>
|
|
<td align="LEFT" valign="TOP">Input</td>
|
|
<td align="LEFT" valign="TOP">Char(8)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="TOP">4</td>
|
|
<td align="LEFT" valign="TOP">Error code</td>
|
|
<td align="LEFT" valign="TOP">I/O</td>
|
|
<td align="LEFT" valign="TOP">Void(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Service Program: QCSTCHT<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Store Clustered Hash Table Entry (QcstStoreCHTEntry) API stores an entry
|
|
in the clustered hash table identified by the connection handle.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <a
|
|
href="../cl/strchtsvr.htm">STRCHTSVR</a> 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.</p>
|
|
|
|
<p>There is no encrypting of the information that is replicated and stored in
|
|
the clustered hash table.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Information stored in the clustered hash table is associated with a key. The
|
|
key can be generated using the <a href="clchtgenkey.htm">Generate Clustered
|
|
Hash Table Key (QcstGenerateCHTKey)</a> API or the user can generate their
|
|
own.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<br>
|
|
<h3>Restrictions:</h3>
|
|
|
|
<ul>
|
|
<li>A connection must have been established with the clustered hash table
|
|
server.</li>
|
|
|
|
<li>When this API is called, the clustered hash table server must be active on
|
|
the requesting node.</li>
|
|
|
|
<li>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 <a href="../rzaig/rzaigtroubleshootpartitionerrors.htm">Partition
|
|
errors</a>. The following are the recommendations if the clustered hash
|
|
table domain is partitioned:
|
|
|
|
<ul>
|
|
<li>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.</li>
|
|
|
|
<li>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.</li>
|
|
|
|
<li>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 <a href="clust1a6.htm">Cluster Version</a>.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>This API must be run under the same job that issued the <a href=
|
|
"clchtconnect.htm">Connect Clustered Hash Table (QcstConnectCHT)</a> API.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<dl>
|
|
<dt><em>Authority to update existing entry (for restricted entries)</em></dt>
|
|
|
|
<dd>*ALLOBJ or owner of the entry</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Connection handle</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(16)
|
|
|
|
<p>This is an active connection handle for the clustered hash table server. It
|
|
is obtained by calling the <a href="clchtconnect.htm">Connect Clustered Hash
|
|
Table (QcstConnectCHT)</a> API.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Store entry description</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>Detailed information for the store request. For more information, see <a
|
|
href="#chts0100">CHTS0100 Format</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Format name</strong></dt>
|
|
|
|
<dd>INPUT; Char(8)
|
|
|
|
<p>The content and format of the information that is stored. The possible
|
|
format names are as follows:</p>
|
|
|
|
<dl>
|
|
<dt><strong>CHTS0100</strong></dt>
|
|
|
|
<dd>Entry description. For more information, see <a href="#chts0100">CHTS0100
|
|
Format</a>.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The structure in which to return error information. For the format of the
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="chts0100"></a>CHTS0100 Format</h3>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Offset to key</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of key</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Offset to data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="center" valign="top">C</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Offset to additional fields</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="center" valign="top">14</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of additional fields</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Update option</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="center" valign="top">1C</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Authority access level</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Time to live</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">*</td>
|
|
<td align="center" valign="top">*</td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Key</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">*</td>
|
|
<td align="center" valign="top">*</td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Data</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<h3>Field Descriptions</h3>
|
|
|
|
<p><strong>Authority access level.</strong> 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 <a href="clust1a6.htm">Cluster Version</a>. Valid special
|
|
values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">The owning user profile or a user with *ALLOBJ
|
|
authority is allowed to retrieve and update the entry.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Any user can retrieve and update the entry
|
|
associated with this key.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Data.</strong> The data to be associated with the specified key.</p>
|
|
|
|
<p><strong>Key.</strong> The key that will be associated with the entry. A
|
|
unique key can be generated by using the <a href="clchtgenkey.htm">Generate
|
|
Clustered Hash Table Key (QcstGenerateCHTKey)</a> API. If the key already
|
|
exists, the update option field determines the action.</p>
|
|
|
|
<p><strong>Length of key.</strong> The length in bytes of the Key field. This
|
|
value must be 16.</p>
|
|
|
|
<p><strong>Length of data.</strong> The length in bytes of the Data field. This
|
|
length can be from 1 to 61000.</p>
|
|
|
|
<p><strong>Length of additional fields.</strong> The length in bytes of the
|
|
additional fields. This field must be zero.</p>
|
|
|
|
<p><strong>Offset to data.</strong> The bytes from the beginning of this
|
|
parameter to the Data field.</p>
|
|
|
|
<p><strong>Offset to key.</strong> The bytes from the beginning of this
|
|
parameter to the Key field.</p>
|
|
|
|
<p><strong>Offset to additional fields.</strong> The bytes from the beginning
|
|
of this parameter to the Additional fields. This field must be zero.</p>
|
|
|
|
<p><strong>Time to live.</strong> 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.</p>
|
|
|
|
<p><strong>Update option.</strong> 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 <a href=
|
|
"clust1a6.htm">Cluster Version</a>. This value is only for the given store
|
|
request. Valid special values for this field are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">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 <a href="clchtgenkey.htm">Generate
|
|
Clustered Hash Table Key (QcstGenerateCHTKey)</a> API to generate a unique key
|
|
for each store request when the current cluster version is 2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">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.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td width="15%" valign="top">CPF3C1D E</td>
|
|
<td width="85%" valign="top">Length specified in parameter &1 not
|
|
valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C19 E</td>
|
|
<td align="left" valign="top">Error occured with receiver variable specified.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C1E E</td>
|
|
<td align="left" valign="top">Required parameter &1 omitted.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C3C E</td>
|
|
<td align="left" valign="top">Value for parameter &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
|
<td align="left" valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
|
<td align="left" valign="top">Error(s) occurred during running of &1 API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBB26 E</td>
|
|
<td align="left" valign="top">Cluster Resource Services not active or not responding.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBB4D E</td>
|
|
<td align="left" valign="top">Cluster Resource Services cannot process the request.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBB5F E</td>
|
|
<td align="left" valign="top">Field value within structure is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBB70 E</td>
|
|
<td align="left" valign="top">Request &1 not compatible with current cluster version.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBD07 E</td>
|
|
<td align="left" valign="top">User profile &1 not authorized to clustered hash table
|
|
entry.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBD08 E</td>
|
|
<td align="left" valign="top">Key already exists in clustered hash table &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBD09 E</td>
|
|
<td align="left" valign="top">Clustered hash table server &1 not active or not
|
|
responding.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBD0A E</td>
|
|
<td align="left" valign="top">Clustered hash table server &1 internal error.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFBD0B E</td>
|
|
<td align="left" valign="top">Connection handle not active.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
API introduced: V5R2
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"clust1a1.htm">Cluster APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|