11.23 Communication Etiquette

When writing code to be run in transaction mode, you must observe the following rules of basic communication etiquette:

• Processes that are participants in the same transaction must require replies for all requests. To include a request that requires no reply, set the flags parameter of tpacall() to TPNOTRAN or TPNOREPLY.
• A service must retrieve all asynchronous transaction replies before calling tpreturn() or tpforward(). This rule must be observed regardless of whether the code is running in transaction mode.
• The initiator must retrieve all asynchronous transaction replies (made without the TPNOTRAN flag) before calling tpcommit().
• Replies must be retrieved for asynchronous calls that expect replies from non-participants of the transaction, that is, replies to requests made with tpacall() in which the transaction, but not the reply, is suppressed.
• If a transaction has not timed out but is marked “abort-only,” any further communication must be performed with the TPNOTRAN flag set so that the results of the communication are preserved after the transaction is rolled back.
• If a transaction has timed out:
  • The descriptor for the timed-out call becomes stale and any further reference to it returns TPEBADDESC.
  • Further calls to tpgetrply() or tprecv() for any outstanding descriptors return a global state of transaction timeout; the system sets tperrno(5) to TPETIME.
  • Asynchronous calls can be made with the flags parameter of tpacall() set to TPNOREPLY, TPNOBLOCK, or TPNOTRAN.
• Once a transaction has been marked “abort-only” for reasons other than timeout, a call to tpgetrply() returns whatever value represents the local state of the call; that is, it returns either success or an error code that reflects the local condition.
• Once a descriptor is used with tpgetrply() to retrieve a reply, or with tpsend() or tprecv() to report an error condition, it becomes invalid and any further reference to it returns TPEBADDESC. This rule is always observed, regardless of whether the code is running in transaction mode.
• Once a transaction is aborted, all outstanding transaction call descriptors (made without the TPNOTRAN flag) become stale, and any further references to them return TPEBADDESC.