Functions performed by APIs with a parameter called Results Information operate asynchronously and will have data sent to a user queue once the API has finished processing. The user queue must be created before calling the API. User queues are created with the Create User Queue (QUSCRTUQ) API. The queue cannot be in an independent auxiliary storage pool. The queue must be created as a KEYED queue. The key for the user queue is described in the format of the user queue entry. The user queue name is passed to the API. The user queue may be in either system or user domain storage. Suggested values for each parameter is shown in the comments.
Parm: Value of Parm:
QUSCRTUQ (
UserQueueName,
ExtendedAttr,
QueueType, /* K Keyed */
KeyLength, /* 28 */
MaxMsgSize, /* 64000 */
InitialNumMsg, /* 1 */
AddtNumMsg, /* 1 */
PublicAuth, /* *EXCLUDE */
TextDescription,
Replace, /* *NO */
ErrorCode,
Domain, /* *USER */
Pointers, /* *NO */
NumberQueueExt, /* -1 */
ReclaimStg /* 0 */
);
When the Distribute Information (QcstDistributeInformation) API is used, the information sent between nodes is deposited on the user queue specified when the CRG was created. This queue must be created by the user on all active nodes in the recovery domain before using the QcstDistributeInformation API. See the Create Cluster Resource Group (QcstCreateClusterResourceGroup) API for details on when the distribute information queue must exist.
The following is the format of the user queue key. All user queue entries have the same format for the Cluster APIs that support the Results Information parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Entry type |
| 10 | A | CHAR(2) | Entry identifier |
| 12 | C | CHAR(16) | Request handle |
The following is the format of the user queue entry. All user queue entries have the same format for the Cluster APIs that support the Results Information parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Message format version ID |
| 4 | 4 | BINARY(4) | Message type |
| 8 | 8 | CHAR(30) | API name |
| 38 | 26 | CHAR(7) | Message identifier |
| 45 | 2D | CHAR(35) | Reserved |
| 80 | 50 | CHAR(8) | Failing node ID |
| 88 | 58 | CHAR(10) | External object name |
| 98 | 62 | CHAR(2) | Reserved |
| 100 | 64 | BINARY(4) | Offset to message data |
| 104 | 68 | BINARY(4) | Message data length |
| 108 | 6C | CHAR(*) | Message data |
API name. The name of the API that caused the results to be sent to the user queue.
Entry identifier. Format of the data. This is set by the IBM® i operating system. Valid values are:
| 00 | Data distributed by the cluster APIs. |
Entry type. The entry type on the user queue. This value is set by the IBM i. Valid values are:
| *CRS | Cluster Resource Services sent the results information to the user queue. |
External object name. The name of the object that was not successfully processed.
Failing node ID. The cluster node that detected the condition being reported.
Message data. The message data for the message identifier. The format of this field depends on the message identifier. The Retrieve Message (QMHRTVM) API can be used to determine the format of the message data for each message identifier.
Message data length. The length of the message data for the message identifier.
Message format version ID. The version of the message format that is being used.
Message identifier. An IBM i message identifier associated with a message description defined by IBM i.
Message type. The type of message sent to the user queue. Any diagnostic or information messages returned as a result of an API will appear before the completion message. The valid values are:
| 1 | Diagnostic |
| 2 | Information |
| 3 | Completion |
| 4 | User data |
Offset to message data. The number of bytes from the start of the user queue entry to the data.
Reserved. Reserved for future use. Set to hexadecimal zeroes.
Request handle. A unique identifier assigned by Cluster Resource Services and returned to the caller of the API.
[ Back to top | Cluster APIs | APIs by category ]