0001 TAPCALL(3)
0002 ==========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpacall - Call XATMI service asynchronously
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpacall(char *'svc', char *'data', long 'len', 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 asynchronously. The 'data' is
0025 optional input XATMI buffer. If it is not a NULL, then it must be allocated
0026 with *tpcalloc()* call, 'len' is used for buffer types such *CARRAY*, where
0027 buffer length is not described by type. If call succeeds, the function return
0028 the call descriptor. With call descriptor it is possible later to receive the
0029 response by using *tpgetrply()* If *TPNOTRAN* is not specified and current
0030 process is in global transaction, then system will make destination process
0031 run in same global transaction.
0032
0033 tpacall() current does not suspend the global transaction before sending
0034 the data. If such logic is required, the *tpsuspend(3)* shall be used
0035 for this purpose.
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
0041 process shall not run in the same global transaction
0042
0043 *TPSIGRSTRT* Restart the system call in progress if interrupted by
0044 signal handler. This affects only underlying mq_* function calls.
0045
0046 *TPNOBLOCK* In case of target service queue is full, do not wait on queue, but
0047 return error. The error code for this situation is *TPEBLOCK*.
0048
0049 *TPNOREPLY* Do not expect reply from the call. This works with principle
0050 "send and forget". In this case return value for successful call is *0*.
0051 This flag cannot be used in global transaction mode.
0052
0053 *TPNOTIME* Do not use timeout setting when sending message to queue,
0054 process will wait indefinitely to submit the message to blocking IPC queue.
0055
0056 RETURN VALUE
0057 ------------
0058 On success, *tpacall()* return call descriptor (>0); on error, -1 is returned,
0059 with *tperrno* set to indicate the error.
0060
0061
0062 ERRORS
0063 ------
0064 Note that *tpstrerror()* returns generic error message plus custom message
0065 with debug info from last function call.
0066
0067 *TPEINVAL* Invalid parameter is given to function. Either service name is
0068 NULL or flags does not allow to change the value. Process is in global
0069 transaction and *TPNOREPLY* flag was specified and *TPNOTRAN* flag was not specified.
0070
0071 *TPENOENT* No service ('svc' parameter) advertised in system.
0072
0073 *TPETIME* Destination service queue was blocking (full) and timeout out
0074 for sending was exceeded (see *NDRX_TOUT* env setting in *ex_env(5)*, *tptoutset(3)* or
0075 *tpsblktime(3)*).
0076
0077 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log,
0078 or debugs for more info. DDR route not found or failed.
0079
0080 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0081 or debugs for more info.
0082
0083 *TPEBLOCK* Service queue was full and *TPNOBLOCK* flag was specified.
0084
0085 *TPNOTIME* Do not expire call by server process, if message age is older
0086 than 'NDRX_TOUT' timeout (or timeout overridden by *tptoutset(3)*).
0087
0088 EXAMPLE
0089 -------
0090 See *atmitest/test001_basiccall/atmiclt1.c* for sample code.
0091
0092 BUGS
0093 ----
0094 Report bugs to support@mavimax.com
0095
0096 SEE ALSO
0097 --------
0098 *tpcall(3)* *tpgetrply(3)* *tpcancel(3)* *tptoutset(3)* *tpsblktime(3)* *ex_env(5)*
0099
0100 COPYING
0101 -------
0102 (C) Mavimax, Ltd
0103
