Reliable Transaction Router introduces greater flexibility and efficiency in how transaction voting (acceptance by servers) is handled; RTR allows implicit voting.

In detail, the sequence of events that a server executes is as follows:

1. Get one or more transaction messages from RTR and process them.
2. Get the vote request message from RTR.
3. Issue the accept (commit).
4. Get the final transaction state.
5. Return to Step 1.

This scheme is not efficient in some cases. For example, a callout (authentication) server may only need to receive the first message of a multiple message transaction, whereupon it can vote immediately.

In Reliable Transaction Router, all these steps can be enforced if required, but optimizations allow some of the steps to be handled implicitly.

An implicit accept allows Step 3 to be omitted; the transaction is accepted by the server when it does the next call to rtr_receive_message .

These optimizations are controlled by flags (RTR_F_OPE_EXPLICIT_PREPARE and RTR_F_OPE_EXPLICIT_ACCEPT) on the call used to open a server channel.

2.9.2.1 The RTR_F_OPE_EXPLICIT_PREPARE Flag

A server channel may be opened with the RTR_F_OPE_EXPLICIT_PREPARE flag; this specifies that it will receive prepare messages (messages of type rtr_mt_prepare). The server is then expected to accept or reject a transaction on receipt of this message (or earlier). The server may accept the transaction before the prepare message is sent: in this case the prepare message is not delivered to the server.

The default behaviour of RTR (that is, when this flag is not set in the call to rtr_open_channel is to not send prepare messages to the server application. In this case RTR expects the server to accept or reject transactions without RTR triggering it into voting activity by sending prepare messages.

2.9.2.2 The RTR_F_OPE_EXPLICIT_ACCEPT Flag

A server channel may be opened with the RTR_F_OPE_EXPLICIT_ACCEPT flag; this specifies that it will accept transactions only by making an explicit call to rtr_accept_tx .

The default behaviour of RTR (that is, when this flag is not set) is to treat a server's call to rtr_receive_message (after the last transaction message has been received) as an implicit acceptance of the transaction.

If a transaction has been accepted before the last message has been received, the setting of the RTR_F_OPE_EXPLICIT_ACCEPT is irrelevant.

However, if a transaction has not been prematurely accepted, when the server's vote is required by RTR, the setting of the flags have the following effects:

1. When both RTR_F_OPE_EXPLICIT_PREPARE and RTR_F_OPE_EXPLICIT_ACCEPT are set, the rtr_mt_prepare message is returned to the server, and the server is must accept or reject the transaction.
2. When RTR_F_OPE_EXPLICIT_PREPARE is set, but RTR_F_OPE_EXPLICIT_ACCEPT is not set, the rtr_mt_prepare message is also returned to the server, but if the server does not perform an explicit accept or reject, then a subsequent call to rtr_receive_message implies an accept of the transaction.
3. When RTR_F_OPE_EXPLICIT_PREPARE is not set, but RTR_F_OPE_EXPLICIT_ACCEPT is set, no rtr_mt_prepare message is returned to the server, and no implicit accept of the transaction will be performed: It is assumed that some other event will trigger the application into voting.
4. With neither RTR_F_OPE_EXPLICIT_PREPARE nor RTR_F_OPE_EXPLICIT_ACCEPT set, no rtr_mt_prepare message is returned to the server. An implicit transaction accept is performed.

All RTR calls return a completion status immediately, except rtr_receive_message . If the immediate status is successful, many calls will also result in a further message or messages being delivered on the channel.

All RTR received messages are of a defined message type. The message type is given in the message status block. (See pmsgsb on rtr_receive_message in Chapter 3).

The message type allows your application to handle the message appropriately; the message type indicates whether this message contains information that is part of a transaction, or a broadcast, or RTR informational, and so on.

The use of rtr_receive_message for both RTR status messages and application data messages requires the application designer to understand how to respond to the different message types. Message types are listed in Table 2-2 and Table 2-3.

All received messages cause the message status block (pmsgsb on rtr_receive_message to be filled; most message types also put data into the user buffer (pmsg on rtr_receive_message . Only the rtr_mt_prepare message type does not fill the user buffer.

Information put in the user buffer for each message type is listed in Table 2-4. Table 2-2 and Table 2-3 list all the message types that server channels or client channels can receive, together with a description of their meaning and the recommended application behaviour. Order is alphabetical.

Table 2-2 RTR Received Message Types for Servers

Message Type	Description	Recommended Action
rtr_mt_accepted	The specified transaction has been accepted by all participants.	Commit the transaction in the database and release database locks.
rtr_mt_closed	Channel has been closed. Sent by RTR if an rtr_open_channel fails (that is, no such facility) or as a result of an operator command such as DELETE FACILITY, or the last message from a rtr_request_info or rtr_set_info call.	Examine reason status. Roll back database for any active transaction.
rtr_mt_msg1	This is the first application message of a transaction, sent by a client.	Process the message.
rtr_mt_msg1_uncertain	This is the first application message of a replayed transaction, that is, a previous incarnation of the server failed during the voting phase.	Check in database to see if the transaction has been processed. If not processed, redo the transaction; else forget the transaction.
rtr_mt_msgn	This is the nth application message (that is, not the first) of a transaction, sent by a client.	Process the message.
rtr_mt_opened	Channel has been opened.	Use the channel.
rtr_mt_prepare	The specified transaction is complete (that is, all messages from the client have been received). This message type is only received by a server which specified that it requires a prepare. (Servers specify this by using the RTR_F_OPE_EXPLICIT_PREPARE flag on the rtr_open_channel call.)	Call either rtr_reject_tx to reject the transaction, or have all required database records locked before calling rtr_accept_tx to accept the transaction.
rtr_mt_rejected	The specified transaction has been rejected by a participant.	Roll back the transaction.
rtr_mt_request_info	Message from a previous call to rtr_request_info .	Use information as required.
rtr_mt_rtr_event	An RTR event with an associated message.	evtnum describes which RTR event occurred. See Table 2-5.
rtr_mt_set_info	Message from a previous call to rtr_set_info .	Use information as required.
rtr_mt_user_event	A user event with an associated message.	evtnum has an application-specific meaning.

Table 2-3 RTR Received Message Types for Clients

Message Type	Description	Recommended Action
rtr_mt_accepted	The specified transaction has been accepted by all participants.	Inform user of successful completion.
rtr_mt_closed	Channel has been closed. Sent by RTR if an rtr_open_channel fails (for example, no such facility) or as a result of an operator command such as DELETE FACILITY, or the last message from an rtr_request_info or rtr_set_info call.	Examine reason status.
rtr_mt_opened	Channel has been opened.	Use the channel.
rtr_mt_prepared	The specific nested transaction has been prepared by all participants. (First phase of the two-phase commit protocol on servers has been completed).	Call rtr_accept_tx to accept or rtr_reject_tx to reject the transaction.
rtr_mt_rejected	The specified transaction has been rejected by a participant.	Inform user of reason for failure.
rtr_mt_reply	This is an application reply message sent by a server.	Process message.
rtr_mt_request_info	Message from a previous call to rtr_request_info .	Use information as required.
rtr_mt_rettosend	This message (which had been sent with the RTR_F_SEN_RETURN_TO_SENDER flag) could not be delivered and has been returned.	Take appropriate action for the transaction as required by your application.
rtr_mt_rtr_event	An RTR event with an associated message.	evtnum describes which RTR event occurred. See Table 2-5.
rtr_mt_set_info	Message from a previous call to rtr_set_info .	Use information as required.
rtr_mt_user_event	A user event with an associated message.	evtnum has an application-specific meaning.

Table 2-4 Contents of The User Buffer for Different Message Types

Message Type	Buffer Contents
rtr_mt_accepted	rtr_status_data_t , see Figure 2-1.
rtr_mt_closed	rtr_status_data_t , see Figure 2-1.
rtr_mt_msg1	The first application message of a transaction, sent by a client.
rtr_mt_msg1_uncertain	The first application message of a replayed transaction.
rtr_mt_msgn	The nth application message (that is, not the first) of a transaction, sent by a client.
rtr_mt_opened	rtr_status_data_t , see Figure 2-1.
rtr_mt_prepare	None.
rtr_mt_prepared	rtr_status_data_t , see Figure 2-1.
rtr_mt_rejected	rtr_status_data_t , see Figure 2-1.
rtr_mt_reply	An application reply message sent by a server.
rtr_mt_request_info	Requested information from rtr_request_info .
rtr_mt_rettosend	Returned message.
rtr_mt_rtr_event	RTR event message.
rtr_mt_set_info	Set information from rtr_set_info .
rtr_mt_user_event	The user broadcast message.

Figure 2-1 shows the data type that is returned in the user buffer with message types rtr_mt_accepted, rtr_mt_rejected, rtr_mt_opened and rtr_mt_closed. You can find the meaning of rtr_status_t using the call rtr_error_text .

Figure 2-1 Type rtr_status_data_t

/* Type returned with rtr_mt_rejected,*/ typedef struct /* rtr_mt_accepted, rtr_mt_opened */ { /* and rtr_mt_closed messages. */ rtr_status_t status; /* RTR status */ rtr_reason_t reason; /* User-supplied reason */ } rtr_status_data_t;

2.11 RTR Events

What are events?

An event in RTR is a trigger which causes an event notification (also called a "broadcast") to be sent to the application which has subscribed to that event. RTR Events are created only by RTR and are used internally by RTR to help manage activities such as site failover. Application developers may subscribe to RTR Events to activate certain processing in their application. User Events are also available to enable application developers to send event notification or broadcast messages to other RTR applications. RTR provides the call rtr_broadcast_event to enable an application developer to trigger a User Event.

Events have special characteristics and restrictions:

• Event notification is delivered on a subscription basis using information supplied on the rtr_open_channel call.
• Events are not transactional and should not be used to transmit information which is, or will be, part of an RTR transaction.
• There is no capability in RTR to turn off RTR Events. The use of User Events is optional.
• User Events may only be transmitted within the RTR facility in which they are defined. User Events may not be sent between facilities or outside RTR.
• The User Event notification may include an optional message, which has a size limit of 64K.
• User Events can only be transmitted from frontend-to-backend or from backend-to-frontend. User Events cannot be used for peer-to-peer communication such as from frontend-to-frontend or from backend-to-backend.
• RTR Events are transmitted from RTR-to-frontend or RTR-to-backend.

The list below shows the RTR Events which are available for subscription. These events can be grouped in four basic categories:

• Shadow node activity (failover, failback, recovery complete)
• Standby node activity (become active, become standby, recovery complete)
• Changes in facility state and participants (clients/routers/servers entering or exiting the facility)
• Changes in configuration of partition key ranges (server available, server not available)

Table 2-5 lists the RTR events that can be received on a channel (associated with the rtr_mt_rtr_event message type). Events are listed in order of event number. See the description for rtr_open_channel in Chapter 3, RTR Call Reference, for further information. RTR sends events to the server either inside or outside a transactional boundary. A transaction is considered to start on receipt of an rtr_mt_msg1 message, and to end when the transaction is accepted or rejected (receipt of an rtr_mt_accepted or rtr_mt_rejected message). Events containing information about primary, secondary, or standby servers can arrive ahead of a transactional boundary. Gain and loss events arrive inside transactional boundaries.

Table 2-5 RTR Event Numbers

Event Number Name	No.	Description
RTR_EVTNUM_FACREADY	96	The facility has become operational.
RTR_EVTNUM_FACDEAD	97	The facility is no longer operational.
RTR_EVTNUM_FERTRGAIN	98	Frontend link to current router established.
RTR_EVTNUM_FERTRLOSS	99	Frontend link to current router lost.
RTR_EVTNUM_RTRBEGAIN	100	Current router established link to a backend.
RTR_EVTNUM_RTRBELOSS	101	Current router lost link to a backend.
RTR_EVTNUM_KEYRANGEGAIN	102	Server(s) for new routing key range are now available.
RTR_EVTNUM_KEYRANGELOSS	103	No more servers remain for a particular routing key range.
RTR_EVTNUM_BERTRGAIN	104	Backend established link to a router.
RTR_EVTNUM_BERTRLOSS	105	Backend lost link to a router.
RTR_EVTNUM_RTRFEGAIN	106	Router established link to a frontend.
RTR_EVTNUM_RTRFELOSS	107	Router lost link to a frontend.
RTR_EVTNUM_SRPRIMARY	108	Server has become primary. 1
RTR_EVTNUM_SRSTANDBY	109	Server has become standby.
RTR_EVTNUM_SRSECONDARY	110	Server in a shadow pair has become secondary. 2
RTR_EVTNUM_SRSHADOWLOST	111	Server in a shadow pair lost its shadow partner. 3
RTR_EVTNUM_SRSHADOWGAIN	112	Server in a shadow pair acquired a shadow partner.
RTR_EVTNUM_SRRECOVERCMPL	113	Server completed recovery processing.