Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 5 Using TIBCO Object Service Broker to Process Adabas Data : Handling of Errors

Handling of Errors
This section explains how TIBCO Object Service Broker requests are handled with respect to the following:
Synchronization and Recovery
Synchronization and recovery are governed by the following:
Adabas locks are not requested when the TIBCO Object Service Broker transaction is running in browse mode and updates on Adabas data cannot be performed.
When a TIBCO Object Service Broker transaction ends successfully, an Adabas CL (Close) command is issued, causing Adabas locks to be released. An Adabas CL implies an ET (End Transaction) command. ET is equivalent to a TIBCO Object Service Broker commit point.
When a TIBCO Object Service Broker transaction ends unsuccessfully, an Adabas BT (Backout Transaction) command is issued, immediately followed by a CL, causing the Adabas updates to be backed out and the locks to be released.
Intermediate COMMIT and ROLLBACK requests are not supported because the locking architecture of TIBCO Object Service Broker and Adabas is fundamentally different. While TIBCO Object Service Broker frees locks at the end of a transaction, Adabas frees locks at COMMIT (ET) or ROLLBACK (BT).
COMMITLIMIT exception does not apply to ADA tables. Adabas update requests are passed to Adabas as they are encountered. They are not held in the TIBCO Object Service Broker intent list.
Data Integrity
Fail Safe level‑1 processing is supported to ensure data integrity when updating both TIBCO Object Service Broker and a single Adabas database from within one TIBCO Object Service Broker transaction.
If you did not request Fail Safe processing, transactions that update both Adabas and TIBCO Object Service Broker data can result in discrepancies if abnormal termination occurs during the transaction end processing. Refer to Implementing Fail Safe Processing for more information.
Data integrity cannot be assured when updating TIBCO Object Service Broker and multiple Adabas databases, because Adabas does not support updates to multiple databases with integrity.
Exceptions
The TIBCO Object Service Broker runtime environment signals system exceptions to enable an application to recover from an error. A three-level hierarchy of exceptions exists. The ERROR exception is the top of the hierarchy and is intended to be a catch all exception. Each exception traps the exceptions that appear below it in the hierarchy.
All errors encountered when accessing Adabas data are trapped under one of the following exceptions:
 
GETFAIL – No occurrence satisfies the selection criteria. The Adabas error code 14 raises this exception.
INSERTFAIL – The primary key provided for an INSERT statement already exists. The Adabas error code 10 raises this exception.
An attempt was made to read more occurrences with Adabas’s primary exclusive lock. Restructure your application to take fewer locks in a transaction, run in browse mode so locks are not taken, or increase the NISNHQ parameter.
A new transaction requested an instance of the server processing the request, but none is available. Control is passed back to the rule, giving the rule the opportunity to try the transaction again. If this exception is raised too often, consider requesting more server instances or reviewing the amount of work being done in your transactions.
A request was made to Adabas and Adabas returned an error code that does not map to one of the specific TIBCO Object Service Broker exceptions. The ON SERVERERROR handler should call @SERVERERROR to parse the error message (contained in ENDMSG).
Refer to @SERVERERROR for more information.
A transaction was in progress when the connection to the server servicing the request was broken, or the server failed. Control is passed back to the rule, giving the rule responsibility for transaction cleanup.
See Also
TIBCO Object Service Broker Programming in Rules for more information about system exceptions.
@SERVERERROR
You must pass @SERVERERROR the contents of RETURN_MESSAGE, which has the following format:
S6BADnnnx serverid serveruserid source: Message
The following table describes the variables necessary to pass the RETURN_MESSAGE contents to @SERVERERROR:
The user ID (IDPREFIX + ###) of the server.
If a specific message has some information that is required to process the error, the table driven approach to the execution of @SERVERERROR causes a rule (specified for that error by the developer using @SERVERERROR) to execute. The error message is interpreted in the @SERVERERROR processing and put into a temporary table until required.
Customization of Error Handling
To customize error handling, you must update data in the @SERVERMSGCNTL control table. The definition of this table is owned by TIBCO Object Service Broker and must not be modified. The data is owned by the users.
Processing of Table
Here is how the table is processed when the SERVERERROR exception is raised and the @SERVERERROR rule is called by your application:
1.
2.
3.
4.
The user-written handler can use other functions and data stored in specific tables to handle any specific external error/status code.
@SERVER ERROR can be called at any time, although it is useful only for parsing TIBCO Object Service Broker messages generated due to external Adabas errors. The original message can always be retrieved using the @SE_MSG rule after @SERVERERROR is called. The information parsed by @SERVERERROR has transaction scope.
You can add your own instances in the @SERVERMSGCNTL table, provided that the OWNER specified begins with letters A to Z, and the key values in their instance are message identifiers in the form S6BADnnnx mentioned above.
@SERVERERRORADA
Use the @SERVERERRORADA rule to reformat the message returned from a SERVERERROR exception.
The @SERVERERRORADA rule populates the fields of a temporary table @SERVERERRORADA by breaking up the returned message string into individual fields. For example, it places the message number into field MSG_ID and the thread ID into the field MSG_THREAD.
See Also
TIBCO Object Service Broker Shareable Tools for more information on the @SERVERERROR and RETURN_MESSAGE tools.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved