CRTCRG (Create Cluster Resource Group)

CRTCRG Command syntax diagram

 

Purpose

The Create Cluster Resource Group (CRTCRG) command creates a cluster resource group object. The cluster resource group serves as the control object for a collection of resilient resources. It identifies a recovery domain, which is a set of nodes in the cluster that will play a role in recovery. You also define additional characteristics for the cluster resource group, such as the exit program that will be called to perform resource specific processing. Successful completion of this command results in a new job started in the QSYSWRK subsystem. The name of this job name is the cluster resource group name.

To change attributes of the cluster resource group use the Change Cluster Resource Group (CHGCRG) command.

This command will do the following:

Restrictions

  1. To use this command have *IOSYSCFG authority.

  2. This CL command cannot be called from a cluster resource group exit program.

  3. The cluster resource group name cannot begin with QCST.

  4. Cluster Resource Services must be active on the node processing the API request.

  5. All nodes in the recovery domain must be in the cluster with a status of Active.

  6. The cluster resource group exit program must exist on all nodes in the recovery domain if an exit program is specified. It must have the same name and be in the same library on each node.

  7. Each node can be specified only once in the recovery domain.

  8. The cluster resource group name cannot be used by an existing cluster resource group on any node in the cluster.

  9. For application cluster resource groups, the following restrictions apply to the specified takeover IP address:

    1. If Cluster Resource Services configures the takeover IP address, all nodes in the recovery domain must be in the same subnet (network address) and the subnet defined on all nodes in the recovery domain.

    2. The takeover IP address must be unique. If Cluster Resource Services is responsible for configuring the takeover IP address, it will be added to each node in the recovery domain.

    3. The takeover IP address must not be active on any node in the recovery domain.

  10. For device cluster resource groups:

    1. Only auxiliary storage pool devices are supported.

    2. All nodes in the recovery domain must belong to the same device domain.

    3. The configuration objects, such as device descriptions, for the devices specified for the cluster resource group must exist on all nodes in the recovery domain and the resource name specified in a configuration object must be the same on all nodes in the recovery domain.

    4. If a data base name is specified in a configuration object, it must be the same on all nodes in the recovery domain.

    5. The server takeover IP address must be unique. It can only be associated with a primary auxiliary storage pool.

    6. The same configuration object cannot be specified for more than one cluster resource group.

    7. Devices attached to the same input/output processor (IOP) or high-speed link I/O bridge can be specified for only one cluster resource group.

    8. If devices attached to different IOPs or high-speed link I/O bridges are grouped such as for an auxiliary storage pool, all devices for the affected IOPs or high-speed link I/O bridges must be specified in the same cluster resource group.

    9. The IOP or high-speed link I/O bridge controlling the devices specified in a cluster resource group must be accessible by all nodes in the cluster resource group's recovery domain. This is verified if sufficient hardware configuration has been performed so that all nodes are aware of the new hardware. If hardware configuration is incomplete, this is verified when the Start Cluster Resource Group (STRCRG) command is called.

    10. If configuration objects are specified and the primary node does not currently own the devices, the command fails with an error message.

    11. A cluster resource group may be created with no device entries. Device entries must be added using the Add Cluster Resource Group Device Entry (ADDCRGDEVE) command before the cluster resource group can be started.

    12. If the cluster resource group contains any members of an auxiliary storage pool group, it must contain all members before the cluster resource group can be started. All members do not have to be specifed when the cluster resource group is created. Additional members can be added with the Add Cluster Resource Group Device Entry (QcstAddClusterResourceGroupDev) API. If the auxiliary storage pool group exists and clustering can determine the members of the group, a warning message is sent if any members were not specified.

 

Required Parameters

CLUSTER
Specifies the name of the cluster containing the cluster resource group which will be created.

cluster-name: Specify the name of the cluster.

CRG
Specifies the name of the cluster resource group to be created.

cluster-resource-group-name: Specify the name of the cluster resource group.

CRGTYPE
Specifies the type of the cluster resource group that is to be created.

*DATA: The cluster resource group is a data cluster resource group.

*APP: The cluster resource group is an application cluster resource group.

*DEV: The cluster resource group is a device cluster resource group.

EXITPGM
Specifies 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. The exit program cannot be in an independent auxiliary storage pool. The action codes are described in Cluster Resource Group Exit Program API.

*NONE: The cluster resource group does not have an exit program. This is valid only for a device cluster resource group.

library-name: Specify the name of the library where the exit program exists. QTEMP is not a valid library name. If the cluster resource group exit program name is *NONE, the exit program library name is ignored.

cluster-resource-group-exit-program-name: Specify the name of the exit program.

USRPRF
Specifies the name of the user profile under which the exit program should be run. The user profile must exist on all nodes in the recovery domain. This field must be set to *NONE if no exit program is specified. The following user profiles are not valid:

  • QDBSHR

  • QDOC

  • QDTFOWN

  • QRJE

  • QLPAUTO

  • QLPINSTALL

  • QSECOFR

  • QSPL

  • QSYS

  • QTSTRQS

*NONE: There is no exit program so no user profile is needed.

user-profile-name: Specify the name of the user profile to use for running the exit program.

RCYDMN
Specifies the list of nodes that compose the recovery domain. A role must be defined for each node in the recovery domain. The node role can be primary, backup, or replicate. Nodes in the recovery domain must be unique.

Element 1: Node Identifier
Specifies the node being added to the recovery domain of the cluster resource group specified. The node specified must be in the cluster and must be unique in the recovery domain of the cluster resource group specified.

node-identifier: Specify the name of the system.

Element 2: Node Role
Specifies the role of the node in the recovery domain of the cluster resource group.

*BACKUP: The node will be added as a backup node.

*PRIMARY: The node will be added as the primary node. One node in the recovery domain must have the role or *PRIMARY.

*REPLICATE: The node will be added as a replicate. Replicate nodes are not ordered.

Element 3: Backup sequence number
Specifies the backup order for a node with role of *BACKUP. At the completion of the request the nodes with backup roles will be sequentially renumbered from the first backup to the last. The first backup will always be 1.

*LAST: The node will be added as the last backup in the recovery domain. If *LAST is specified for more than one node, then the first node specified with *LAST will be the last backup node, second node specified will be the second to the last backup node, etc..

backup-sequence-number: Specify the backup sequence number.

TKVINTNETA
Specifies the interface address that is to be associated with an application. This is the takeover IP address that will be switched between systems. The field must be represented in dotted decimal format.

takeover-IP-address: Specify the takeover IP address for the application cluster resource group.

 

Optional Parameters

EXITPGMDTA
Specifies up to 256 bytes of data that is passed to the cluster resource group exit program when it is called. This parameter may contain any scalar data except pointers. For example, it can be used to provide state information. This data will be stored with the specified clcuster resource group and copied to all nodes in the recovery domain. Pointers in this area will not resolve correctly on all nodes and should not be placed in the data.

*NONE: There is no exit program data.

exit-program-data: Specify up to 256 bytes of data to be passed to the cluster resource group exit program.

CRGMSGUSRQ
Specifies the name of the user queue to receive distributed information from the Distribute Information (QcstDistributeInformation) API. If the user would like to distribute cluster-wide information through this cluster resource group using the Distribute Information API, then this field must be set to a value other than *NONE. If this field is set, the specified user queue must exist on all nodes in the recovery domain after the exit program completes. The only way to change the value of this field once the cluster resource group has been created is to delete and recreate the cluster resource group.

*NONE: The Distribute Information API will not be used to distribute information through this cluster resource group.

Element 1: library-name: Specify the name of the library that contains the user queue to receive the distributed information. The library name cannot be *CURLIB, QTEMP, or *LIBL.

Element 2: distribute-information-user-queue-name: Specify the name of the user queue.

CFGINTNETA
Specifies who is responsible for configuring (adding and removing) the takeover IP address. This does not affect the starting and ending of the takeover IP address, Cluster Resource Services will perform this function.

*CRS: Cluster Resource Services is responsible for configuring the takeover IP address. The takeover IP address must not exist on any of the nodes in the recovery domain prior to creating cluster resource group. The takeover IP address will be removed when the cluster resource group is deleted.

*USR: User is responsible for configuring the takeover IP address. The takeover IP address must be added on all nodes in the recovery domain except replicates prior to starting the cluster resource group. For details on configuring a takeover IP address for an application cluster resource group that has recovery domain nodes in different subnets, go to Configuring under the Clustering topic in the iSeries Information Center. You can access the Information Center from the iSeries 400 Information Center CD-ROM.

JOB
Specifies the name given the batch job that is submitted by the cluster resource group. This job will call the cluster resource group exit program with the action code generated by the command being used. If this field is blank, the job name will be the value of the job description found in the user profile.

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

job-name: Specify the name to be given to the batch job submitted for running the exit program.

ALWRESTART
Specifies whether or not to restart an application if the cluster resource group exit program fails.

*NO: Do not attempt to restart the application. The cluster resource group exit program is called with an action code of Failover.

*YES: Attempt to restart the application on the same node. The cluster resource group exit program will be called with an action code of Restart. If the application cannot be restarted in the specified maximum number of attempts, the cluster resource group exit program will be called with an action code of Failover.

NBRRESTART
Specifies the number of times a cluster resource group exit program can be called on a same node before failure occurs. Maximum number of restarts is 3.

*NONE: There should be no restart attempts before a failover is started.

number-of-restarts: Specify the number of times that restart will be attempted before doing a failover.

CFGOBJ
Specifies detailed information about the resilient devices to be added to the cluster resource group.

*NONE: There are no configuration objects defined for this cluster resource group.

Element 1: Configuration Object
The name of the auxiliary storage pool device description object which can be switched between the nodes in the recovery domain. An auxiliary storage pool device description can be specified in only one cluster resource group.

configuration-object: Specify the device description name.

Element 2: Configuration Object Type
Specifies the type of configuration object specified with configuration object name.

*DEVD: Type of configuration object is device description.

Element 3: Configuration Object Online
Specifies what configuration action to take when the cluster resource group is switched over or failed over to a backup node. The configuration object can be varied on and the server takeover IP address can be started or leave the configuration object varied off and the server takeover IP address inactive when a device ownership is moved to another node. This attribute does not vary the device on or off when the cluster resource group is started or ended.

*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 and starting of the server takeover IP address is determined by the corresponding primary ASP for this ASP group.

Element 4: Server Takeover IP Addresss
Specifies a takeover IP address for servers associated with the relational database name in the device description for an auxiliary storage pool. This element is optional and can only be specified for a primary auxiliary storage pool. If specified, the addresss must be presented in dotted decimal format. The specified address must exist on all nodes in the recovery domain if the cluster resource group is active. If not specified, or for a secondary or UDFS auxiliary storage pool, the element must be set to *NONE.

*NONE: There is no server takeover IP address associated with the relational database name in the device description for an auxiliary storage pool.

server-takeover-IP-address: Specify the server takeover IP address for the relational database.

TEXT
Specifies the text used to briefly describe the cluster resource group object.

*NONE: There is no text describing this cluster resource group.

text-description: Specify the text to describe the cluster resource group object.

FLVMSGQ
Specifies the name of the message queue to receive messages (CPABB01) dealing with failover. If the user would like to receive notice before a failover occurs, then this parameter must be set to a value other than *NONE. If this field is set, the specified message queue must exist on all nodes in the recovery domain after the exit program completes. The message queue cannot be in an independent auxiliary storage pool.

*NONE: No messages will be sent when a failover occurs for this cluster resource group. This is the way V5R1M0 and prior releases work.

library-name: Specify the qualified name of where the failover message queue exist. The library name cannot be *CURLIB, QTEMP, or *LIBL.

failover-message-queue-name: Specify the name of the failover message queue.

FLVWAITTIM
Specifies the number of minutes to wait for a reply to the failover message that was enqueued on the failover message queue.

*NOWAIT: Failover proceeds without user intervention. Acts the same as V5R1M0 and prior.

*NOMAX: Wait forever until a response is given to the failover inquiry message.

number-of-minutes: Specify the number of minutes to wait for a response to the failover inquiry message. If no response is received in the specified number of minutes, the failover default action field will be looked at to decide how to proceed.

FLVDFTACN
If a response to the failover message in the failover message queue is not received in the failover wait time limit, then this field tells clustering what it should do pertaining to the failover request.

*PROCEED: Proceed with failover.

*CANCEL: Do not attempt failover.

Example for CRTCRG 

CRTCRG CLUSTER(MYCLUSTER) CRG(MYCRG) CRGTYPE(*DEV) EXITPGM(TEST/EXITPGM)
USRPRF(USER1) TEXT('IASP for Application 17')
RCYDMN((NODE01 *PRIM)(NODE *BACKUP *LAST)) CFGOBJL(*NONE)

This command creates a device cluster resource group called MYCRG in the cluster called MYCLUSTER. The recovery domain consists of two nodes. NODE01 is the primary and NODE02 is the only backup. The list of configuration objects not specified. They will be added later with the ADDCRGDEVE command.

Error messages for CRTCRG

*ESCAPE Messages

CPF0001
Error found on &1 command.