Unload Inbound Transmission Processing and Error Reporting

When an application receives an UnloadDepositGroup event, it should:

  • Perform any work necessary to unload the selected transmission
  • Log any messages or result text to the deposit group message table
  • Return an pass or fail indication to Transaction Server

The UnloadDepositGroup event payload contains the identifier for the transmission that is being unloaded and an unload deposit group bean containing the details for the unload. The applications use the payload to examine the inbound transmission being unloaded, perform any necessary clean up, and generate messages that are included in the final unload report. All messages, results and informational text are added to the deposit group message table in the database. The application itself must put any information it requires in the deposit group message table.

Table 1 shows the format of each row of the deposit group message table.

Table 1. Deposit Group Message Table Format
Column Name Data Type Description
DEPOSIT_GROUP_ID BIGINT The inbound (outbound) transmission identifier for the batch (ICL) being unloaded
PROCESS_NAME CHAR(20) The string value UNLOAD. This indicates the message is for an unload operation.
PRODUCT_NAME CHAR(30) The name of the application that generated this message
CREATED TIMESTAMP Timestamp when this message was inserted into the database
MSG_INDEX INTEGER A message ordering index value. Each product should generate its own sequence.
MSG_ID CHAR(9) An optional message identifier that is used to generate the text for this message
MSG VARCHAR(1024) The message text itself

Applications can use the unload deposit group bean from the payload to create the messages in the database. Several of the methods return information that is unique to the transmission and helpful to display in the messages. The bean also has methods to make adding messages to the database easier. If they are used, make sure to supply a valid database connection to the bean before calling them. For example, addMessage requires a database connection before it is called.

Table 2 shows the methods that are available in the unload deposit group bean.

Table 2. Unload Deposit Group Bean Methods
Getter Method Data Type Description
getDepositGroupId ( ) PresentmentGroupId Returns the inbound transmission identifier for the unload operation
getMessageIndex ( ) Int Returns the current message index value. The current index likely already contains a message. Use nextMessageIndex ( ) to return an index to use for a new message.
getTargetName ( ) String Returns the destinationId value from the scheduler XML for this event
getPayload ( ) String Returns the value that was specified in the ABSvcPayload parameter in the scheduler XML for this event
nextMessageIndex ( ) Int Returns an auto-incremented index value that can be used as the message index for adding rows to the deposit group message table
setConnection ( ) java.sql.Connection Supplies the unload deposit group bean with a database connection it can use when accessing the database. This method must be called with a working database connection before calling the addMessage method.
addMessage ( ) String, String, String Adds a new message to the deposit group message table. It has the following parameters:
  • Product name
  • Message identifier
  • Message text
This method uses the inbound transmission ID, the UNLOAD process name, and the next available message index fields to populate the rest the deposit group message entry.

Additionally, consider the following when logging messages:

  • Build the message text using National Language Support (NLS) text from a resource bundle
  • If the message text was built using NLS, use the optional message id parameter, which can be saved along with the message instance, to specify the NLS message ID
commit ( ) N/A Commits the current database work
rollback ( ) N/A Rolls back the current database work
close ( ) N/A Closes any resources consumed by this unload deposit group bean instance. This method has the added effect of removing the reference to any supplied database connection.

Once the target application is finished analyzing the inbound transmission being unloaded, it must indicate if it detected an unload error. Table 3 shows the return values for unloading an inbound transmission.

Table 3. Unload Inbound Transmission Return Values
Return Value Description
false The application completed the unload operation successfully
true The application detected an unload error

The application notifies the caller whether the unload succeeded or failed as follows:

  1. Returns a Messaging API response with the return value in the payload
  2. Uses the return value as a return code

The Messaging API response is the preferred method for reporting the unload status. If a boolean value is not returned in the Messaging API payload, the Transaction Server detects this, adds a message stating that a return value was not received from the application, and proceeds as if no unload error was detected by the application.

Note: This is true only if there is no error code returned in the response. Reply time-outs are treated as unload failures.

Returning a return code is usually only used when the Messaging API message has a failure, such as a timeout waiting for a reply. If this method is used, the application can either include a return error message describing the failure or log it itself using the unload message bean. The Transaction Server automatically adds any error messages returned to the deposit group message table.