Retrieve Cluster (RTVCLU)

Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX)
Threadsafe: Yes
Parameters
Examples
Error messages

The Retrieve Cluster (RTVCLU) command is used in a control language (CL) program or a REXX procedure to get one or more of the values that are stored and associated with a cluster. The values are returned in the specified variables.

The parameter prompt text lists the minimum length for the variables next to the appropriate parameters you want to retrieve. For character variables, a single number is shown which indicates the minimum variable length. For decimal variables, two numbers are shown; the first number indicates the minimum number of digits and the second number indicates the minimum number of decimal positions.

Top

Parameters

Keyword Description Choices Notes
CLUSTER Cluster Name, * Optional, Positional 1
RTVNODCNT Retrieve node count 1-128, *ALL Optional
RTNCLU CL var for RTNCLU (10) Character value Optional
RTNCLUSTS CL var for RTNCLUSTS (1) Character value Optional
CURNODE CL var for CURNODE (8) Character value Optional
CURNODSTS CL var for CURNODSTS (2 0) Decimal number Optional
NODELIST CL var for NODELIST (14736) Character value Optional
HAVER CL var for HAVER (3 0) Decimal number Optional
HAMODLVL CL var for HAMODLVL (3 0) Decimal number Optional
CLUVER CL var for CLUVER (3 0) Decimal number Optional
CLUMODLVL CL var for CLUMODLVL (3 0) Decimal number Optional
CLUMSGQ CL var for CLUMSGQ (10) Character value Optional
CLUMSGQLIB CL var for CLUMSGQLIB (10) Character value Optional
FLVWAITTIM CL var for FLVWAITTIM (4 0) Decimal number Optional
FLVDFTACN CL var for FLVDFTACN (10) Character value Optional
Top

Cluster (CLUSTER)

Specifies the cluster whose information is to be retrieved.

*
The cluster that has previously been configured on this system is used.
name
Specify the name of the cluster whose information is to be retrieved.
Top

Retrieve node count (RTVNODCNT)

Specifies the maximum number of nodes that can be returned in the NODELIST parameter. Most clusters contain less than 128 nodes. Rather than declaring a CL variable that is 16,144 characters long for NODELIST, RTVNODCNT can specify a number less than 128 that tells the command how much memory is available to contain node information. Each node's information returned in NODELIST requires 126 characters.

If the command was run for a 3 node cluster, RTVNODCNT could specify a value of 3 and NODELIST could be defined to be only 394 characters long.

RTVNODCNT can be used to limit the node information that is returned in NODELIST. If RTVCLU is run on a five-node cluster but the value specified for RTVNODCNT is 2, information for only two nodes would be returned in the NODELIST variable.

In CL programs, RTVNODCNT can refer to a CL program variable. The variable would be declared as a 4-character variable if the value is *ALL. If the variable's value is a number, it could be declared either as a character data type or a numeric data type.

*ALL
All cluster nodes are to be returned.
1-128
Specify the number of nodes for which information is returned. If the number specified is larger than the actual number of nodes, only the actual number is returned.
Top

CL var for RTNCLU (10) (RTNCLU)

Specifies the name of a variable that is used to retrieve the name of the cluster. In CL programs, this should be a 10-character variable. If * is specified for the Cluster (CLUSTER) parameter, the value returned is the cluster configured on the system. If a name is specified for the CLUSTER parameter, that name is returned.

Top

CL var for RTNCLUSTS (1) (RTNCLUSTS)

Specifies the name of a variable that is used to retrieve the status of the rest of the cluster information. In CL programs, this should be a 1-character variable. Possible values are:

0
The information is consistent for all active nodes in the cluster.
1
The information retrieved from the node running the command may not be consistent with all active nodes in the cluster. In order to obtain consistent information:
  • Run the RTVCLU command on an active node in the cluster.
  • Start Cluster Resource Services on the node and run the RTVCLU command again.
Top

CL var for CURNODE (8) (CURNODE)

Specifies the name of a variable that is used to retrieve the name of the cluster node the command is run on. In CL programs, this should be a 8-character variable.

Top

CL var for CURNODSTS (2 0) (CURNODSTS)

Specifies the name of a variable that is used to retrieve the status of the cluster node this command is run on. In CL programs, this should be a decimal variable with a length of (2 0). Possible values are:

1
New. A node has been added to the cluster membership list but the Cluster Resource Services has never been started on that node. The Cluster Resource Service data structures have not been created on the node. During a Create Cluster operation, the Cluster Resource Service data structures will be created only on the node running the Create Cluster API.
2
Active. The node has been started either with the Create Cluster API or Add Cluster Node Entry API with the "Start indicator" parameter set to 1, or with the Start Cluster Node API. Cluster Resource Services is active on the node .
3
Remove Pending. The node is in the process of being removed from the cluster membership list as the result of a Remove Cluster Node Entry API.
4
Active Pending. The node is in the process of being started either as the result of a Create Cluster API or Add Cluster Node Entry API call with the "Start indicator" parameter set to 1 or because of a Start Cluster Node API call. In addition, the node could have previously had a status of Partition and will change to the Active Pending status as a result of the partitions being merged.
5
Inactive Pending. Cluster Resource Services is in the process of ending on this node as the result of an End Cluster Node API call. The node is still in the cluster membership list.
6
Inactive. Cluster Resource Services has been ended on the node as the result of an End Cluster Node API call. The node is still in the cluster membership list, but is no longer communicating with other nodes in the cluster.
7
Failed. A previously active node has failed. A failure is defined to be a system or clustering failure detected by Cluster Resource Services.
8
Partition. The node is only communicating with a subset of the cluster due to a network failure detected by Cluster Resource Services which has resulted in the loss of communications to one or more nodes in the cluster. Once the partitioned nodes have been merged back into a whole cluster, the node will change to Active status without operator intervention. Of course, any node that had a status of Failed in any partition will still have a status of Failed after the merge.
Top

CL var for NODELIST (14736) (NODELIST)

Specifies the name of a variable that is used to retrieve the list of nodes defined in the cluster. In CL programs, this can be a character variable up to 16144 characters long. Each node entry is 126 characters long. A cluster can have a maximum of 128 nodes defined. If there are fewer nodes in the cluster this command is retrieving information for, the length of this variable can be less. For example if there are only 4 nodes, the length of this variable could be 520 characters.

Unless the RTVNODCNT parameter is used indicate how many nodes' information can be contained in the NODELIST variable, it is assumed that enough memory has been allocated to contain all the nodes in the current cluster. If the RTVNODCNT parameter is not specified and insufficient memory is allocated for the NODELIST parameter, results are unpredictable.

The NODELIST contains a 16 byte header composed of the following which is then followed by one or more node entries.

Position  Length                 Field
1         4-byte integer number  Offset from beginning
                                 of NODELIST to first
                                 node entry
5         4-byte integer number  Length of each node entry
9         4-byte integer number  Number of nodes in the
                                 cluster
13        4-byte integer number  Number of node entries
                                 returned in NODELIST

Each 126-character node entry is composed of the following. The first node entry should be addressed by using the offset field in the above header. Subsequent node entries should be addressed by using the length field in the above header.

Position  Length                Field
1         8 characters          Node identifier
9         45 characters         First IP address
54        45 characters         Second IP address
99        10 characters         Device domain identifier
109       (2 0) decimal number  Node status
111       (2 0) decimal number  Potential node version
113       (2 0) decimal number  Potential node version
                                modification level
115       10 characters         Potential PowerHA version
125       (3 0) decimal number  Current PowerHA fix level

If the node is not part of a device domain, those 10 characters will be blanks.

The IP addresses are left justified and padded on the right with blanks. If there is only one IP address, the second one will contain blanks.

If the node does not have the PowerHA licensed program installed on it, the Potential PowerHA version will be blank and the Current HA fix level will be 0.

See the CL var for CURNODSTS (2 0) (CURNODSTS) parameter for the definition of node status values.

Top

CL var for HAVER (3 0) (HAVER)

Specifies the name of a variable that is used to retrieve the PowerHA version of the cluster. In CL programs, this should be a decimal variable with a length of (3 0).

Top

CL var for HAMODLVL (3 0) (HAMODLVL)

Specifies the name of a variable that is used to retrieve the PowerHA modification level of the cluster. In CL programs, this should be a decimal variable with a length of (3 0).

Top

CL var for CLUVER (3 0) (CLUVER)

Specifies the name of a variable that is used to retrieve the cluster version. In CL programs, this should be a decimal variable with a length of (3 0).

Top

CL var for CLUMODLVL (3 0) (CLUMODLVL)

Specifies the name of a variable that is used to retrieve the cluster modification level. In CL programs, this should be a decimal variable with a length of (3 0).

Top

CL var for CLUMSGQ (10) (CLUMSGQ)

Specifies the name of a variable that is used to retrieve the cluster message queue name. In CL programs, this should be a 10-character variable. If no message queue is associated with the cluster, the value returned in the variable is *NONE.

Top

CL var for CLUMSGQLIB (10) (CLUMSGQLIB)

Specifies the name of a variable that is used to retrieve the name of the library that contains the message queue associated with the cluster. In CL programs, this should be a 10-character variable. If there is no message queue associated with the cluster, blanks are returned in the variable.

Top

CL var for FLVWAITTIM (4 0) (FLVWAITTIM)

Specifies the name of a variable that is used to retrieve the failover wait time which is the number of minutes to wait for a reply to the failover message that was enqueued on the cluster message queue. In CL programs, this should be a decimal variable with a length of (4 0). -1 is returned if the failover wait time is *NOMAX. 0 is returned if the failover wait time is *NOWAIT.

Top

CL var for FLVDFTACN (10) (FLVDFTACN)

Specifies the name of a variable that is used to retrieve the failover default action for the failover message that was enqueued on the cluster message queue. In CL programs, this should be a 10-character variable.

Possible values are:

*PROCEED
Proceed with failover.
*CANCEL
Do not attempt failover.
Top

Examples

CRTCLU CLUSTER(SAMPLE)
       NODE((KANSAS ('9.7.100.1')) (TEXAS ('9.7.200.1')))
       CLUMSGQ(*NONE)
ADDDEVDMNE CLUSTER(SAMPLE)
           DEVDMN(ASPDEVICE)
           NODE(KANSAS)
ADDDEVDMNE CLUSTER(SAMPLE)
           DEVDMN(ASPDEVICE)
           NODE(TEXAS)

If a cluster had been created using the above commands, and a CL program was run on the TEXAS node containing the following:

DCL VAR(&CLUSTER)  TYPE(*CHAR) LEN(10)
DCL VAR(&MYNODE)   TYPE(*CHAR) LEN(8)
DCL VAR(&ALLNODES) TYPE(*CHAR) LEN(246)
DCL VAR(&MSGQ)     TYPE(*CHAR) LEN(10)
DCL VAR(&MSGQLIB)  TYPE(*CHAR) LEN(10)
RTVCLU   CLUSTER(*CURRENT)
         RTVNODCNT(2)
         RTNCLU(&CLUSTER)
         CURNODE(&MYNODE)
         NODELIST(&ALLNODES)
         CLUMSGQ(&MSGQ)
         CLUMSGQLIB(&MSGQLIB)

Information for the cluster on the system where the CL program was run would return the information into the following CL program variables:

&CLUSTER    'SAMPLE    '
&MYNODE     'TEXAS   '
&ALLNODES   '                KANSAS  9.7.100.1                 '
            '                                                  '
            '                                                  '
            '              ASPDEVICE 020700TEXAS   9.7.200.1   '
            '                                                  '
            '                           ASPDEVICE 020700'
&MSGQ       '*NONE     '
&MSGQLIB    '          '

Top

Error messages

*ESCAPE Messages

CPFBB02
Cluster &1 does not exist.
HAE000A
All cluster command user spaces busy.
HAE004E
Length of CL program variable not valid.
HAE004F
&1 command failed.
Top