ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/clcntrmvcne.htm

513 lines
15 KiB
HTML
Raw Permalink Normal View History

2024-04-02 14:02:31 +00:00
<!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>Remove Cluster Node Entry (QcstRemoveClusterNodeEntry) 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>Remove Cluster Node Entry (QcstRemoveClusterNodeEntry) 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">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">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">6</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 Remove Cluster Node Entry (QcstRemoveClusterNodeEntry) API is used to
remove a node from a cluster. The node specified will be removed from the
cluster membership list and will no longer be considered a member of the
cluster. The node will also be removed from the device domain it belongs to.
The cluster resource group (CRG) objects on the node being removed are deleted
only if the node has a status of Active or if the program that calls this API
is running on the node that is being removed.</p>
<p>The following conditions apply to this API:</p>
<ul>
<li>A node can be removed regardless of its status.</li>
<li>If this API is called from a program running on a node with a status of
Active, any node in the cluster can be removed.</li>
<li>If this API is called from a program running on a node where cluster
resource services is Inactive, only the node running the API can be
removed.</li>
<li>If all of the nodes in the cluster have a status of New, this API can only
be called from a program running on the node where the cluster was originally
created.</li>
<li>To remove a node that is not Active, this API should be called from a
program running on the node being removed and on a node in the cluster that is
Active.</li>
<li>There must be more than one node in the membership list.</li>
<li>If the node being removed is Active, the cluster resource group exit
program will be passed an action code of Remove Node (12). The exit program on
all other nodes in the recovery domain of the cluster resource group will be
passed an action code of Failover (9). If the node being removed is the primary
node for a device cluster resource group, ownership of the hardware associated
with the cluster resource group will be moved to a backup node. If there are no
backup nodes or all the backup nodes are either inactive or in a different
cluster partition, ownership of the hardware is left with the node being
removed.</li>
<li>If the node being removed is Inactive, the cluster resource group exit
program will be passed an action code of Remove Node (12) on all nodes in the
recovery domain. Ownership of hardware associated with a device cluster
resource group will not be changed but will remain with the node being
removed.</li>
<li>If the node being removed is Inactive, the cluster resource group exit
program will be called with an action code of Delete Command (14) on the node
being removed if the API is run on the node being removed.</li>
<li>If the node being removed is a member of a device domain and it later will
be added back to a cluster, the node most likely has to be IPLed before it can
be added to any device domain. One example of this situation would be if a
device description for an auxiliary storage pool has been varied on since the
last IPL.</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.<br>
</p>
<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 from which the node will be removed.</p>
</dd>
<dt><strong>Node entry</strong></dt>
<dd>INPUT; CHAR(*)
<p>This parameter contains the information associated with the node which is
being removed from the cluster membership list. The size of this parameter is
implied by the format name.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information supplied in the node entry. The
possible format names are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#rmvn0100">RMVN0100</a></em></td>
<td align="left" valign="top">Node id 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 <a href=
"#usage_notes">Usage Notes</a> 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="rmvn0100">RMVN0100 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>
</table>
<br>
<h3>Field Descriptions</h3>
<p><strong>Node id.</strong> A unique string of characters that identifies a
node.</p>
<h3><a name="usage_notes">Usage Notes</a></h3>
<h4>Results Information User Queue</h4>
<p>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">CPF18BA D</td>
<td align="left" valign="top">Errors occurred with subsystem.</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">CPFBB09 D</td>
<td align="left" valign="top">Cluster node &amp;1 does not exist 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
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">CPFBB58 D</td>
<td align="left" valign="top">Cluster node &amp;1 cannot be removed from
cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPIBB04 I</td>
<td align="left" valign="top">Cluster node &amp;1 removed from cluster
&amp;2.</td>
</tr>
</table>
<br>
<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">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF2113 E</td>
<td width="85%" valign="top">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">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">CPFBB09 E</td>
<td align="left" valign="top">Cluster node &amp;1 does not exist 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 used within 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">CPFBB58 E</td>
<td align="left" valign="top">Cluster node &amp;1 cannot be removed from
cluster &amp;2.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R4
<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>