0001 TPSUSPEND(3)
0002 ============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpsuspend - Suspend global transaction, and disassociate current thread from XA transaction
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpsuspend (TPTRANID *'tranid', 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 Disassociate XA transaction from current thread and store transaction details
0024 to 'tranid' variable. The transaction can be resumed as by doing *tpresume(3)*.
0025 *tranid* must not be NULL. 'flags' are reserved for future use, and currently must
0026 be set to 0. It is error to have any open call descriptors (either by *tpacall(3)*
0027 or by *tpconnect(3)*). Suspending can be done by any involved process in transaction.
0028 But the role of participant does not change. The *TPTRANID* type
0029 records the information about caller, is it transaction originator or not.
0030
0031 If transaction was suspended, it must be resumed afterwards with *tpresume(3)*,
0032 otherwise XA resources may rejected the underlying xa_prepare() call with protocol error,
0033 which would lead to the fact that commit will be aborted, and *tpcommit(3)*
0034 would return *TPEABORT* error.
0035
0036
0037 *Valid flags*
0038
0039 *TPTXNOOPTIM* Do not use cached known resource managers in 'tranid'. Thus having
0040 this flag set, this process even for previously involved RMs will perform
0041 xa transaction start and if that fails, then attempt *TM_JOIN*.
0042
0043 *TPTXTMSUSPEND* Transaction shall be suspended with *TMSUSPEND*
0044 flag instead of *TMSUCCESS*. If this flag is used, then 'tranid' shall not be
0045 used in other thread/process that this particular which performed suspend. The
0046 benefit for this flag is that certain XA resources might allow to resume operations
0047 on cursors, etc. . This applies to XA switches which support join operation
0048 and join is not disabled by *NOJOIN* flag in *NDRX_XA_FLAGS*.
0049
0050 RETURN VALUE
0051 ------------
0052 On success, *tpsuspend()* return zero; on error, -1 is returned,
0053 with *tperrno* set to indicate the error.
0054
0055
0056 ERRORS
0057 ------
0058 Note that *tpstrerror()* returns generic error message plus custom message
0059 with debug info from last function call.
0060
0061 *TPEINVAL* flags was not 0. Or 'tranid' was NULL.
0062
0063 *TPEPROTO* XA subsystem was not initialized (did not call *tpopen()*), global
0064 transaction was not already started, or there was open call descriptors.
0065
0066 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log,
0067 or debugs for more info.
0068
0069 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0070 or debugs for more info.
0071
0072 EXAMPLE
0073 -------
0074 See *atmitest/test021_xafull/atmiclt21-cli.c* for sample code.
0075
0076 BUGS
0077 ----
0078 Report bugs to support@mavimax.com
0079
0080 SEE ALSO
0081 --------
0082 *tpcommit(3)* *tpopen(3)* *tpclose(3)* *tpresume(3)*
0083
0084 COPYING
0085 -------
0086 (C) Mavimax, Ltd
0087
