xa_start()-- Start an XA Transaction Branch (Transaction Scoped Locks)


  Syntax
 #include <xa.h>

 int xa_switch.xa_start_entry(XID *xid,     
     int rmid, long flags);

  Default Public Authority: *USE

  Service Program: QTNXADTP

  Threadsafe: Yes

A transaction manager calls xa_start() to inform a resource manager that an application may do work on behalf of a transaction branch. The calling thread becomes associated with the transaction branch.


Parameters

*xid
(Input) A pointer to the transaction branch identifier for the transaction branch that is to be associated with this thread.

rmid
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid identifies the resource manager.

flags
(Input) Following are the valid settings of flags.

TMJOIN: 0x00200000L Caller is joining an existing transaction branch.

TMRESUME: 0x08000000L Caller is resuming association with a suspended transaction branch.

TMNOWAIT: 0x10000000L Do not associate the transaction branch with the thread if a blocking condition exists.

TMNOFLAGS: 0x00000000L To be used when no other flags are set.


Authorities

None


Return Value

The following return codes may be returned for any flags setting.

-8 [XAER_DUPID]

Neither TMRESUME nor TMJOIN were specified, and the xid already exists within the resource manager.
-7 [XAER_RMFAIL]

An error occurred that makes the resource manager unavailable.
-6 [XAER_PROTO]

xa_start() was not successful. Function was called in an improper context.
-5 [XAER_INVAL]

xa_start() was not successful. Incorrect arguments were specified.
-4 [XAER_NOTA]

TMRESUME or TMJOIN was specified, and the xid is not known by the resource manager.
-3 [XAER_RMERR]

xa_start() was not successful. The resource manager detected an error when associating the transaction branch with the thread.
-2 [XAER_ASYNC]

xa_start() was not successful. The resource manager does not support asynchronous operations.
0 [XA_OK]

xa_start() was successful.
4 [XA_RETRY]

TMNOWAIT was set in flags and a blocking condition exists. The thread was not associated with the transaction branch.

The following return codes indicate that TMJOIN or TMRESUME was specified, and the specified transaction branch was not associated with the thread and is marked rollback-only.

100 [XA_RBROLLBACK]

The transaction branch was marked rollback-only for an unspecified reason.
101 [XA_RBCOMMFAIL]

A communications failure occurred within the resource manager.
102 [XA_RBDEADLOCK]

A deadlock condition was detected within the resource manager.
103 [XA_RBINTEGRITY]

The resource manager detected a violation of the integrity of its resources.
104 [XA_RBOTHER]

The transaction branch was marked rollback-only for a reason not on this list.
105 [XA_RBPROTO]

A protocol error occurred in the resource manager.
106 [XA_RBTIMEOUT]

A timeout occurred in the resource manager.
107 [XA_RBTRANSIENT]

A transient error was detected in the resource manager.


Error Messages

The following messages may be sent from this function.

Message ID Error Message Text
CPE3418 E Possible APAR condition or hardware failure.
CPF3CF2 E Error(s) occurred during running of &1 API.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.


Related Information


Example

See Code disclaimer information for information pertaining to code examples.

#include <xa.h>

main() {
  XID  *xid;
  int  rmid;
  long flags;
  int  retcode;
  extern struct xa_switch_t xa_switch;

  retcode =
     xa_switch.xa_start_entry(xid, rmid, flags);
}

API introduced: V5R2
Top | UNIX-Type APIs | APIs by category