Users need to register an resource manager first, to invoke RTR XA support when creating a facility. Please see the RTR System Manager's Manual for more details about how to register and unregister resource managers. In the server application, specify the flag RTR_F_OPE_XA_MANAGED and the underlying resource manager information when issuing the rtr_open_channel call. Once this flag is specified for a given RTR partition, all transactions running in that RTR partition are committed using the XA interface between RTR and the resource manager. When the partition is deleted or the resource manager is unregistered, RTR commits transactions running in this partition in a conventional manner.

Applications using RTR in a multiplatform (that is, mixed endian) environment with non-string application data have to tell RTR how to marshall the data for the destination architecture. The sender of a message must supply both a description of the application data being sent and the application data itself. This description is supplied as the msgfmt argument to rtr_send_to_server , rtr_reply_to_client , and rtr_broadcast_event .

The default (that is, when no msgfmt is supplied) is to assume the application message is string data.

2.15.1 Defining a Message Format

The msgfmt string is a null-terminated ASCII string consisting of a number of field-format specifiers:

[field-format-specifier,...]

The field-format specifier is defined as:

%[dimension]field-type

where:

Field	Description	Meaning
%	indicates a new field description is starting.
dimension	is an optional integer denoting array cardinality (default 1)
field-type	is one of the following:
	Code	Meaning
	UB	8 bit unsigned byte
	SB	8 bit signed byte
	UW	16 bit unsigned
	SW	16 bit signed
	UL	32 bit unsigned
	SL	32 bit signed
	C	8 bit signed char
	UC	8 bit unsigned char
	B	boolean

For example, consider the following data structure:

typedef struct { rtr_uns_32_t first ; rtr_sgn_32_t second ; char str[12] ; } example_t ;

The msgfmt for this structure could be " %ul%sl%12c ".

The transparent data type conversion of RTR does not support certain conversions (for example, floating point). These should be converted to another format, for example, character string.

2.16 Application Design and Tuning Issues

This section addresses some considerations for design and tuning, including:

• Transactions that can cause server failure
• Transaction grouping and database applications
• Transaction sequence and shadow servers
• Transaction sequencing

It is possible for a "rogue" client transaction, due to a user application bug, to "kill" the server process. If RTR were to re-apply this transaction indefinitely, all available servers would be destroyed. To avoid a transaction killing all server processes, the following mechanism is implemented:

• A transaction for which no rtr_accept_tx has been called by a server is aborted after it has caused the death of three concurrent servers to which it has been presented. The transaction abort status reported to the client is RTR_STS_SRVDIED. Retry count for transactions that have not been voted on is three; for transactions that have been voted on, retry count can be limited with the RTR command SET PARTITION/RECOVERY_RETRY_COUNT (default: unlimited).
• An RTR error log message with the same status is also written on the backend where the server deaths occurred.

The limitation of this feature to transactions which have not yet been accepted prevents possible transaction inconsistencies which could otherwise arise between client and server(s), and on shadow secondary sites. This implies that it is advisable for a server application to complete any necessary validation of client transaction messages before accepting the transaction, if they wish to take advantage of this feature.

2.16.2 Transaction Grouping and Database Applications

RTR generates commit sequence numbers (CSN) for each transaction committed on the primary site. Concurrent servers can have several transactions assigned to a single CSN value. Transactions with the same CSN are understood by RTR to be independent, and hence their relative commit ordering to the database does not violate the serialisability requirements of transactions.

For purposes of throughput, RTR attempts to group as many transactions as possible into a single CSN during a given vote cycle. (Grouped transactions are only those that explicitly vote (i.e., call rtr_accept_tx on the server.)

The vote cycle completes as soon as RTR is ready to ask a server to commit the next transaction. For this mechanism to work correctly with the application, RTR places the following restriction on the server design:

• A server must obtain an exclusive lock on any resource that another concurrent server may be accessing for a different transaction before it issues the call to rtr_accept_tx.

Database applications, in general, do not have a problem with such an assumption. In cases where the database management software allows "dirty reads," the application has to apply this rule explicitly, so that RTR can correctly serialise transactions during shadowing or other recovery. Failure to comply with this rule can result in unsynchronised copies of shadow databases.

2.16.3 Transaction Sequence and Shadow Servers

When using a facility having a shadow site and two or more partitions, the transaction sequence is the same at both shadow sites within a single partition only. Sequences across partitions are not preserved. For example, suppose the following transactions are executed on one half of a shadow site in the following chronological order:

• tx1_for_partition1
• tx2_for_partition1
• tx3_for_partition1
• tx1_for_partition2
• tx4_for_partition1

When replayed on the secondary, the order could be:-

• tx1_for_partition1
• tx2_for_partition1
• tx3_for_partition1
• tx4_for_partition1
• tx1_for_partition2

Do not write your application to expect transaction serialization across partitions to be preserved.

2.16.4 Transaction Independence

RTR normally assumes that each transaction processed by a given server depends on the transactions that particular server has previously accepted.

To keep the shadowed database identical to that on the primary, RTR controls the order in which the secondary executes transactions. The secondary is constrained to execute transactions in the same order as the primary. Under some circumstances, this can lead to the secondary sitting idle, waiting to be given a transaction to execute.

RTR provides a performance enhancement that may help some applications decrease idle time on the secondary, reducing the corresponding backlog. If the application knows that particular transactions are independent of the transactions previously received, then the application can set one of two flags listed in Table 2-9:

Table 2-9 Independent Transaction Flags

Flag	Meaning
RTR_F_ACC_INDEPENDENT	Set on an rtr_accept_tx call to indicate this transaction is independent.
RTR_F_REP_INDEPENDENT	Set on an rtr_reply_to_client call along with RTR_F_REP_ACCEPT to indicate this transaction is independent.

A transaction accepted with one of these flags can be started on the secondary while other transactions are still running. All transactions flagged with one of these flags must truly be independent of the transactions which have previously executed. They will execute in an arbitrary sequence on the secondary site.

An application can be written to create CSN boundaries to ensure independence. A transaction always receives a CSN, and the INDEPENDENT flag could be used to prevent the CSN from being incremented, so an application could be coded to force dependence between sets of transactions. This could be important in certain cases where transactions coming in at a particular time of day are independent of each other, but other transactions executed, say, at the end of the day, need to ensure that the day's transactions have been processed, and the following day's transactions need to ensure that the previous end-of-day processing has completed.

This chapter contains the environmental limits and syntax definitions for all Portable API calls.

3.1 RTR Environmental Limits

RTR deals with several environmental entities that have architectural limits as shown in Table 3-1. Actual limits in a specific configuration are determined by performance.

Table 3-1 Environmental Limits

Component	Limit
BE or TR nodes	512
Bytes per message	64000
Channels per application process	256
Facilities	100 to 1000, depending on operating system
FE nodes	1000
Journal files	16
Memory per process	OpenVMS: 4GB; UNIX: unlimited; NT: 2GB
Messages per transaction	unlimited
Partitions	500
Processes per node	1000
Size of journal file	256MB
Threads per application process (where supported by operating system)	4096

3.2 RTR Calls

The calls are presented in alphabetical order.

Accept the transaction currently active on the specified channel.

Syntax

status = rtr_accept_tx (channel, flags, reason)

Argument	Data Type	Access
status	rtr_status_t	write
channel	rtr_channel_t	read
flags	rtr_acc_flag_t	read
reason	rtr_reason_t	read

C Binding

rtr_status_t rtr_accept_tx (

rtr_channel_t channel ,
rtr_acc_flag_t flags ,
rtr_reason_t reason
)

Arguments

channel

The channel identifier (returned earlier by rtr_open_channel() ).

flags

Flags that specify options for the call.

Table 3-2 shows the flags that are defined.

Table 3-2 Accept Transaction Flags

Flag name	Description
RTR_F_ACC_FORGET	Set to prevent receipt of any more messages (or completion status) associated with the transaction. Any such messages are discarded. This flag is valid only on server channels; it has no effect on client channels.
RTR_F_ACC_INDEPENDENT	Set to indicate this transaction is independent. (See Section 2.16.4 for further information.)

If you do not require any flags, specify RTR_NO_FLAGS for this parameter.

reason

Optional reason for accepting the transaction. This reason is ORed together with the reasons of the other participants in the transaction and returned in the reason field of the rtr_status_data_t structure returned with the rtr_mt_accepted message to all participants of the transaction. Specify RTR_NO_REASON if no reason is required.

Description

The rtr_accept_tx() call accepts the transaction currently active on the specified channel. After rtr_accept_tx() has been called, the caller may no longer actively participate in the fate of the transaction; that is, messages and the final completion status can still be received, but no further messages may be sent for the transaction.

Example

/* * Client is done with the txn; if the server accepts the * transaction, there is no reason for us to reject it. * Accept it, then go on to a new transaction. */ if (msgsb.msgtype == rtr_mt_accepted) { status = rtr_accept_tx( &channel, RTR_NO_FLAGS, RTR_NO_REASON ); check_status( status ); } else . . Issue the error message returned by the . server, and recover from there. .

See Also

• rtr_open_channel()
• rtr_reject_tx()

Broadcast (send) a user event message.

Syntax

status = rtr_broadcast_event (channel, flags, pmsg, msglen, evtnum, rcpspc, msgfmt)

Argument	Data Type	Access
status	rtr_status_t	write
channel	rtr_channel_t	read
flags	rtr_bro_flag_t	read
pmsg	rtr_msgbuf_t	read
msglen	rtr_msglen_t	read
evtnum	rtr_evtnum_t	read
rcpspc	rtr_rcpspc_t	read
msgfmt	rtr_msgfmt_t	read

C Binding

rtr_status_t rtr_broadcast_event (

rtr_channel_t channel ,
rtr_bro_flag_t flags ,
rtr_msgbuf_t pmsg ,
rtr_msglen_t msglen ,
rtr_evtnum_t evtnum ,
rtr_rcpspc_t rcpspc ,
rtr_msgfmt_t msgfmt
)

Arguments

channel

The channel identifier (returned earlier by rtr_open_channel() ).

flags

No flags are currently defined. Specify RTR_NO_FLAGS for this parameter.

pmsg

Pointer to the message to broadcast.

msglen

Length in bytes of the message broadcast.

evtnum

User event number associated with this broadcast. (Recipients must specify this to receive it.) For more information on user event numbers, see Section 2.11.

rcpspc

Name of the recipient(s). This null terminated character string contains the name of the recipient(s) [specified with the rcpnam parameter on the call to rtr_open_channel() ].

Wildcards ( "*" for any sequence of characters, and "%" for any one character) can be used in this string to address more than one recipient. rcpspc is an optional parameter. Specify RTR_NO_RCPSPC for this parameter if no rcpspc is required. Note that the event number (evtnum) must also be specified by the sender and the recipient.

Note that rcpspc is case sensitive.

msgfmt

Message format description. This null-terminated character string contains the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. See Section 2.15 for information on defining a message format description.

This parameter is optional. Specify RTR_NO_MSGFMT if message content is platform independent, or there is no intent to use other hardware platforms.

Description

The rtr_broadcast_event() call broadcasts a user event message. The caller must first open a channel (using rtr_open_channel() ), before it can send user event messages.

A client channel can be used to send user event messages to servers.

A server channel can be used to send user event messages to clients.

Example

#define reunion_announcement 678 // In user .h file. rtr_msg_buf_t reunion_msg = "Jones family reunion today!"; rtr_rcpspc_t recipients = "*Jones"; /* * If today is the date of the Jones family reunion, tell * any client whose last name is Jones that they need to * be there! */ if (strcmp(today, reunion_date) == 0) { status = rtr_broadcast_event( &channel, RTR_NO_FLAGS, reunion_msg, strlen(reunion_msg), reunion_announcement, recipients, RTR_NO_MSGFMT ); check_status( status ); }

See Also

• rtr_receive_message()
• rtr_open_channel()