Distribute Information (QcstDistributeInformation) API
Required Parameter Group:
| 1 | Request handle | Output | Char(16) |
| 2 | Cluster name | Input | Char(10) |
| 3 | Cluster resource group name | Input | Char(10) |
| 4 | Distribute information | Input | Char(*) |
| 5 | Format name | Input | Char(8) |
| 6 | Results information | Input | Char(30) |
| 7 | Error code | I/O | Char(*) |
Service Program: QCSTCRG2
Default Public Authority: *EXCLUDE
Threadsafe: Yes
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," 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:
- 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.
- Enqueue the data on the user queue specified.
- 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:
- Cluster Resource Services active on the node processing the request.
- Existence of the specified user queue on all nodes in the array of node ids specified on this API.
- The key at the beginning of the data, if using a keyed user queue.
- 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)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Message delivery type |
| 4 | 4 | BINARY(4) | Length of message key |
| 8 | 8 | BINARY(4) | Offset to message |
| 12 | C | BINARY(4) | Length of message |
| 16 | 10 | BINARY(4) | Offset to array of node ids |
| 20 | 14 | BINARY(4) | Number of node ids |
| 24 | 18 | CHAR(*) | Message |
| * | * | Array of CHAR(8) | Node id |
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:
| 0 | Non-keyed user queue. |
| >=1 | Size of the key. |
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:
| 0 | Total ordering. Guaranteed delivery of totally ordered message and that receipt of message on all active nodes in the recovery domain. |
| 1 | First-In, First Out (FIFO). Non guaranteed delivery. Message delivered FIFO and no receipt/acknowledgment required. |
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:
| -1 | The message will be sent point to point to all active nodes in the recovery domain. |
| 0 | Total ordering, no node ids can be specified. Message processed on all nodes in the recovery domain at the same time. |
| 1 | Message deliver is First-In, First Out(FIFO). Only one node id can be specified. |
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).
| Message ID | Message Text |
|---|---|
| CPCBB01 C | Cluster Resource Services API &1 completed. |
| CPF2113 D | Cannot allocate library &1. |
| CPF2204 D | User profile &1 not found. |
| CPF3CF2 D | Error(s) occurred during running of &1 API. |
| CPF9801 D | Object &2 in library &3 not found. |
| CPF9802 D | Not authorized to object &2 in &3. |
| CPF9803 D | Cannot allocate object &2 in library &3. |
| CPF9804 D | Object &2 in library &3 damaged. |
| CPF9810 D | Library &1 not found. |
| CPFBB0A D | Cluster node &1 in cluster &2 not active. |
| CPFBB0F D | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB18 D | Request &1 is not allowed for cluster resource group &2. |
| CPFBB2D D | Timeout detected while waiting for a response. |
| CPFBB32 D | Attributes of user queue &1 in library &2 are not valid. |
| CPFBB38 D | Library name &1 is not allowed for this request. |
| CPFBB46 D | Cluster Resource Services internal error. |
| CPFBB47 D | Cluster Resource Services ended abnormally. |
| CPFBB5F D | Field value within structure is not valid. |
| CPFBB8F D | Enqueue on distribute information queue &1 in library &2 failed. |
| CPIBB0B I | Distribute information message delivered to &1. |
| CPIBB0C I | Distribute information message could not be delivered to &1. |
| CPIBB0D I | No attempt made to deliver distribute information message to node &1. |
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.
| Message ID | Error Message Text |
|---|---|
| CPF2204 E | User profile &1 not found. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C29 E | Object name &1 is not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF980C E | Object &1 in library &2 cannot be in an independent auxiliary storage pool. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFBB02 E | Cluster &1 does not exist. |
| CPFBB0F E | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| CPFBB32 E | Attributes of user queue &1 in library &2 not valid. |
| CPFBB38 E | Library name &1 is not allowed for this request. |
| CPFBB46 E | Cluster Resource Services internal error. |
| CPFBB5F E | Field value within structure is not valid. |
| CPFBB70 E | API request &1 not compatible with current cluster version. |
| CPFBB88 E | Node &1 not in recovery domain for Cluster Resource Group &2. |
| CPFBB8C E | &2 API will not work against cluster resource group &1. |
API introduced: V5R1
[ Back to top | Cluster APIs | APIs by category ]