Sidebar
endurox:v7.5.x:api:xatmi:tpcall.3
Name
tpcall — Call XATMI service
Synopsis
#include <atmi.h>
int tpcall(char *svc, char *idata, long ilen, char **odata, long *olen, long flags);
For XATMI client link with -latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm
For XATMI server link with -latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm
DESCRIPTION
Call the XATMI service by given svc name. The idata is optional input XATMI buffer. If it is not a NULL, then it must be allocated with tpcalloc() call, ilen is used for buffer types such CARRAY, where buffer length is not described by type. When caller receives response, it is stored in odata buffer which must be also allocated by tpcalloc(). If the allocated buffer size is shorter then received one, then Enduro/X will automatically realloc the buffer to new size. olen is mandatory field, where the received buffer length is stored. If TPNOTRAN is not specified and current thread is in global transaction, then system will make destination process run in same destination process. In case of error, global transaction (if associated with current thread) is marked for abort, except if TPNOABORT flag was specified or particular error code indicates that global transaction is not aborted.
Valid flags
TPNOTRAN Do not call service in transaction mode. This is effective in case if caller process is running in transaction mode, but destination process shall not run in the same global transaction
TPSIGRSTRT Restart the system call in progress if interrupted by signal handler. This affects only underlaying mq_* function calls.
TPNOTIME Ignore timeout setting (NDRX_TOUT env variable). Wait for reply for infinitely.
TPNOCHANGE Do not allow to change the reply buffer type. If flag is set and different buffer type is received than original, then error TPEINVAL is returned.
TPTRANSUSPEND Force suspend the current transaction in progress prior actual service call. This applies to resource managers which xa switch does not support join operations: Resource is configured with NOJOIN or NOSUSPEND in NDRX_XA_FLAGS (see ex_env(5)). For other cases transaction is automatically suspend (starting Enduro/X version 7.5.26).
TPNOBLOCK In case of target service request queue is full, do not wait on queue, but return error. The error code for this situation is TPEBLOCK. This affects only request part of the call. This flag does not affect waiting for response from server.
TPNOABORT Do not abort global transaction (if one in progress), even if service failed.
RETURN VALUE
On success, tpcall() returns 0; on error, -1 is returned, with tperrno set to indicate the error. When server did tpreturn(), the rcode value is accessible by caller by using tpurcode().
ERRORS
Note that tpstrerror() returns generic error message plus custom message with debug info from last function call.
TPEINVAL Invalid parameter is given to function. Either service name is NULL. Global transaction is not marked for abort only, if one was associated with current thread.
TPEOTYPE Flags does not allow to change the response buffer type.
TPENOENT No service (svc parameter) advertised in system. Global transaction is not marked for abort only, if one was associated with current thread.
TPETIME Service did not reply in given time (NDRX_TOUT).
TPESVCFAIL Service returned TPFAIL. This is application level failure.
TPESVCERR System level service failure. Server died during the message presence in service queue. Or internals of tpreturn(3) failed at server code, e.g. failed to commit auto-tran.
TPESYSTEM System failure occurred during serving. See logs i.e. user log, or debugs for more info. DDR route not found or failed. If TPTRANSUSPEND and when reply was received, transaction was expired at tmsrv(8).
TPEOS System failure occurred during serving. See logs i.e. user log, or debugs for more info.
TPEBLOCK Service request queue was full and TPNOBLOCK flag was specified. Global transaction is not marked for abort only, if one was associated with current thread.
TPETRAN Called service is configured as auto-tran, but internal tpbegin(3) at XATMI server code failed. Or server failed to join global transaction. See reasons in log file.
TPEITYPE There was problem with XATMI data type buffer, not supported by service or corrupted. Global transaction is not marked for abort only, if one was associated with current thread.