Example 4-4 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

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

RTR C++ 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, refer to the Reliable Transaction Router C++ Foundation Classes manual and the Reliable Transaction Router Application Design Guide.

Sample C++ client code

The following example illustrates object creation in a program that is to act as an RTR client application. The first step is to create a Transaction Controller. This is followed by creating an RTR Data Object that will hold the ASCII message for the server, sending the message to the server application, and finally accepting the transaction.

// // 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

The following example illustrates creation of an object in a server application that is to act as an RTR server. First it creates a key segment for a specific range of ASCII values (A to L) and creates a data object to hold each incoming message or event. Then it loops continuously, receiving messages and dispatching them to the handlers.

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); }

Sample system management code

The following examples illustrates creation of objects in an application to perform system management tasks for RTR.

Example 4-5 Creating a Facility with the C++ API

// Use the C++ interface to create an RTR facility RTRFacilityManager::CreateFacilityWithAllRoles_3() { bool bOverallResult = true; //Create facility manager, abort if creation fails RTRFacilityManager * pFacilityManager; pFacilityManager = new RTRFacilityManager; if ( IsFailure(pFacilityManager != NULL) ) { return false; } // Create the facility rtr_status_t stsCreateFacility; stsCreateFacility = pFacilityManager->CreateFaclity("FaclityWithAllRoles_3", GetDefaultRouterName(), GetDefaultFrontendName(), GetDefaultBackendName(), true, false); //If facility creation is not successful, report it if ( IsFailure( stsCreateFaciltiy == RTR_STS_OK ) ) { bOverallResult = false; OutputStatus( stsCreateFacility); } else // Delete a successfully created facility { rtr_status_t stsDeleteFacility; stsDeleteFacility = pFacilityManager->DeleteFacility("FacilityWithAllRoles_3"); if ( IsFailure( stsDeleteFacility == RTR_STS_OK ) ) { bOverallResult = false; OutputStatus) stsDeleteFacility); } } // Clean up and return delete pFacilityManager; return bOverallResult; }

Sample C++ system management code

The following examples perform specific RTR system management tasks. They can be used individually or together.

• The first starts RTR.
• The second creates a facility.
• The third creates a partition in the previously created facility.

Example 4-6 Starting RTR with the C++ API

//Start RTR. RTR rtr; rtr.Start();

Example 4-7 Creating a Facility with the C++ API

//Create facility named "myFacility". RTRFacilityManager FacMgr; rtr_status_t sts = FacMgr.CreateFacility("myFacility", "router", "frontend", "backend", false, false) ;

Example 4-8 Creating a Partition with the C++ API

//Create a partition named "myPartition" in facility "myFacility." int low = 100; int max = 199; RTRKeySegment Key100To199( rtr_keyseg_unsigned, sizeof(int), 0, &low, &max ); RTRPartitionManager PartitionMgr; sts = PartitionMgr.CreateBackendPartition( "myPartition", "myFacility", Key100To199, false, false) ;

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, refer to the Reliable Transaction Router C Application Programmer's Reference Manual and the Reliable Transaction Router Application Design Guide.

Snippets from client and server programs using the RTR C-programing API follow and are more fully shown in the Reliable Transaction Router 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. For a more complete discussion of application designs, refer to the Reliable Transaction Router Application Design Guide.

The RTR environment has two parts:

• System management environment
• Runtime environment

You manage your RTR environment from a management station, which can be on a node running RTR or on some other node. You can manage your RTR environment either from your management station running a network browser using the RTR Manager or from the command line using the RTR CLI. From a managment station using a network browser, processes use http, the hyper text transfer protocol, for communication.

The RTR system management environment contains four processes:

• RTR Control Process, RTRACP
• RTR Command Line Interface, RTR CLI
• RTR Command Server Process, RTRCOMSERV
• RTR daemon, RTRD

The RTR Control Process, RTRACP, is the master program. It resides on every node where RTR has been installed and is running. RTRACP performs the following functions:

• Manages network links
• Sends messages between nodes
• Handles all transactions and recovery

RTRACP handles interprocess communication traffic, network traffic, and is the main repository of runtime information. ACP processes operate across all RTR roles and execute certain commands both locally and at remote nodes. These commands include:

• FACILITY
• SET LINK/NODE
• SET/CREATE PARTITION
• SHOW NODE
• STOP RTR

RTR CLI is the Command Line Interface that:

• Accepts commands entered locally by the system manager
• Sends commands to the Command Server Process RTRCOMSERV
• Can initiate commands on one node and execute them on another in most cases

Commands executed directly by the CLI include:

• DISPLAY
• DO (to the local operating system)
• MONITOR commands
• RECALL
• SET ENVIRONMENT
• SPAWN
• HELP

RTR COMSERV is the Command Server Process that:

• Receives commands from RTR
• Remains temporarily waiting for another command
• Exits automatically when idle for some time

The Command Server Process executes commands both locally and across nodes. Commands that can be executed at the RTR COMSERV include:

• START RTR
• CREATE/MODIFY JOURNAL
• SHOW LINK/FACILITY/SERVER/CLIENT (ACP must be running)
• Application programmer commands (for testing and demonstration)

Figure 5-1 illustrates the RTR system management environment. While the figure shows the RTR Management Station on a node declared as a frontend (FE), you can manage RTR from any node where RTR is running, whether the node is declared as a frontend, router, or backend. The RTR COMSERV must be running to manage RTR. The RTR Management Station runs web browser software with which you manage RTR.

For further details on the RTR entities such as RTRACP and the RTR COMSERV, see RTR Runtime Environment in a later section of this manual.

Figure 5-1 RTR System Management Environment

RTR Monitor pictures or the RTR Monitor let you view the detailed status and activities of RTR and your applications. A monitor picture is dynamic, its data periodically updated. RTR SHOW commands that also let you view status are snapshots, giving you a view at one moment in time. A full list of RTR Monitor pictures is available in the Reliable Transaction Router System Manager's Manual "RTR Monitoring" chapter and in the help file under RTR_Monitoring. RTR Monitor pictures are available using the RTR browser interface.

Transaction Management

The RTR transaction is the heart of an RTR application, and transaction state characterizes the current condition of a transaction. As a transaction passes from one state to another, it undergoes a state transition. Transaction states are maintained in memory, and some states are stored in the RTR journal for use in recovery.

RTR uses three transaction states to track transaction status:

• Transaction runtime state
• Transaction journal state
• Transaction server state

Transaction runtime state describes how a transaction progresses from the point of view of RTR roles (FE, TR, BE). A transaction, for example, can be in one state as seen from the frontend, and in another as seen from the router.

Transaction journal state describes how a transaction progresses from the point of view of the RTR journal. The transaction journal state, not seen by frontends and routers, managed by the backend, is used by RTR for recovery replay of a transaction after a failure.

Transaction server state, also managed by the backend, describes how a transaction progresses from the point of view of the server. RTR uses this state to determine if a server is available to process a new transaction, or if a server has voted on a particular transaction.

The RTR SHOW TRANSACTION command shows transaction status, and the RTR SET TRANSACTION command can be used, under certain well-constrained circumstances, to change the state of a live transaction. For more details on use of SHOW and SET commands, refer to the Reliable Transaction Router System Manager's Manual.

Partition Management

As illustrated in Figure 1-18, you can use key ranges in your application with RTR data-content routing to route transactions to specific database partitions. Partitions exist for each range of values in the routing key for which a server is available to process transactions. Redundant instances of partitions can be started in a distributed network, to which RTR automatically manages the state and flow of transactions. Partitions and their characterisitcs can be defined by the system manager or operator independently of the application, as well as within application programs.

RTR management functions enable the system manager or C++ application operation to manage many partition-based attributes and functions including:

• Creation/deletion of a partition with a user-specified name
• Defining/changing a key-range definition
• Selecting a preferred primary node
• Selecting failover precedence between local and cross-site shadows
• Suspending/resuming operations to synchronize database backup with transaction flow
• Overriding the automatic recovery procedures of RTR with manual recovery procedures, for added flexibility
• Specifying retry limits for problem transactions

The operator can selectively inspect transactions, modify states, or remove transactions from the journal or the running RTR system. This allows for greater operational control and enhanced management of a system where RTR is running.

For more details on managing partitions and their use in applications, refer to the chapter on "Partition Management" in the Reliable Transaction Router System Manager's Manual.

When all RTR and application components are running, the RTR runtime environment contains:

• Client application
• Server application
• RTR shareable image, LIBRTR
• RTR control process, RTRACP
• RTR daemon, RTRD
• RTR command line interface, RTR CLI
• RTR command server, RTR COMSERV

Figure 5-2 shows these components and their placement on frontend, router, and backend nodes. The frontend, router, and backend can be on the same or different nodes. If these are all on the same node, there is only one RTRACP process.

Figure 5-2 RTR Runtime Environment

This concludes the material on RTR concepts and capabilities that all users and implementors should know. For more information, proceed as follows:

If you are:	Read these documents in this order:
a system manager, system administrator, or software installer	1. RTR Release Notes 2. RTR Installation Guide 3. RTR Migration Guide (if upgrading from RTR V2 to V3/V4) 4. RTR System Manager's Manual

If you are:	Read these documents:
an applications or system management developer, programmer, or software engineer	1. RTR Application Design Guide RTR C++ Foundation Classes or RTR C Application Programmer's Reference Manual