0001 TPBEGIN(3)
0002 =========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpbegin - Start the global transaction
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpbegin (unsigned long 'timeout', long 'flags');
0016
0017 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0018
0019 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0020
0021 DESCRIPTION
0022 -----------
0023 Begin the global transaction. The current user must be open *XA* subsystem by
0024 *topopen()*. 'timeout' is setting for transaction manager (*tmsrv*) how long
0025 transaction can hang in active state (i.e. not prepared/committed). Field
0026 'flags' is reserved for future use and must be 0. The work done by *tpbegin()*
0027 transaction is only in scope of processes which uses *XA* interfaces for
0028 resource managers. Any others works are outside of current scope. If 'timeout'
0029 is set to 0, then default maximum time for transaction processing is used.
0030 Transaction must be committed or aborted by client process by using *tpcommit()*
0031 or *tpabort()*. If any *tpcall()* with no *TPNOTRAN* flag fails within given
0032 global transaction, then transaction is automatically marked as abort only.
0033
0034 Client process can suspend the global transaction by *tpsuspend(3)* and some
0035 other process can resume the transaction as client with suspend data. In that
0036 case that other process can do the commit.
0037
0038 If service code completes auto-tran manually and then starts new transaction
0039 in given call context, then this new transaction from *tpreturn(3)* and
0040 *tpforward(3)* perspective would be treated as continuation of the auto-tran
0041 i.e. *tpreturn(3)* would finish it correspondingly and *tpforward(3)* would
0042 receive initiator of the auto-tran.
0043
0044 If *tmsrv* is started in the singleton process groups, the upper limit
0045 for 'timeout' is by *NDRX_SGLOCKINC* env parameter value, multiplied by
0046 *exsinglesv(8)* parameter *chkinterval*.
0047
0048 RETURN VALUE
0049 ------------
0050 On success, *tpbegin()* return zero; on error, -1 is returned, with *tperrno*
0051 set to indicate the error.
0052
0053 ERRORS
0054 ------
0055 Note that *tpstrerror()* returns generic error message plus custom
0056 message with debug info from last function call.
0057
0058 *TPEINVAL* flags was not 0.
0059
0060 *TPETIME* Transaction manager (*tmsrv(8)*) did not respond in configured
0061 time-out time. The state of transaction is unknown.
0062
0063 *TPESVCERR* Failed to call transaction manager, with service error.
0064 The state of transaction is unknown.
0065
0066 *TPEPROTO* XA subsystem was not initialized (did not call *tpopen()*) or
0067 global transaction already started.
0068
0069 *TPESYSTEM* System failure occurred during serving. See logs i.e.
0070 user log, or debugs for more info.
0071
0072 *TPEOS* System failure occurred during serving. See logs i.e.
0073 user log, or debugs for more info.
0074
0075 EXAMPLE
0076 -------
0077 See *atmitest/test021_xafull/atmiclt21.c* for sample code.
0078
0079 BUGS
0080 ----
0081 Report bugs to support@mavimax.com
0082
0083 SEE ALSO
0084 --------
0085 *tpabort(3)* *tpcommit(3)* *tpopen(3)* *tpclose(3)* *tpsuspend(3)* *tpresume(3)*
0086
0087 COPYING
0088 -------
0089 (C) Mavimax, Ltd
0090
