Retrieve CRG (RTVCRG)

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.

Parameters

Cluster resource group (CRG)

Specifies the cluster resource group whose information is to be retrieved.

This is a required parameter.

name

Specify the name of the cluster resource group whose information is to be retrieved.

Cluster (CLUSTER)

Specifies the cluster which contains the cluster resource group.

*

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.

Retrieve recovery domain count (RTVDMNCNT)

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.

*ALL

All recovery domain nodes are to be returned.

1-128

Specify the number of recovery domain nodes for which information is returned.. If the number specified is larger than the actual number of recovery domain nodes, only the actual number is returned.

Retrieve config object count (RTVCFGCNT)

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.

*ALL

All configuration objects are to be returned.

1-256

Specify the number of configuration objects to return. If the number specified is larger than the actual number of configuration objects, only the actual number is returned.

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.

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 RTVCRG command on an active node in the cluster.
• Start Cluster Resource Services on the node and run the RTVCRG command again.

CL var for CRGSTS (4 0) (CRGSTS)

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:

10

Active. The resources managed by the cluster resource group are currently resilient.

20

Inactive. The resources managed by the cluster resource group are currently not resilient.

30

Indoubt. 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.

40

Restored. 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.

500

Add Node Pending. 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.

510

Delete Pending. 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.

520

Change Pending. 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.

530

End Cluster Resource Group Pending. 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.

540

Initialize Pending. 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.

550

Remove Node Pending. 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.

560

Start Cluster Resource Group Pending. 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. For peer model cluster resource groups all nodes defined with a role of peer are active access points for the cluster resources.

570

Switchover Pending. 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. While the switchover function is not valid for a peer cluster resource group, users may see the status "switchover pending" during a node failure.

580

Delete Command Pending. Cluster resource group object is being deleted by the Delete Cluster Resource Group (DLTCRG) command. 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.

590

Add Device Entry Pending. 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.

600

Remove Device Entry Pending. 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.

610

Change Device Entry Pending. 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.

620

Change Node Status Pending. 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.

CL var for CRGTYPE (10) (CRGTYPE)

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:

*DATA

A data cluster resource group.

*APP

An application cluster resource group.

*DEV

A device cluster resource group.

*PEER

A peer cluster resource group.

CL var for RCYDMNLIST(25872) (RCYDMNLIST)

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:

0

Primary node. Only one node will have this value.

>=1

Backup node. The backup order is designated by increasing value.

-1

Replicate node. All replicates have this value.

-4

Peer node. All peers have this value.

Possible node membership status values are:

0

Active. The node is an active member of the cluster resource group membership.

1

Inactive. The node is not an active member of the cluster resource group membership. The Cluster Resource Services may not be active on the node or the cluster resource group job could be ended on the node.

2

Partition. The node is partitioned from the other members of the cluster resource group membership.

3

Ineligible. The node is an active member of the cluster resource group membership but not eligible to become the cluster resource group primary node.

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.

CL var for CFGOBJLIST(18448) (CFGOBJLIST)

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:

*DEVD

Configuration objects of type device description.

*CTLD

Configuration objects of type controller description.

*LIND

Configuration objects of type line description.

*NWSD

Configuration objects of type network server description.

Possible values for the device type are:

1

Auxiliary storage pool

2

Asynchronous line

3

BSC line

4

Cryptographic device

5

DDI line

6

Ethernet line

7

Fax line

8

Integrated xSeries guest server

9

Integrated xSeries iSCSCI server

10

Integrated xSeries server

11

Local work station controller

12

Optical device

14

PPP line

15

SDLC line

16

Tape controller or device

18

Token ring line

19

Wireless line

20

X.25 line

29

Network server host

33

Network server Windows NT

Possible values for the device subtype are:

-1

The subtype cannot be determined because hardware configuration is not complete.

0

This device type does not have a subtype.

1

UDFS independent auxiliary storage pool.

2

Secondary independent auxiliary storage pool.

3

Primary independent auxiliary storage pool.

Possible values for the vary configuration object attribute are:

*OFFLINE

Do not vary the configuration object on and do not start the server takeover IP address.

*ONLINE

Vary the configuration object on and start the server takeover IP address.

*PRIMARY

This is a secondary ASP. Vary on processing is determined by the corresponding primary ASP for this ASP group.

If there is no IP address, it will contain blanks.

CL var for TKVINTNETA (45) (TKVINTNETA)

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.

CL var for USRPRF (10) (USRPRF)

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.

CL var for JOB (10) (JOB)

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:

*JOBD

The job name in the job description for the specified user profile will be used.

*NONE

The cluster resource group does not have an exit program.

name

The specified name to be given to the batch job.

CL var for EXITPGM (10) (EXITPGM)

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.

CL var for EXITPGMLIB (10) (EXITPGMLIB)

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.

CL var for EXITPGMFMT (8) (EXITPGMFMT)

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.

CL var for EXITPGMDTA (256) (EXITPGMDTA)

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.

CL var for MSGUSRQ (10) (MSGUSRQ)

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.

CL var for MSGUSRQLIB (10) (MSGUSRQLIB)

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.

CL var for CFGINTNETA (8) (CFGINTNETA)

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:

*CRS

Cluster Resource Services is responsible for configuring the takeover IP address.

*USR

User is responsible for configuring the takeover IP address.

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:

*YES

Allow the takeover IP address to already be active when starting the cluster resource group.

*NO

Do not allow the takeover IP address to already be active when starting the cluster resource group.

CL var for ALWRESTART (4) (ALWRESTART)

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:

*YES

Attempt to restart the application on the same node.

*NO

Do not attempt to restart the application. address.

CL var for NBRRESTART (2 0) (NBRRESTART)

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).

CL var for FLVMSGQ (10) (FLVMSGQ)

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.

CL var for FLVMSGQLIB (10) (FLVMSGQLIB)

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.

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 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.

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 failover message queue. In CL programs, this should be a 10-character variable.

Possible values are:

*PROCEED

Proceed with failover.

*CANCEL

Do not attempt failover.

CL var for APPID (20) (APPID)

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.

CL var for TEXT (50) (TEXT)

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.

Examples

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               '
            '                      '

Error messages

*ESCAPE Messages

CPFBB02

Cluster &1 does not exist.

CPFBB0F

Cluster resource group &1 does not exist in cluster &2.

HAE000A

All cluster command user spaces busy.

HAE004E

Length of CL program variable not valid.

HAE004F

&1 command failed.