0001 TPRETURN(3)
0002 ===========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpreturn - terminate XATMI service processing and return control back to caller.
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 void tpreturn(int 'rval', long 'rcode', char *'data', long 'len', long 'flags');
0016
0017 Link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd
0018 -lpthread -lrt -lm'
0019
0020 DESCRIPTION
0021 -----------
0022 Function is used to terminate service processing and return control to caller.
0023 The return buffer 'data' must be auto buffer or allocated by *tpalloc()*. In either
0024 case the buffer's are made free by Enduro/X. I.e. The original request buffer
0025 is made free (if available) and the return buffer is made free too, if different
0026 than request buffer.
0027
0028 Normally the auto-buffer shall not be made free by user, as that will cause the
0029 corruption at the stage of the *tpreturn*. But auto-buffer free by user can be
0030 suitable in case if doing call state transfer over the non XATMI sub-system,
0031 then call context restore in other OS process with *tpsrvsetctxdata(3)*
0032 must be done with *TPNOAUTBUF* flag specified, and the original service which
0033 received request prior doing *tpcontinue(3)* shall make the auto buffer free *tpfree(3)*.
0034 If the 'TPNOAUTBUF' was specified at state restore, then tpreturn() command will
0035 not try to free the auto buffer.
0036
0037 Note that if with call buffer user internally makes calls which changes the buffer
0038 type, then original call buffer is made free and the changed type buffer now
0039 is user allocated. Thus to deallocated the buffer either user does free of it,
0040 or performs tpreturn/tpforward with it.
0041
0042 'len' is needed in case if buffer type is not self describing. Internally function uses
0043 long jump to get back to internal message polling mechanisms. *tpreturn()* is
0044 used for normal service calls and for conversational service calls. *tpdiscon()*
0045 shall not be used by service program, but use *tpreturn()* instead. 'rcode'
0046 field is used by user program, to return back the specific value to caller.
0047
0048 If process have started a global transaction and performs tpreturn() without
0049 completing the transaction, transaction is automatically aborted and initiating
0050 service caller receives *TPESVCERR* error.
0051
0052 *'rval'* values:
0053
0054 *TPSUCCESS* service terminated with success.
0055
0056 *TPFAIL* service terminated with failure. In case of global transaction, this
0057 return value will mark it as abort only.
0058
0059 *TPEXIT* functionality is the same as with *TPFAIL*, but additionally process
0060 performs shutdown after service returns. The shutdown is performed in clean
0061 way with corresponding invocations of *tpsvrdone(3)* and *tpsvrthrdone(3)*.
0062 Once binary exits, the *ndrxd(8)* process will restart the server process,
0063 if configured so. See *tpexit(3)* for more details.
0064
0065 *'flags'* values:
0066
0067 *TPSOFTTIMEOUT* soft timeout occurred. This can be used to simulate *TPETIME*
0068 error for caller. In this case 'rcode' is set to *TPETIME*, that is later used
0069 at client side for *tpreturn(3)* to respond with XATMI error.
0070
0071 *TPSOFTERR* software generate XATMI error code. In this case 'rcode' indicates
0072 the error code to be returned to service caller.
0073
0074 This function is available only for XATMI servers.
0075
0076 RETURN VALUE
0077 ------------
0078 Function is marked as void and it have no return values.
0079
0080
0081 ERRORS
0082 ------
0083 No errors available (but some details migth be logged in trace files).
0084
0085
0086 EXAMPLE
0087 -------
0088 See *atmitest/test001_basiccall/atmisv1.c* for sample code.
0089
0090 BUGS
0091 ----
0092 Report bugs to support@mavimax.com
0093
0094 SEE ALSO
0095 --------
0096 *tpforward(3)* *tpcall(3)* *tpexit(3)*
0097
0098 COPYING
0099 -------
0100 (C) Mavimax, Ltd
0101
