The benefits of creating RTR solutions with C++ foundation classes include the following:

• Each major RTR concept is represented by its own individual foundation class.
• Simple methods within RTR classes transform features of RTR for streamlined solutions.
• Major classes include Get and Set methods for changing transaction states.
• Default handling code is provided for all Messages and Events, where appropriate.
• You do not need to provide handling code for all messages and events.
• The sending and receiving of data is abstracted to a higher level with transaction controller and data classes.
• No buffers and links coding is needed.
• Internal RTR information is accessible without a need to know RTR internals.

The XA interface is part of the X/Open DTP (Distributed Transaction Processing) standard. It defines the interface that transaction managers (TM) and resource managers (RM) use to perform the two-phase commit protocol. (Resource managers are underlying database systems such as ORACLE RDBMS, Microsoft SQL Server, and others.) This interface is not used by the application programs; it is only used by TM-to-RM exchanges to coordinate a transaction.

For details on using XA, see the RTR C Application Programmer's Reference Manual and the RTR Application Design Guide.

Reliability in RTR is enhanced by the use of:

• Concurrent servers
• Standby servers
• Shadow servers
• Callout servers
• Router failover

Note that, conceptually, servers can be contrasted as follows:

• Concurrent servers handle similar transactions which access the same data partition and run on the same node.
• Shadow servers handle the same transactions and run on different nodes.
• Standby servers provide a node that can take over processing on a data partition when the primary server or node fails.
• Callout servers run on backends or routers and receive all messages within a facility so that authentication and logging operations can be performed in parallel.

All servers are further described in the earlier section on RTR Terminology.

RTR provides several capabilities to ensure failover and recovery under several circumstances.

Router Failover

Frontend nodes automatically connect to another router if the one being used fails. This reconnection is transparent to the application.

Routers are responsible for coordinating the two-phase commit for transactions. If the original router coordinating a transaction fails, backend nodes select another router that can ensure correct transaction completion.

Backend Restart Recovery

Transactions in the process of being committed at the time of a failure are recovered from RTR's disk journal. Recovery could be with a concurrent server, a standby server, or a restarted server created when the failed backend restarts.

Correct ordering of the execution of transactions against the database is maintained.

Transaction Message Replay

Transaction messages which are lost in transit are re-sent when possible. The frontend and backend nodes keep an in-memory copy of all active messages for this purpose.

Link Failure Recovery

In the event of a communications failure, RTR tries to reconnect the link or links until it succeeds.

This section describes how RTR recovers from different hardware and software failure. For additional information on failure and recovery scenarios, see the RTR Application Design Guide.

Backend Recovery

If standby or shadow servers are available on another backend node, operation of the rest of the system will continue without interruption, using the standby or shadow server.

If a backend processor is lost, any transactions in progress are remembered by RTR and later recovered, either when the backend restarts, or by a standby if one is present. Thus, the distributed database is brought back to a transaction-consistent state.

Router Recovery

If a router fails and another router node is available, all in-progress transactions are transparently re-routed by the other router. System operation will continue without interruption.

Frontend Recovery

If a frontend is lost:

• All transactions committed but not completed on the frontend node at the time of failure will be completed.
• All transactions started but not committed on the frontend node at the time of failure will be aborted.

RTR provides interfaces for management and application programming.

You manage RTR with a management interface from the RTR management station. The management interfaces are:

• The command line interface or CLI
• The browser interface

The application programming interfaces (APIs) are:

• The object-oriented API for C++ programming, available with RTR Version 4.0. Use this API for all new development and, where appropriate, for new work on existing applications. An application can contain both object-oriented classes and portable API calls. This API can be used to implement applications on all platforms supported by RTR.
• The RTR API for C programming, available with RTR V3. This interface is also called the Portable API because it can be used to implement applications on all platforms supported by RTR.
• The OpenVMS API containing OpenVMS calls, available with RTR V2. This API, supported on OpenVMS only, is obsolete for new development. While applications using this API should be rewritten in the new object-oriented API to take advantage of new RTR features and capabilities, they can be changed by adding object-oriented classes rather than being rewritten.

You can use the command line interface to the API to write simple RTR applications for testing and experimentation. The CLI is described in the Reliable Transaction Router System Manager's Manual. Its use is illustrated in this chapter.

The RTR application programming interfaces are identical on all hardware and operating system platforms that support RTR. The object-oriented API is fully described in the manual Reliable Transaction Router C++ Foundation Classes. The C-programming API is fully described in the Reliable Transaction Router C Application Programmer's Reference Manual. Both APIs are used in designs in the RTR Application Design Guide.

You can manage RTR from a node on which RTR is running, from a remote node from which you send RTR commands to a node running RTR, or from a browser. The node where you enter commands, interact with the browser, or view results is your management station.

RTR Command Line Interface

The command line interface (CLI) to the RTR API enables the programmer to write short RTR applications from the RTR command line. This can be useful for testing short program segments and exploring how RTR works. For example, the following sequence of commands starts RTR and exchanges a message between a client and a server. To use these examples, you execute RTR commands simulating your RTR client application on the frontend and commands simulating your server application on the backend.

The following example shows communication between a client and a server created by entering commands at a terminal keyboard. The client application is executing on the frontend and the server on the backend.

The user is called user, the facility being defined is called DESIGN, a client and a server are established, and a test message containing the words "Kathy's text today" is sent from the client to the server. After the server receives this text, the user on the server enters the words "And this is my response." System responses begin with the characters % RTR-. Notes on the procedure are enclosed in square brackets [ ]. For clarity, commands you enter are shown in bold. You can view the status of a transaction with the SHOW TRANSACTION command.

The exchange of messages you observe in executing these commands illustrates RTR activity. You need to retain a similar sequence in your own designs for starting up RTR and initiating your own application.

You can use RTR SHOW and MONITOR commands to display status and examine system state at any time from the CLI. For more information on RTR commands, see the Reliable Transaction Router System Manager's Manual.

[The user issues the following commands on the server application where RTR is running on the backend.]

$ RTR Copyright Compaq Computer Corporation 1994. RTR> set mode/group %RTR-I-STACOMSRV, starting command server on node NODEA %RTR-I-GRPMODCHG, group changed from " " to "username" %RTR-I-SRVDISCON, server disconnected on node NODEA RTR> CREATE JOURNAL %RTR-I-STACOMSRV, starting command server on node NODEA in group "username" %RTR-S-JOURNALINI, journal has been created on device D: RTR> SHOW JOURNAL Journal configuration on NODEA in group "username" at Mon Aug 28 14:54:11 2000:- Disk: D:\ Blocks: 1000 RTR> start rtr %RTR-I-NOLOGSET, logging not set %RTR-S-RTRSTART, RTR started on node NODEA in group "username" RTR> CREATE FACILITY DESIGN/ALL_ROLES=(NODEA) [- or /all=NODEA,NODEB] %RTR-S-FACCREATED, facility DESIGN created RTR> SHOW FACILITY Facilities on node NODEA in group "username" at Mon Aug 28 15:00:28 2000: Facility Frontend Router Backend DESIGN yes yes yes RTR> rtr_open/server/accept_explicit/prepare_explicit/chan=s/fac=DESIGN %RTR-S-OK, normal successful completion RTR> RTR_RECEIVE_MESSAGE/CHAN=S %RTR-S-OK, normal successful completion channel name: S . . . msgtype: rtr_mt_opened . . . status: normal successful completion

[When the next command is issued, RTR waits for a message from the client.]

RTR> RTR_RECEIVE_MESSAGE/CHAN=S %RTR-S-OK, normal successful completion channel name: S msgsb msgtype: rtr_mt_msg1 msglen: 19 usrhdl: 0 Tid: 63b01d10,0,0,0,0,2e59,43ea2002 message offset bytes text 000000 4B 61 74 68 79 27 73 20 74 65 78 74 20 74 6F 64 Kathy's text tod 000010 61 79 00 ay. reason: Ox00000000 RTR> RTR_REPLY_TO_CLIENT/CHAN=S "And this is my response." %RTR-S-OK, normal successful completion RTR> show transaction Frontend transactions on node NodeA in group "username" at Mon Aug 28 15:12:10 2000 Tid Facility FE-User State 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. SENDING Router transactions on node NodeA in group "username" at Mon Aug 28 15:12:10 2000: 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. SENDING Backend transactions on node NodeA in group "username" at Mon Aug 28 15:12:10 2000: 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. RECEIVING RTR> RTR_RECEIVE_MESSAGE/CHAN=S %RTR-S-OK, normal successful completion channel name: S msgsb msgtype: rtr_mt_prepare [if OK, use: RTR_ACCEPT_TX else, use: RTR_REJECT_TX] RTR> RTR_RECEIVE_MESSAGE/TIME=0 RTR> STOP RTR [Ends example test.]

[Commands and system response at client.]

$ RTR RTR> START RTR %RTR-S-RTRSTART, RTR started on node NODEA in group "username" RTR> RTR_OPEN_CHANNEL/CHANNEL=C/CLIENT/fac=DESIGN %RTR-S-OK, normal successful completion RTR> RTR_RECEIVE_MESSAGE/CHANNEL=C/tim [to get mt_opened or mt_closed] %RTR-S-OK, normal successful completion channel name: C msgsb msgtype: rtr_mt_opened msglen: 8 message status: normal successful completion reason: Ox00000000 RTR> RTR_START_TX/CHAN=C %RTR-S-OK, normal successful completion RTR> RTR_SEND_TO_SERVER/CHAN=C "Kathy's text today." [text sent to the server] %RTR-S-OK, normal successful completion RTR> show transaction Frontend transactions on node NodeA in group "username" at Mon Aug 28 15:05:43 2000 Tid Facility FE-User State 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. SENDING Router transactions on node NodeA in group "username" at Mon Aug 28 15:06:43 2000: 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. SENDING Backend transactions on node NodeA in group "username" at Mon Aug 28 15:06:43 2000: 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. SENDING RTR> RTR_RECEIVE_MESSAGE/TIME=0/CHAN=C

[The following lines arrive at the client from RTR after the user enters commands at the server.]

%RTR-S-OK, normal successful completion channel name: C msgsb msgtype: rtr_mt_reply msglen: 25 usrhdl: 0 tid: 63b01d10,0,0,0,0,2e59,43ea2002 message offset bytes text 000000 41 6E 64 20 74 68 69 73 20 69 73 20 6D 79 20 72 And this is my r 000010 65 73 70 6F 6E 73 65 2E 00 esponse.. RTR> RTR_ACCEPT_TX/CHANNEL=C %RTR-S-OK, normal successful completion

RTR> show transaction Frontend transactions on node NodeA in group "username" at Mon Aug 28 15:17:45 2000 Tid Facility FE-User State 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. VOTING Router transactions on node NodeA in group "username" at Mon Aug 28 15:17:45 2000: 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. VOTING Backend transactions on node NodeA in group "username" at Mon Aug 28 15:17:45 2000: 63b01d10,0,0,0,0,2e59,43ea2002 DESIGN username. COMMIT RTR> RTR_RECEIVE_MESSAGE %RTR-S-OK, normal successful completion channel name: S . . . msgtype: rtr_mt_accepted . . . RTR> STOP RTR

Browser Interface

With the RTR browser interface, your management station has a network-browser-like display from which you can view RTR status and issue RTR certain commands with a point-and-click operation, rather than by entering commands. Figure 4-1 shows one screen of the browser interface as you may view it from your management station running Microsoft Internet Explorer. Not all RTR CLI commands are accessible to the browser interface, only the most commonly used commands are available with the RTR browser. The browser interface provides help (for forms input) and logging windows, and navigational aids between displays.

Figure 4-1 RTR Browser Interface

You write application programs and management applications with the RTR application programming interfaces.

RTR Object-Oriented Programming Interface

You can use the object-oriented programming interface to write C++ applications that use RTR. For more information on the object-oriented programming interface, see the RTR C++ Foundation Classes manual and the RTR Application Design Guide.

Sample C++ client code

Example of object creation in an RTR client program.

// // Create a Transaction Controller to receive incoming messages // and events from a client. // RTRClientTransactionController *pTransaction = new RTRClientTransactionController(); // // Create an RTRData object to hold an ASCII message for the server. // RTRData *pMessage1 = new RTRData("You are pretty easy to use!!!"); // // Send the Server a message // sStatus = pTransaction->SendApplicationMessage(pMessage1); ASSERT(RTR_STS_OK == sStatus); // // Since we have successfully finished our work, tell RTR we accept the // transaction. // pTransaction->AcceptTransaction();

Sample C++ server code

Example of object creation in an RTR server program.

void CombinationOrderProcessor::StartProcessingOrdersAtoL() { // // Create an RTRKeySegment for all ASCII values between "A" and "L." // m_pkeyRange = new RTRKeySegment (rtr_keyseg_string, //To process strings. 1, //Length of the key. OffsetIntoApplicationProtocol, //Offset value. "A", //Lowest ASCII value for partition. "L"); //Highest ASCII value for partition. StartProcessingOrders(PARTITION_NAMEAToL,m_pKeyRange); } // // Create an RTRData Oobject to hold each incoming message or event. This // object will be reused. // RTRData *pDataReceived= new RTRData(); // // Continually loop, receiving messages and dispatching them to the handlers. // while(true) { sStatus = pTransaction->Receive(&pDataReceived); ASSERT(RTR_STS_OK == sStatus); sStatus = pDataReceived->Dispatch(); ASSERT(RTR_STS_OK == sStatus); }

RTR C Programming Interface

You can use the C programming interface to write C applications that use RTR. For more information on the C programming interface, see the RTR C Application Programmer's Reference Manual and the RTR Application Design Guide.

Snippets from client and server programs using the RTR C-programing API follow and are more fully shown in the RTR Application Design Guide.

Sample C client code

Example of an open channel call in an RTR client program:

status = rtr_open_channel(&Channel, Flags, Facility, Recipient, RTR_NO_PEVTNUM, Access, RTR_NO_NUMSEG, RTR_NO_PKEYSEG); if (Status != RTR_STS_OK)

Sample C server code

Example of a receive message call in an RTR server program:

status = rtr_receive_message(&Channel, RTR_NO_FLAGS, RTR_ANYCHAN, MsgBuffer, DataLen, RTR_NO_TIMOUTMS, &MsgStatusBlock); if (status != RTR_STS_OK)

A client can have one or multiple channels, and a server can have one or multiple channels. A server can use concurrent servers, each with one channel. How you create your design depends on whether you have a single CPU or a multiple CPU machine, and on your overall design goals and implementation requirements.