Programming Guide

xa_begin

Starts a middleware transaction

Synopsis

xa_begin [ EXCEPTION_HANDLER handler, UNLOAD_HANDLER handler, 
	TIMEOUT timeout]

Arguments

EXCEPTION_HANDLER handler
Specifies an exception handler to be installed for the duration of the transaction; use NULL if none is to be specified. For further information on exception events and handlers, refer to "Exception Events" in JetNet/Oracle Tuxedo Guide.

UNLOAD_HANDLER handler
Specifies an unload handler to be installed for the duration of the transaction. The handler should control all unloading of transaction data to Panther target variables; use @NULL if none is to be specified.

For example, this command specifies the unload handler myhandler: 

xa_begin UNLOAD_HANDLER "myhandler"

For more information on unload events and handlers, refer to "Unload Events" in JetNet/Oracle Tuxedo Guide.

TIMEOUT timeout
Resume processing if the transaction is not complete before timeout elapses. If you omit this option, transaction processing continues without a time limit. Specify timeout with this format: 
"[ +days hours::minutes::]seconds"

Seconds are required; minutes, hours, or days (space delimiter between days and hours) can also be specified. If more than seconds is specified, the + symbol and the quotation marks are mandatory. If only seconds are specified, both are optional.

Note: JPL's colon preprocessor expands colon-prefixed variables. To prevent expansion of variables that contain colons, you must prefix literal colons with another colon (::) or a backslash (\:).

For example, this command specifies a time interval of 30 seconds: 

xa_begin TIMEOUT 30

The following command specifies a time interval of 3 hours: 

xa_begin TIMEOUT "+3::00::00"

Environment

Oracle Tuxedo

Scope

Client, Server

Description

The xa_begin command initiates a transaction to be performed on XA-compliant resource managers. Once initiated, a transaction must be completed by a call to either xa_commit, xa_rollback or xa_end. When a transaction is in progress, any service requests made to XA-compliant resources can be processed on behalf of the current transaction.

Use the EXCEPTION_HANDLER option to specify an exception handler to be installed for the lifetime of this transaction. All exceptions generated within the scope of this transaction are passed to the associated handler, unless a more specific scope has specified its own handler, for example, by an individual request.

For example, this command starts a transaction with the exception handler 

my_exc_handler:
xa_begin EXCEPTION_HANDLER "my_exc_handler"

Exceptions related to the parsing or execution of the xa_begin command do not cause the associated exception handler to be invoked, since the exception occurs before the transaction has begun.

For information about event scopes and handler properties, refer to "Handler Scope and Installation"in JetNet/Oracle Tuxedo Guide.

The following application properties are affected by execution of xa_begin:

Property Value 
tp_return

TP_NOTRAN or TP_TOP_LEVEL—Indicates type of transaction started, if any. 

tp_tran_status

TP_WILL_COMMIT—If a new transaction is started and becomes the active transaction context. Otherwise, unchanged.

Exceptions

xa_begin can generate the following exceptions:

Exception Severity Cause 
TP_BEGIN_FAILED
 
TP_COMMAND TP_ERROR

The middleware is unable to begin a transaction 

TP_INVALID_CONNECTION
 
TP_COMMAND

There is no connection to the middleware 

TP_INVALID_OPTION_VALUE
 
TP_COMMAND

An invalid timeout value is specified 

TP_MONITOR_ERROR
 
TP_ERROR

Error is reported from the middleware 

TP_INVALID_MONITOR_OPTION
 
TP_WARNING

timeout is specified as INFINITE and the middleware does not support it. If the command continues, the maximum timeout allowed by the middleware is used 

TP_TRANSACTION_LIMIT
 
TP_COMMAND

A transaction is already active; only one is allowed to exist at a time

Example

// Process a bank account withdrawal.
// FML buffers are used in a call to service WITHDRAWAL
proc withd ()
vars message
//******** Perform ATM Withdrawal ********
if (account_id == "")
{
	msg quiet "Account id is required"
	return 0
}

if (amount > 0)
{
	xa_begin
	service_call "WITHDRAWAL" ({account_id, amount}, \
		{message, balance = account_balance})
	xa_end
	if (@app()->tp_svc_outcome == TP_FAILURE)
	{ 
		msg quiet message
	}
}
 
else
{
	msg quiet "Invalid withdrawal amount"
}
return 0

See Also

xa_commit, xa_end, xa_rollback