Developing with XCC

Use the xdmp:xa-complete() built-in function to heuristically complete the MarkLogic Server branch of a prepared global XA transaction. When using xdmp:xa-complete(), you must indicate

Usually, you should rollback the local transaction and remember the heuristic decision outcome.

Forgetting the heuristic decision leads to an error and possibly loss of data integrity when the Transaction Manager subsequently attempts to resynchornize the global transaction. If the outcome is remembered, then the Transaction Manager can learn the status of the branch and properly resume the global transaction.

The following examples demonstrate several forms of heuristic completion. The 3rd parameter indicates whether or not to commit. The 4th parameter indicates whether or not to remember the outcome:

(: commit and remember the transaction outcome:)
xdmp:xa-complete($forest-id, $txn-id, fn:true(), fn:true())
(: roll back and remember the transaction outcome:)
xdmp:xa-complete($forest-id, $txn-id, fn:false(), fn:true())
(: commit and forget the transaction outcome :)
xdmp:xa-complete($forest-id, $txn-id, fn:true(), fn:false())

The forest id parameter of xdmp:xa-complete() identifies the coordinating forest. Once an XA transaction is prepared, the coordinating forest remembers the state of the MarkLogic Server branch until the global transaction completes. Use the Admin Interface or xdmp:forest-status() to determine the transaction id and coordinating forest id.

For example, the following query retrieves a list of all transaction participants in transactions that are prepared but not yet comitted. The coordinating forest id for each participant is included in the results. For details, see xdmp:forest-status() in XQuery and XSLT Reference Guide.

xquery version "1.0-ml";
for $f in xdmp:database-forests(xdmp:database())
return xdmp:forest-status($f)//*:transaction-participants

Additional cleanup may be necessary if the Transaction Manager resumes and the global transaction has an outcome that does not match the heuristic decision. For details, see Cleaning Up After Heuristic Completion.

You may also use the Admin Interface to heuristically rollback XA transaction or to forget a heuristic decision. See Rolling Back a Prepared XA Transaction Branch in Administrating MarkLogic Server.