0001 TPFORWARD(3)
0002 ============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpforward - forward the service call to another service
0009
0010 SYNOPSIS
0011 --------
0012 #include <atmi.h>
0013
0014 void tpforward (char *'svc', char *'data', long 'len', long 'flags');
0015
0016 Link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0017
0018 DESCRIPTION
0019 -----------
0020 Send the current request control to another process/service and free up current
0021 processing instance for next request. This basically makes original *tpcall()*
0022 chaining in *relay race* mode. The original caller is unaware that it's
0023 call now will be serviced by another service. The destination service is
0024 provided in parameter 'svc', data buffer is passed in 'data'/'len' pair.
0025 'data' buffer must be allocated by *tpalloc()* or can be auto-buffer. Auto-buffer
0026 is made free by default when call state is return or forwarded. If the buffer in
0027 'data' is not auto-buffer, then it will be deallocated too.
0028
0029 Normally the auto-buffer shall not be made free by user, as that will cause the
0030 corruption at the stage of the *tpreturn*. But auto-buffer free by user can be
0031 suitable in case if doing call state transfer over the non XATMI sub-system,
0032 then call context restore in other OS process with *tpsrvsetctxdata(3)*
0033 must be done with *TPNOAUTBUF* flag specified, and the original service which
0034 received request prior doing *tpcontinue(3)* shall make the auto buffer free *tpfree(3)*.
0035 If the 'TPNOAUTBUF' was specified at state restore, then tpforward() command will
0036 not try to free the auto buffer.
0037
0038 Note that if with call buffer user internally makes calls which changes the buffer
0039 type, then original call buffer is made free and the changed type buffer now
0040 is user allocated. Thus to deallocated the buffer either user does free of it,
0041 or performs tpreturn/tpforward with it.
0042
0043 If current process was in global transaction, then it will make the target process
0044 to join the global transaction too. If invalid service name is specified in
0045 'svc' (service is not advertised in system), then call will be returned
0046 the caller with service error (*TPESVCERR*). 'flags' is reserved for future use.
0047
0048 If process have started a global transaction and performs tpforward() without
0049 completing the transaction, transaction is automatically aborted and initiating
0050 service caller receives *TPESVCERR* error.
0051
0052 *tpreturn()* will make the current service routine go back/pop-up the stack to
0053 Enduro/X polling mechanisms for next incoming message.
0054
0055 This function is available only for XATMI servers.
0056
0057 RETURN VALUE
0058 ------------
0059 Function is marked as void and it have no return values.
0060
0061 ERRORS
0062 ------
0063 No errors available (but some details might be logged in trace files).
0064
0065 EXAMPLE
0066 -------
0067 See *atmitest/test002_basicforward/atmisv2FIRST.c* for sample code.
0068
0069 BUGS
0070 ----
0071 Report bugs to support@mavimax.com
0072
0073 SEE ALSO
0074 --------
0075 *tpreturn(3)* *tpcall(3)*
0076
0077 COPYING
0078 -------
0079 (C) Mavimax, Ltd
0080
