This APAR introduces multiple enhancements to business events support, including a new system error handling routine, improved error messages related to IBM MQ, and the ability to clear usage and error counts for business events and dispatch adapters. 

With this APAR, the following enhancements have been introduced: 

Improved error handling during dispatch processing 

With the introduction of a new system error handling routine, business event dispatch processing can properly handle processed and in-progress events if an unexpected system error occurs.Figure 1. An error occurred during business event dispatch processing. 

Business event dispatch ECBs process events within transaction scopes to ensure reliability and prevent event loss if an unexpected error occurs. For efficiency, multiple events might be processed within a single transaction scope. If an error occurs during business event processing, the in-progress event is moved to the optional error queue, and the transaction scope is closed. In Figure 1, Event 1 and Event 2 were processed in the same transaction scope. After Event 1 was successfully processed, a dispatch ECB processed Event 2. When an error occurred during the processing of Event 2, it was moved to the error queue, and the transaction scope was closed. Figure 2. A system error with exit occurred during business event dispatch processing. 

Figure 2 illustrates how business event processing previously handled system errors. Similarly to Figure 1, Event 1 was successfully processed. During business event dispatch processing of Event 2, a system error with exit occurred and z/TPF’s exit processing rolled back the transaction scope. By rolling back the transaction scope, Event 1 and Event 2 were put back on the dispatch queue.  At this point, a new dispatch ECB will process the events again and might hit the same error. If the error persists on each retry, it could significantly slow down or even block dispatch queue processing.  

Figure 3. The error recovery routine responds to a system error with exit during business event dispatch processing.  

With the new system error handling routine, system errors are managed similarly to other errors during business event dispatch processing (Figure 1). As in Figure 2, Event 1 was successfully processed, but a system error with exit occurred during the processing of Event 2. In Figure 3, Event 2 is now placed on the error queue, and the transaction scope is closed, rather than rolled back. This ensures that completed events are finalized and not retransmitted, while in-progress events are preserved for later review, preventing repeated processing errors and improving overall system resilience. 

Enhanced IBM MQ error messages 

Business events error messages related to IBM MQ have been updated to include resolved queue names and textual descriptions of IBM MQ reason codes. With IBM MQ, you have the ability to define remote queues, alias queues, or use IBM MQ dynamic routing support. Previously, if an error occurred as a result of a failed IBM MQ API call from business events, the affected queue name displayed in the error message might not have reflected the actual queue accessed. With this enhancement, the resolved queue name field in each error message displays the actual queue name, allowing you to easily identify the affected queue and take proper action.  

With a plethora of possible error codes returned by IBM MQ functions, it can be time-consuming to understand the meaning of each. The added reason text for IBM MQ reason codes aim to reduce the investigation required to determine the nature of the error.  

The following example shows error message, BEVA0037E, including the ‘RESOLVED QUEUE’ and ‘REASON TEXT’. These enhancements allow users to understand the cause of the error more easily. 

System: BEVA0037E 16.03.55 BUSINESS EVENT PROCESSING WAS UNABLE TO TRANSMIT DATA FOR AN EVENT. 

EVENT -            NewReservation 

TRANSMIT QUEUE –   ALIAS.XMIT.QUEUE _ 

RESOLVED QUEUE -   RESERVATIONS.XMIT.QUEUE 

DISPATCH ADAPTER - Resv_JSON_MQ 

REASON CODE -      2053 

REASON TEXT -      Q FULL+ 

ZBEVF CLEAR command support 

The ZBEVF CLEAR command has been added to allow you to clear usage and error statistics for business events and dispatch adapters. Over time, or with frequent use, business event processing can rapidly accumulate these statistics.  

You might monitor daily usage counts of business events and dispatch adapters on the z/TPF system. By issuing the ZBEVF CLEAR command on a scheduled basis, you can more easily track daily trends. 

This command is also useful for identifying changes in counts following system changes. For example, a problematic user program could cause error counts to spike for specific dispatch adapters. After resolving the issue, you might want to clear all counts for the affected dispatch adapters to clearly identify and monitor any new activity. 

The following example clears the usage and error counts for all business events and dispatch adapters. 

User:   ZBEVF CLEAR * 

System: BEVF0083I 16.27.06 USAGE AND ERROR COUNTS WERE CLEARED FOR DEPLOYED BUSINESS EVENTS AND DISPATCH ADAPTERS THAT                               MATCH THE SPECIFIED NAME PATTERN.   

                           PATTERN: *

                           NUMBER CLEARED: 80+ 

The following example clears the usage and error counts for all dispatch adapters with a name that begins with the text FLIGHT, followed exactly by one character. 

User:   ZBEVF CLEAR FLIGHT? TYPE-DISPATCH 
System: BEVF0079I 16.42.20  USAGE AND ERROR COUNTS WERE CLEARED FOR DEPLOYED DISPATCH ADAPTERS THAT MATCH THE SPECIFIED                              NAME PATTERN.

                            PATTERN: FLIGHT?

                            NUMBER CLEARED: 1+  

For more information about APAR PJ47215, see the APEDIT