Application enrichment program format

You can use the application enrichment program to capture context for the business event directly from the application ECB, because the program is called inside of the application ECB commit scope and can access the application ECB and the application ECB memory space.

To use the application enrichment program format, specify the 4-character program name in the business event specification. If an application enrichment program is defined for an event, business event processing calls the specified program. When enrichment processing is completed, the application enrichment program must call the tpf_bev_addToDispatchQ function to continue processing the event. When the application enrichment program returns control to the caller, the function returns control to the program that triggered the event without any additional processing.

If there is no application enrichment program defined for an event, business event processing puts the event on the dispatch queue.

The application enrichment program must accept parameters as defined by the application_enrichment typedef.

Format

#include <tpf/ibev.h>
typedef int (*application_enrichment)(struct tpf_bev_evtmsg *evtMsg,
                                      struct tpf_bev_event_controls *controls);

Parameters

evtMsg
A pointer to the address of the tpf_bev_evtmsg structure, which contains the sizes and addresses of the event message components. You can use the application enrichment program to add or modify components in this structure, like the event ECB context or event user context.
controls
A pointer to the tpf_bev_event_controls structure. You must include this structure on the tpf_bev_addToDispatchQ function call. The application enrichment program can use this structure to change the settings for this particular business event.

For example, the application enrichment program can use the information defined in this structure to determine which dispatch adapter to use based on the priority of the data for this event. The control structure includes a list of dispatch adapters for this event. The nbrDispatchAdapters field contains the number of items in the daItem array. When the application enrichment program is entered, the status for each dispatch adapter in the daItem array is marked as in use. The application enrichment program can change the status of a particular dispatch adapter so that the event data is not sent to that dispatch adapter.

Return values

The return from the application enrichment program must be an integer:
  • A value of 0 indicates successful completion.
  • Values 1 - 99 are reserved for IBM.
  • For a signal event, values of 100 or greater are returned to the program that called the tpf_bev_signal function.
  • For data events that are created by the tpf_dev_create or df_dev_create function, values of 100 or greater are returned to the program that called the data event function.
  • For data events that are created automatically by the z/TPF system, values of 100 or greater are ignored by data event processing.

Programming considerations

  • The application_enrichment typedef is defined in the tpf/ibev.h header file.
  • Specify the 4-character application enrichment program name in the business event specification by using the <esApplicationEnrichmentProgram> element.
  • Business event processing uses the TPF_CALL_BY_NAME function to call the application enrichment program.
  • Business event processing determines whether the application enrichment program is available. If the application enrichment program is not available, the business event is not processed, and business event processing takes the following actions:
    • If this is a signal event, the tpf_bev_signal function returns an error.
    • If this is a data event, a message is issued and a count of errors is incremented. The business event monitor reports the number of errors that occurred in the last minute.
  • The event header in the tpf_bev_evtmsg structure contains the business event information including the event name, intercept name, and so on. The event header is mapped by the tpf_bev_evtmsg_hdr structure in the tpf/ibev.h header file.
  • The application enrichment program is called in the commit scope that is established by the application ECB. In this way, the application enrichment program participates in the commit scope of the application and can retrieve any necessary data from the application ECB.
  • After the application enrichment program finishes enrichment for this business event, the enrichment program uses the tpf_bev_addToDispatchQ function to add the event to the dispatch queue. If the event is not added to the dispatch queue, the event is discarded by business event processing.
  • The event ECB context in the evtMsg parameter is set when ECB heap was tagged by using the tpf_eheap_tag function and the TPF_BEV_ECBCTX_HEAPTAG symbolic name. If the application enrichment program changes event ECB context, the context is changed for the current and all subsequent events for this ECB.
  • If the event ECB context was not set before the application enrichment program is called, you can set the event ECB context in the following ways:
    • To set event ECB context for the current event, you can set the address and size of the event ECB context in the tpf_bev_evtmsg structure by using the TPF_BEV_EVTMSG_ECBCTX index.
    • To set the event ECB context for future events, the event ECB context must be allocated in ECB heap and tagged by using the tpf_eheap_tag function and the TPF_BEV_ECBCTX_HEAPTAG symbolic name.
  • If the application enrichment program allocates any storage such as ECB heap, the application enrichment program is responsible for releasing that storage. For example, if the application enrichment program allocates new storage for parts of the event message, the program must release the new storage before the program returns to the caller. The application enrichment program must not release any storage that is passed as input to the program.
  • When you use the application enrichment program for an event message data event for a z/TPF file, ensure that the application enrichment program does not lose control by taking the following actions.
    • Ensure that the application enrichment program does not call any system services or other programs that can cause a loss of control.
    • Specify the PRELOAD fetch indicator and the NOTIMESLICE program attribute in the control file for the application enrichment program and any programs that the application enrichment program calls.
    If the application enrichment program loses control, the 06401D system error is issued and the ECB exits.