friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/clcntaddcne.htm

661 lines
20 KiB
HTML
Raw Permalink Blame History

<!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>Add Cluster Node Entry (QcstAddClusterNodeEntry) API</title>
<!-- Begin Header Records ========================================== -->
<!-- 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 -->
<!-- CLUST2A SCRIPT A converted by B2H R4.1 (346) (CMS) by NLJONES at -->
<!-- RCHVMX on 24 Feb 1999 at 17:15:51 -->
<!-- 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>Add Cluster Node Entry (QcstAddClusterNodeEntry) API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;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%">Request handle</td>
<td align="LEFT" valign="TOP" width="20%">Output</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">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">3</td>
<td align="LEFT" valign="TOP">Node entry</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Char(*)</td>
</tr>
<tr>
<td align="center" valign="TOP">4</td>
<td align="LEFT" valign="TOP">Start indicator</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="TOP">5</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">6</td>
<td align="LEFT" valign="TOP">Results information</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Char(30)</td>
</tr>
<tr>
<td align="center" valign="TOP">7</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>
&nbsp;&nbsp;Service Program: QCSTCTL<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Add Cluster Node Entry (QcstAddClusterNodeEntry) API is used to add a
node to the membership list of an existing cluster.</p>
<p>If the "Start Indicator" parameter is set to 0, the node that is being added
will have a status of New and Cluster Resource Services will not be started on
that node. The <a href="clcntstcn.htm">Start Cluster Node
(QcstStartClusterNode) API</a> can be called from a program running on one of
the active nodes in the cluster to start Cluster Resource Services on a node
that does not have a status of Active.</p>
<p>If the "Start Indicator" parameter on this API is set to 1, Cluster Resource
Services will be started on the node that is being added. If Cluster Resource
Services is successfully started, the status for the added node will be set to
Active. If the Cluster Resource Services cannot be started, the status of the
added node will be set to New.</p>
<p>During the activation of Cluster Resource Services, the allow add to cluster
(ALWADDCLU) network attribute is checked to see whether the node being added
should be part of the cluster and whether to validate the cluster request
through the use of X.509 digital certificates. If validation is required, the
requesting node and the node being added must have the
<img src="delta.gif" alt="Start of change">software required for
<a href="..//rzain/rzainplanssl.htm">
SSL</a> installed on the systems.
<img src="deltaend.gif" alt="End of change">
</p>
<p>The following conditions apply to this API:</p>
<ul>
<li>A node cannot add itself to a cluster. It must be added from a node in the
cluster that has a status of Active. If Cluster Resource Services has not been
started on any of the nodes in the cluster, this API must be called from a
program running on the node where the cluster was originally created, and the
start indicator must be set to 0.</li>
<li>The node being added to the cluster must not already be a member of this or
any other cluster. A node can be a member of only one cluster.</li>
<li>If the start indicator is set to 1, the node must be IP reachable (TCP/IP
active and the INETD server started).</li>
<li>The API will fail if any node in the cluster has a status of
Partition.</li>
<li>If the start indicator is set to 1, the potential node version of the node
being added must be equal to the current cluster version or up to one level
higher than the current cluster version. The potential node version and the
current cluster version can be retrieved by using the <a href=
"clcntlstci.htm">List Cluster Information (QcstListClusterInfo) API</a>. The
potential node version can also be retrieved by using the <a href=
"clcntrtvci.htm">Retrieve Cluster Information (QcstRetrieveClusterInfo)
API</a>.</li>
</ul>
<p>This API operates in an asynchronous mode.
See <a href="clust1a3.htm#HDRASYMOD">Behavior of Cluster Resource Services APIs</a> for
more information.</p>
<p><strong>Restriction:</strong> This API cannot be called from a cluster
resource group exit program.</p>
<br>
<h3>Authorities and Locks</h3>
<p>The program that calls this API must be running under a user profile with
*IOSYSCFG special authority.</p>
<dl>
<dt><em>User Queue Authority</em></dt>
<dd>*OBJOPR and *ADD</dd>
<dt><em>User Queue Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>User Queue Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Request handle</strong></dt>
<dd>OUTPUT; CHAR(16)
<p>A unique string or handle that identifies this API call. It is used to
associate this call to any responses placed on the user queue specified in the
results information parameter.</p>
</dd>
<dt><strong>Cluster name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the cluster to which the node is being added. It must be a valid
simple name.</p>
</dd>
<dt><strong>Node entry</strong></dt>
<dd>INPUT; CHAR(*)
<p>This parameter contains the information associated with the node which is
being added to the cluster membership list.</p>
</dd>
<dt><strong>Start indicator</strong></dt>
<dd>INPUT; BINARY(4)
<p>An indicator which specifies whether or not Cluster Resource Services is to
be started on the node that is being added.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Cluster Resource Services will not be started on
the node.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Cluster Resource Services will be started on the
node.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information supplied for the node entry. The
possible format names are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#addn0100">ADDN0100</a></em></td>
<td align="left" valign="top">Node entry information</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Results information</strong></dt>
<dd>INPUT; CHAR(30)
<p>A library qualified user queue name followed by a reserved field.</p>
<p>Library qualified user queue: A user queue, which exists on the node from
which the API was called, that receives results information after the function
has completed on all active nodes in the cluster. See the <strong>Usage
Notes</strong> section of this API for a description of the data that is placed
on this queue. This is a 20 character field. The first 10 characters contain
the user queue name and the second 10 characters contain the user queue library
name. No special values are supported. QTEMP, *LIBL, and *CURLIB are not valid
for the library name. The attributes of this user queue must be keyed.</p>
<p>Reserved. The last 10 characters of results information are reserved and
must be set to hexadecimal zero.</p>
</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="addn0100">ADDN0100 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%">CHAR(8)</td>
<td align="LEFT" valign="TOP" width="60%">Node id</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 first cluster interface entry</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">Number of cluster interfaces</td>
</tr>
<tr>
<td align="LEFT" valign="TOP" colspan="2">This field repeats for each number of
cluster interfaces.</td>
<td align="LEFT" valign="TOP">CHAR(16)</td>
<td align="LEFT" valign="TOP">Cluster interface address</td>
</tr>
</table>
<br>
<h3>Field Descriptions</h3>
<p><strong>Cluster interface address.</strong> The cluster interface address is
an IP address that is used by Cluster Resource Services to communicate with
other nodes in the cluster. The address is in dotted decimal format and is a
null-terminated string.</p>
<p><strong>Note:</strong> Cluster Resource Services uses existing IP interfaces
configured for an iSeries. See <a href="../rzai2/rzai2kickoff.htm">TCP/IP</a> for
instructions for configuring IP interfaces on the iSeries. The IP addresses
defined as cluster interface addresses can be used by other applications. If an
IP address is reconfigured through the TCP/IP configuration functions, the <a
href="clcntchgcne.htm">Change Cluster Node Entry (QcstChangeClusterNodeEntry)
API</a> should be used to make the corresponding change to the cluster
interface address. A mismatch will cause cluster errors to occur.</p>
<p><strong>Node id.</strong> A valid simple name that uniquely identifies the
node.</p>
<p><strong>Number of cluster interfaces.</strong> The number of IP interfaces
associated with a cluster node. It is limited to 1 or 2 entries only.</p>
<p><strong>Offset to first cluster interface entry.</strong> The offset from
the beginning of the structure to the first cluster interface address
entry.</p>
<h3><a name="usage_notes">Usage Notes</a></h3>
<p><strong>Results Information User Queue.</strong> Asynchronous results are
returned to a user queue specified by the Results Information parameter of the
API. See <a href="clust1a4.htm">Cluster APIs Use of User Queues</a> and <a
href="clust1a5.htm">Using Results Information</a> for details on how to create
the results information user queue, the format of the entries, and how to use
the data placed on the queue. The data is sent to the user queue in the form of
a message identifier and the substitution data for the message (if any exists).
The following identifies the data sent to the user queue (excluding the message
text).</p>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPCBB01 C</td>
<td width="85%" valign="top">Cluster Resource Services API &amp;1
completed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2204 D</td>
<td align="left" valign="top">User profile &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 D</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB01 D</td>
<td align="left" valign="top">Cluster already exists.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB05 D</td>
<td align="left" valign="top">Cluster node &amp;1 cannot be started.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB07 D</td>
<td align="left" valign="top">Node &amp;1 could not be added to cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB11 D</td>
<td align="left" valign="top">Cluster node &amp;1 already exists in cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB12 D</td>
<td align="left" valign="top">Cluster node &amp;1 in cluster &amp;2 could not be
started.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB13 D</td>
<td align="left" valign="top">Cluster interface address &amp;1 already assigned to cluster
node &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB17 D</td>
<td align="left" valign="top">&amp;1 API cannot be processed in cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB24 D</td>
<td align="left" valign="top">Node &amp;1 not participating in &amp;2 API protocol.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB2D D</td>
<td align="left" valign="top">Timeout detected while waiting for a response.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB46 D</td>
<td align="left" valign="top">Cluster Resource Services internal error.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB54 D</td>
<td align="left" valign="top">Node &amp;1 not be added to the cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB71 D</td>
<td align="left" valign="top">Potential node version &amp;1 of node &amp;2 not
compatible.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB96 D</td>
<td align="left" valign="top">Internal device domain mismatch.</td>
</tr>
<tr>
<td align="left" valign="top">CPIBB03 I</td>
<td align="left" valign="top">Cluster node &amp;1 added to cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPIBB05 I</td>
<td align="left" valign="top">Cluster node &amp;1 started in cluster &amp;2.</td>
</tr>
</table>
<h3>Error Messages</h3>
<p>Messages that are delivered through the error code parameter are listed
here. The data (messages) sent to the results information user queue are listed
in the <a href="#usage_notes">Usage Notes</a> above.</p>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Message Text</th>
</tr>
<tr>
<td valign="top" width="15%">CPF2113 E</td>
<td valign="top" width="85%">Cannot allocate library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1E E</td>
<td align="left" valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C29 E</td>
<td align="left" valign="top">Object name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C39 E</td>
<td align="left" valign="top">Value for reserved field 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 &amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9804 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF980C E</td>
<td align="left" valign="top">Object &amp;1 in library &amp;2 cannot be in an independent
auxiliary storage pool.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB02 E</td>
<td align="left" valign="top">Cluster &amp;1 does not exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB04 E</td>
<td align="left" valign="top">Number of cluster interface addresses not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB07 E</td>
<td align="left" valign="top">Node &amp;1 could not be added to cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB0D E</td>
<td align="left" valign="top">Cluster interface address &amp;1 specified more than
once.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB11 E</td>
<td align="left" valign="top">Cluster node &amp;1 already exists in cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB13 E</td>
<td align="left" valign="top">Cluster interface address &amp;1 already assigned to cluster
node &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB17 E</td>
<td align="left" valign="top">&amp;1 API cannot be processed in cluster &amp;2.</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">CPFBB32 E</td>
<td align="left" valign="top">Attributes of user queue &amp;1 in library &amp;1 are not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB39 E</td>
<td align="left" valign="top">Current user does not have IOSYSCFG special authority.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB44 E</td>
<td align="left" valign="top">&amp;1 API cannot be called from a cluster resource group exit
program.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB46 E</td>
<td align="left" valign="top">Cluster Resource Services internal error.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB55 E</td>
<td align="left" valign="top">Value &amp;1 specified for start indicator not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB57 E</td>
<td align="left" valign="top">Offset to cluster interface entry not valid.</td>
</tr>
<tr>
<td align="left" valign="top">TCP1901 E</td>
<td align="left" valign="top">Internet address &amp;1 not valid.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R4
<hr>
<center>
<table cellpadding="2" cellspacing="2" width="600">
<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>
Reference in New Issue View Git Blame Copy Permalink