Multicast exception reporting
Use this information to learn about IBM® MQ Multicast event handlers and reporting IBM MQ Multicast exceptions.
IBM MQ Multicast assists with problem determination by calling the event handler to report multicast events which are reported using the standard IBM MQ event handler mechanism.
An individual Multicast event can result in more than one IBM MQ event being called because there might be multiple MQHCONN connection handles using the same multicast transmitter or receiver. However, each multicast exception causes only one event handler to be called per IBM MQ connection.
The IBM MQ MQCBDO_EVENT_CALL constant enables applications to register a callback to receive only IBM MQ events, and the MQCBDO_MC_EVENT_CALL enable applications to register a callback to receive only multicast events. If both constants are used, both types of event are received.
Requesting Multicast events
IBM MQ Multicast events use the MQCBDO_MC_EVENT_CALL constant in the
cbd.Options field. The following example demonstrates how to request multicast events:
cbd.CallbackType = MQCBT_EVENT_HANDLER;
cbd.Options = MQCBDO_MC_EVENT_CALL;
cbd.CallbackFunction = EventHandler;
MQCB(Hcon,MQOP_REGISTER,&cbd,MQHO_UNUSABLE_HOBJ,NULL,NULL,&CompCode,&Reason);
When the MQCBDO_MC_EVENT_CALL option is specified for the
cbd.Options field, the event handler is sent only IBM MQ Multicast events instead of connection level events. To request that both types of events are sent to the event handler, the application must specify the MQCBDO_EVENT_CALL constant in the cbd.Options field as well as the MQCBDO_MC_EVENT_CALL constant as shown in the following example:
cbd.CallbackType = MQCBT_EVENT_HANDLER;
cbd.Options = MQCBDO_EVENT_CALL | MQCBDO_MC_EVENT_CALL
cbd.CallbackFunction = EventHandler;
MQCB(Hcon,MQOP_REGISTER,&cbd,MQHO_UNUSABLE_HOBJ,NULL,NULL,&CompCode,&Reason);
For more information about values for the Options field see Options (MQLONG).
Multicast event format
IBM MQ Multicast exceptions include some supporting information which is returned in the Buffer parameter of the callback function. The Buffer pointer points to an array of pointers and the
MQCBC.DataLength field specifies the size, in bytes, of the array. The first element of the array always points to a short text description of the event. More parameters might be supplied depending on the type of event. The following table lists the exceptions:
| Event code | Description | Additional data |
|---|---|---|
| MQMCEV_PACKET_LOSS | Unrecoverable packet loss | Number of lost packets |
| MQMCEV_HEARTBEAT_TIMEOUT | Long absence of heartbeat control packet | N/A |
| MQMCEV_VERSION_CONFLICT | Reception of newer protocol version packets | N/A |
| MQMCEV_RELIABILITY | Different reliability modes of the transmitter and the receiver | N/A |
| MQMCEV_CLOSED_TRANS | Topic transmission is closed by 1 source | N/A |
| MQMCEV_STREAM_ERROR | Error detected on stream | N/A |
| MQMCEV_NEW_SOURCE | A new source starts to transmit on the topic | Source structure |
| MQMCEV_RECEIVE_QUEUE_TRIMMED | Packets removed from PacketQ due to time or space expiration | Number of trimmed packets |
| MQMCEV_PACKET_LOSS_NACK_EXPIRE | Unrecoverable packet loss due to NACK expiration | Number of lost packets |
| MQMCEV_ACK_RETRIES_EXCEEDED | Packets removed from history after max_ack_retries was exceeded | Number of packets removed |
| MQMCEV_STREAM_SUSPEND_NACK | NACKs have been suspended on a stream accepted by this topic | Suspend stream ID
Time in milliseconds that the stream is suspended for |
| MQMCEV_STREAM_RESUME_NACK | NACKs have been resumed after they have been suspended on a stream | Stream ID |
| MQMCEV_STREAM_EXPELLED | A stream accepted by this topic has been rejected due to an expel request | Stream ID |
| MQMCEV_FIRST_MESSAGE | First message from a source | Message number |
| MQMCEV_LATE_JOIN_FAILURE | Failed to start late join session | N/A |
| MQMCEV_MESSAGE_LOSS | Unrecoverable message loss | Number of lost messages |
| MQMCEV_SEND_PACKET_FAILURE | Multicast transmitter failed to send a multicast packet | N/A |
| MQMCEV_REPAIR_DELAY | Multicast receiver did not receive a repair packet for an outstanding NAK | N/A |
| MQMCEV_MEMORY_ALERT_ON | Receiver reception buffers are filling up | Buffer pool utilization percentage |
| MQMCEV_MEMORY_ALERT_OFF | Receiver reception buffers are down to normal | Buffer pool utilization percentage |
| MQMCEV_NACK_ALERT_ON | Receiver repair packet request rate reached high water mark | Current repair request rate in packets per second |
| MQMCEV_NACK_ALERT_OFF | Receiver repair packet request rate is down to normal | Current repair request rate in packets per second |
| MQMCEV_REPAIR_ALERT_ON | Transmitter repair packet send rate reached high water mark | N/A |
| MQMCEV_REPAIR_ALERT_OFF | Transmitter repair packet send rate is down to normal | N/A |
| MQMCEV_SHM_DEST_UNUSABLE | The Shared Memory region used by a transmitter topic destination has been detected to be unusable | N/A |
| MQMCEV_SHM_PORT_UNUSABLE | The Shared Memory port used by a receiver instance has been detected to be unusable | N/A |
| MQMCEV_CCT_GETTIME_FAILED | The get time from Coordinated Cluster Time failed | N/A |
| MQMCEV_DEST_INTERFACE_FAILURE | The network interface used by a transmitter topic destination has failed and a backup network interface is unavailable | |
| MQMCEV_DEST_INTERFACE_FAILOVER | The network interface used by a transmitter topic destination has failed and a successful failover to another Interface has been completed | |
| MQMCEV_PORT_INTERFACE-FAILURE | The network interface used by a receiver rmmPort has failed and a backup network interface is unavailable (or has also failed) | RMM configuration |
| MQMCEV_PORT_INTERFACE_FAILOVER | The network interface used by a receiver rmmPort has failed and a successful failover to another Interface has been completed | RMM configuration |