Event error program format

The event error program must accept parameters as defined by the eventErrorProgram typedef.

Format

#include <tpf/ibev.h>
typedef int (*eventErrorProgram)(int callType,
                                 int errorReason,
                                 struct tpf_bev_evtmsg *evtMsg,
                                 struct tpf_bev_event_controls **controls,
                                 struct tpf_bev_data_format_user_data **usrFmtData,
                                 struct tpf_bev_standard_format_user_data 	
                                 **stdFmtData
                                 );

Parameters

callType

The reason for calling the event error program. One of the following values is set for this parameter:

TPF_BEV_ERROR_BEFORE_ERROR_QUEUE: Calls the event error program before the event message is added to the error queue.
TPF_BEV_ERROR_MOVE_FROM_ERROR_QUEUE: Calls the event error program before the event message is moved from the error queue to the dispatch queue.

errorReason

Indicates the error that occurred. Error reasons are defined in the tpf/ibev.h header file in the bev_errorQueueReason enumerated type.

evtMsg

A pointer to the address of the tpf_bev_evtmsg structure, which contains the sizes and addresses of the event message components.

controls

A pointer to a pointer to the structure that contains controls for processing this business event. The event error program can use this parameter to change settings for this particular business event.

The tpf_bev_event_controls structure is defined in the tpf/ibev.h header file.

usrFmtData

A pointer to a pointer of the structure that contains information that you want to pass to the data format programs. Use this parameter to pass information to the data format program that is not included in the event message. For example, you can use this data to control how the event custom data format program formats the event message. If you want to modify the default values in the Common Base Event header, the event error program passes the information pointed to by this parameter to the data format program. For Common Base Event formatted data, the information is passed to the Common Base Event data user exit (ubev_cbeData_user_exit).

The tpf_bev_data_format_user_data structure is defined in the tpf/ibev.h header file.

stdFmtData

A pointer to a pointer of the structure that contains more information that you want to pass to the standard data format programs. Use this parameter to pass information to the z/TPF standard data format programs to populate any header information that is not populated by default. For example, if you want to populate more header information in the Common Base Event header, the event error program passes the information pointed to by this parameter to the Common Base Event format program. The Common Base Event format program adds the information to the XML document.

The tpf_bev_standard_format_user_data structure is defined in the tpf/ibev.h header file. For more information about this structure, see Standard format data.

Return values

When the event error program is called before the data is added to the error queue, the return from the event error program must be an integer as follows:

A value of 0 indicates that the calling program will not add the event message to the error queue.
A nonzero value indicates that the calling program will add the event message to the error queue.

When the event error program is called before the event message is moved from the error queue to the dispatch queue, the return from the event error program must be an integer as follows:

A value of 0 indicates that the calling program will not add the event message to the dispatch queue.
A nonzero value indicates that the calling program will add the event message to the dispatch queue.

Programming considerations

The eventErrorProgram typedef is defined in the tpf/ibev.h header file.
Specify the 4-character event error program name in the business event specification by using the <esEventErrorProgram> element.
Business event processing uses the TPF_CALL_BY_NAME API to call the enrichment program.
Business event processing determines if the event error program is available. If the event error program is not available, an error is issued and the event message is processed as if the event error program provided a nonzero return code.
The event header in the tpf_bev_evtmsg structure contains the event name, intercept name, and other information regarding this event. The event header is mapped by the tpf_bev_evtmsg_hdr structure in the tpf/ibev.h header file.
If the event error program changes the pointer to the controls, usrFmtData, or stdFmtData parameter, or to any event message items in the evtMsg parameter, business event processing assumes that the new structures are in ECB heap. If the event error program changes the pointer to any of these structures, business event processing releases the old and new storage after processing the event. Ensure that the event error program releases storage that it gets only if that storage is not used to replace the controls, usrFmtData, or stdFmtData parameter, or to any event message items in the evtMsg parameter.
The event error program can signal another event. Consider the following example:
1. The event error program is called before the event message is moved to the dispatch queue and, instead of adding the event message to the dispatch queue, processing determines that additional information is included.
2. The event error program creates a separate event with the original event message and additional information to indicate that an error occurred.
3. When the event error program returns, the return code indicates that the event message is not to be added to the dispatch queue.
When you use business event remote dispatch processing, the event error program might be called on a source complex or the dispatch complex, depending on where the error occurred.