txControlRequestType

txControlRequestType is a complex type. It is a sequence of six elements, which must occur in the order shown.

XML

<txControlRequest xmlns="http://soapam.com/types/">
  <onRequest></onRequest>
  <onReplyCodeValid></onReplyCodeValid>
  <onReplyCodeOther></onReplyCodeOther>
  <validReplyCodes></validReplyCodes>
  <txURL></txURL>
  <txTimeout></txTimeout>
</txControlRequestType>

When a user-defined service's method includes a <transactionControl> element that enables client control of transactions, a client application can control a SOAPam 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.

Elements

Element	Data type	Usage	Default value	Description
onRequest	onRequestEnum	required	none	Indicates which transaction control operation SOAPam 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 SOAPam 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 SOAPam 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	none	One of: "suspend", "commit" or "abort". Indicates which transaction control operation SOAPam 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	none	One of: "suspend", "commit" or "abort". Indicates which transaction control operation SOAPam 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	none	A list of reply codes used by SOAPam 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 'low-value:high-value' where low-value and high-value are integers in the range -32768 to 32767. Asterisk may "*" 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	none	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	0	If greater than zero, the number of seconds that the transaction should be allowed to remain active before it is automatically aborted by the TMF. 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).

Example

The following are sample validReplyCodes strings and a description of the reply codes they represent:

validReplyCodes value	description
*	any reply code
0	reply code 0 only
0,100	reply code 0 or 100
~~199:~~100,0,999:9999	reply code in the range -199 to -100 inclusive, or 0, or in the range 999 to 9999 inclusive

The following SOAP request contains a txControlRequestType header. It specifies that SOAPam Server should begin a new transaction before forwarding the request to the target server. Upon reply, SOAPam Server 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, SOAPam Server should abort the transaction. Furthermore, if the transaction is not committed within 60 seconds from the time it was begun, it should be aborted.

XML

<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>
    </txControlRequest>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    ...
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>