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

528 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>List Cluster Resource Groups (QcstListClusterResourceGroups) 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>List Cluster Resource Groups (QcstListClusterResourceGroups) 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%">Qualified user space name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</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">3</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">4</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: QCSTCRG3<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The List Cluster Resource Groups (QcstListClusterResourceGroups) API
generates a list of and descriptive information about the cluster resource
groups in the cluster specified by the cluster name parameter. The generated
list is placed in the specified user space and replaces any existing list.
Information will be returned for all cluster resource groups in the cluster,
even if they do not exist on the node running the API. All the cluster resource
groups will be returned in the generated list regardless of the authority of
the user calling the API. The <a href="qusljob.htm">List Objects (QUSLOBJ)</a>
API can be used to provide a list of cluster resource group objects on this
node only. Since the request for information is not distributed to other nodes
in the cluster, the information about a cluster resource group that is returned
shows the values obtained from the node running the API. Several conditions
(for example, Cluster Resource Services not active on the node running the API)
may produce inconsistent information about a cluster resource group in the
cluster.</p>
<p>This API can be called from a cluster resource group exit program.<br>
</p>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>User Space Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>User Space Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>User Space Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Qualified user space name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the *USRSPC object that is to receive the generated list. The
first 10 characters contain the user space object name, and the second 10
characters contain the name of the library where the user space is located. No
special values are supported for library name, for example, QTEMP, *CURLIB, or *LIBL.</p>
<p>The user space cannot be in an independent auxiliary storage pool.</p>
</dd>
<dt><strong>Format Name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the information returned for each cluster resource group
object. Possible values are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRCSTL1">CRGL0100</a></em></td>
<td align="left" valign="top">Cluster resource group object names</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Cluster name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the cluster for which the list of cluster resource group objects
is retrieved.</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="HDRCSTLIST">Format of the Generated Lists</a></h3>
<p>The cluster resource group list consists of:</p>
<ul>
<li>A user space</li>
<li>A generic header</li>
<li>An input parameter section</li>
<li>A header section</li>
<li>A list data section:
<ul>
<li>CRGL0100 format</li>
</ul>
</li>
</ul>
<p>For details about the user area and generic header, see <a href=
"../apiref/usf.htm">User Space Format for List APIs</a>. For detailed descriptions of the
fields in the list returned, see <a href="#HDRCSTDDE">Field
Descriptions</a>.</p>
<p>The completion code in the generic header should be checked to determine if
the API completed successfully. When you retrieve list entry information from a
user space, you must use the entry size returned in the generic header. The
size of each entry may be padded at the end. If you do not use the entry size,
the result may not be valid.<br>
</p>
<h3><a name="HDRCSTLIP1">Input Parameter Section</a></h3>
<p>An exact copy of the parameters coded in the call to the API.<br>
</p>
<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(10)</td>
<td align="left" valign="top" width="60%">User space name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User space library name</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Cluster name</td>
</tr>
</table>
<br>
<h3>Header Section</h3>
<p>Global information about the cluster resource groups.<br>
</p>
<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(1)</td>
<td align="left" valign="top" width="60%">Information status</td>
</tr>
</table>
<br>
<h3><a name="HDRCSTL1">CRGL0100 Format</a></h3>
<p>General information about the cluster resource groups in the cluster.
Detailed information about a single cluster resource group can be obtained by
using the <a href="clrglstcrgi.htm">List Cluster Resource Group Information
(QcstListClusterResourceGroupIn)</a> API.<br>
</p>
<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(10)</td>
<td align="left" valign="top" width="60%">Cluster resource group name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">BINARY(2)</td>
<td align="left" valign="top">Cluster resource group type</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Cluster resource group status</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Primary node id</td>
</tr>
<tr>
<td align="center" valign="top"><img src="delta.gif" alt="Start of change">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Application id<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<br>
<h3><a name="HDRCSTDDE">Field Descriptions</a></h3>
<p><strong><img src="delta.gif" alt="Start of change">Application id.</strong>
This is a string to identify the application supplying the peer cluster
resource group. The recommended format is 'vendor-id.name' where vendor-id is an
identifier for the vendor creating the cluster resource group and name is the application
name. For example, QIBM.ExamplePeer, indicates it is supplied by IBM for the ExamplePeer
application. It is not recommended to use QIBM for vendor id name unless
the cluster resource group is supplied by IBM.
<img src="deltaend.gif" alt="End of change"></p>
<p><strong>Cluster name.</strong> The name of the cluster for which the list of
cluster resource groups is to be retrieved.</p>
<p><strong>Cluster resource group name.</strong> The name of the cluster
resource group.</p>
<p><strong>Cluster resource group status.</strong> The status of the cluster
resource group when this information was gathered. See <a href=
"clust3a1TOC.htm#Header_3">Summary of Cluster Resource Group Status</a> for the
possible values and definitions of the status.<br>
</p>
<p><strong>Cluster resource group type.</strong> The type of the cluster
resource group. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Data resiliency.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Application resiliency.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Device resiliency.</td>
</tr>
<tr>
<td align="left" valign="top"><em><img src="delta.gif" alt="Start of change">4</em></td>
<td align="left" valign="top">Peer resiliency.<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<p><strong>Format name.</strong> The content and format of the information
returned for each cluster resource group object entry. The value must be set to
CRGL0100.</p>
<p><strong>Information status.</strong> Indicates the consistency of the
retrieved information.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The information is consistent for all active
nodes in the cluster.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The information retrieved from the node running
the API may not be consistent with all active nodes in the cluster. In order to
obtain consistent information:
<ul>
<li>Call this API on an active node in the cluster, if the node running the API
is not active.</li>
<li>Start Cluster Resource Services on the node running the API if it is not
active.</li>
</ul>
</td>
</tr>
</table>
<p><strong>Primary node id.</strong> A unique string of characters that
identifies the node that has a current node role of primary for the cluster
resource group object.</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em><img src="delta.gif" alt="Start of change">*NONE</em></td>
<td align="left" valign="top">Valid only for peer cluster resource group. There is no primary node for a peer cluster resource group.<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<p><strong>User space library name.</strong> The name of the library that
contains the user space.</p>
<p><strong>User space name.</strong> The name of the user space that receives
the list.</p>
<br>
<h3>Error Messages</h3>
<p>Messages that are delivered through the error code parameter are listed
here.</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">CPF24B4 E</td>
<td width="85%" valign="top">Severe error while addressing parameter list.</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">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">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">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</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>
</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>