Section 3c - C Functions

ATMI C Function Reference

tperrordetail(3c)

Name

tperrordetail()—Gets additional detail about an error generated from the last BEA Tuxedo ATMI system call.

Synopsis

#include <atmi.h>
int tperrordetail(long flags)

Description

tperrordetail() returns additional detail related to an error produced by the last BEA Tuxedo ATMI system routine called in the current thread. tperrordetail() returns a numeric value that is also represented by a symbolic name. If the last BEA Tuxedo ATMI system routine called in the current thread did not produce an error, then tperrordetail() will return zero. Therefore, tperrordetail() should be called after an error has been indicated; that is, when tperrno has been set.

Currently flags is reserved for future use and must be set to 0.

A thread in a multithreaded application may issue a call to tperrordetail() while running in any context state, including TPINVALIDCONTEXT.

Return Values

Upon failure, tperrordetail() returns a -1 and sets tperrno to indicate the error condition.

These are the symbolic names and meaning for each numeric value that tperrordetail() may return. The order in which these are listed is not significant and does not imply precedence.

TPED_CLIENTDISCONNECTED

A Jolt client is disconnected currently. The TPACK flag is used in a tpnotify() call and the target of tpnotify() is a currently disconnected Jolt client. When tpnotify() fails, a subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_CLIENTDISCONNECTED.

TPED_DECRYPTION_FAILURE

A process receiving an encrypted message cannot decrypt the message. This error most likely occurs because the process does not have access to the private key required to decrypt the message.

When a call fails due to this error, a subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_DECRYPTION_FAILURE.

TPED_DOMAINUNREACHABLE

A domain is unreachable. Specifically, a domain configured to satisfy a request that a local domain cannot service was not reachable when a request was made. After the request failure, a subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_DOMAINUNREACHABLE.

The following table indicates the corresponding values returned by tperrno when calls to tpcall(), tpgetrply(), or tprecv() fail because of an unreachable domain. The error detail returned by a subsequent call to tperrordetail() is TPED_DOMAINUNREACHABLE.

ATMI Call	tperrno	Error Detail
`tpcall`	`TPESVCERR`	`TPED_DOMAINUNREACHABLE`
`tpgetrply`	`TPESVCERR`	`TPED_DOMAINUNREACHABLE`
`tprecv`	`TPEEVENT TPEV_SVCERR`	`TPED_DOMAINUNREACHABLE`

Note that the TPED_DOMAINUNREACHABLE feature applies to BEA Tuxedo Domains only. It does not apply to other domains products such as Connect OSI TP Domains and Connect SNA Domains.

TPED_INVALID_CERTIFICATE

A process receiving a digitally signed message cannot verify the digital signature because the associated digital certificate is invalid. This error most likely occurs because the digital certificate has expired, the digital certificate was issued by an unknown Certification Authority (CA), or the digital certificate has been altered.

When a call fails due to this error, a subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_INVALID_CERTIFICATE.

TPED_INVALID_SIGNATURE

A process receiving a digitally signed message cannot verify the digital signature because the signature is invalid. This error most likely occurs because the message has been altered, the timestamp for the digital signature is too old, or the timestamp for the digital signature is too far into the future.

When a call fails due to this error, a subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_INVALID_SIGNATURE.

TPED_INVALIDCONTEXT

A thread is blocked in an ATMI call when another thread terminates its context. Specifically, any thread blocked in an ATMI call when another thread terminates its context will return from the ATMI call with a failure return; tperrno is set to TPESYSTEM. A subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_INVALIDCONTEXT.

TPED_INVALID_XA_TRANSACTION

An attempt was made to start a transaction but the NO_XA flag was turned on in this domain.

TPED_NOCLIENT

No client exists. The TPACK flag is used in a tpnotify() call but there is no target for tpnotify(). When tpnotify() fails, tperrno is set to TPENOENT. A subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_NOCLIENT.

TPED_NOUNSOLHANDLER

A client does not have an unsolicited handler set. The TPACK flag is used in a tpnotify() call and the target of the tpnotify() is in a BEA Tuxedo ATMI session, but it has not set an unsolicited notification handler. When tpnotify() fails, tperrno is set to TPENOENT. A subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_NOUNSOLHANDLER.

TPED_SVCTIMEOUT

A server was terminated due to a service timeout. The service timeout is controlled by the value of SVCTIMEOUT in the UBBCONFIG file or TA_SVCTIMEOUT in T_SERVER and T_SERVICE classes in the TM_MIB. When a call fails due to this error, a subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_SVCTIMEOUT.

TPED_TERM

A Workstation client has been disconnected from the application. When a call fails due to this error, a subsequent call to tperrordetail() with no intermediate ATMI calls will return TPED_TERM.

Errors

Upon failure, tperrordetail() sets tperrno to one of the following values:

TPEINVAL

flags not set to zero