Custom adapter program

The custom adapter program is a user-written program that transmits a formatted business event to one or more event consumers. The custom adapter program must accept parameters as defined by the customAdapter typedef.

Format

#include <tpf/ibev.h>
typedef int (*customAdapter)(int   callReason,
                             void *callStructure);

Parameters

callReason
The reason that the custom adapter program was called, which can be one of the following values:
0
Transmits the event data (bev_ca_transmit).
1
Performs set up processing (bev_ca_setup). The custom adapter program is called with this value during cycle to NORM state processing when the associated dispatch adapter is in an active loadset.
callStructure
A pointer to one of the following structures, based on the callReason:
  • For bev_ca_transmit, this parameter points to the tpf_bev_ca_transmit structure.
  • For bev_ca_setup, this parameter points to the tpf_bev_ca_setup structure.

Return values

  • When callReason is bev_ca_transmit, the return from the custom adapter program must be an integer that contains the number of bytes that were transmitted:
    • A value of 0 indicates that an error occurred during transmission.
    • A nonzero value represents the number of bytes that were transmitted.
  • When callReason is bev_ca_setup, the only valid return value is 0.

Programming considerations

  • The customAdapter typedef is defined in the tpf/ibev.h header file.
  • Specify the 4-character custom adapter program name in the business event dispatch adapter specification.
  • Business event processing uses the TPF_CALL_BY_NAME API to call the custom adapter program.
  • When callReason is bev_ca_transmit, and the custom adapter program returns an error to the caller or is not available, the business event cannot be transmitted to the event consumer and business event processing takes the following actions:
    • A count of errors is incremented.
    • The business event monitor reports the number of errors that occurred in the last minute.
    • If the number of errors in one minute exceeds a specified threshold, the business event dispatch adapter is undeployed and a message is issued. You can set this threshold by entering the ZBEVF SET command with the MAXERRORS parameter specified.
    • The business event processing transmit errors user exit (ubev_dataTransmitErrors_user_exit in ubev.cpp) is called for every error. You can use this user exit to take a specific action when an error occurs. You also can customize how the error handling logic handles the business event dispatch adapter in one of the following ways:
      • Automatically undeploy the dispatch adapter.
      • Never automatically undeploy the dispatch adapter.
      • Take the default action and undeploy the dispatch adapter based on the maximum error count threshold.
    • The event error program might be called and the event message might be added to the error queue based on the business event specification.
    • After all dispatch adapters are processed for this event, business event processing throttles dispatch processing for the dispatch queue because of the transmit error.