txControlRequestType |
  
|
txControlRequestType |
|
txControlRequestType is a complex type. It is a sequence of six elements, which must occur in the order shown.
<header-or-parameter-name xmlns="http://soapam.com/types/">
<onRequest> </onRequest>
<onReplyCodeValid> </onReplyCodeValid>
<onReplyCodeOther> </onReplyCodeOther>
<validReplyCodes> </validReplyCodes>
<txURL> </txURL>
<txTimeout> </txTimeout>
</header-or-parameter-name>
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 method, including a header or parameter of type txControlRequestType in the SOAP request. A header or parameter of txControlResponseType 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 |
|||
onRequest |
onRequestEnum |
required |
|
Indicates which transaction control operation SOAP/AM Server is to perform on receipt of the SOAP request, before sending the request IPM to the target server. One of: "begin" or "resume". "begin" indicates that SOAP/AM Server should begin a new transaction before sending the request to the target server. txURL should be omitted; the response will contain the new transaction's txURL. "resume" indicates that SOAP/AM Server should resume the previously suspended transaction identified by txURL before sending the request to the destination server. txURL must contain the URL of a transaction currently in the suspended state. |
|||
onReplyCodeValid |
onReplyCodeEnum |
required |
|
One of: "suspend", "commit" or "abort". Indicates which transaction control operation SOAP/AM Server is to perform after it receives the reply from the target server and the 'reply code' (the integer value contained in the first two byte word of the server's reply interprocess message) is contained in validReplyCodes. A suspended transaction's txURL can be used in subsequent requests or the TransactionCommit and TransactionAbort methods of the TransactionControl service. |
|||
onReplyCodeOther |
onReplyCodeEnum |
required |
|
One of: "suspend", "commit" or "abort". Indicates which transaction control operation SOAP/AM Server is to perform after it receives the reply from the target server and the 'reply code' (the integer value contained in the first two byte word of the server's reply interprocess message) is not contained in validReplyCodes. A suspended transaction's txURL can be used in subsequent requests or the TransactionCommit and TransactionAbort methods of the TransactionControl service. |
|||
validReplyCodes |
xsd:string |
required |
|
A list of reply codes used by SOAP/AM Server to determine whether to perform the onReplyCodeValid or the onReplyCodeOther transaction control operation. The comma-separated list may contain one or more reply code values and/or ranges. A range is represented as 'lo:hi' where lo and hi are integers in the range -32768 to 32767. In lieu of a list, "*" may be used to represent 'any' reply code. Typically, the 'valid' reply codes represent the reply codes that the application considers as 'success' or 'warning'. validReplyCodes should not contain whitespace. See examples below. |
|||
txURL |
xsd:string |
optional |
|
When onRequest is "resume", the identifier of a suspended transaction to be operated on; copied from the response of an earlier transaction control operation. When onRequest is "begin", txURL should be omitted. |
|||
txTimeout |
xsd:int |
optional |
|
If greater than zero, the number of seconds that the transaction should be allowed to 'live' before it is automatically aborted. If omitted or the specified value is greater than the configured NonStop TM/MP AutoAbort attribute, the AutoAbort value is used. txTimeout is only relevant when onRequest is "begin". |
|||
Remarks
A SOAP fault will be generated if any part of the txControlRequestType is invalid. This will occur, for example, if the txURL specified is not a valid transaction identifier or the transaction it represents has already been aborted (because its timeout has expired, perhaps).
Examples
The following are sample validReplyCodes strings and a description of the reply codes they represent:
validReplyCodes |
description |
|---|---|
* |
any reply code; same as -32768:32767 |
0 |
reply code zero only |
0,100 |
reply code zero or 100 |
-199:-100,0,999:9999 |
reply code in the range -199 to -100 (inclusive) or zero or in the range 999 to 9999 (inclusive) |
Header of type txControlRequestType in SOAP request
The following SOAP request contains a txControlRequestType header named txControlRequest. It specifies that SOAP/AM should begin a new transaction before forwarding the request to the target server. It further specifies that SOAP/AM should suspend the transaction (so that subsequent requests may be included in the same transaction) if the target server's reply code is zero or in the range of 9000 to 9999 (inclusive). Otherwise, SOAP/AM should abort the transaction. Furthermore, if the transaction is not committed within 60 seconds from the time it was begun, it should be aborted.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header>
<txControlRequest xmlns="http://soapam.com/types/">
<onRequest>begin</onRequest>
<onReplyCodeValid>suspend</onReplyCodeValid>
<onReplyCodeOther>abort</onReplyCodeOther>
<validReplyCodes>0,9000:9999</validReplyCodes>
<txURL></txURL>
<txTimeout>60</txTimeout>
</txControl>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
... detail omitted ...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>