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

569 lines
16 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>Add Device Domain Entry (QcstAddDeviceDomainEntry) 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 -->
<!-- 030206 JETAYLOR fixed links to other IC topics -->
<!-- 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 Device Domain Entry (QcstAddDeviceDomainEntry) 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">Device domain 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">Device domain entry information</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Char(*)</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: QCSTDD<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 Device Domain Entry (QcstAddDeviceDomainEntry) API is used to add a
cluster node to the membership list of a device domain. There is no API to
create a device domain, the device domain will be created when the first
cluster node is added to it.</p>
<p>The following conditions apply to this API:</p>
<ul>
<li>This API can be called from a program running on any node in the cluster
which has a status of Active.</li>
<li>The node to be added and at least one current member of the device domain
must be Active. On certain conditions, all current members of the device domain
must be Active.</li>
<li>A node can only be a member of one device domain.</li>
<li>The API will fail if any member of the device domain to which the node
being added has a status of Partition.</li>
<li>The API will fail if it is the first node being added to the device domain
and any node in the cluster has a status of Partition.</li>
</ul>
<p>This API requires that i5/OS option 41, HA Switchable Resources, is
installed and a valid license key exists on all cluster nodes that will be in
the device domain.</p>
<p>For more information, see these Information Center topics:
<ul>
<li><a href="../rzaig/rzaigconceptsdevicedomain.htm">Device domains</a>
<li><a href="../rzaig/rzaigconceptsresilientdevices.htm">Resilient devices</a> and
device cluster resource groups
<li><a href="../rzaly/rzalyoverview.htm">
Auxiliary storage pools</a>
</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 that contains the node.</p>
</dd>
<dt><strong>Device domain name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the device domain to which the node is being added. It must be a
valid simple name. If the device domain does not currently exist, it will be
created.</p>
</dd>
<dt><strong>Device domain entry information</strong></dt>
<dd>INPUT; CHAR(*)
<p>Detailed information about device domain entry to be added to the device
domain.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the device domain entry information. The possible
format names are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#add0100">ADDD0100</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 <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>Device Domain Entry Information</h3>
<h3><a name="add0100">ADDD0100 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%">Length of data provided</td>
</tr>
<tr>
<td align="CENTER" valign="TOP">4</td>
<td align="CENTER" valign="TOP">4</td>
<td align="LEFT" valign="TOP">CHAR(8)</td>
<td align="LEFT" valign="TOP">Node id</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions</h3>
<p><strong>Length of data provided.</strong> This is the total length of data
provided (including this field) for the device domain entry information.</p>
<p><strong>Node id.</strong> A unique string of characters that identifies a
cluster node to be added to the device domain.</p>
<br>
<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">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">CPFBB02 D</td>
<td align="left" valign="top">Cluster &amp;1 does not exist.</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">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">CPFBB73 D</td>
<td align="left" valign="top">Cluster node &amp;1 could not be added to device
domain &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB74 D</td>
<td align="left" valign="top">Cluster node &amp;1 already a member of device
domain &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB78 E</td>
<td align="left" valign="top">Request cannot be processed in cluster
&amp;1.</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>
</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">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">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">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">CPFBB5F E</td>
<td align="left" valign="top">Field value within structure is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB70 E</td>
<td align="left" valign="top">API request &amp;1 not compatible with current
cluster version.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB73 E</td>
<td align="left" valign="top">Cluster node &amp;1 could not be added to device
domain &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB74 E</td>
<td align="left" valign="top">Cluster node &amp;1 already a member of device
domain &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB78 E</td>
<td align="left" valign="top">Request cannot be processed in cluster
&amp;1.</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>