SOAP/AM Server Development > Service Definition File Reference > Schema Reference

The txControl type is a complex type. It is a sequence of six elements, all of which must occur exactly once and in the order shown.

When a user-defined service's method includes a <transactionControl> element that enables client control of transactions, a client application can control a SOAP/AM server-managed transaction by...

•calling the user-defined method, including a header or parameter of type txControl

•calling the built-in TransactionControl method, which takes a parameter of type txControl

In either case, an updated txControl element is returned to the client in the SOAP response. See Client Transaction Control for more information.

element name	content data type	usage	default value
description

txOperation

txOperationType

required

Indicates which transaction control operation SOAP/AM Server is to perform.

These txOperation types are to be used only when the txControl element is sent as a header or parameter in user-defined method:

suspend

Indicates that SOAP/AM Server should begin a new transaction (if txURL is empty), or resume a transaction that was previously begun and suspended (identified by txURL), before sending the request to the destination server. If a new transaction was begun, the response will contain the new txURL. In either case, SOAP/AM Server suspends or aborts the transaction after the destination server replies, subject to txRange. The determination as to whether to suspend or abort the transaction is made by examining the reply code (the first 2-byte word) of the server's reply interprocess message and comparing it to txRange. If the reply code falls within the range of values specified in txRange, the transaction is suspended, otherwise the transaction is aborted. A suspended transaction's txURL can be used in subsequent transaction control operations.

end

Indicates that SOAP/AM Server should resume the previously suspended transaction identified by txURL before sending the request to the destination server and to end the transaction after the destination server replies. The determination as to whether to end the transaction by committing it or aborting it is made by examining the reply code (the first 2-byte word) of the server's reply interprocess message and comparing it to txRange. If the reply code falls within the range of values specified in txRange, the transaction is committed, otherwise the transaction is aborted.

These txOperation types are to be used only when the txControl element is sent as a parameter to the built-in TransactionControl method:

begin	Indicates that SOAP/AM Server should be a new transaction and immediately suspend it. The txURL of the request's txControl element should be empty. The response's txControl element will contain the new txURL. A suspended transaction's txURL can be used in subsequent txControl operations.
commit	Indicates that SOAP/AM Server should commit the transaction identified by txURL immediately.
abort	Indicates that SOAP/AM Server should abort the transaction identified by txURL immediately.

txURL	xsd:URI	required
In a request, the identifier of the suspended transaction to be operated on; copied from the response of an earlier transaction control operation. txURL should be empty when a new transaction is desired (txOperation is "suspend" or "begin"); the txURL of the suspended transaction is returned in the response.

txTimeout	xsd:nonNegativeInteger	required
If greater than zero, the number of seconds that the transaction should be allowed to live before it is automatically aborted. If the specified value is greater than the configured NonStop TM/MP AutoAbort attribute, the AutoAbort value takes precedence. If the value is equal to zero, the AutoAbort value is used. txTimeout is only relevant when a new transaction is begun.

txRange	xsd:token	required
A comma-separated list of ranges where range is 'lo:hi' and lo and hi are integers in the range -32768 to 32767. "*" may be used to represent the entire range. A range that represents a single value may be abbreviated to just the value itself. txRange is used by SOAP/AM Server when txOperation is "suspend" or "end". If the destination server's reply interprocess message's first word (2 bytes) falls inside the range, the transaction is suspended or ended (committed) as requested, otherwise it is aborted.

txOutcome	xsd:token	required
In a response, one of "committed", "aborted" or "suspended", indicating the outcome of the operation. In a request, txOutcome should be empty.

txResult	xsd:nonNegativeInteger	required	0
In a response, the result code (file system error number) of the NSK transaction control API, e.g. ENDTRANSACTION() used by SOAP/AM Server to execute the requested transaction control operation. If non-zero, the status of the transaction is unknown. In the request, txResult should be empty.

Remarks

Always examine the txResult element contained in the response. If non-zero, the status of the transaction is unknown. A transaction control error will not generate a SOAP fault.

Example

txControl as header in SOAP request

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Header>

<txURL>soapamtx://\MYSYS.0.12345678</txURL>

</txControl>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

... detail omitted ...

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

txControl as header in SOAP response

<?xml version="1.0" encoding="UTF-8"?>