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

607 lines
18 KiB
HTML

<!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 Resource Group (QcstEndClusterResourceGroup) 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 -->
<!-- CLUST3A SCRIPT A converted by B2H R4.1 (346) (CMS) by NLJONES at -->
<!-- RCHVMX on 24 Feb 1999 at 17:23:22 -->
<!-- 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 Resource Group (QcstEndClusterResourceGroup) 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">Cluster resource group 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">Exit program data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(256)</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: QCSTCRG2<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 Resource Group (QcstEndClusterResourceGroup) API
disables resiliency of the specified
cluster resource group. If an exit program is specified for the cluster
resource group, the cluster resource group exit program is called with an
action code of End (4) on each active node in the recovery domain.
</p>
<p>When the exit program is called, the cluster resource group status is set to
End Cluster Resource Group Pending (550). Successful completion of the exit
program sets the cluster resource group status Inactive (20). After the exit program completes successful, for
an application cluster resource group:</p>
<ul>
<li>The current exit program job will be cancelled with the *IMMED option</li>
<li>The takeover IP interface for the cluster resource group will be
ended.</li>
</ul>
If the exit program fails and the original state of the cluster resource group
cannot be recovered, the cluster resource group status is set to Indoubt (30).
<p>Ending a device cluster resource group will not change the ownership of
devices. The devices remain on whatever nodes owns them at the time the API is
run. Also, the devices are not varied off when the cluster resource group is
ended. </p>
<P><img src="delta.gif" alt="Start of change">
Ending a peer cluster resource group will end the access point for cluster
resources on all nodes defined as a peer node.<img src="deltaend.gif" alt="End of change">
<p>This API requires:</p>
<ol>
<li>Cluster Resource Services started on the node processing the request.</li>
<li>Cluster resource group status of Active (10) or Indoubt (30).</li>
</ol>
<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>Cluster Resource Group Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>Cluster Resource Group Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Cluster Resource Group Lock</em></dt>
<dd>*EXCL</dd>
<dt><em>Exit Program Authority <img src="delta.gif" alt="Start of change"> (applies
to user profile calling the API and user
profile to run the exit program)<img src="deltaend.gif" alt="End of change"> </em></dt>
<dd>*EXECUTE</dd>
<dt><em>Exit Program Library Authority <img src="delta.gif" alt="Start of change"> (applies to user profile calling the API and user
profile to run the exit program)<img src="deltaend.gif" alt="End of change"> </em></dt>
<dd>*EXECUTE</dd>
<dt><em>User Profile Authority <img src="delta.gif" alt="Start of change">(applies to user profile to run the exit program)<img src="deltaend.gif" alt="End of change"></em></dt>
<dd>*USE</dd>
<dt><em>Request Information User Queue Authority</em></dt>
<dd>*OBJOPR, *ADD</dd>
<dt><em>Request Information User Queue Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Request Information 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 containing the cluster resource group.</p>
</dd>
<dt><strong>Cluster resource group name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the cluster resource group which will be ended.</p>
</dd>
<dt><strong>Exit program data</strong></dt>
<dd>INPUT; CHAR(256)
<p>256 bytes of data that is passed to the cluster resource group exit program
when it is called. This parameter may contain any scalar data except pointers.
For example, it can be used to provide state information. This data will be
stored with the specified cluster resource group and copied to all nodes in the
recovery domain. Pointers in this area will not resolve correctly on all nodes
and should not be placed in the data. See <a href="clrgexit.htm">Cluster
Resource Group Exit Program</a> for information about the cluster resource
group exit program. The data specified will replace the existing exit program
data stored with the cluster resource group. If blanks are specified, then the
exit program data stored with the cluster resource group will be cleared. This
parameter must be set to *SAME if no exit program is specified for the cluster
resource group. The following special value can be used:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*SAME</em></td>
<td align="left" valign="top">The exit program data stored with the cluster
resource group specified will be passed to the exit program. This must be left
justified.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Results information</strong></dt>
<dd>INPUT; CHAR(30)
<p>This parameter identifies a qualified user queue field and is followed by a
reserved field.</p>
<p>Qualified user queue: Completion information is returned to this user queue,
which exists on the node from which the API was called, after the function has
completed. 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, *CURLIB are
not valid library names. The attributes of this user queue must be keyed.
</p>
<p>Reserved: The last 10 characters of the 30-character results information are
reserved. Each character in this field 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="usage_notes">Usage Notes</a></h3>
<h3>Results Information User Queue</h3>
<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">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">CPF2113 E</td>
<td align="left" valign="top">Cannot allocate library &amp;1.</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">CPF9801 D</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 D</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 D</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9804 D</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 D</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB0F D</td>
<td align="left" valign="top">Cluster resource group &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">CPFBB18 D</td>
<td align="left" valign="top">Request &amp;1 not allowed for cluster resource group
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB2C D</td>
<td align="left" valign="top">Attributes of exit program &amp;1 in library &amp;2 are not
valid.</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">CPFBB2E D</td>
<td align="left" valign="top">Job submission failed for cluster resource group &amp;1 in
cluster &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB32 D</td>
<td align="left" valign="top">Attributes of user queue &amp;1 are not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB47 D</td>
<td align="left" valign="top">Cluster Resource Services ended abnormally.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB48 D</td>
<td align="left" valign="top">Cluster Resource Services error detected.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB6E E</td>
<td align="left" valign="top">Exit program data cannot be specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPIBB10 D</td>
<td align="left" valign="top">Cluster resource group exit program &amp;1 in library &amp;2
on node &amp;3 failed.</td>
</tr>
<tr>
<td align="left" valign="top">TCP1B61 D</td>
<td align="left" valign="top">Unable to determine if &amp;1 interface ended.&amp;2
successful (&amp;3 %).</td>
</tr>
<tr>
<td align="left" valign="top">TCP1B62 D</td>
<td align="left" valign="top">Cannot determine if &amp;1 interface ended.</td>
</tr>
<tr>
<td align="left" valign="top">TCP1B65 D</td>
<td align="left" valign="top">&amp;2 interface not ended. Reason &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">TCP1B72 D</td>
<td align="left" valign="top">&amp;1 interface not ended. &amp;1 interface is not
active.</td>
</tr>
<tr>
<td align="left" valign="top">TCP1B73 D</td>
<td align="left" valign="top">&amp;1 interface not ended. &amp;1 interface not defined in
TCP/IP configuration.</td>
</tr>
<tr>
<td align="left" valign="top">TCP1B74 D</td>
<td align="left" valign="top">&amp;1 interface not ended. Line description &amp;2 not
found.</td>
</tr>
<tr>
<td align="left" valign="top">TCP1B85 D</td>
<td align="left" valign="top">&amp;1 interface not ended.</td>
</tr>
<tr>
<td align="left" valign="top">TCP9999 D</td>
<td align="left" valign="top">Internal system error in program &amp;1.</td>
</tr>
</table>
<h3><a name="Header_39">Error Messages</a></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">CPF2204 E</td>
<td align="left" valign="top">User profile &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter list.</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">CPF3C1E E</td>
<td align="left" valign="top">Required parameter &amp;1 omitted.</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">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">CPF9803 E</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library &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">CPFBB02 E</td>
<td align="left" valign="top">Cluster &amp;1 does not exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB0F E</td>
<td align="left" valign="top">Cluster resource group &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">CPFBB2C E</td>
<td align="left" valign="top">Attributes of exit program &amp;1 in library &amp;2 are not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB32 E</td>
<td align="left" valign="top">Attributes of user queue &amp;1 are not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBB38 E</td>
<td align="left" valign="top">Library name &amp;1 not allowed for this request.</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">CPFBB6E E</td>
<td align="left" valign="top">Exit program data cannot be specified.</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>