0001 TPCALL(3)
0002 =========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpcall - Call XATMI service
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpcall(char \*'svc', char \*'idata', long 'ilen', char **'odata', long *'olen', long 'flags');
0016
0017
0018 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0019
0020 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0021
0022 DESCRIPTION
0023 -----------
0024 Call the XATMI service by given 'svc' name. The 'idata' is optional input XATMI
0025 buffer. If it is not a NULL, then it must be allocated with *tpcalloc()* call,
0026 'ilen' is used for buffer types such *CARRAY*, where buffer length is not
0027 described by type. When caller receives response, it is stored in 'odata'
0028 buffer which must be also allocated by *tpcalloc()*. If the allocated buffer
0029 size is shorter then received one, then Enduro/X will automatically realloc the
0030 buffer to new size. 'olen' is mandatory field, where the received buffer length
0031 is stored. If *TPNOTRAN* is not specified and current thread is in global
0032 transaction, then system will make destination process to run in
0033 same global transaction. In case of error, global transaction (if associated
0034 with current thread) is marked for abort, except if *TPNOABORT* flag was
0035 specified or particular error code indicates that global transaction is not aborted.
0036
0037 *Valid flags*
0038
0039 *TPNOTRAN* Do not call service in transaction mode. This is effective in
0040 case if caller process is running in transaction mode, but destination process
0041 shall not run in the same global transaction
0042
0043 *TPSIGRSTRT* Restart the system call in progress if interrupted by signal
0044 handler. This affects only underlaying mq_* function calls.
0045
0046 *TPNOTIME* Ignore timeout setting (*NDRX_TOUT* env variable).
0047 Wait for reply for infinitely.
0048
0049 *TPNOCHANGE* Do not allow to change the reply buffer type. If flag
0050 is set and different buffer type is received than original,
0051 then error *TPEINVAL* is returned.
0052
0053 *TPTRANSUSPEND* Force suspend the current transaction in progress prior
0054 actual service call. This applies to resource managers which xa switch does not
0055 support join operations: Resource is configured with
0056 *NOJOIN* or *NOSUSPEND* in *NDRX_XA_FLAGS* (see *ex_env(5)*).
0057 For other cases transaction is automatically suspend (starting Enduro/X version *7.5.26*).
0058
0059 *TPNOBLOCK* In case of target service request queue is full, do not wait on queue, but
0060 return error. The error code for this situation is *TPEBLOCK*. This affects only
0061 request part of the call. This flag does not affect waiting for response from server.
0062
0063 *TPNOABORT* Do not abort global transaction (if one in progress), even if service
0064 failed.
0065
0066 RETURN VALUE
0067 ------------
0068 On success, *tpcall()* returns 0; on error, -1 is returned,
0069 with *tperrno* set to indicate the error. When server did tpreturn(), the 'rcode'
0070 value is accessible by caller by using tpurcode().
0071
0072
0073 ERRORS
0074 ------
0075 Note that *tpstrerror()* returns generic error message plus custom message with
0076 debug info from last function call.
0077
0078 *TPEINVAL* Invalid parameter is given to function. Either service name is NULL.
0079 Global transaction is not marked for abort only, if one was associated
0080 with current thread.
0081
0082 *TPEOTYPE* Flags does not allow to change the response buffer type.
0083
0084 *TPENOENT* No service ('svc' parameter) advertised in system.
0085 Global transaction is not marked for abort only, if one was associated
0086 with current thread.
0087
0088 *TPETIME* Service did not reply in given time ('NDRX_TOUT').
0089
0090 *TPESVCFAIL* Service returned 'TPFAIL'. This is application level failure.
0091
0092 *TPESVCERR* System level service failure. Server died during the message presence
0093 in service queue. Or internals of *tpreturn(3)* failed at server code, e.g.
0094 failed to commit auto-tran.
0095
0096 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log,
0097 or debugs for more info. DDR route not found or failed. If *TPTRANSUSPEND* and
0098 when reply was received, transaction was expired at *tmsrv(8)*.
0099
0100 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0101 or debugs for more info.
0102
0103 *TPEBLOCK* Service request queue was full and *TPNOBLOCK* flag was specified.
0104 Global transaction is not marked for abort only, if one was associated
0105 with current thread.
0106
0107 *TPETRAN* Called service is configured as auto-tran, but internal *tpbegin(3)*
0108 at XATMI server code failed. Or server failed to join global transaction. See
0109 reasons in log file.
0110
0111 *TPEITYPE* There was problem with XATMI data type buffer, not supported by service
0112 or corrupted. Global transaction is not marked for abort only, if one was associated
0113 with current thread.
0114
0115 EXAMPLE
0116 -------
0117 See *atmitest/test001_basiccall/atmiclt1.c* for sample code.
0118
0119 BUGS
0120 ----
0121 Report bugs to support@mavimax.com
0122
0123 SEE ALSO
0124 --------
0125 *tpacall(3)* *tpgetrply(3)*
0126
0127 COPYING
0128 -------
0129 (C) Mavimax, Ltd
0130
