| 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 |
| 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 |
Specifies the cluster whose information is to be retrieved.
| Top |
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.
| Top |
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 |
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:
| Top |
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 |
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:
| Top |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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:
| Top |
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 |
*ESCAPE Messages
| Top |