Plan for business event dispatch queue and dispatch processing

Choose a dispatch queue for your business event

The type of dispatch queue that is defined in the business event specification determines how business event dispatch processing processes events on the dispatch queue. Business event dispatch queues can be classified as unordered, ordered, or remote. For more information about business event dispatch queue types and their properties, see Business events dispatch queue types.

Unless otherwise specified, each business event uses the system default dispatch queue named IBEV.UNORDERED.DISPATCH.QUEUE. You can use a different dispatch queue for a business event by specifying the optional <esDispatchQueueName> element in the event specification. You might want to use different dispatch queues for different business events so that you can separate events based on volume, destination, service level agreements, or other criteria. For more information about using different dispatch queues, see Separate business events by using different dispatch queues.

Queue depth considerations

If the number of items on the business event dispatch queue becomes too large, it can be an indication of a problem. The process that removes the items from the dispatch queue might not be able to keep up with the rate that events are being created, or there might be an error in the event custom data format program or custom adapter program.

You can set a queue depth warning level to monitor the number of items on the dispatch queue by entering the ZBEVF SET command with the QDEPTHWARN parameter specified. Once per minute, the business event processing monitor checks the high-water mark of the number of messages on the dispatch queue and then resets the high-water mark to 0. If the high-water mark value exceeds the specified QDEPTHWARN parameter value, the BEVA0004W warning message is issued to the z/TPF console once per minute until the number of messages on the dispatch queue is lower than the QDEPTHWARN parameter value.

You also can specify a maximum depth for the business event dispatch queue by using the MAXDEPTH parameter on the ZMQSC DEFINE QL command. The default value of 0 specifies that there is no maximum queue depth. You can prevent the number of items on the dispatch queue from growing too large by setting the MAXDEPTH parameter to a value other than 0. When business event processing tries to add an event to the dispatch queue, and the number of items on the queue exceeds the specified MAXDEPTH parameter value, business event processing receives an error. As a result, business event processing enters error processing. The event error program might be called and the event message might be added to the error queue based on the business event specification. If you did not specify an error queue in the business event specification, the business event is discarded.

Certain scenarios might temporarily create a high amount of business event activity. As a result, the depth of the dispatch queue might spike temporarily. Set the MAXDEPTH parameter value large enough so that business event processing does not return errors when temporary spikes in activity occur. To determine an appropriate MAXDEPTH parameter value, you must understand the expected rate of events per second. With an appropriate value set for the MAXDEPTH parameter, the queue can hold the expected number of events during temporary spikes in activity. For more information, see IBM MQ data collection reports and Business events summary report.

If you need to change the maximum depth for a dispatch queue after the initial definition, enter the ZMQSC ALTER QL command with the MAXDEPTH parameter specified.

Message length considerations

Each IBM MQ queue has a maximum message length. Set the maximum message length based on the IBM MQ data collection reports. The report includes information about message sizes for each IBM MQ queue. Use the information from the report to see whether business event messages are approaching the defined maximum message length for the IBM MQ queue. If message lengths approach the maximum message length, change the maximum message length by entering the ZMQSC ALTER QL command with the MAXMSGL parameter specified.

Loosely coupled considerations

Business event processing is program base unique. Additionally, you can deploy the business event deployment descriptors on a processor by processor basis. Therefore, you can have a loosely coupled complex with one processor that uses business event processing and another processor that does not use business event processing.

When you remove a processor from the loosely coupled complex, you must move any messages that are on the dispatch queue to another active processor in the complex. You can move event messages from one dispatch queue to another by entering the ZMQSC MOVEMSGS command from a processor that was not removed from the loosely coupled complex.