XA—External Transaction Manager : tibemsXAResource

tibemsXAResource
Type
Purpose
Coordinate XA transactions.
Remarks
Each tibemsXAResource instance can coordinate a series of transactions, but only one transaction at a time. A program that keeps n transactions open simultaneously must create n instances of this type.
The transaction manager assigns each resource instance a unique RMID, which it uses to bind together a thread, a resource and a transaction.
 
tibemsXAResource_Commit
Function
Purpose
Commit a transaction.
C Declaration
tibems_status tibemsXAResource_Commit(
    tibemsXAResource xaResource,
    XID* xid,
    tibems_bool onePhase );
COBOL Call
CALL "tibemsXAResource_Commit"
USING BY VALUE xaResource,
BY REFERENCE xid,
BY VALUE onePhase,
RETURNING tibems-status
END-CALL.
 
xaResource and xid have usage pointer.
Parameters
 
TIBEMS_TRUE requests a one-phase commit.
TIBEMS_FALSE requests a two-phase commit.
tibemsXAResource_End
Function
Purpose
Disassociate a transaction from the resource.
C Declaration
tibems_status tibemsXAResource_End(
    tibemsXAResource xaResource,
    XID* xid,
    int flags );
COBOL Call
CALL "tibemsXAResource_End"
USING BY VALUE xaResource,
BY REFERENCE xid,
BY VALUE flags,
RETURNING tibems-status
END-CALL.
 
xaResource and xid have usage pointer.
Parameters
 
TMSUCCESS—Completely end the transaction.
TMSUSPEND—Temporarily disassociate the transaction from this resource.
tibemsXAResource_Forget
Function
Purpose
Unimplemented.
C Declaration
tibems_status tibemsXAResource_Forget(
    tibemsXAResource xaResource,
    XID* xid );
COBOL Call
CALL "tibemsXAResource_Forget"
USING BY VALUE xaResource,
BY REFERENCE xid,
RETURNING tibems-status
END-CALL.
 
xaResource and xid have usage pointer.
Parameters
 
Remarks
In the XA interface, the transaction manager can instruct a resource to forget a transaction.
However, this call is not implemented in EMS; it is present for completeness only.
tibemsXAResource_GetRMID
Function
Purpose
Get the RMID of the resource.
C Declaration
tibems_status tibemsXAResource_GetRMID(
    tibemsXAResource xaResource,
    tibems_int* rmid );
COBOL Call
CALL "tibemsXAResource_GetRMID"
USING BY VALUE xaResource,
BY REFERENCE rmid,
RETURNING tibems-status
END-CALL.
 
xaResource has usage pointer.
Parameters
 
Remarks
The transaction manager assigns a unique RMID to each resource instance, which it uses to bind together a thread, a resource and a transaction.
tibemsXAResource_GetTransactionTimeout
Function
Purpose
Get the timeout limit.
C Declaration
tibems_status tibemsXAResource_GetTransactionTimeout(
    tibemsXAResource xaResource,
    tibems_int* seconds );
COBOL Call
CALL "tibemsXAResource_GetTransactionTimeout"
USING BY VALUE xaResource,
BY REFERENCE seconds,
RETURNING tibems-status
END-CALL.
 
xaResource has usage pointer.
Parameters
 
Remarks
If an open, unprepared transaction does not log any activity on the server for this length of time, then the server automatically rolls back the transaction.
See Also
tibemsXAResource_SetTransactionTimeout on page 367
tibemsXAResource_isSameRM
Function
Purpose
Determine whether two resource objects originate from the same connection to an EMS server.
C Declaration
tibems_status tibemsXAResource_isSameRM(
    tibemsXAResource xaResource,
    tibemsXAResource xaResource2,
    tibems_bool* result );
COBOL Call
CALL "tibemsXAResource_isSameRM"
USING BY VALUE xaResource,
BY VALUE xaResource2,
BY REFERENCE result,
RETURNING tibems-status
END-CALL.
 
xaResource and xaResource2 have usage pointer.
Parameters
 
tibemsXAResource_Prepare
Function
Purpose
Prepare a transaction for commit.
C Declaration
tibems_status tibemsXAResource_Prepare(
    tibemsXAResource xaResource,
    XID* xid );
COBOL Call
CALL "tibemsXAResource_Prepare"
USING BY VALUE xaResource,
BY REFERENCE xid,
RETURNING tibems-status
END-CALL.
 
xaResource and xid have usage pointer.
Parameters
 
tibemsXAResource_Recover
Function
Purpose
Get a list of prepared transactions.
C Declaration
tibems_status tibemsXAResource_Recover(
    tibemsXAResource xaResource,
    XID* xids,
    tibems_int desiredCount,
    tibems_int* returnedCount,
    tibems_int flag );
COBOL Call
CALL "tibemsXAResource_Recover"
     USING BY VALUE xaResource,
           BY REFERENCE xids,
           BY VALUE desiredCount,
           BY REFERENCE returnedCount,
           BY VALUE flag,
           RETURNING tibems-status
END-CALL.
 
xaResource and xids have usage pointer.
Parameters
 
TMSTARTRSCAN—Start a new list of XIDs; the EMS server generates a complete list, and sends the first batch.
TMNOFLAGS—Continue the list of XIDs; the EMS server sends the next batch.
TMENDRSCAN—The EMS server discards its list of prepared transactions, and reclaims storage.
Remarks
When this call returns, if returnedCount  desiredCount, then more prepared transactions might exist. To get the next batch of XIDs, call this function again with TMNOFLAGS flag until returnedCount < desiredCount.
tibemsXAResource_Rollback
Function
Purpose
Roll back a transaction.
C Declaration
tibems_status tibemsXAResource_Rollback(
    tibemsXAResource xaResource,
    XID* xid );
COBOL Call
CALL "tibemsXAResource_Rollback"
USING BY VALUE xaResource,
BY REFERENCE xid,
RETURNING tibems-status
END-CALL.
 
xaResource and xid have usage pointer.
Parameters
 
Remarks
Messages sent to a queue with prefetch=none and maxRedelivery=number properties are not received number times by an EMS application that receives in a loop and does an XA rollback after the XA prepare phase.
tibemsXAResource_SetRMID
Function
Purpose
Assign an RMID to a resource.
C Declaration
tibems_status tibemsXAResource_SetRMID(
    tibemsXAResource xaResource,
    tibems_int rmid );
COBOL Call
CALL "tibemsXAResource_SetRMID"
USING BY VALUE xaResource,
BY VALUE rmid,
RETURNING tibems-status
END-CALL.
 
xaResource has usage pointer.
Parameters
 
tibemsXAResource_SetTransactionTimeout
Function
Purpose
Set the timeout limit.
C Declaration
tibems_status tibemsXAResource_SetTransactionTimeout(
    tibemsXAResource xaResource,
    tibems_int seconds );
COBOL Call
CALL "tibemsXAResource_SetTransactionTimeout"
USING BY VALUE xaResource,
BY VALUE seconds,
RETURNING tibems-status
END-CALL.
 
xaResource has usage pointer.
Parameters
 
Remarks
If an unprepared transaction does not log any activity on the server for this length of time, then the server automatically rolls back the transaction.
See Also
tibemsXAResource_GetTransactionTimeout on page 360
tibemsXAResource_Start
Function
Purpose
Associate a transaction with a resource.
C Declaration
tibems_status tibemsXAResource_Start(
    tibemsXAResource xaResource,
    XID* xid,
    tibems_int flags );
COBOL Call
CALL "tibemsXAResource_Start"
USING BY VALUE xaResource,
BY REFERENCE xid,
BY VALUE flags,
RETURNING tibems-status
END-CALL.
 
xaResource and xid have usage pointer.
Parameters
 
TMNOFLAGS—This is a new transaction, which was not previously associated with the resource.
TMRESUME—This transaction was previously associated with the resource.