Distribute Information (QcstDistributeInformation) API

The Distribute Information (QcstDistributeInformation) API is used to deliver information from a node in the recovery domain to other nodes in the recovery domain. The information will be delivered to the active nodes in the recovery domain for that cluster resource group. The number of nodes field in format RGDD0100 is used to send the information to only one node or all nodes.

The amount of information that can be sent between nodes with this API is between 1 and 62,000 bytes in length. The API does not encrypt the message data before sending it.

When the information is delivered to a node, it will be placed on the specified user queue. If the user queue is keyed, the key length must be greater than zero and the key must be at the beginning of the data. If the key length is 0, the queue will be assumed to be non-keyed. The user queue cannot be in an independent auxiliary storage pool. The results information queue will indicate the success or failure of the distribution for each active node in the recovery domain. For each failed delivery, a diagnostic message will be placed on the results information queue. When the API completes, a completion message is placed on the results information queue. If the message type is "First-In,First-Out" then no completion message will be placed on the results information queue.

This API can only be run on a node that is an active member in the recovery domain of a cluster resource group. For example, if nodes A, B, and C are active and nodes A and B make up the recovery domain for CRGA, the Distribute Information API for CRGA can only be run on nodes A or B.

Message delivery is determined by the value specified for message delivery type field. If you want all nodes in the recovery domain to receive the message in the same sequence, specify a 0. If you want to just send the message without guarantee of delivery, specify a 1. Messages are ordered within the same delivery type from the same sender.

This API requires the qualified distribute information user queue name field to be specified when the cluster resource group is created, otherwise this API will not be allowed to execute.

This API will:

1. Distribute the data to each node in the recovery domain with a status of Active (10) or to a single node if the number of nodes field in RGDD0100 is set to 1.
2. Enqueue the data on the user queue specified.
3. Work when the cluster is in a partition state. When the cluster is partitioned, the message is sent only to those nodes that are in the same partition as the node where the API was called.

This API requires:

1. Cluster Resource Services active on the node processing the request.
2. Existence of the specified user queue on all nodes in the array of node ids specified on this API.
3. The key at the beginning of the data, if using a keyed user queue.
4. The node processing the request must be in the recovery domain of the cluster resource group, otherwise the API is not valid.

This API operates in asynchronous mode. See Behavior of Cluster Resource Services APIs for more information. This API may be called from a cluster resource group exit program. The cluster resource group exit program will not be called when this API is run.

Restriction: This API should not be called from a cluster resource group exit program when a node is joining this cluster resource group, a node is being added to the recovery domain of this cluster resource group, or this cluster resource group is being created. The reason for this is that the node that is joining or being added will not get the information that the Distribute Information API sent.

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

Request Information User Queue Authority

*OBJOPER, *ADD

Request Information User Queue Library Authority

*EXECUTE

Request Information User Queue Lock

*EXCLRD

User Profile Authority

*USE

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.

If the message type is "First-In,First-Out" then the request handle field will be blank.

Cluster name

INPUT; CHAR(10)

The name of the cluster to which the cluster resource group belongs.

Cluster resource group name

INPUT; CHAR(10)

This name of the cluster resource group.

Distribute information

INPUT; CHAR(*))

The detailed information about the message that is be distributed. For more information, see Distribute Information (RGDD0100 Format).

Format name

INPUT;CHAR(8)

The content and format of the distribute information parameter. The possible format names are:

RGDD0100

Distribute information

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

Distribute Information (RGDD0100 Format)

Field Descriptions

Length of message. The length of the data that is to be distributed. This includes the key length. This value must be between 1 and 62,000.

Length of message key. The length of the key used to enqueue the message on a keyed user queue. The key must be at the start of the distributed message. Possible values are:

Message. The message to be distributed to the nodes in the recovery domain of the cluster resource group or node id array. Since pointers will not resolve correctly on other nodes, pointers should not be included in the message.

Message delivery type. The method used to deliver the message. Possible values are:

Node id. Name of the node to receive the message. If number of node ids is not 1, this field is ignored. If the number of node ids is 1, this value must contain the name of an active node in the recovery domain.

Number of node ids. The number of nodes in the array of node ids. If message delivery type is 0, the number of node ids must be 0. If message delivery type is 1, this field must contain 1 or -1. Possible values are:

Offset to array of node ids. The byte offset from the beginning of this table to the first node id. If number of node ids is -1 or 0, this field must be zero.

Offset to message. The byte offset from the beginning of this table to the message.

Usage Notes

Results Information User Queue

Asynchronous results are returned to a user queue specified by the Results Information parameter of the API. See Using Results Information and Cluster APIs Use of User Queues 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.