friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/clust3a1TOC.htm

1127 lines
45 KiB
HTML
Raw Permalink Normal View History

Add readme and dist folders
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>Cluster Resource Group APIs</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. -->
<!-- CLUST3A SCRIPT A converted by B2H R4.1 (346) (CMS) by NLJONES at -->
<!-- RCHVMX on 24 Feb 1999 at 17:23:22 -->
<!-- 031106 JETAYLOR replaced API and/or Exit listings with -->
<!-- pagegenerator output from javascript array -->
<!-- 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>Cluster Resource Group APIs</h2>
<p>The information provided here includes:</p>
<ul>
<li><a href="#header_1">Cluster Resource Group APIs--Introduction</a></li>
<li><a href="#clust">Cluster Resource Group API List</a></li>
</ul>
<br>
<h3><a name="header_1">Cluster Resource Group APIs--Introduction</a></h3>
<p>The Cluster Resource Group (CRG) function within a cluster is to:</p>
<ul>
<li>maintain operationally identical cluster resource groups (CRGs) on every
node of the cluster resource group recovery domain.</li>
<li>call the Cluster Resource Group exit program for most cluster resource
group APIs</li>
<li>coordinate activities performed whenever access points for cluster resource
groups are changed from one node to another.</li>
</ul>
<p>Any cluster resource group API may be called on any node in the cluster.
Most cluster resource group APIs have an asynchronous behavior.</p>
<p>The majority of the cluster resource group APIs require that Cluster
Resource Services be active. This is necessary to ensure consistency of cluster
resource groups across the cluster. Each API indicates whether or not Cluster
Resource Services needs to be active for the API to complete successfully.</p>
<p>Cluster Resource Services maintains synchronous copies of cluster resource
groups (perceptively and operationally identical) on all nodes in the group's
recovery domain. When a node joins the cluster or when a cluster partition is
resolved, the cluster resource group object is reconciled. This may mean
copying the cluster resource group object from some node already in the cluster
to the joining node or from the primary partition to nodes in the secondary
partition. See <a href=
"#header_7">Partition Rules</a> for details on primary and secondary
partitions.</p>
<h3><a name="PriBckModel">Types of Cluster Resource Groups</a></h3>
<p><img src="delta.gif" alt="Start of change">There are two
models of cluster resource groups.
<ul>
<li>Primary-backup model. All cluster resource groups of this model define
nodes in the recovery domain with a specific role: either primary, backup or
replicate. The primary and backup nodes are available to be the access point for the cluster
resource. However only one node will be the active access point at a given point in time.
This node will be the primary node. Replicate nodes are not available to be an access
point. A node role
can be changed by assigning the replicate node a role of backup.
Examples of cluster resource groups of this model are data, device and application.
<li>Peer model. All cluster resource groups of this model define
nodes in the recovery domain with a role of peer or replicate. The peer nodes are available
to be the access point for the cluster resource group. All nodes defined as peer will be
the access point at the same time when the cluster resource group is started. Replicate
nodes are not available to be an access point. This can be changed by assigning the
replicate node a role of peer. Example of cluster resource groups of this
model are peer cluster resource groups<img src="deltaend.gif" alt="End of change">.
</ul>
<p>Cluster resource group objects are either data resiliency, application
resiliency, device resiliency<img src="delta.gif" alt="Start of change">or peer
resiliency.<img src="deltaend.gif" alt="End of change">
Data resiliency represents multiple copies of
data maintained on more than one node in a cluster. Application resiliency
enables an application (program) to be restarted on either the same or a
different node in the cluster. This is made possible by a Takeover IP Address.
Device resiliency allows devices such as auxiliary storage pools to be switched
from one node in a cluster to another node.<img src="delta.gif" alt="Start of change">Peer
resiliency represents resources being accessed by mutliple clients.
<img src="deltaend.gif" alt="End of change">.</p>
<br>
<h3><a name="header_2">Recovery Domain</a></h3>
<p>Cluster resource groups contain a recovery domain. A <strong>Recovery
Domain</strong> is that set of cluster nodes which, for a particular cluster
resource group, describes the access points of the cluster resource. Each node
in the recovery domain is assigned a role that reflects its point of
access:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><strong>Primary Node</strong></td>
<td align="left" valign="top">The cluster node that is the point of access for
the resilient cluster resource. For a replicated resource, the primary node
also contains the principal copy of a resource. If this node fails, all cluster
resource group objects having this node as the primary access point will
failover to a backup node. <img src="delta.gif" alt="Start of change">This role
is allowed for primary-backup model cluster resource groups.
<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><strong>Backup Nodes</strong></td>
<td align="left" valign="top">Cluster nodes that will take over the role of
primary access if the present primary node fails. For a replicated cluster
resource, this cluster node contains a copy of that resource. In the case of a
data cluster resource group, copies of the data are kept current with
replication.<img src="delta.gif" alt="Start of change">This role
is allowed for primary-backup model cluster resource groups.<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top" nowrap><strong>Replicate Nodes</strong></td>
<td align="left" valign="top">Cluster nodes that has copies of cluster
resources. <img src="delta.gif" alt="Start of change">The node
it is unable
to assume the role of primary, backup, or peer<img src="deltaend.gif" alt="End of change">.
</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><strong><img src="delta.gif" alt="Start of change">Peer Nodes</strong></td>
<td align="left" valign="top">All nodes have the same copy of the cluster
resources. A node defined with this role is available to be the active point of access
for the cluster resources. This role is only supported for peer cluster
resource groups.
<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<br>
<p>Some <a href="clust2a4TOC.htm">Cluster Control APIs</a> cause cluster
resource group actions to be taken. For example, an <a href=
"clcntendcn.htm">End Cluster Node (QcstEndClusterNode) API</a> will cause the
active cluster resource groups on that node to be ended and the <a href=
"clrgexit.htm">Cluster Resource Group exit program</a> to be called. In these
instances, the success indicator returned by the exit program will be ignored.
The operations will always be considered successful.</p>
<p>A cluster resource group has a recovery domain of one or more cluster nodes.
Each cluster node within the recovery domain has two roles: preferred and
current. The two node roles need not be the same. When a cluster resource group
is initially created, the preferred and the current roles are the same. When a cluster
resource group is created, a cluster resource group job is started on each
active node in the cluster and a *CRG object will be created on each
recovery domain node.</p>
<p>The current role of a node in the recovery domain is changed as a result of
operations occurring within the cluster (for example nodes ending, nodes
starting, and nodes failing).</p>
<p><img src="delta.gif" alt="Start of change">For primary-backup model cluster
resource groups<img src="deltaend.gif" alt="End of change">
<ul>
<li>When the
recovery domain is obtained by the <a href="clrglstcrgi.htm">List
Cluster Resource Group Information (QcstListClusterResourceGroupIn) API</a> or
when it is passed to the exit program, it is always presented as an array with
the primary node first, followed by backup nodes, and finally replicate nodes.
If the cluster resource group is active, backup nodes in the recovery domain
are ordered so that active nodes appear before nodes that are inactive or
partitioned. APIs or cluster events that affect a node's membership status in
the recovery domain also cause the order of the backup nodes to change for an
active cluster resource group.
<li>If a cluster resource group is not active, APIs can cause changes to the
order of the recovery domain but cluster events such as nodes failing or
rejoining the cluster do not. This is done to keep the current recovery domain
in the order last requested by the user or the last order when the cluster
resource group was ended during times when node failures or rejoins are not
important. However, when the cluster resource group becomes active such as with
the <a href="clrgstcrg.htm">Start Cluster Resource Group
(QcstStartClusterResourceGroup) API</a>, the recovery domain will be reordered
if necessary to put active backup nodes before inactive or partitioned backup
nodes.
<li>When the <a href="clrginitso.htm">Initiate Switchover
(QcstInitiateSwitchOver) API</a> is used on an active cluster resource group,
the first active backup node becomes the new primary and the old primary
becomes the last active backup node.
<li>When the primary node fails for an active cluster resource group, the first
active backup node becomes the new primary and the old primary becomes the last
inactive backup.
</ul>
<p><img src="delta.gif" alt="Start of change">For peer model cluster resource groups:
<ul>
<li>When the recovery domain is obtained by the <a href="clrglstcrgi.htm">List
Cluster Resource Group Information (QcstListClusterResourceGroupIn) API</a> or
when it is passed to the exit program, it is always presented as an array with
the peer nodes first followed by replicate nodes.
<li>The <a href="clrginitso.htm">Initiate Switchover (QcstInitiateSwitchOver) API</a>
is not allowed.
<li>The nodes are not reordered when nodes fail for an active cluster resource group.
<img src="deltaend.gif" alt="End of change">
</ul>
<p>The preferred role of a node in the cluster is changed only by running the
following APIs:</p>
<ul>
<li>Add Node to Recovery Domain</li>
<li>Remove Node from Recovery Domain</li>
<li>Change Cluster Resource Group</li>
</ul>
<p>Changes to the node roles are done independently. The role specified for a
node in any of these APIs will be assigned to both the current and preferred
roles of the node. </p>
<p><strong><a name="FIGCLU508">Example of node roles for a <img src="delta.gif" alt="Start of change">primary-backup model cluster resource group.
<img src="deltaend.gif" alt="End of change">.</a></strong></p>
<p>
For example, the recovery domain of a
<img src="delta.gif" alt="Start of change">primary-backup model
<img src="deltaend.gif" alt="End of change">cluster resource group
object has preferred roles of N1-primary, N2-backup1, and N3-backup2, but the
current roles are N1-backup2, N2-primary, and N3-backup1. N4 is being added as
backup2. Therefore, the preferred roles of the nodes are N1-primary,
N2-backup1, N3-backup3, and N4-backup2, and the current roles are N1-backup3,
N2-primary, N3-backup1, and N4-backup2.</p>
<p align="center"><img src="rbafx508.gif" alt="Example of node roles"></p>
<img src="delta.gif" alt="Start of change">
<p><strong><a name="FIGCLU509">Example of node roles for a <img src="delta.gif" alt="Start of change">peer model cluster resource group.
</a></strong></p>
<p>In this example, the recovery domain of a
<img src="delta.gif" alt="Start of change">peer model
cluster resource group
object preferred roles are N1-peer, and N2-replicate, but the
current roles are N1-peer, and N2-replicate. N3 is being added as
peer. Therefore, the preferred roles of the nodes are N1-peer,
N2-replicate, and N3-peer, and the current roles are N1-peer,
N2-replicate, and N3-peer. Notice that the recovery domain is reordered when
another node is added to the recovery domain with a role of peer.</p>
<p align="center"><img src="rbafx670.gif" alt="Example of node roles"></p>
<img src="deltaend.gif" alt="End of change">
<br>
<h3><a name="header_5">Exit Program</a></h3>
<p>Every data or application cluster resource group has an associated exit
program. A device cluster resource group can also have an exit program but one
is not required. This exit program will be called for each of the different
action codes listed under the Cluster Resource Group exit program. The exit
program is called from a separate job using the user profile supplied when the
cluster resource group is created. See <a href="clrgexit.htm">Cluster Resource
Group exit program</a> for a description of the conditions that cause the exit
program to be called.</p>
<p>The user exit program will be restricted from calling some of the APIs.
Each API specifies the user exit program restrictions.</p>
<br>
<h3><img src="delta.gif" alt="Start of change">Application
<img src="deltaend.gif" alt="End of change">Takeover IP Address</h3>
<p>An
img src="delta.gif" alt="Start of change">application
<img src="deltaend.gif" alt="End of change">
takeover IP address is a high availability mechanism used to insulate
clients from application server outages. The concept is to use IP address
aliasing (multihoming) to define a &quot;floating IP address&quot; associated with
multiple application servers or hosts. When one application server in a cluster
fails, another cluster node can assume the responsibilities of the application
server without requiring the user to reconfigure the clients.</p>
<p>To support address aliasing, application groups contain an IP address
resource and a recovery domain. When the application or the node running the
application fails, Cluster Resource Services initiates a failover of the group
using the IP address to the node assigned the current role of first backup.</p>
<p>The address specified for the takeover IP address must not be used for any
other purposes. Cluster Resource Services will not allow certain API operations
to complete successfully if the IP address is in use. This restriction ensures
that the structures being created will provide application resilience.</p>
<br>
<h3>Server Takeover IP Address</h3>
<p>A server takeover IP address is just like the
<img src="delta.gif" alt="Start of change">
application
<img src="deltaend.gif" alt="End of change">
takeover IP address for an
application CRG, except it is used for servers associated with the relational
database name in the device description for an auxiliary storage pool. The
address can only be specified for a primary auxiliary storage pool. Only one IP
address can be specified per primary auxiliary storage pool. The address must
be unique, and must not be used for any other purpose.</p>
<p>The user is responsible for configuring and managing the server takeover IP
address. The IP address must be added on all nodes in the recovery domain prior
to starting the cluster resource group. Starting of a device cluster resource
group will not start the server IP address or vary on the device. That is the
user's responsibility. Cluster Resource Service manages the IP address only
during a switchover or failover.</p>
<p>On switchover or failover, clustering will end the IP address on the current
primary, and uses the value in the "configuration object online" field to
determine what action should occur on the new primary node. Based on the value
in the "configuration object online" field it will either start the IP address
and vary on the device or do nothing to the IP address and device.</p>
<br>
<h3>Failover Message Queue</h3>
<p>A failover message queue allows a user to control what happens at failover
time. A failover policy could be:</p>
<ul>
<li>failover continues to act like it did for V5R1M0 and prior.</li>
<li>failover sends an inquiry message to the failover message queue and waits
the specific amount of time specified by the user.</li>
</ul>
<p>A failover message queue may be specifed when a cluster resource group is
created. A message will be placed on the queue when the primary node of the
active cluster resource group either ends or fails, forcing the cluster
resource group to fail over to a new primary. In the case of a node failure,
each cluster resource group will enqueue a separate message to its failover
message queue if one is defined. No message will be enqueued if the primary
node is removed from the cluster.</p>
<p>The message will be placed on the message queue on the new primary node
before the call to the exit program. This gives the user the option of
continuing the failover to the new primary, or cancelling the failover. If the
failover is cancelled, the primary node will not be changed, and the cluster
resource group will become Inactive. The exit program will be called with an
action code of Failover Cancelled.</p>
<p>There are two associated parameters with the qualified failover message
queue. The failover wait time allows the user to specify how long Cluster
Resource Services should wait for a reply to the failover message. The user can
choose to wait forever, proceed with failover without waiting for a reply, or
wait a specified number of minutes. The failover default action allows the user
to choose whether to continue or cancel failover if a reply to the failover
message is not received within the time limit specified in the failover wait
time parameter or if the message cannot be enqueued for some reason.</p>
<br>
<h3>Site Name and Data Port IP Addresses</h3>
<p>Site name and data port IP addresses are associated with a recovery domain node
for a device CRG, applicable only to cross-site mirroring.
Both must be specified together for a recovery domain node. That is, a node which
has a site name must also have at least one data port IP address specified.
<p>
Geographic mirroring, which is a subfunction of cross-site mirroring,
supports two physical copies of
auxiliary storage pool, one on each site. Only two sites are supported.
A site primary node is the node which has the highest node role ranking for that site.
A production site primary node, which is also the primary node for a device CRG, owns a
production copy of the auxiliary storage pool.
A mirror site primary node, which is the backup node which has the highest node role
ranking at the mirror site, owns a mirror copy of the auxiliary storage pool.
<p>
A site may contain one or more recovery domain nodes at the same
physical location. All nodes at a site must have access to the same physical copy
of auxiliary storage pool.
If there is only one node at a site, the auxiliary storage pool on that site does not need to be switchable.
A node which belongs to more than one device CRG may or may not have the same
site name.
<p>
Geographic mirroring is performed by sending updates from a production site primary node
to a mirror site primary node via data port IP addresses.
Each recovery domain node could have up to four data port IP addresses.
They must be unique across all recovery domain nodes and CRGs.
<p>
User is responsible for configuring and managing data port IP addresses.
They must already exist on all nodes in the recovery domain prior to
starting a device CRG.
Clustering will not start or end data port IP addresses under any circumstances,
including starting and ending of a cluster resource group, switchover and failover.
User must start the data port IP addresses before geographic
mirroring can be performed. It is recommended that data port IP addresses are
dedicated for geographic mirroring use only.
It is also recommended that multiple data port IP addresses on each recovery domain node
map to different adapters. This will help to avoid a single point of failure on the
adapter and also improve performance of geographic mirroring.
<br>
<h3><a name="Header_3">Summary of Cluster Resource Group Status</a></h3>
<p>Each cluster resource group has a status associated with it. The status of
the cluster resource group may govern the behavior of a particular API call. In
the following list of values, an indication of what happens when the exit
program completes successfully applies only to a cluster resource group which
has an exit program. If no exit program was specified, the same action occurs
as for a successful completion. The possible values are:</p>
<p>10&nbsp;&nbsp;<strong>Active.</strong>&nbsp;&nbsp;The resources managed by
the cluster resource group are currently resilient. </p>
<p>20&nbsp;&nbsp;<strong>Inactive.</strong>&nbsp;&nbsp;The resources managed by
the cluster resource group are currently not resilient.</p>
<p>30&nbsp;&nbsp;<strong>Indoubt</strong>.&nbsp;&nbsp;The information contained
within the cluster resource group object may not be accurate. This status
occurs when an exit program is called with an action of Undo and fails to
complete successfully.</p>
<p>40&nbsp;&nbsp;<strong>Restored.</strong>&nbsp;&nbsp;The cluster resource
group object was restored on this node and has not been copied to the other
nodes in the recovery domain. When Cluster Resource Services is started on this
node, the cluster resource group will be synchronized with the other nodes in
the recovery domain and its status set to Inactive.</p>
<p>500&nbsp;&nbsp;<strong>Add Node Pending.</strong>&nbsp;&nbsp;A new node is
in the process of being added to the recovery domain of a cluster resource
group. If the exit program is successful the status is reset to its value at
the time the API was called. If the exit program fails and the original state
cannot be recovered, the status is set to Indoubt.</p>
<p>510&nbsp;&nbsp;<strong>Delete Pending.</strong>&nbsp;&nbsp;Cluster resource
group object is in the process of being deleted. When the exit program
completes the cluster resource group is deleted from all nodes in the recovery
domain.</p>
<p>520&nbsp;&nbsp;<strong>Change Pending.</strong>&nbsp;&nbsp;The cluster
resource group is in the process of being changed. If the exit program is
successful the status is reset to the value at the time the API was called. If
the exit program fails and the original state cannot be recovered, status is
set to Indoubt.</p>
<p>530&nbsp;&nbsp;<strong>End Cluster Resource Group
Pending.</strong>&nbsp;&nbsp;Resiliency for the cluster resource group is in
the process of ending. If the exit program is successful, the status is set to
Inactive. If the exit program fails and the original state cannot be recovered,
the status is set to Indoubt.</p>
<p>540&nbsp;&nbsp;<strong>Initialize Pending.</strong>&nbsp;&nbsp;A cluster
resource group is being created and is in the process of being initialized. If
the exit program is successful, the status is set to Inactive. If the exit
program fails, the cluster resource group will be deleted from all nodes.</p>
<p>550&nbsp;&nbsp;<strong>Remove Node Pending.</strong>&nbsp;&nbsp;A node is in
the process of being removed from the recovery domain of the cluster resource
group. If the exit program is successful, the status is reset to the value at
the time the API was called. If the exit program fails and the original state
cannot be recovered, the status is set to Indoubt.</p>
<p>560&nbsp;&nbsp;<strong>Start Cluster Resource Group
Pending.</strong>&nbsp;&nbsp;Resiliency is in the process of starting for the
cluster resource group. If the exit program is successful, the status is set to
Active. If the exit program fails and the original state cannot be recovered,
the status is set to Indoubt. <img src="delta.gif" alt="Start of change">For
peer model cluster resource groups all nodes defined with a role of peer are active
access points for the cluster resources. <img src="deltaend.gif" alt="End of change"></p>
<p>570&nbsp;&nbsp;<strong>Switchover Pending.</strong>&nbsp;&nbsp;The Initiate
Switchover API was called, a failure of a cluster resource group occurred, or a
node failed, causing a switchover or failover to begin. The first backup node is
in the process of becoming the primary node. If the exit program is successful,
the status is set to Active. If the exit program fails and the original state
cannot be recovered, the status is set to Indoubt.
<img src="delta.gif" alt="Start of change">While the switchover function is not
valid for a peer cluster resource group, users may see the status "switchover
pending" during a node failure.
<img src="deltaend.gif" alt="End of change">
</p>
<p>580&nbsp;&nbsp;<strong>Delete Command Pending.</strong>&nbsp;&nbsp;Cluster
resource group object is being deleted by the <a href="../cl/dltcrg.htm">Delete
Cluster Resource Group (DLTCRG) command</a>. The Cluster resource group object
is only removed from the node running the command. This is not a distributed
request. At the completion of the command, the cluster resource group is
deleted from the node.</p>
<p>590&nbsp;&nbsp;<strong>Add Device Entry Pending.</strong>&nbsp;&nbsp;A
device entry is being added to a cluster resource group. If the exit program is
successful, the status is reset to its value at the time the API was called. If
the exit program fails and the original state cannot be recovered, the status
is set to Indoubt.</p>
<p>600&nbsp;&nbsp;<strong>Remove Device Entry Pending.</strong>&nbsp;&nbsp;A
device entry is being removed from a cluster resource group. If the exit
program is successful, the status is reset to its value at the time the API was
called. If the exit program fails and the original state cannot be recovered,
the status is set to Indoubt.</p>
<p>610&nbsp;&nbsp;<strong>Change Device Entry Pending.</strong>&nbsp;&nbsp;A
device entry is being changed in a cluster resource group. If the exit program
is successful, the status is reset to its value at the time the API was called.
If the exit program fails and the original state cannot be recovered, the
status is set to Indoubt.</p>
<p>620&nbsp;&nbsp;<strong>Change Node Status Pending.</strong>&nbsp;&nbsp;The
status of a node in the cluster resource group"s current recovery domain is
being changed. If the change is successful, the status is reset to its value at
the time the Change Cluster Node Entry API was called. Failure of the exit
program causes the status of the cluster resource group to be set to Indoubt.
If a backup node is reassigned as the primary node for a resilient device
cluster resource group and the ownership of the device cannot be transferred to
the new primary node, the status is set to Indoubt.</p>
<p>The relationship between the cluster resource group status and the cluster
resource group APIs is summarized in the following table. See the cluster
resource group APIs for additional details on the cluster resource group
status.<br>
</p>
<p><strong><a name="TBLCRGST">Summary of cluster resource group statuses for
affected Cluster Resource Services API</a></strong></p>
<table border>
<tr>
<th align="left" valign="bottom">Cluster Resource Services API</th>
<th align="left" valign="bottom">Original status</th>
<th align="left" valign="bottom">Status while exit program running</th>
<th align="left" valign="bottom">Action Code</th>
<th align="left" valign="bottom">Status - exit program successful</th>
<th align="left" valign="bottom">Status - exit program failure on Undo</th>
</tr>
<tr>
<td align="left" valign="top"><strong>Add Cluster Resource Group Device
Entry</strong></td>
<td align="left" valign="top">
<ul>
<li>Active</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored - ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Add Device Entry Pending</td>
<td align="left" valign="top">17 - Add Device Entry</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Add Node to Recovery Domain</strong></td>
<td align="left" valign="top">
<ul compact>
<li>Active
<ul>
<li>Adding primary - Error</li>
<li>Adding backup, replicate <img src="delta.gif" alt="Start of change">or peer<img src="deltaend.gif" alt="End of change">
</ul>
</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored - ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Add Node Pending</td>
<td align="left" valign="top">11 - Add Node</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Change Cluster Node Entry</strong></td>
<td align="left" valign="top">When changing node status:
<ul>
<li>Active</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored - ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Change Node Status Pending</td>
<td align="left" valign="top">20 - Change Node Status</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt
<p>** Indoubt if device ownership cannot be transferred for a resilient device
cluster resource group.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Change Cluster Resource
Group</strong></td>
<td align="left" valign="top">If changing node to primary or changing takeover
IP address:
<ul>
<li>Active -- ERROR</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored - ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
<p>All other changes:</p>
<ul>
<li>Active</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored - ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Change Pending</td>
<td align="left" valign="top">13 - Change
<p><strong>Note:</strong> Only call exit program for changing node role in
recovery domain.</p>
</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Change Cluster Resource Group Device
Entry</strong></td>
<td align="left" valign="top">
<ul>
<li>Active</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored - ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Change Device Entry Pending</td>
<td align="left" valign="top">19 - Change Device Entry</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Create Cluster Resource
Group</strong></td>
<td align="left" valign="top">N/A</td>
<td align="left" valign="top">Initialize Pending</td>
<td align="left" valign="top">1 - Initialize</td>
<td align="left" valign="top">Inactive</td>
<td align="left" valign="top">*CRG deleted</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Delete Cluster Resource
Group</strong></td>
<td align="left" valign="top">
<ul compact>
<li>Active -- ERROR</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Delete Pending</td>
<td align="left" valign="top">
<ul>
<li>5 - Verification Phase</li>
<li>7 - Delete</li>
</ul>
</td>
<td align="left" valign="top">*CRG deleted</td>
<td align="left" valign="top">
<ul>
<li>orginal status (if during Verification Phase, no undo, *CRG not deleted)</li>
<li>*CRG deleted (if during Delete)</li>
</ul>
<p>** Indoubt if Cluster Resource Services fails</p>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong>End Cluster Resource Group</strong></td>
<td align="left" valign="top">
<ul compact>
<li>Active</li>
<li>Inactive -- ERROR</li>
<li>Indoubt</li>
<li>Restored -- ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">End Cluster Resource Group Pending</td>
<td align="left" valign="top">4 - End</td>
<td align="left" valign="top">Inactive</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>End Cluster Node</strong></td>
<td align="left" valign="top">
<ul compact>
<li>Active</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored</li>
<li>Any pending status</li>
</ul>
</td>
<td align="left" valign="top">Switchover Pending</td>
<td align="left" valign="top">
<ul>
<li>16 - End Node for the node ending</li>
<li>9 - Failover for other nodes</li>
</ul>
</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Initiate Switchover</strong><br>
</td>
<td align="left" valign="top">
<ul>
<li>Active</li>
<li>Inactive -- ERROR</li>
<li>Indoubt -- ERROR</li>
<li>Restored -- ERROR</li>
<li>Any pending status - ERROR</li>
<li><img src="delta.gif" alt="Start of change">Any peer cluster resource group - ERROR <img src="deltaend.gif" alt="End of change"></li>
</ul>
</td>
<td align="left" valign="top">Switchover Pending</td>
<td align="left" valign="top">10 - Switchover
<p><strong>Note:</strong> If application cluster resource group, exit program
called again with action Start.</p>
</td>
<td align="left" valign="top">Active</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Remove Cluster Node Entry</strong></td>
<td align="left" valign="top">
<ul>
<li>Active</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored</li>
<li>Any pending status</li>
</ul>
</td>
<td align="left" valign="top">Switchover Pending</td>
<td align="left" valign="top">
<ul compact>
<li>12 - Remove Node for the node being removed</li>
<li>9 - Failover for other nodes</li>
</ul>
</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Remove Cluster Resource Group Device
Entry</strong></td>
<td align="left" valign="top">
<ul>
<li>Active - ERROR if last device entry removed</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored - ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Remove Device Entry Pending</td>
<td align="left" valign="top">18 - Remove Device Entry</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Remove Node From Recovery
Domain</strong><br>
</td>
<td align="left" valign="top">
<ul>
<li>Active
<ul>
<li>Removing primary - ERROR</li>
<li>Removing backup, replicate<img src="delta.gif" alt="Start of change"> or peer<img src="deltaend.gif" alt="End of change"></li>
</ul>
</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored -- ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Remove Node Pending</td>
<td align="left" valign="top">12 - Remove Node</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Start Cluster Node Entry</strong></td>
<td align="left" valign="top">
<ul>
<li>Active</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored</li>
<li>Any pending status</li>
</ul>
</td>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">No pending value used <img src="deltaend.gif" alt="End of change"></td>
<td align="left" valign="top">8 - Rejoin</td>
<td align="left" valign="top">original status</td>
<td align="left" valign="top">Indoubt</td>
</tr>
<tr>
<td align="left" valign="top"><strong>Start Cluster Resource
Group</strong></td>
<td align="left" valign="top">
<ul>
<li>Active -- ERROR</li>
<li>Inactive</li>
<li>Indoubt</li>
<li>Restored -- ERROR</li>
<li>Any pending status - ERROR</li>
</ul>
</td>
<td align="left" valign="top">Start Cluster Resource Group Pending</td>
<td align="left" valign="top">2 - Start</td>
<td align="left" valign="top">Active</td>
<td align="left" valign="top">Indoubt</td>
</tr>
</table>
<br>
<br>
<h3><a name="header_7">Partition Rules</a></h3>
When a partition is detected, each partition is designated as a primary or
secondary partition for each cluster resource group defined in the cluster.
<p><img src="delta.gif" alt="Start of change">For primary-backup model cluster
resource groups:<img src="deltaend.gif" alt="End of change">
<p> The primary partition contains the node that has the current node role of primary.
All other partitions are secondary. The primary partition may not be the same
for all cluster resource groups.
<p><img src="delta.gif" alt="Start of change">For peer model cluster resource
groups:
<ul>
<li>If the recovery domain nodes are fully contained within one partition, it will be the
primary partition.</li>
<li>If the recovery domain nodes span a partition, there will be no primary partion. Both
partitions will be secondary partitions.</li>
<li>If the cluster resource group is active and there are no peer nodes in the given partition,
the cluster resource group will be ended.</li>
<li>Operational changes are allowed in a secondary partition as long as the restrictions for the operational changes are met.</li>
<li>No configuration changes are allowed in a secondary partition.</li>
</ul>
<img src="deltaend.gif" alt="End of change">
<p>The restrictions for each API when in a
partition state are:</p>
<dl>
<dt><strong>Add Cluster Resource Group Device Entry</strong></dt>
<dd>Allowed only in a primary partition and all nodes in the cluster resource
group"s recovery domain must be active in the primary partition.</dd>
<dt><strong>Add Node to Recovery Domain</strong></dt>
<dd>Allowed only in a primary partition. </dd>
<dt><strong>Change Cluster Resource Group</strong></dt>
<dd>Allowed only in a primary partition. </dd>
<dt><strong>Change Cluster Resource Group Device Entry</strong></dt>
<dd>Allowed only in a primary partition.</dd>
<dt><strong>Create Cluster Resource Group</strong></dt>
<dd>Not allowed in any partition.</dd>
<dt><strong>Delete Cluster Restore Group</strong></dt>
<dd>Allowed in any partition, but only affects partition running the API.</dd>
<dt><strong>Distribute Information</strong></dt>
<dd>Allowed in any partition, but only affects partition running the API.</dd>
<dt><strong>End Cluster Resource Group</strong></dt>
<dd>Allowed only in a primary partition. <img src="delta.gif" alt="Start of change">Allowed in all partitions for peer cluster resource groups, but only affects the partition running the API.<img src="deltaend.gif" alt="End of change"></dd>
<dt><strong>Initiate Switchover</strong></dt>
<dd>Allowed only in a primary partition.</dd>
<dt><strong>List Cluster Resource Groups</strong></dt>
<dd>Allowed in any partition.</dd>
<dt><strong>List Cluster Resource Group Information</strong></dt>
<dd>Allowed in any partition.</dd>
<dt><strong>Remove Cluster Resource Group Device Entry</strong></dt>
<dd>Allowed only in a primary partition. </dd>
<dt><strong>Remove Node from Recovery Domain</strong></dt>
<dd>Allowed only in a primary partition. </dd>
<dt><strong>Start Cluster Resource Group.</strong></dt>
<dd>Allowed only in a primary partition. <img src="delta.gif" alt="Start of change">Allowed in all partitions for peer cluster resource groups, but only affects the partition running the API.<img src="deltaend.gif" alt="End of change"></dd>
</dl>
<p>By applying these restrictions, cluster resource groups can be
resynchronized when the cluster is no longer partitioned. As nodes rejoin the
cluster from a partitioned status, the version of the
cluster resource group in the primary partition will be copied to nodes in a secondary
partition.<img src="delta.gif" alt="Start of change">When merging two secondary
partitions for peer-model, the partition which has cluster resource group with status
of Active will override the other partition. If both partitions have the same status for
cluster resource group, the partition which contains the first active node listed in
the cluster
resource group recovery domain will be copied to all nodes in the recovery domain.
The version of the
cluster resource group in the winning partition will be copied to nodes in
the overridden partition.<img src="deltaend.gif" alt="End of change"></p>
<p>On occasion, a partition condition may be reported incorrectly and one or
more nodes may have actually failed. If one of these failed nodes has the
current role of primary for a cluster resource group, special recovery actions
are required in order to assign the primary node role to a node in a secondary
partition.</p>
<p>After these actions have been taken, returning the failed nodes to the
cluster becomes much more difficult. Thus, these actions should be taken only
when the failed node will be unavailable for an extended period of time. An
example of when to do this would be the loss of a primary site.</p>
<p>The Change Cluster Node Entry API may be used to tell Cluster Resource
Services that a node has really failed rather than partitioned. Once all nodes
have been identified as failing, the List Cluster Resource Group Information
API can be used to determine if the recovery domain has been reordered as the
situation requires, and the Start Cluster Resource Group API can be used to
restart the cluster resource group.</p>
<p>See <a href="clcntchgcne.htm">Change Cluster Node Entry
(QcstChangeClusterNodeEntry) API</a> for additional information.<br>
</p>
<br>
<h3><a name="clust">Cluster Resource Group API List</a></h3>
<p>The cluster resource group APIs are:</p>
<!-- ***** NOTE ***** Do not manually update text or links in this section. -->
<!-- Updates made in this section *will* be overlaid by automated tools -->
<!-- Notify User Technologies of needed updates to be made in XML for API finder.-->
<!--***************API BEGIN PASTE***************-->
<ul>
<li><A HREF="clrgadddevent.htm">Add Cluster Resource Group Device Entry</A> (QcstAddClusterResourceGroupDev) adds a new device entry to a cluster resource group.</li>
<li><A HREF="clrgaddnrd.htm">Add Node To Recovery Domain</A> (QcstAddNodeToRcvyDomain) adds a new node to the recovery domain of an existing cluster resource group.</li>
<li><A HREF="clrgchgcrg.htm">Change Cluster Resource Group</A> (QcstChangeClusterResourceGroup) changes some of the attributes of a cluster resource group.</li>
<li><A HREF="clrgchgdevent.htm">Change Cluster Resource Group Device Entry</A> (QcstChgClusterResourceGroupDev) changes a device entry in a cluster resource group.</li>
<li><A HREF="clrgcrtcrg.htm">Create Cluster Resource Group</A> (QcstCreateClusterResourceGroup) creates a cluster resource group object.</li>
<li><A HREF="clrgdltcrg.htm">Delete Cluster Resource Group</A> (QcstDeleteClusterResourceGroup) deletes a cluster resource group.</li>
<li><A HREF="cldistinfo.htm">Distribute Information</A> (QcstDistributeInformation) delivers information from a node in the recovery domain to other nodes in the recovery domain.</li>
<li><A HREF="clrgendcrg.htm">End Cluster Resource Group</A> (QcstEndClusterResourceGroup) calls the Cluster Resource Group Exit Program to disable the resilience of the objects or application.</li>
<li><A HREF="clrginitso.htm">Initiate Switchover</A> (QcstInitiateSwitchOver) changes the current recovery domain of a cluster resource group by making the primary node the last backup node and first backup node the primary node.</li>
<li><A HREF="clrglstcrgi.htm">List Cluster Resource Group Information</A> (QcstListClusterResourceGroupIn) returns the contents of a cluster resource group object.</li>
<li><A HREF="clrglstcrg.htm">List Cluster Resource Groups</A> (QcstListClusterResourceGroups) generates a list of cluster resource groups and descriptive information about them.</li>
<li><A HREF="clrgrmvdevent.htm">Remove Cluster Resource Group Device Entry</A> (QcstRmvClusterResourceGroupDev) removes a device entry from a cluster resource group.</li>
<li><A HREF="clrgrmvnrd.htm">Remove Node From Recovery Domain</A> (QcstRemoveNodeFromRcvyDomain) removes a node from the recovery domain of an existing cluster resource group.</li>
<li><A HREF="clrgstcrg.htm">Start Cluster Resource Group</A> (QcstStartClusterResourceGroup) calls the Cluster Resource Group Exit Program to enable resilience for the objects or application.</li>
</ul>
<!--***************API END PASTE***************-->
<hr>
<table align="center" 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>
</body>
</html>
Reference in New Issue Copy Permalink