Sidebar
endurox:v7.5.x:api:xatmi:tpacall.3
Name
tpacall — Call XATMI service asynchronously
Synopsis
#include <atmi.h>
int tpacall(char *svc, char *data, long len, 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 asynchronously. The data is optional input XATMI buffer. If it is not a NULL, then it must be allocated with tpcalloc() call, len is used for buffer types such CARRAY, where buffer length is not described by type. If call succeeds, the function return the call descriptor. With call descriptor it is possible later to receive the response by using tpgetrply() If TPNOTRAN is not specified and current process is in global transaction, then system will make destination process run in same destination process.
tpacall() current does not suspend the global transaction before sending the data. If such logic is reuqired, the tpsuspend(3) shall be used for this purpose.
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 underlying mq_* function calls.
TPNOBLOCK In case of target service queue is full, do not wait on queue, but return error. The error code for this situation is TPEBLOCK.
TPNOREPLY Do not expect reply from the call. This works with principle "send and forget". In this case return value for successful call is 0. This flag cannot be used in global transaction mode.
TPNOTIME Do not use timeout setting when sending message to queue, process will wait indefinatelly to submit the message to blocking IPC queue.
RETURN VALUE
On success, tpacall() return call descriptor (>0); on error, -1 is returned, with tperrno set to indicate the error.
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 or flags does not allow to change the value. Process is in global transaction and TPNOREPLY flag is used.
TPENOENT No service (svc parameter) advertised in system.
TPETIME Destination service queue was blocking (full) and timeout out for sending was exceeded (see NDRX_TOUT env setting in ex_env(5), tptoutset(3) or tpsblktime(3)).
TPESVCFAIL Service returned TPFAIL. This is application level failure.
TPESVCERR System level service failure. Server died during the message presence in service queue.
TPESYSTEM System failure occurred during serving. See logs i.e. user log, or debugs for more info. DDR route not found or failed.
TPEOS System failure occurred during serving. See logs i.e. user log, or debugs for more info.
TPEBLOCK Service queue was full and TPNOBLOCK flag was specified.
TPNOTIME Do not expire call by server process, if message age is older than NDRX_TOUT timeout (or timeout overridden by tptoutset(3)).