Change Cluster Resource Services (QcstChgClusterResourceServices) API

  Required Parameter Group:

1	Request handle	Output	Char(16)
2	Cluster name	Input	Char(10)
3	Cluster resource services information	Input	Char(*)
4	Length of cluster resource services information	Input	Binary(4)
5	Format name	Input	Char(8)
6	Results information	Input	Char(30)
7	Error code	I/O	Char(*)

  Service Program: QCSTCTL2

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

The Change Cluster Resource Services (QcstChgClusterResourceServices) API is used to tune cluster performance and configuration parameters. The API provides a base level of tuning support where the cluster will adjust to a predefined set of values identified for high, low, and normal timeout and messaging interval values using format CRSC0100. If an advanced level of tuning is desired, usually anticipated with the help of IBM support personnel, then individual parameters may be tuned over a predefined range of values using format CRSC0200. Example control language command source has been provided in the base operating system option 7 (Example Tools Library, QUSRTOOL). See member, TCSTINFO, in file QUSRTOOL/QATTSYSC for more information.

The default values are set on a create operation and changes must be made under the Change Cluster Resource Services API documented here. Values for current settings may be retrieved using the Retrieve Cluster Resource Services Information (QcstRetrieveCRSInfo) API.

The rules for merging of partitioned nodes are as follows:

• If the tuning parameters defined under the Change Cluster Resource Services API documented here match exactly in both partitions, a merge will be allowed.

This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.

Restriction: This API cannot be called from a cluster resource group exit program.

Authorities and Locks

The program that calls this API must be running under a user profile with *IOSYSCFG special authority.

User Queue Authority

*OBJOPR and *ADD

User Queue Library Authority

*EXECUTE

User Queue Lock

*EXCLRD

Required Parameter Group

Request handle

OUTPUT; CHAR(16)

A unique string or handle that identifies this API call. It is used to associate this call to any responses placed on the user queue specified in the results information parameter.

Cluster name

INPUT; CHAR(10)

The name of the cluster.

Cluster resource services information

INPUT; CHAR(*)

Detailed information about the cluster resource services.

Length of cluster resource services information

INPUT; BINARY(4)

The length of the cluster resource services information.

Format name

INPUT; CHAR(8)

The format of the Cluster Resource Services information to be changed. The possible format names are:

CRSC0100	Automatic tuning to a level of high, low or normal heartbeat intervals and message timeout values for cluster performance and configuration parameters.
CRSC0200	Manually tune one or more of the cluster performance and configuration parameters.

Results information

INPUT; CHAR(30)

A library qualified user queue name followed by a reserved field.

Library qualified user queue: A user queue, which exists on the node from which the API was called, that receives results information after the function has completed on all active nodes in the cluster. See the Usage Notes section of this API for a description of the data that is placed on this queue. This is a 20 character field. The first 10 characters contain the user queue name and the second 10 characters contain the user queue library name. No special values are supported. QTEMP, *LIBL, and *CURLIB are not valid for the library name. The attributes of this user queue must be keyed.

Reserved: The last 10 characters of results information are reserved and must be set to hexadecimal zero.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

CRSC0100 Format

CRSC0200 Format

Field Descriptions

Note: Specify -1 on any parameters that are not changed. This pertains to format CRSC0200 only.

Note: Units and ranges for the fields described here may be found in the Field Settings Range Table located at the end of this Field Descriptions section of this document.

Ack remote fragments. Provides a switch to enable or disable a cluster messaging level acknowledgment for receipt of each fragment sent to a remote cluster node. Fragments are sent by the cluster messaging service for each cluster message whose size is greater than the specified Message fragment size. Remote cluster nodes are defined to be any nodes not on the local LAN (having a network or subnet IP address other than that of the source node for the message). ACKing remote fragments may be desirable in those few cases where low bandwidth gateways, routers, or bridges exist between local and remote systems.

CDAT protocol timeout interval. The timeout value used for distributing the Cluster Destination Address Table (CDAT) and synchronizing cluster communications when doing a create cluster, add node, or start node process. As the number of nodes in the cluster increases, the time required to run this synchronizing protocol increases. This is a low level Cluster Resoure Services start-up protocol.

Cluster recovery interval. The interval at which a cluster node takes inventory of required recovery actions and attempts automatic recovery as necessary. Those items checked are:

• Unreachable alternate point-point interface addresses for remote nodes.
• Unreachable multicast IP address for the local subnet.
• Partitioned nodes.

Configuration tuning level. Provides for a simple way to set cluster performance and configuration parameters. The valid values for this field are:

1	Adjustments are made to cluster communications to decrease the heartbeating frequency and increase the various message timeout values. With fewer heartbeats and longer timeout values, the cluster will be slower to respond (less sensitive) to communications failures.
2	Default values are used for cluster communications performance and configuration parameters. This setting may be used to return all parameters to the original default values.
3	Adjustments are made to cluster communications to increase the heartbeating frequency and decrease the various message timeout values. With more frequent heartbeats and shorter timeout values, the cluster will be quicker to respond (more sensitive) to communications failures.

Delayed ack timer. The timer used over inbound reliable messages to force an acknowledgment for unacknowledged messages should the sender not have requested an acknowledgment over the last delayed ack time period. This timer is started on receipt of a reliable message and stopped when an acknowledgment is sent for one or more unacknowledged messages.

Enable multicast. The cluster communications infrastructure makes use of User Datagram Protocol (UDP) multicast capabilities as the preferred protocol for sending cluster management information between nodes in a cluster. Where multicast capabilities are supported by the underlying physical media, cluster communications will utilize the UDP multicast to send management messaging from a given node to all local cluster nodes supporting the same subnet address. Messages being sent to nodes on remote networks will always be sent using UDP point to point capabilities. Cluster communications does not rely on routing capability of multicast messages.

The multicast traffic supporting cluster management messaging tends by nature to be bursty. Depending on the number of nodes on a given LAN (supporting a common subnet address) and the complexity of the cluster management structure that is chosen by the cluster administrator, cluster related multicast packets can easily exceed 40 packets/second. Bursts of this nature could have a negative impact on older networking equipment. One example would be congestion problems on devices on the LAN serving as Simple Network Management Protocol (SNMP) agents which need to evaluate each and every UDP multicast packet. Some of the earlier networking equipment does not have adequate bandwidth to keep up with this type of traffic. Insure that the network administrator has reviewed the capacity of the networks to handle UDP multicast traffic to make certain that clustering will not have a negative impact on the health and performance of the networks over which it is chosen to operate.

If the network does not wish to have the more efficient multicast capabilities used, setting this field to FALSE (0) will disable the multicast capabilities of the cluster and only point to point communications will be used by the cluster messaging services.

Maximum retry time. Reliable messages are resent at exponentially increasing times should they timeout (that is, not receive a timely acknowledgment). The initial timeout value for a message is the Retry Timer Value and each successive retry builds up by a factor of 2 until the Maximum retry timer value is exceeded. For the default cases, a message would be sent, resent 1 second later, then 2 seconds, 4 seconds, and finally 8 seconds. This represents a total of 15 seconds following which attempts to use alternate internet addressing are tried with the same timer values.

Maximum retry timer ratio. Remote subnets (remote cluster nodes on another LAN/WAN/BUS supporting a different subnet interface address than the sending node) use an extended message timeout value which is based from the Maximum retry time used for local subnets (local cluster nodes supporting the same subnet interface address). For the default case, the Maximum retry time for a local multicast message would be 8 seconds and for a remote point to point message would be 8 x 8 = 64 seconds. This allows for network routing considerations.

Message fragment size. Cluster communications fragments its own messages. This fragment size should be set consistent with the physical media and routing capabilities throughout the network used for clustering. The preferred settings allow for the largest fragment size possible that does not exceed any of the hardware Maximum Transmission Units defined over the entire path so that clustering does all of the fragmentation, not the intermediary networks. The default is set to assume a minimum 1500 byte (less network header space) Ethernet environment.

Message send window. The number of messages allowed outstanding without having received an acknowledgment. The higher the number, the lower the message latency but the larger the required buffer space on a node to save inbound messages.

Number of ack messages threshold. The number of repeat messages that are received over the course of a cluster recovery interval before acknowledgments are sent to multiple source interface addresses for a given node instead of just the current primary address for each message received. While increasing the number of ACKs flowing, this reduces the message resends and latency given that an intermittent communications condition is detected. Eventually, one of the node addresses should be marked as failed and at cluster recovery time, messaging will settle back down using single acknowledgments.

Number of bad messages threshold. The number of undeliverable messages per Cluster recovery interval allowed before a failing status is assigned to a node's interface address. At this time, a secondary address (if available) is assigned to be the new primary interface address for the subject remote node.

Performance class. The requested performance characteristics of the cluster communications messaging protocol. Pacing is selectively used for sending out fragments of large messages. Messages are fragmented by the cluster messaging service at the specified message fragment size. The pacing mechanism releases a set number of fragments to the underlying physical layer, then delays, then releases a next set. This is to avoid over running slower physical media. Local here refers to nodes on a local LAN. Remote refers to messaging to cluster nodes on other than the local LAN. Valid values for the performance class are as follows:

Reachable heartbeat ack threshold. A node becomes reachable (formerly having been marked as unreachable) from a Cluster Communications heartbeating perspective if "Reachable heartbeat ack threshold" (or greater) heartbeat message ACKs are received for the last "Reachable heartbeat threshold" heartbeat messages sent to a node. For the default case, a node becomes reachable if 3 or more of the last four heartbeats sent to the marked unreachable node are now acknowledged.

Reachable heartbeat threshold. See Reachable heartbeat ack threshold field description.

Receive/send heartbeat timer ratio. Ratio of incoming heartbeat messages expected from a neighboring node to the number of heartbeat messages that are sent out. The send rate is always set higher to insure a neighboring node's receive heartbeat timer does not fire under normal operational circumstances.

Retry timer value. See Maximum retry time field description.

Send heartbeat interval. The interval at which a low level Cluster Communications heartbeat message is sent to a neighboring node.

Send queue overflow. The maximum number of messages that are allowed to be queued up in a Cluster Communications outbound message queue. The cluster communication send queues are distributed amongst the various groups. The larger the number, the greater the memory resources that are required to support cluster messaging. If a send queue overflow is hit for a given group, the inability to send a message could lead to the termination of that group resulting from the lack of resources on a node.

Unreachable heartbeat ack threshold. A reachable node becomes unreachable from a cluster communications heartbeating perspective if "Unreachable heartbeat ack threshold" heartbeat message ACKs (or less) are received for the last "Unreachable heartbeat threshold" heartbeat messages sent to a node. For the default case, a node becomes unreachable if one or less of the last four heartbeats sent to the marked reachable node are acknowledged.

Unreachable heartbeat threshold. See Unreachable heartbeat ack threshold field description.

Field Settings For CRSC0200 Format

Field Settings Range

Usage Notes

Results Information User Queue

Asynchronous results are returned to a user queue specified by the Results Information parameter of the API. See Cluster APIs Use of User Queues and Using Results Information for details on how to create the results information user queue, the format of the entries, and how to use the data placed on the queue. The data is sent to the user queue in the form of a message identifier and the substitution data for the message (if any exists). The following identifies the data sent to the user queue (excluding the message text).

Error Messages

Messages that are delivered through the error code parameter are listed here. The data (messages) sent to the results information user queue are listed in the Usage Notes above.