MYSQLND_MS_XA_BEGIN(3)							 1						    MYSQLND_MS_XA_BEGIN(3)

mysqlnd_ms_xa_begin - Starts a distributed/XA transaction among MySQL servers

SYNOPSIS

       int mysqlnd_ms_xa_begin (mixed  $connection, string  $gtrid, [int  $timeout])

DESCRIPTION

	Starts a XA transaction among MySQL servers. PECL/mysqlnd_ms acts as a transaction coordinator the distributed transaction.

	Once  a  global transaction has been started, the plugin injects appropriate XA BEGIN SQL statements on all MySQL servers used in the fol-
       lowing. The global transaction is either ended by calling mysqlnd_ms_xa_commit(3), mysqlnd_ms_xa_rollback(3) or by an implicit rollback	in
       case of an error.

	During	a  global  transaction,  the  plugin tracks all server switches, for example, when switching from one MySQL shard to another MySQL
       shard. Immediately before a query is run on a server that has not been participating in the global transaction yet, XA BEGIN is executed on
       the  server. From a users perspective the injection happens during a call to a query execution function such as mysqli_query(3). Should the
       injection fail an error is reported to the caller of the query execution function. The failing server does not become a participant in  the
       global  transaction.  The  user may retry executing a query on the server and hereby retry injecting XA BEGIN, abort the global transaction
       because not all required servers can participate, or ignore and continue the global without the failed server.

	Reasons to fail executing XA BEGIN include but are not limited to a server being unreachable or the server having an open,  concurrent	XA
       transaction using the same xid.

	Please	note,  global  and  local transactions are mutually exclusive. You cannot start a XA transaction when you have a local transaction
       open. The local transaction must be ended first. The plugin tries to detect this conflict as early as possible. It monitors API	calls  for
       controlling local transactions to learn about the current state. However, if using SQL statements for local transactions such as BEGIN, the
       plugin may not know the current state and the conflict is not detected before XA BEGIN is injected and executed.

	The use of other XA resources but MySQL servers is not supported by the function. To carry out a global transaction among, for example,  a
       MySQL server and another vendors database system, you should issue the systems SQL commands yourself.

       Note

	      Experimental

	       The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments.

PARAMETERS

	      o $connection
		- A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

	      o $gtrid
		-  Global transaction identifier (gtrid). The gtrid is a binary string up to 64 bytes long. Please note, depending on your charac-
		ter set settings, 64 characters may require more than 64 bytes to store.  In accordance with the MySQL SQL syntax, XA transactions
		use  identifiers made of three parts. An xid consists of a global transaction identifier (gtrid), a branch qualifier (bqual) and a
		format identifier (formatID). Only the global transaction identifier can and needs to be set.  The  branch  qualifier  and  format
		identifier  are  set  automatically.  The  details  should  be considered implementation dependent, which may change without prior
		notice. In version 1.6 the branch qualifier is consecutive number which is incremented whenever a  participant	joins  the  global
		transaction.

	      o $timeout
		-  Timeout  in	seconds.  The  default	value is 60 seconds.  The timeout is a hint to the garbage collection. If a transaction is
		recorded to take longer than expected, the garbage collection begins checking the transactions status.	Setting a  low	value  may
		make  the  garbage  collection	check the progress too often. Please note, checking the status of a global transaction may involve
		connecting to all recorded participants and possibly issuing queries on the servers.

RETURN VALUES

	Returns TRUE if there is no open local or global transaction and a new global transaction can be started. Otherwise, returns FALSE

SEE ALSO

       Quickstart XA/Distributed transactions, Runtime configuration, mysqlnd_ms_get_stats(3).

PHP Documentation Group 												    MYSQLND_MS_XA_BEGIN(3)