The BEA Tuxedo system uses the tperrno variable to supply information to a process when a function fails. All ATMI functions that normally return an integer or pointer return -1 or NULL, respectively, on error and set tperrno to a value that describes the nature of the error. When a function does not return to its caller, as in the case of tpreturn() or tpforward(), which are used to terminate a service routine, the only way the system can communicate success or failure is through the variable tperrno in the requester.
The tperrordetail() and tpstrerrordetail() functions can be used to obtain additional detail about an error in the most recent BEA Tuxedo system call on the current thread. tperrordetail() returns an integer (with an associated symbolic name) which is then used as an argument to tpstrerrordetail() to retrieve a pointer to a string that contains the error message. The pointer can then be used as an argument to userlog() or fprintf().
The codes returned in tperrno represent categories of errors, which are listed in the following table.
|
Error Category
|
tperrno Values
|
|
Abort
|
TPEABORT2
|
|
BEA Tuxedo system1
|
TPESYSTEM
|
|
Call descriptor
|
TPELIMIT and TPEBADDESC
|
|
Conversational
|
TPEVENT
|
|
Duplicate operation
|
TPEMATCH
|
|
General communication
|
TPESVCFAIL, TPESVCERR, TPEBLOCK, and TPGOTSIG
|
|
Heuristic decision
|
TPEHAZARD2 and TPEHEURISTIC2
|
|
Invalid argument1
|
TPEINVAL
|
|
MIB
|
TPEMIB
|
|
No entry
|
TPENOENT
|
|
Operating system1
|
TPEOS
|
|
Permission
|
TPEPERM
|
|
Protocol1
|
TPEPROTO
|
|
Queueing
|
TPEDIAGNOSTIC
|
|
Release compatibility
|
TPERELEASE
|
|
Resource manager
|
TPERMERR
|
|
Timeout
|
TPETIME
|
|
Transaction
|
TPETRAN2
|
|
Typed buffer mismatch
|
TPEITYPE and TPEOTYPE
|
1. Applicable to all ATMI functions for which failure is reported by the value returned in tperrno.
2. Refer to Fatal Transaction Errors for more information on this error category.
As footnote 1 shows, four categories of errors are reported by tperrno(5) and are applicable to all ATMI functions. The remaining categories are used only for specific ATMI functions.The following sections describe some error categories in detail.
In the atmi.h, you can find the definitions of the tperrno values:
/*
* tperrno values - error codes
* The man pages explain the context in which the following error codes
* can return.
*/
#define TPMINVAL 0 /* minimum error message */
#define TPEABORT 1
#define TPEBADDESC 2
#define TPEBLOCK 3
#define TPEINVAL 4
#define TPELIMIT 5
#define TPENOENT 6
#define TPEOS 7
#define TPEPERM 8
#define TPEPROTO 9
#define TPESVCERR 10
#define TPESVCFAIL 11
#define TPESYSTEM 12
#define TPETIME 13
#define TPETRAN 14
#define TPGOTSIG 15
#define TPERMERR 16
#define TPEITYPE 17
#define TPEOTYPE 18
#define TPERELEASE 19
#define TPEHAZARD 20
#define TPEHEURISTIC 21
#define TPEEVENT 22
#define TPEMATCH 23
#define TPEDIAGNOSTIC 24
#define TPEMIB 25
#define TPMAXVAL 26 /* maximum error message */
[TPEINVAL]
Invalid arguments were given (for example, svc is NULL or flags are invalid).
[TPENOENT]
Cannot send to svc because it does not exist, or it is a conversational service, or the name provided begins with a dot (.).\
[TPEITYPE]
The type and subtype of idata is not one of the allowed types and subtypes that svc accepts.
[TPEOTYPE]
Either the type and subtype of the reply are not known to the caller; or, TPNOCHANGE was set in flags and the type and subtype of *odata do not match the type and subtype of the reply sent by the service. Neither *odata, its contents, nor *olen is changed. If the service request was made on behalf of the caller's current transaction, then the transaction is marked abort-only since the reply is discarded.
[TPETRAN]
svc belongs to a server that does not support transactions and TPNOTRAN was not set.
[TPETIME]
This error code indicates that either a timeout has occurred or tpcall() has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) In either case, no changes are made to *odata, its contents, or *olen. If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set). When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
[TPESVCFAIL]
The service routine sending the caller's reply called tpreturn() with TPFAIL. This is an application-level failure. The contents of the service's reply, if one was sent, is available in the buffer pointed to by *odata. If the service request was made on behalf of the caller's current transaction, then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to tpacall() with TPNOREPLY, TPNOTRAN, and TPNOBLOCK set.
[TPESVCERR]
A service routine encountered an error either in tpreturn(3c) or tpforward(3c) (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither *odata, its contents, nor *olen is changed). If the service request was made on behalf of the caller's transaction (that is, TPNOTRAN was not set), then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to tpacall() with TPNOREPLY, TPNOTRAN, and TPNOBLOCK set. If either SVCTIMEOUT in the UBBCONFIG file or TA_SVCTIMEOUT in the TM_MIB is non-zero, TPESVCERR is returned when a service timeout occurs.
[TPEBLOCK]
A blocking condition was found on the send call and TPNOBLOCK was specified.
[TPGOTSIG]
A signal was received and TPSIGRSTRT was not specified.
[TPEPROTO]
A library routine was called in an improper context. For example, tpcall() was called improperly.
Protocol errors occur when an ATMI function is invoked, either in the wrong order or using an incorrect process. For example, a client may try to begin communicating with a server before joining the application. Or tpcommit() may be called by a transaction participant instead of the initiator.
You can correct a protocol error at the application level by enforcing the rules of order and proper usage of ATMI calls.
To determine the cause of a protocol error, answer the following questions:
- Is the call being made in the correct order?
- Is the call being made by the correct process?
[TPESYSTEM]
A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]
An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned even if tpcall() returned successfully.