| Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX) Threadsafe: Yes |
Parameters Examples Error messages |
The Retrieve Cluster Resource Group (RTVCRG) 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 resource group. 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 |
|---|---|---|---|
| CRG | Cluster resource group | Name | Required, Positional 1 |
| CLUSTER | Cluster | Name, * | Optional |
| RTVDMNCNT | Retrieve recovery domain count | 1-128, *ALL | Optional |
| RTVCFGCNT | Retrieve config object count | 1-256, *ALL | Optional |
| RTNCLU | CL var for RTNCLU (10) | Character value | Optional |
| RTNCLUSTS | CL var for RTNCLUSTS (1) | Character value | Optional |
| CRGSTS | CL var for CRGSTS (4 0) | Decimal number | Optional |
| CRGTYPE | CL var for CRGTYPE (10) | Character value | Optional |
| RCYDMNLIST | CL var for RCYDMNLIST(25872) | Character value | Optional |
| CFGOBJLIST | CL var for CFGOBJLIST(18448) | Character value | Optional |
| TKVINTNETA | CL var for TKVINTNETA (45) | Character value | Optional |
| USRPRF | CL var for USRPRF (10) | Character value | Optional |
| JOB | CL var for JOB (10) | Character value | Optional |
| EXITPGM | CL var for EXITPGM (10) | Character value | Optional |
| EXITPGMLIB | CL var for EXITPGMLIB (10) | Character value | Optional |
| EXITPGMFMT | CL var for EXITPGMFMT (8) | Character value | Optional |
| EXITPGMDTA | CL var for EXITPGMDTA (256) | Character value | Optional |
| MSGUSRQ | CL var for MSGUSRQ (10) | Character value | Optional |
| MSGUSRQLIB | CL var for MSGUSRQLIB (10) | Character value | Optional |
| CFGINTNETA | CL var for CFGINTNETA (8) | Character value | Optional |
| ALWRESTART | CL var for ALWRESTART (4) | Character value | Optional |
| NBRRESTART | CL var for NBRRESTART (2 0) | Decimal number | Optional |
| FLVMSGQ | CL var for FLVMSGQ (10) | Character value | Optional |
| FLVMSGQLIB | CL var for FLVMSGQLIB (10) | Character value | Optional |
| FLVWAITTIM | CL var for FLVWAITTIM (4 0) | Decimal number | Optional |
| FLVDFTACN | CL var for FLVDFTACN (10) | Character value | Optional |
| APPID | CL var for APPID (20) | Character value | Optional |
| TEXT | CL var for TEXT (50) | Character value | Optional |
| Top |
Specifies the cluster resource group whose information is to be retrieved.
This is a required parameter.
| Top |
Specifies the cluster which contains the cluster resource group.
| Top |
Specifies the maximum number of recovery domain nodes that can be returned in the RCYDMNLIST parameter. It is possible that a cluster resource group could contain 128 nodes in its recovery domain. Rather than declaring a CL variable that is 25,872 characters long for RCYDMNLIST, RTVDMNCNT can contain a number less than 128 that tells the command how much memory is available to contain recovery domain node information. Each recovery domain entry returned in RCYDMNLIST requires 202 characters.
If the command was run for a cluster resource group which had 3 nodes, RTVDMNCNT could specify a value of 3 and RCYDMNLIST could be defined to be only 622 characters long.
RTVDMNCNT can be used to limit the node information that is returned in RCYDMNLIST. If RTVCRG is run on a cluster resource group which had 5 nodes in its recovery domain but the value specified for RTVDMNCNT is 2, information for only two 2 nodes would be returned in the RCYDMNLIST variable.
In CL programs, RTVDMNCNT can refer to a CL program variable. The variable would be declared as a 4-character variable if the value was *ALL. If the variable's value was a number, it could be declared either as a character data type or a numeric data type.
| Top |
Specifies the maximum number of configuration objects that can be returned in the CFGOBJLIST parameter. It is possible that a cluster resource group could contain 256 configuration objects. Rather than declaring a CL variable that is 18,448 characters long for CFGOBJLIST, RTVCFGCNT can contain a number less than 256 that tells the command how much memory is available to contain configuration object information. Each configuration object entry returned in CFGOBJLIST requires 72 characters.
If RTVCRG is run for a cluster resource group which has only one configuration object, RTVCFGCNT could specify a value of 1 and CFGOBJLIST could be defined to be only 88 characters long.
RTVCFGCNT can be used to limit the configuration object information that is returned in CFGOBJLIST. If RTVCRG is run on a cluster resource group which has five configuration objects but the value specified for RTVCFGCNT is 2, information for only two configuration objects would be returned in the CFGOBJLIST variable.
In CL programs, RTVCFGCNT can refer to a CL program variable. The variable would be declared as a 4-character variable if the value was *ALL. If the variable's value was 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 status of the cluster resource group. In CL programs, this should be a decimal variable with a length of (4 0). Possible values are:
| Top |
Specifies the name of a variable that is used to retrieve the cluster resource group type. In CL programs, this should be a 10-character variable. Possible values are:
| Top |
Specifies the name of a variable that is used to retrieve the list of recovery domain nodes defined in the cluster resource group. In CL programs, this can be a character variable up to 25,872 characters long. Each recovery domain node entry is 202 characters long. A cluster resource group can have a maximum of 128 recovery domain nodes defined. If there are fewer recovery domain nodes in the cluster resource group this command is retrieving information for, the length of this variable can be less. For example if there are only 4 recovery domain nodes, the length of this variable could be 824 characters.
Unless the RTVDMNCNT parameter is used to indicate the number of recovery domain nodes for which information can be contained in the RCYDMNLIST variable, it is assumed that enough memory has been allocated to contain information for all the recovery domain nodes in the cluster resource group. If the RTVDMNCNT parameter is not specified and insufficient memory is allocated for the RCYDMNLIST parameter, results are unpredictable.
The RCYDMNLIST contains a 16-byte header composed of the following which is then followed by one or more recovery domain entries.
Position Length Field
1 4-byte integer number Offset from beginning
of RCYDMNLIST to first
recovery domain entry
5 4-byte integer number Length of each recovery
domain entry
9 4-byte integer number Number of recovery domain
nodes configured in the
cluster resource group
13 4-byte integer number Number of recovery
domain node entries
returned in RCYDMNLIST
Each 202-character recovery domain node entry is composed of the following. The first recovery domain node entry should be addressed by using the offset field in the above header. Subsequent recovery domain node entries should be addressed by using the length field in the above header.
Position Length Field
1 8 characters Node identifier
9 (3 0) decimal number Current node role
11 (3 0) decimal number Preferred node role
13 (2 0) decimal number Node membership status
within the CRG
15 8 characters Site name
23 45 characters First data port IP address
68 45 characters Second data port IP address
113 45 characters Third data port IP address
158 45 characters Fourth data port IP address
The current or preferred role possible values are:
Possible node membership status values are:
If the node is not part of a site, *NONE will be returned in the site name field.
If there is no IP address, it will contain blanks.
| Top |
Specifies the name of a variable that is used to retrieve the list of configuration objects defined in the cluster resource group. Configuration objects only exist in a device cluster resource group. In CL programs, this can be a character variable up to 18,448 characters long. Each recovery configuration object entry is 72 characters long. A cluster resource group can have a maximum of 256 configuration objects defined. If there are fewer configuration objects in the cluster resource group this command is retrieving information for, the length of this variable can be less than 18,448. For example, if there are only two configuration objects, the length of this variable could be 160 characters.
Unless the RTVCFGCNT parameter is used to indicate the number of configuration objects for which information can be contained in the CFGOBJLIST variable, it is assumed that enough memory has been allocated to contain information for all the configuration objects in the cluster resource group. If the RTVCFGCNT parameter is not specified and insufficient memory is allocated for the CFGOBJLIST parameter, results are unpredictable.
The CFGOBJLIST contains a 16-byte header composed of the following, which is followed by one or more configuration object entries.
Position Length Field
1 4-byte integer number Offset from beginning of
CFGOBJLIST to first
configuration object entry
5 4-byte integer number Length of each configuration
object entry
9 4-byte integer number Number of configuration
objects in the cluster
resource group
13 4-byte integer number Number of configuration
object entries returned
in CFGOBJLIST
Each 72-character entry is composed of the following. The first configuration object entry should be addressed by using the offset field in the above header. Subsequent configuration object entries should be addressed by using the length field in the above header.
Position Length Field
1 10 characters Configuration object name
11 5 characters Configuration object type
16 (2 0) decimal number Device type
18 (2 0) decimal number Device subtype
20 8 characters Vary configuration object
attribute
28 45 characters Server takeover IP address
If there are no configuration objects configured for the cluster resource group, *NONE is returned in the CFGOBJLIST variable. The rest of the receiver variable remains unchanged.
Possible values for the configuration object type are:
Possible values for the device type are:
Possible values for the device subtype are:
Possible values for the vary configuration object attribute are:
If there is no IP address, it will contain blanks.
| Top |
Specifies the name of a variable that is used to retrieve the application takeover internet address. In CL programs, this should be a 45-character variable.
| Top |
Specifies the name of a variable that is used to retrieve the user profile under which the exit program should be run. In CL programs, this should be a 10-character variable.
| Top |
Specifies the name of a variable that is used to retrieve the name given the batch job that is submitted by the cluster resource group. This job will call the cluster resource group exit program. In CL programs, this should be a 10-character variable. Possible values are:
| Top |
Specifies the name of a variable that is used to retrieve the name of the exit program that is used to handle action codes that are passed to it due to operations on the cluster resource group. In CL programs, this should be a 10-character variable. If the cluster resource group does not have an exit program, *NONE is returned in this variable.
| Top |
Specifies the name of a variable that is used to retrieve the name of the library that contains the exit program. In CL programs, this should be a 10-character variable. If the cluster resource group does not have an exit program, blanks are returned in this variable.
| Top |
Specifies the name of a variable that is used to retrieve the format which is used for the information passed to the user when a CRG exit program is called. In CL programs, this should be a 8-character variable. The value is left justified and padded on the right with blanks. If no exit program is defined for this cluster resource group, EXTP0100 is returned.
| Top |
Specifies the name of a variable that is used to retrieve the exit program data that is passed to the cluster resource group exit program when it is called. In CL programs, this should be a 256-character variable. If no exit program data was specified, blanks will be returned in this variable.
| Top |
Specifies the name of a variable that is used to retrieve the name of the user queue to receive distributed information from the Distribute Information (QcstDistributeInformation) API. In CL programs, this should be a 10-character variable. If there is no user queue associated with the cluster resource group, *NONE is returned in the variable.
| Top |
Specifies the name of a variable that is used to retrieve the name of the library that contains the user queue associated with the cluster resource group. In CL programs, this should be a 10-character variable. If there is no user queue associated with the cluster resource group, blanks are returned in the variable.
| Top |
Specifies the name of a variable that is used to retrieve the information about who is responsible for configuring the takeover IP address. In CL programs, this should be a 8-character variable. It is composed of two pieces. The left-most 4 characters indicates the responsible party. Possible values are:
The next 4 characters specifies whether or not a takeover IP address can be active when starting an application cluster resource group. Possible values are:
| Top |
Specifies the name of a variable that is used to retrieve whether or not to restart an application if the cluster resource group exit program fails. In CL programs, this should be a 4-character variable. Possible values are:
| Top |
Specifies the name of a variable that is used to retrieve the number of times a cluster resource group exit program can be called on a same node before failure occurs. In CL programs, this should be a decimal variable with a length of (2 0).
| Top |
Specifies the name of a variable that is used to retrieve the failover message queue name. In CL programs, this should be a 10-character variable. If no message queue is associated with the cluster resource group, 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 failover message queue associated with the cluster resource group. In CL programs, this should be a 10-character variable. If there is no failover message queue associated with the cluster resource group, 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 failover 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. -2 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 failover message queue. In CL programs, this should be a 10-character variable.
Possible values are:
| Top |
Specifies the name of a variable that is used to retrieve the application identifier. In CL programs, this should be a 20-character variable. *NONE is returned if there is no application identifier.
| Top |
Specifies the name of a variable that is used to retrieve the user-defined description for the specified cluster resource group. In CL programs, this should be a 50-character variable. If there is no text associated with the user, blanks are returned in the CL variable.
| Top |
CRTCRG CLUSTER(SAMPLE)
CRG(ORDERDB)
CRGTYPE(*DEV)
EXITPGM(ORDERLIB/ORDEREXIT)
USRPRF(DBADMIN)
RCYDMN((TEXAS *PRIMARY) (KANSAS *BACKUP 1))
CFGOBJ((ORDERIASP *DEVD *OFFLINE '8.1.20.5'))
If a cluster resource group had been created using the above command, and a CL program was run on a SAMPLE cluster node containing the following:
DCL VAR(&CRGSTAT) TYPE(*DEC) LEN(4 0)
DCL VAR(&CFGCNT) TYPE(*INT) LEN(4) VALUE(1)
DCL VAR(&CFGOBJ) TYPE(*CHAR) LEN(72)
RTVCRG CRG(ORDERDB)
CLUSTER(*CURRENT)
RTVCFGCNT(&CFGCNT)
CRGSTS(&CRGSTAT)
CFGOBJLIST(&CFGOBJ)
Information for the cluster resource group on the system where the CL program was run would return the information into the following CL program variables:
&CRGSTAT 0010
&CFGOBJ 'ORDERIASP *DEVD0103*OFFLINE8.1.20.5 '
' '
| Top |
*ESCAPE Messages
| Top |