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

546 lines
16 KiB
HTML
Raw 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>End Cluster Node (QcstEndClusterNode) 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>End Cluster Node (QcstEndClusterNode) 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">Option</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 End Cluster Node (QcstEndClusterNode) API is used to end Cluster
Resource Services on one or all the nodes in the membership list of an existing
cluster. The status of each node that is ended is set to Inactive. In order to
restart Cluster Resource Services on nodes that have been ended, the <a href=
"clcntstcn.htm">Start Cluster Node (QcstStartClusterNode) API</a> is used.</p>
<p>When a node in the cluster is ended, it is not removed from the cluster
membership list.</p>
<p>If all the nodes in the cluster are being ended, cluster resource group exit
programs will not be called with an indication to failover.</p>
<p>The following conditions apply to this API:</p>
<ul>
<li>The node being ended must be ACTIVE.</li>
<li>This API can be called from a program running on the node which is to be
ended, or it can be called from a program running on any node in the cluster
which has a status of Active.</li>
<li>The cluster resource group exit program on the node being ended will be
called with an action code of End Node (16). The exit program on all other
nodes in the recovery domain will be called with an action code of Failover
(9).</li>
<li>If this API is called when the cluster is partitioned, only nodes in the
partition running the API will process the request.</li>
<li>The recovery domain of cluster resource groups on the node that had ended
will indicate a node status of Active even though the node is Inactive. For all
the other nodes in the recovery domain, the status of the node will be
Inactive. If the node being ended is the primary node for an active device
cluster resource group, ownership of the hardware associated with the cluster
resource group will be moved to a backup node. If the cluster resource group is
not active, there are no backup nodes, or all backup nodes are either inactive
or in a different cluster partition, the ownership of the hardware is left with
the node being ended.</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 that contains the node or nodes being ended.</p>
</dd>
<dt><strong>Node entry</strong></dt>
<dd>INPUT; CHAR(*)
<p>This parameter contains the node id being ended. It is ignored if the
special value *ALL is specified as the node id.</p>
</dd>
<dt><strong>Option</strong></dt>
<dd>INPUT; BINARY(4)
<p>The method used to end the node:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Immediate. The request to end replication for all
CRGs on the node will be processed immediately.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Controlled. Pending CRG actions will complete
before the request to end replication is processed.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information supplied in the node entry array.
The possible format names are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#endn0100">ENDN0100</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="endn0100">ENDN0100 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>
<br>
<h3>Field Descriptions</h3>
<strong>Node id.</strong>
<p>A valid simple name that uniquely identifies a node. A special value of *ALL
can be specified to end all nodes in a cluster. The special value must be
left-justified.<br>
</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">Error 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">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">CPFBB1C D</td>
<td align="left" valign="top">Cluster node &amp;1 in cluster &amp;2 cannot be
ended.</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">CPIBB06 I</td>
<td align="left" valign="top">Cluster node &amp;1 ended in 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">CF980C 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">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">CPFBB1C E</td>
<td align="left" valign="top">Cluster node &amp;1 in cluster &amp;2 already
ended.</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">CPFBB59 E</td>
<td align="left" valign="top">Value &amp;1 specified for option not valid.</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>