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. |
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.
- 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:
- 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).
- If none of the business objects in the event file have failed
processing, the connector archives the successfully processed ones
in an archive file with the extension specified in the
SuccessArchiveExt attribute.
- If any of the business objects in the event file have failed
processing, the connector archives the successfully processed ones
in an archive file with the extension specified in the
PartialArchiveExt attribute.
- After it has written business objects to the file specified in
the SuccessArchiveExt attribute, if any business object
fails processing, the connector changes the extension of this file
to the one specified in PartialArchiveExt.
The delivered default values for these extensions are
.success and .partial.
- If errors occur, the connector does the following:
- Subscription errors-- the connector creates the archive file in
the archive directory with the extension specified in the
UnsubscribedArchiveExt meta-object attribute. The
delivered default value for this extension is .unsub.
- Formatting errors or sending errors--the connector creates the
archive file in the archive directory with the extension specified
in the FailArchiveExt meta-object attribute. The delivered
default value for this extension is .fail.
- Business object delimiter errors--the connector creates the
archive file in the archive directory with the extension specified
in the FailArchiveExt attribute. It also backs up the
event file by moving it to the archive directory and changing its
extension to the one specified in OriginalArchiveExt.
The connector does not log the failed business objects to
event.log.
- 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.
- 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 there are no entries, the connector sends all business
objects in the event file to the integration broker.
- If there are entries, the connector uses this information to
resume processing an 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 sends 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, if the event
file contains 15 business objects and the last sequence number in
the log file is 8, the connector sends the last seven business
objects to the integration broker.
Using the log file prevents the connector from sending the same
event multiple times to the integration broker. The connector keeps
the log file in memory to enhance performance. The connector
accesses the file on disk only to update it with a new entry, and
reads the log file only at recovery time.
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.
- To recover from errors that occurred during the event
notification process, you must restart the connector. Before doing
this, however, do the following:
- Examine the files that the connector created for failed and
unsubscribed business objects. Make appropriate corrections so that
the business object strings can be successfully processed when the
connector starts.
- Copy appropriate files from the archive directory to the event
directory and change all .fail or .unsub
extensions to the extension specified in the EventExt
attribute (by default, .in). To facilitate record-keeping,
rename these files in a meaningful way. For example, rename
Customer.unsub to
Customer_unsub_resubmit.in.
- You may need to perform additional steps manually to recover,
depending on the type of failure that has occurred.
The following guidelines can help you determine what recovery
steps to take, based on the type of error that occurred.
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:
- 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.
- Review the connector's log file (specified in the
LogFileName configuration attribute) to determine other
reasons why the process failed.
- 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.
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:
- 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.
- Ensure that the integration broker is running.
- 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.
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:
- Open the archived file and verify that:
- The business object string format matches the expected format
in the meta-object. If there is a mismatch, either change the
format type in the meta-object or in the business object
string.
- The formatting syntax of the business object string is correct.
If it is incorrect, correct it.
- 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.
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:
- Verify that all components of the business-integration system
are running.
- 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.
- Restart the connector.
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:
- MO_JTextConnector_Default
- MO_JTextConnector_BusObjName
(meta-objects created for specific business objects)
- Business objects that are to be read from or written to a
file.
- The meta-object for the data handler (which is specified in the
DataHandlerConfigMO attribute of the
MO_JTextConnector_Default meta-object).
