JText failure handling

For the JText connector, the following types of errors can occur:

Table 8. JText error types

Type of error Description
Business object delimiter failures Business object delimiter failures occur when the EndBODelimiter attribute in the top-level meta-object is set to a valid value, and the event file contains the specified delimiter at the end of each business object, but the data itself uses the delimiter value in its text. When the connector encounters the delimiter value in the text, it sends a partial business object string to the formatter, which fails processing. In this case, the connector writes the event to the filename_timestamp.fail file, which contains records for all business objects that encountered delimiter failures.
Subscription errors Can occur if the connector can find the business object delimiter and retrieve the business object name, but the business object is not subscribed. In this case, an event is sent to the filename_timestamp.unsub file, which contains records for all unsubscribed business objects.
Formatting errors Can occur if the connector finds the delimiter with a business object name that does not match the input business object name, or the format in the business object file does not match the format of the meta-object. An event is sent to the filename_timestamp.fail file, which contains records for all business objects that failed formatting.
Sending errors Can occur if the connector tries to send a business object when the integration broker is down. If the Send operation fails, an event is sent to the filename_timestamp.fail file, which contains records for all business objects that were not successfully sent.

Event log file

The connector logs information about successfully processed business objects to the event.log file. If the connector goes down before it processes all business objects in an event file, it uses this log file during recovery to ensure that it sends each business object only once to the integration broker.

The format of the log file is:

EventFileName::1,2,n
 

where EventFileName is the name of the current event file, and each number represents the sequence number of a successfully processed business object in that file.

For example, assume that the connector has successfully processed three of the first four business objects in the Customer.in file, and that the second business object failed processing. Assume also that the connector has not yet finished processing Customer.in. In this case, the event.log file might look like the following on UNIX:

$ProductDir/JText/Event/Customer.in:: 1,3,4
 

and like the following on Windows:

C:\JText\Event\Customer.in:: 1,3,4
 

If the connector went down before processing the entire Customer.in file, at startup the connector uses the information in the log file to resume processing the event file at the point where it had stopped processing. The connector reads the log to get the name of the event file to be recovered and the latest business-object sequence number. Then the connector begins sending to the integration broker all business objects in the event file whose sequence number is greater than the last number in the log file. For example, given the file above, the connector begins processing the fifth business object in the Customer.in file.

The connector keeps the contents of the log file in memory to enhance performance. It accesses the file on disk only to update it with a new entry. The connector reads the log file only at recovery time.

For information on how the connector uses the event.log file in the recovery process, see Failure recovery.

Failure recovery

Note:
The following recovery steps do not apply if a disk failure occurs or a disk is full.

To recover from failures during event notification, the connector does the following:

  1. The connector processes business object strings from the event file. When it successfully processes an entry, the connector logs the entry in the event.log file. It also writes it to a file in the archive directory (specified in the ArchiveDir meta-object attribute).

    The delivered default values for these extensions are .success and .partial.

  2. If errors occur, the connector does the following:

    The connector does not log the failed business objects to event.log.

  3. After the connector processes all business objects in an event file, it clears the event.log file and begins writing entries to it from the next event file.
  4. If the connector goes down before it processes all business objects in an event file, it uses the information in event.log to determine where to begin processing during the recovery process. When it comes back up, the connector checks whether there are any entries in the log file.

    If you set the EventRecovery configuration property to retry, the connector at startup automatically recovers outstanding events from a previously processed file. However, if you set this property to abort, the connector terminates during startup if there are any events to be recovered.

  5. To recover from errors that occurred during the event notification process, you must restart the connector. Before doing this, however, do the following:

The following guidelines can help you determine what recovery steps to take, based on the type of error that occurred.

Recovery from business object delimiter errors

The connector writes the business object to an archive file in the archive directory, giving it the extension specified in the FailArchiveExt meta-object attribute. To handle recovery for such a failure, do the following:

  1. Ensure that the event file contains the business object delimiter, that the delimiter is correct, and that it does not contain the delimiter value in the data itself as text. If the use of the delimiter is not correct, correct it.
  2. Review the connector's log file (specified in the LogFileName configuration attribute) to determine other reasons why the process failed.
  3. Copy the file from the archive directory to the event directory and change the .fail extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful way. For example, rename Customer.fail to Customer_delimiter_error.in.

Recovery from subscription errors

The connector writes the business object to a file located in the archive directory, giving it the extension specified in the UnsubscribedArchiveExt meta-object attribute. To handle recovery for such a failure, do the following:

  1. Open the archived file, find that business object string, and verify that the business object name and verb are subscribed. Make appropriate corrections if necessary.
  2. Ensure that the integration broker is running.
  3. Copy the file from the archive directory to the event directory and change the .unsub extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful way. For example, rename Customer.unsub to Customer_unsub_resubmit.in.

Recovery from formatting errors

The connector writes the business object to a file located in the archive directory, giving it the extension specified in the FailArchiveExt meta-object attribute. To handle recovery for such a failure, do the following:

  1. Open the archived file and verify that:
  2. Copy the file from the archive directory to the event directory and change the .fail extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful way. For example, rename Customer.fail to Customer_fail_formatting.in.

Recovery from sending errors

The connector writes the business object to a file located in the archive directory, giving it the extension specified in the FailArchiveExt meta-object attribute. To handle recovery for such a failure, do the following:

  1. Verify that all components of the business-integration system are running.
  2. Copy the file from the archive directory to the event directory and change the .fail extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful way. For example, rename Customer.fail to Customer_fail_sending.in.
  3. Restart the connector.

Data handlers and supported business objects

If the connector returns an error stating that the data handler has not been configured, verify that the meta-object for the data handler is included in the list of supported business objects. The most common error returned by the connector states that the BOPrefix is not set.

The list of supported business objects for the DHFormatter should include the following:

Copyright IBM Corp. 1997, 2003