715 lines
25 KiB
HTML
715 lines
25 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>Retrieve Cluster Resource Services Information (QcstRetrieveCRSInfo)
|
||
|
|
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 -->
|
||
|
|
<!-- 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>
|
||
|
|
|
||
|
|
<h2>Retrieve Cluster Resource Services Information (QcstRetrieveCRSInfo)
|
||
|
|
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%">Receiver variable</td>
|
||
|
|
<td align="left" valign="top" width="20%">Output</td>
|
||
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Length of receiver variable</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">Cluster name</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(10)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</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">5</td>
|
||
|
|
<td align="left" valign="top">Error code</td>
|
||
|
|
<td align="left" valign="top">I/O</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program: QCSTCTL1<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Retrieve Cluster Resource Services Information (QcstRetrieveCRSInfo) API
|
||
|
|
retrieves information about the cluster performance and configuration
|
||
|
|
parameters on a requesting node. The requesting node does not need to be active
|
||
|
|
in the cluster to retrieve the information. This API may be called from a
|
||
|
|
cluster resource group exit program.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
<p>None</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Receiver variable</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>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 parameter correctly. As a result, the API returns only
|
||
|
|
the data that the area can hold.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of receiver variable</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
|
||
|
|
<p>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 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.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Cluster name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(10)
|
||
|
|
|
||
|
|
|
||
|
|
<p>The name of the cluster for which the information is being retrieved.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Format name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
|
||
|
|
<p>The content and format of the information that is returned. The possible
|
||
|
|
format names are as follows:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="25 75" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em><a href="#rcrs0100">RCRS0100</a></em></td>
|
||
|
|
<td align="left" valign="top">Returns information about the current settings of
|
||
|
|
the cluster performance and configuration parameters. These parameters may be
|
||
|
|
changed using the
|
||
|
|
<a href="clcntchgcrs.htm">Change Cluster Resource Services (QcstChgClusterResourceServices)
|
||
|
|
API</a>.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</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="rcrs0100">RCRS0100 Format</a></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%">Bytes returned</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">Bytes available</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="left" valign="top">CHAR(4)</td>
|
||
|
|
<td align="left" valign="top">Reserved</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">Configuration tuning level</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">16</td>
|
||
|
|
<td align="center" valign="TOP">10</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Receive/Send heartbeat timer ratio</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">24</td>
|
||
|
|
<td align="center" valign="TOP">18</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Maximum retry timer ratio</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">32</td>
|
||
|
|
<td align="center" valign="TOP">20</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Send heartbeat interval</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">40</td>
|
||
|
|
<td align="center" valign="TOP">28</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Retry timer value</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">48</td>
|
||
|
|
<td align="center" valign="TOP">30</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">CDAT protocol timeout interval</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">56</td>
|
||
|
|
<td align="center" valign="TOP">38</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Cluster recovery interval</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">64</td>
|
||
|
|
<td align="center" valign="TOP">40</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Maximum retry time</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">72</td>
|
||
|
|
<td align="center" valign="TOP">48</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Message fragment size</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">80</td>
|
||
|
|
<td align="center" valign="TOP">50</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Send queue overflow</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">88</td>
|
||
|
|
<td align="center" valign="TOP">58</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Number of bad messages threshold</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">96</td>
|
||
|
|
<td align="center" valign="TOP">60</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Number of ack messages threshold</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">104</td>
|
||
|
|
<td align="center" valign="TOP">68</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Unreachable heartbeat ack threshold</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">112</td>
|
||
|
|
<td align="center" valign="TOP">70</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Reachable heartbeat ack threshold</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">120</td>
|
||
|
|
<td align="center" valign="TOP">78</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Unreachable heartbeat threshold</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">128</td>
|
||
|
|
<td align="center" valign="TOP">80</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Reachable heartbeat threshold</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">136</td>
|
||
|
|
<td align="center" valign="TOP">88</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Delayed ack timer</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">144</td>
|
||
|
|
<td align="center" valign="TOP">90</td>
|
||
|
|
<td align="left" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Message send window</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">152</td>
|
||
|
|
<td align="center" valign="TOP">98</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Enable multicast</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">160</td>
|
||
|
|
<td align="center" valign="TOP">A0</td>
|
||
|
|
<td align="left" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Performance class</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP">168</td>
|
||
|
|
<td align="center" valign="TOP">A8</td>
|
||
|
|
<td align="LEFT" valign="TOP">BINARY(8)</td>
|
||
|
|
<td align="LEFT" valign="TOP">Ack remote fragments</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Field Descriptions</h3>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> Units and ranges for the fields described here may be
|
||
|
|
found in the <a href="clcntchgcrs.htm#fldset">Field Settings Range Table</a> located at the end of the Field
|
||
|
|
Descriptions section of the Change Cluster Resource
|
||
|
|
Services API.</p>
|
||
|
|
|
||
|
|
<p><strong>Ack remote fragments.</strong> Provides a switch to enable or
|
||
|
|
disable a cluster messaging level acknowledgment for receipt or each fragment
|
||
|
|
sent to a remote cluster node. Fragments are sent by the cluster messaging
|
||
|
|
service for each cluster message whose size is greater than the specified
|
||
|
|
message fragment size. Remote cluster nodes are defined to be any nodes not on
|
||
|
|
the local LAN (having a network or subnet IP address other than that of the
|
||
|
|
source node for the message). ACKing remote fragments may be desirable in those
|
||
|
|
few cases where low bandwidth gateways, routers, or bridges exist between local
|
||
|
|
and remote systems. The valid 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">Acknowledgments are disabled.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">Acknowledgments are enabled.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Bytes available.</strong> The number of bytes of data available to
|
||
|
|
be returned to the user.</p>
|
||
|
|
|
||
|
|
<p><strong>Bytes returned.</strong> The number of bytes of data returned to the
|
||
|
|
user.</p>
|
||
|
|
|
||
|
|
<p><strong>CDAT protocol timeout interval.</strong> The timeout value used for
|
||
|
|
distributing the Cluster Destination Address Table (CDAT) and synchronizing
|
||
|
|
cluster communications when doing a create cluster, add node, or start node
|
||
|
|
process. As the number of nodes in the cluster increases, the time required to
|
||
|
|
run this synchronizing protocol increases. This is a low level Cluster
|
||
|
|
Resource Services start-up protocol.</p>
|
||
|
|
|
||
|
|
<p><strong>Cluster recovery interval.</strong> The interval at which a cluster
|
||
|
|
node takes inventory of required recovery actions and attempts automatic
|
||
|
|
recovery as necessary. Those items checked are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Unreachable alternate point-point IP addresses for remote nodes.</li>
|
||
|
|
|
||
|
|
<li>Unreachable multicast IP address for the local subnet.</li>
|
||
|
|
|
||
|
|
<li>Partitioned nodes.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><strong>Configuration tuning level.</strong> Retrieves the cluster performance and configuration parameters settings. The individual
|
||
|
|
parameter settings for a fast path set option are defined in the <a href="clcntchgcrs.htm#fldset">Field Settings
|
||
|
|
Table</a> found in the Change Cluster Resource Service
|
||
|
|
API documentation. The valid
|
||
|
|
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">Settings have been adjusted individually and are
|
||
|
|
not currently set to one of the fast path settings.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">Adjustments are made to cluster communications to
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
decrease
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
the heartbeating
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
frequency
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
and increase the various message timeout
|
||
|
|
values. With fewer heartbeats and longer timeout values, the cluster will be
|
||
|
|
slower to respond (less sensitive) to communications failures.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">Normal default values are used for cluster
|
||
|
|
communications performance and configuration parameters.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
|
<td align="left" valign="top">Adjustments are made to cluster communications to
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
increase
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
the heartbeating
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
frequency
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
and decrease the various message timeout
|
||
|
|
values. With more frequent heartbeats and shorter timeout values, the cluster
|
||
|
|
will be quicker to respond (more sensitive) to communications failures.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Delayed ack timer.</strong> The timer used over inbound reliable
|
||
|
|
messages to force an acknowledgment for unacknowledged messages should the
|
||
|
|
sender not have requested an acknowledgment over the last delayed ack time
|
||
|
|
period. This timer is started on receipt of a reliable message and stopped when
|
||
|
|
an acknowledgment is sent for one or more unacknowledged messages.</p>
|
||
|
|
|
||
|
|
<p><strong>Enable multicast.</strong> The cluster communications infrastructure
|
||
|
|
makes use of User Datagram Protocol (UDP) multicast capabilities as the
|
||
|
|
preferred protocol for sending cluster management information between nodes in
|
||
|
|
a cluster. Where multicast capabilities are supported by the underlying
|
||
|
|
physical media, cluster communications will utilize the UDP multicast to send
|
||
|
|
management messaging from a given node to all local cluster nodes supporting
|
||
|
|
the same subnet address. Messages being sent to nodes on remote networks will
|
||
|
|
always be sent using UDP point to point capabilities. Cluster communications
|
||
|
|
does not rely on routing capability of multicast messages.</p>
|
||
|
|
|
||
|
|
<p>The multicast traffic supporting cluster management messaging tends by
|
||
|
|
nature to be bursty. Depending on the number of nodes on a given LAN
|
||
|
|
(supporting a common subnet address) and the complexity of the cluster
|
||
|
|
management structure that is chosen by the cluster administrator, cluster
|
||
|
|
related multicast packets can easily exceed 40 packets/second. Bursts of this
|
||
|
|
nature could have a negative impact on older networking equipment. One example
|
||
|
|
would be congestion problems on devices on the LAN serving as Simple Network
|
||
|
|
Management Protocol (SNMP) agents which need to evaluate each and every UDP
|
||
|
|
multicast packet. Some of the earlier networking equipment does not have
|
||
|
|
adequate bandwidth to keep up with this type of traffic. Insure that the
|
||
|
|
network administrator has reviewed the capacity of the networks to handle UDP
|
||
|
|
multicast traffic to make certain that clustering will not have a negative
|
||
|
|
impact on the health and performance of the networks over which it is chosen to
|
||
|
|
operate.</p>
|
||
|
|
|
||
|
|
<p>If the network does not wish to have the more efficient multicast
|
||
|
|
capabilities used, setting this field to FALSE (0) will disable the multicast
|
||
|
|
capabilities of the cluster and only point to point communications will be used
|
||
|
|
by the cluster messaging services. The valid 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">Multicast is disabled.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">Multicast is enabled.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Maximum retry time.</strong> Reliable messages are resent at
|
||
|
|
exponentially increasing times should they timeout (that is, not receive a timely
|
||
|
|
acknowledgment). The initial timeout value for a message is the Retry Timer
|
||
|
|
Value and each successive retry builds up by a factor of 2 until the Maximum
|
||
|
|
retry timer value is exceeded. For the default cases, a message would be sent,
|
||
|
|
resent 1 second later, then 2 seconds, 4 seconds, and finally 8 seconds. This
|
||
|
|
represents a total of 15 seconds following which attempts to use alternate IP
|
||
|
|
addressing are tried with the same timer values.</p>
|
||
|
|
|
||
|
|
<p><strong>Maximum retry timer ratio.</strong> Remote subnets (remote cluster
|
||
|
|
nodes on another LAN/WAN/BUS supporting a different subnet IP address than the
|
||
|
|
sending node) use an extended message timeout value which is based from the
|
||
|
|
Maximum retry time used for local subnets (local cluster nodes supporting the
|
||
|
|
same subnet IP address). For the default case, the Maximum retry time for a
|
||
|
|
local multicast message would be 8 seconds and for a remote point to point
|
||
|
|
message would be 8 x 8 = 64 seconds. This allows for network routing
|
||
|
|
considerations.</p>
|
||
|
|
|
||
|
|
<p><strong>Message fragment size.</strong> Cluster communications fragments its
|
||
|
|
own messages. This fragment size should be set consistent with the physical
|
||
|
|
media and routing capabilities throughout the network used for clustering. The
|
||
|
|
preferred settings allow for the largest fragment size possible that does not
|
||
|
|
exceed any of the hardware Maximum Transmission Units defined over the entire
|
||
|
|
path so that clustering does all of the fragmentation, not the intermediary
|
||
|
|
networks. The default is set to assume a minimum 1500 byte (less network header
|
||
|
|
space) Ethernet environment.</p>
|
||
|
|
|
||
|
|
<p><strong>Message send window.</strong> The number of messages allowed
|
||
|
|
outstanding without having received an acknowledgment. The higher the number,
|
||
|
|
the lower the message latency but the larger the required buffer space on a
|
||
|
|
node to save inbound messages.</p>
|
||
|
|
|
||
|
|
<p><strong>Number of ack messages threshold.</strong> The number of repeat
|
||
|
|
messages that are received over the course of a cluster recovery interval
|
||
|
|
before acknowledgments are sent to multiple source IP addresses for a given
|
||
|
|
node instead of just the current primary address for each message received.
|
||
|
|
While increasing the number of ACKs flowing, this reduces the message resends
|
||
|
|
and latency given that an intermittent communications condition is detected.
|
||
|
|
Eventually, one of the node addresses should be marked as failed and at cluster
|
||
|
|
recovery time, messaging will settle back down using single
|
||
|
|
acknowledgments.</p>
|
||
|
|
|
||
|
|
<p><strong>Number of bad messages threshold.</strong> The number of
|
||
|
|
undeliverable messages per cluster recovery interval allowed before a failing
|
||
|
|
status is assigned to a node's internet address. At this time, a secondary address
|
||
|
|
(if available) is assigned to be the new primary IP address for the subject
|
||
|
|
remote node.</p>
|
||
|
|
|
||
|
|
<p><strong>Performance class.</strong> The requested performance
|
||
|
|
characteristics of the cluster communications messaging protocol. Pacing is
|
||
|
|
selectively used for sending out fragments of large messages. Messages are
|
||
|
|
fragmented by the cluster messaging service at the specified message fragment
|
||
|
|
size. The pacing mechanism releases a set number of fragments to the underlying
|
||
|
|
physical layer, then delays, then releases a next set. This is to avoid over
|
||
|
|
running slower physical media. Local here refers to nodes on a local LAN.
|
||
|
|
Remote refers to messaging to cluster nodes on other than the local LAN. Valid
|
||
|
|
values for the performance class are as follows:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">Normal: Pacing applied to local and remote
|
||
|
|
fragments.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">High Throughput Local: Pacing applied to remote
|
||
|
|
fragments.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">High Throughput Local and Remote: No pacing of
|
||
|
|
any fragmented messages.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
|
<td align="left" valign="top">High Throughput Remote: Pacing applied to local
|
||
|
|
fragments.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Reachable heartbeat ack threshold.</strong> A node becomes reachable
|
||
|
|
(formerly having been marked as unreachable) from a Cluster Communications
|
||
|
|
heartbeating perspective if "Reachable heartbeat ack threshold" (or greater)
|
||
|
|
heartbeat message ACKs are received for the last "Reachable heartbeat
|
||
|
|
threshold" heartbeat messages sent to a node. For the default case, a node
|
||
|
|
becomes reachable if 3 or more of the last four heartbeats sent to the marked
|
||
|
|
unreachable node are now acknowledged.</p>
|
||
|
|
|
||
|
|
<p><strong>Reachable heartbeat threshold.</strong> See Reachable heartbeat ack
|
||
|
|
threshold field description.</p>
|
||
|
|
|
||
|
|
<p><strong>Receive/Send heartbeat timer ratio.</strong> Ratio of incoming
|
||
|
|
heartbeat messages expected from a neighboring node to the number of heartbeat
|
||
|
|
messages that are sent out. The send rate is always set higher to insure a
|
||
|
|
neighboring node's receive heartbeat timer does not fire under normal
|
||
|
|
operational circumstances.</p>
|
||
|
|
|
||
|
|
<p><strong>Reserved.</strong> This field will contain hexadecimal zeroes.</p>
|
||
|
|
|
||
|
|
<p><strong>Retry timer value.</strong> See Maximum retry time field
|
||
|
|
description.</p>
|
||
|
|
|
||
|
|
<p><strong>Send heartbeat interval.</strong> The interval at which a low level
|
||
|
|
Cluster Communications heartbeat message is sent to a neighboring node.</p>
|
||
|
|
|
||
|
|
<p><strong>Send queue overflow.</strong> The maximum number of messages that
|
||
|
|
are allowed to be queued up in a Cluster Communications outbound message queue.
|
||
|
|
The CC send queues are distributed amongst the various Distributed Activity
|
||
|
|
(DA) groups. The larger the number, the greater the memory resources that are
|
||
|
|
required to support cluster messaging. If a send queue overflow is hit for a
|
||
|
|
given DA, the inability to send a message could lead to the termination of that
|
||
|
|
DA resulting from the lack of resources on a node.</p>
|
||
|
|
|
||
|
|
<p><strong>Unreachable heartbeat ack threshold.</strong> A reachable node
|
||
|
|
becomes unreachable from a Cluster Communications heartbeating perspective if
|
||
|
|
"Unreachable heartbeat ack threshold" heartbeat message ACKs (or less) are
|
||
|
|
received for the last "Unreachable heartbeat threshold" heartbeat messages sent
|
||
|
|
to a node. For the default case, a node becomes unreachable if one or less of
|
||
|
|
the last four heartbeats sent to the marked reachable node are
|
||
|
|
acknowledged.</p>
|
||
|
|
|
||
|
|
<p><strong>Unreachable heartbeat threshold.</strong> See Unreachable heartbeat
|
||
|
|
ack threshold field description.<br>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<p>Messages that are delivered through the error code parameter are listed
|
||
|
|
here.</p>
|
||
|
|
|
||
|
|
<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">CPF3C1E E</td>
|
||
|
|
<td width="85%" valign="top">Required parameter &1 omitted.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C21 E</td>
|
||
|
|
<td align="left" valign="top">Format name &1 is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C24 E</td>
|
||
|
|
<td align="left" valign="top">Length of the receiver variable is 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">CPF9872 E</td>
|
||
|
|
<td align="left" valign="top">Program or service program &1 in library &2 ended.
|
||
|
|
Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFBB02 E</td>
|
||
|
|
<td align="left" valign="top">Cluster &1 does not exist.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFBB70 E</td>
|
||
|
|
<td align="left" valign="top">API request &1 not compatible with current cluster
|
||
|
|
version.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R1
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|