BEA TUXEDO Release v6.4 provides two new APIs that return more refined error information to your applications: tperrordetail and tpstrerrordetail.
BEA TUXEDO follows the XATMI standard for error reporting. For errors caused by system anomalies in particular, the XATMI standard opts for simplicity in error reporting. This leads to much simpler client programming as the client need not be concerned with the thousands of potential system problems that can crop up during a session.
Because these system errors vary among operating systems and among versions of each system, it would be difficult to require client software, server software, and BEA TUXEDO System software to keep up with this ever changing landscape. Also, if BEA TUXEDO returned error information down to the finest granularity available, it would be almost impossible for client software to properly interpret the information to be useful for the user. So, there are a very few error codes (TPESYSTEM, TPESVCERR, etc.) and conversational events (TPEV_SVCFAIL, TPEV_SVCERR, etc.) that are returned by BEA TUXEDO to represent this class of error. (Note that when one of these codes is returned, the ULOG, if possible, contains more information about the problem so that a system administrator may do further analysis.)
Sometimes, however, additional information about these generic errors is needed. This is especially true when one of these errors originates from a user-specified BEA TUXEDO configuration option. For this reason, new APIs have been created to produce more refined information, when available, for BEA TUXEDO applications.
tperrordetail (3c) returns additional detail related to an error produced by the last BEA TUXEDO routine called in the current thread. It returns a numeric value that is also represented by a symbolic name. If the last BEA TUXEDO routine called in the current thread has not produced an error, then tperrordetail returns zero. Therefore, tperrordetail should be called only after an error has been indicated; that is, when a BEA TUXEDO routine has returned -1 and tperrno has been set.
long tperrordetail(long flags)
A flags parameter is required, however initially there are no valid flags. BEA TUXEDO v6.4 validates the flags parameter to make sure it is zero. The value of tperrno is set to TPEINVAL and -1 is returned, if flags are set incorrectly.
The following three classes of values may be returned to the application:
tperrordetail has not been approved an as extension of the XATMI standard. (To keep your application compliant, do not call tperrordetail.
tperrordetail is not available in releases of BEA TUXEDO prior to 6.4. If your site supports multiple releases of BEA TUXEDO, plan your configuration to accommodate the fact that you will not receive error detail from your pre-v6.4 servers and clients. A client will not be able to get error detail from a server unless Release 6.4 is installed on both the client and server.
To take advantage of tperrordetail, we recommend that you perform the following actions:
Standards Compliance
Adapting Your Site to Use tperrordetail
tpstrerrordetail retrieves the text of an error detail of a System/T error. This API should be called whenever an application requires the default error detail string associated with the numeric or symbolic representation of an error detail.
char * tpstrerrordetail(long detailerrno, long flags)
A value representing an error detail is required. A flags parameter is also required, however initially there are no valid flags.
The following classes of values may be returned to the application:
The New tpstrerrordetail API
About the Interface
Programming Specification
Inputs, Outputs, and Validations
tpstrerrordetail has not been approved as an extension of the XATMI standard. To keep your application compliant, do not call tpstrerrordetail.
tpstrerrordetail is not available in releases of BEA TUXEDO prior to 6.4. If your site supports multiple releases of BEA TUXEDO, plan your configuration to accommodate the fact that you will not receive error detail from your pre-v6.4 servers and clients. A client will not be able to get error detail from a server unless Release 6.4 is installed on both the client and server.
To take advantage of tpstrerrordetail, we recommend that you perform the following actions:
Standards Compliance
Adapting Your Site to Use tpstrerrordetail
tperrordetail - get additional detail about an error generated from the last TUXEDO call
#include <atmi.h>
long tperrordetail() returns additional detail related to an error produced by the last BEA TUXEDO routine called in the current thread. tperrordetail() returns a numeric value that is also represented by a symbolic name. If the last BEA TUXEDO routine called in the current thread did not produce an error, then tperrordetail() will return zero. Therefore, tperrordetail() should be called only after an error has been indicated; that is, when a BEA TUXEDO routine has returned a -1 and tperrno has been set.
Currently, flags are reserved for future use and must be set to 0.
tperrordetail() returns -1 on an error and sets tperrno to indicate the error condition.
Following are the symbolic names and meanings for each numeric value that tperrordetail() may currently return. Their order is not significant and does not imply precedence.
The New tperrordetail(3c) Manual Page
Name
Synopsis
tperrordetail(long flags)
Description
Return Values
Under the following conditions, tperrordetail() fails and sets tperrno to:
[TPEINVAL] tpstrerrordetail - get error detail message string for System/T error.
#include <atmi.h>
char * tpstrerrordetail() is used to retrieve the text of an error detail of a System/T error. detailerrno is the value returned by tperrordetail(3c).
You can use the pointer returned by tpstrerrordetail() as an argument to userlog(3c) or fprintf(3fml).
If detailerrno is an invalid error code, tpstrerrordetail() returns a NULL. If successful, the function returns a pointer to a string that contains the error detail message text.
Under the following conditions, tperrordetail() fails and sets tperrno to:
[TPEINVAL] #include <atmi.h>
. long de;
char *p;
if (tpbegin(10,0) == -1) {
de = tperrordetail(0);
if (de != 0) {
p = tpstrerrordetail( de );
userlog("%s", p);
}
. }
. intro(3c), tperrordetail(3c), tpstrerror(3c), userlog(3c), tperrno(5)
Errors
flags is not set to zero.
See Also
intro(3c), tpstrerrordetail(3c), tperrno(5) The New tpstrerrordetail(3c) Manual Page
Name
Synopsis
tpstrerrordetail(long detailerrno)
Description
Return Values
Errors
flags is not set to zero.
Example
.
.
.
.
.
.
See Also