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

591 lines
17 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>Start Cluster Node (QcstStartClusterNode) 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>Start Cluster Node (QcstStartClusterNode) 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 Start Cluster Node (QcstStartClusterNode) API is used to start Cluster
Resource Services on a node in the cluster. If Cluster Resource Services is
successfully started on the node specified, the status of the node will be set
to Active. Beginning with
cluster version 3, a node can start itself and will be able to rejoin the
current active cluster, provided it can find an active node in the cluster.</p>
<p>When a node starts itself, instead of assuming itself as the only active
member in the cluster, it will first attempt to find a sponsor node from its
cluster membership list. Any active member in the cluster can be a sponsor
node. If the joiner finds a sponsor node, the start request will be forwarded
to the sponsor node. The joiner then will be started by the cluster (the
sponsor node), as if the start request was originated from the sponsor node
initially. The sponsor, along with other actives members in the cluster, will
process the start-joiner request. The joiner eventually rejoins the
cluster.</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 started
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
<img src="delta.gif" alt="Start of change">must have the
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>The node being started must exist in the cluster membership list.</li>
<li>If all nodes have a status of New, this API must be called from a program
running on the node on which the cluster was originally created.</li>
<li>The node to be started must be IP reachable (TCP/IP is active and the INETD
server is started).</li>
<li>The first time a node is started, this API must be called from a program
running on a node that is ACTIVE.</li>
<li>If all nodes in the cluster are not ACTIVE, this API can be called from a
program running on any node that had been previously ACTIVE.</li>
<li>For cluster version 2 or
lower, if any node that had been previously but not currently ACTIVE starts
itself, it will be started as a singleton cluster. Starting in cluster version
3, a node which starts itself will be able to rejoin the current active cluster
if it can find another active node in the cluster, otherwise it will become a
singleton cluster.</li>
<li>If the cluster is partitioned, this API may be used to start nodes in the
partition running the API.</li>
<li>The potential node version of the node being started 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 for all nodes in the
cluster by using the <a href=
"clcntlstci.htm">List Cluster Information (QcstListClusterInfo) API</a>. The
potential node version for the
local node can also be
retrieved by using the <a href="clcntrtvci.htm">Retrieve Cluster
Information(QcstRetrieveClusterInfo)</a> or the List Cluster Information
API.</li>
</ul>
<p>If the node being started is in a device domain, this API requires that
i5/OS option 41, HA Switchable Resources, is installed and a valid license key
exists on that node.</p>
<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 used in 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 to which the node belongs.</p>
</dd>
<dt><strong>Node entry</strong></dt>
<dd>INPUT; CHAR(*)
<p>The node id to be started.</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 array.
The possible format names are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#strn0100">STRN0100</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="strn0100">STRN0100 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>
<p><strong>Node id.</strong> A unique string of characters that identifies the
node to be started.<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="clust1a5.htm">Using Results
Information</a> and <a href="clust1a4.htm">Cluster APIs Use of User Queues</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">Error 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">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">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">CPFBB10 D</td>
<td align="left" valign="top">Specified cluster interface not defined on this
system.</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">CPFBB19 D</td>
<td align="left" valign="top">Cluster node &amp;1 in cluster &amp;2 already
started.</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">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">CPFBB79 D</td>
<td align="left" valign="top">Cluster node &amp;1 could not be started.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB7A D</td>
<td align="left" valign="top">Internal Cluster Resource Services mismatch.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB93 D</td>
<td align="left" valign="top">Base operating system option 41 not installed or
license key not valid.</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">CPIBB05 I</td>
<td align="left" valign="top">Cluster node &amp;1 started 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">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">CPFBB19 E</td>
<td align="left" valign="top">Cluster node &amp;1 in cluster &amp;2 already
started.</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">CPFBB98 E</td>
<td align="left" valign="top">Cluster node &amp;1 cannot be started by cluster
node &amp;2.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R4
<hr>
<center>
<table cellpadding="2" cellspacing="2" align="center">
<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>