Reliable Transaction Router (RTR) is failure-tolerant transactional messaging middleware used to implement large, distributed applications with client/server technologies. RTR helps ensure business continuity across multivendor systems and helps maximize uptime.

Failure and fault tolerance

Failure tolerance is supplied by the RTR software that enables an application to continue even when failures such as node or site outages occur. Failover is automatic. Fault tolerance is supplied by systems with hardware that is built with redundant components to ensure that processing survives failure of an individual component. Depending on system requirements and hardware, an RTR configuration can be both failure and fault tolerant.

Interoperability

You use the architecture of RTR to ensure high availability and transaction completion. RTR supports applications that run on different hardware and different operating systems. RTR applications can be designed to work with several database products including Oracle, Microsoft Access, Microsoft SQL Server, Sybase, and Informix. For specifics on operating systems, operating system versions, and supported hardware, refer to the VSI Reliable Transaction Router Software Product Description for each supported operating system.

Networking

RTR can be deployed in a local or wide area network and can use either TCP/IP or DECnet for its underlying network transport.

Transaction processing

A transaction involves the exchange of something for something else, for example, the exchange of cash for something purchased such as a book or restaurant meal. Transactions are the fodder of the commercial world in which we live. Transaction processing is the use of computers to do the bookkeeping for the physical transactions in which people engage. RTR is the premier transaction processing software available for many computer systems, offering unique benefits to ensure the integrity and correctness of transactions under its control.

Corporations and institutions benefit when the data they need is current and kept rapidly up-to-date. This ensures that they have increased control of their business or institution, and can react more effectively to changes in the business or institutional environment.

For example, an inventory management system provides current inventory for inquiry and can automatically request inventory updates when needed. Or an production manager can make production decisions based on current status of manufacturing elements directly from the shop floor, and a credit card company can respond with accurate information when a card request for validation arrives. Or a shipping company can determine and report the location of a package in transit anywhere in the world, or a personnel system can enable an employee to update personal information online. All of these systems perform transaction processing tasks as designed by their developers.

With RTR, applications can be written to be deployed over a wide geography to take advantage of distributed resources, both computers and personnel. Implementing a transaction processing system using RTR requires analysis, planning, and considered execution.

For more details on transactional ACID properties, see the discussion later in this document, and in the VSI Reliable Transaction Router Application Design Guide.

RTR Application

An RTR application is user-written software that executes within the confines of several distributed processes. The RTR application may perform user interface, business, and server logic tasks and is written in response to some business need. An RTR application can be written in one of the supported languages, C, C++, or Java and includes calls to RTR. RTR applications are composed of two kinds of actors, client applications and server applications. An application process is shown in diagrams as an oval, open for a client application (see Figure 1.1, “Client Symbol”), filled for a server application (see Figure 1.2, “Server Symbol”).

Client

A client is always a client application, one that initiates and demarcates a piece of work. In the context of RTR, a client must run on a node defined to have the frontend role. Clients typically deal with presentation services, handling forms input, screens, and so on. A client could connect to a browser running a browser applet or be a webserver acting as a gateway. In other contexts, a client can be a physical system, but in RTR and in this document, physical clients are called frontends or nodes. You can have more than one instance of a client on a node.

Server

A server is always a server application, one that reacts to a client's units of work and carries them through to completion. This may involve updating persistent storage such as a database file, toggling a switch on a device, or performing another predefined task. In the context of RTR, a server must run on a node defined to have the backend role. In other contexts, a server can be a physical system, but in RTR and in this document, physical servers are called backends or nodes. You can have more than one instance of a server on a node. Servers can have partition states such as primary, standby, or shadow.

Channel

RTR expects client and server applications to identify themselves before they request RTR services. During the identification process, RTR provides a tag or handle that is used for subsequent interactions. This tag or handle is called an RTR channel. A channel is used by client and server applications to exchange units of work with the help of RTR. An application process can have one or more client or server channels. Channel management is handled transparently by the C++ and Java APIs.

RTR configuration

An RTR configuration consists of nodes that run RTR client and server applications. An RTR configuration can run on several operating systems including OpenVMS, Tru64 UNIX, and Windows NT among others (for the full set of supported operating systems, see the title page of this document, and the appropriate SPD). Nodes are connected by network links.

Roles

A node that runs client applications is called a frontend (FE), or is said to have the frontend role. A node that runs server applications is called a backend (BE). Additionally, the transaction router (TR) contains no application software but acts as a traffic cop between frontends and backends, routing transactions to the appropriate destinations. The router controls the distributed RTR nodes, and takes care of two-phase commit,failover and failback.

The router also eliminates any need for frontends and backends to know about each other in advance. This relieves the application programmer from the need to be concerned about network configuration details. The router can reside on a node running as a frontend or a backend but is often run on a node where neither backends nor frontends are running. Figure 1.3, “Roles Symbols” shows the symbol for each of the RTR roles.

Facility

The mapping between nodes and roles is done using a facility. An RTR facility is the user-defined name for a particular configuration whose definition provides the role-to-node map for a given application. The facility symbol (see Figure 1.4, “Facility Symbol”) illustrates its use in the RTR environment. Nodes can share several facilities. The role of a node is defined within the scope of a particular facility. Normally a facility is defined across all roles but facility definition depends on application design

The router is the only role that knows about all three roles. A router can run on the same physical node as the frontend or backend, if that is required by configuration constraints,but such a setup would not take full advantage of failover characteristics.

A facility name is mapped to specific physical nodes and their roles using the CREATE FACILITY command.

Figure 1.5, “Components in the RTR Environment” shows the logical relationship between client application, server application, frontends (FEs), routers (TRs), and backends (BEs) in the RTR environment. The database is represented by the cylinder. Two facilities are shown (indicated by the large double-headed arrows), the User Accounts Facility and the General Ledger Facility. The User Accounts Facility uses three nodes, FE, TR,and BE, while the General Ledger Facility uses only two, TR and BE in the configuration shown. Its FEs are on nodes not shown in the figure, at another location

Clients send messages to servers to ask that a piece of work be done. Such requests may be bundled together into transactions. An RTR transaction consists of one or more messages that have been grouped together by a client application, so that the work done as a result of each message can be undone completely, if some part of that work cannot be done. If the system fails or is disconnected before all parts of the transaction are done, then the transaction remains incomplete.

Transaction

A transaction is a piece of work or group of operations that must be executed together to perform a consistent transformation of data. This group of operations can be distributed across many nodes serving multiple databases. Applications use services that RTR provides.

Because typically a transaction consists of several operations, a system or network failure at any step in the process will cause the transaction to be in doubt. RTR ensures that all transactions have the ACID properties so that all transactions are in a known state. (See the description of ‘‘Transactional messaging’’ for further clarification of transaction integrity.)

Transaction controller

With the C++ API, the Transaction Controller manages transactions (one at a time), channels, messages, and events.

Transactional messaging

RTR provides transactional messaging in which transactions are enclosed in messages controlled by RTR.

Transactional messaging ensures that each transaction is complete, and not partially recorded. For example, a transaction or business exchange in a bank account might be to move money from a checking account to a savings account. The complete transaction is to remove the money from the checking account and add it to the savings account.

A transaction that transfers funds from one account to another consists of two individual updates: one to debit the first account, and one to credit the second account. The transaction is not complete until both actions are done. If a system performing this work goes down after the money has been debited from the checking account but before it has been credited to the savings account, the transaction is incomplete. With transactional messaging, RTR ensures that a transaction is “all or nothing” – either fully completed or discarded; either both the checking account debit and the savings account credit are done, or the checking account debit is backed out and not recorded in the database. RTR transactions have the ACID properties.

Nontransactional messaging

An application will also contain nontransactional tasks such as writing diagnostic trace messages or sending a broadcast message about a change in a stock price after a transaction has been completed.

Transaction ID

Every transaction is identified on initiation with a transaction identifier or transaction ID, with which it can be logged and tracked. RTR guarantees that TIDs are unique.

To reinforce the use of these terms in the RTR context, this section briefly reviews other uses of configuration terminology.

Tiers

A traditional two-tier client/server environment is based on hardware that separates application presentation and business logic (the clients) from database server activities. The client hardware runs presentation and business logic software, and server hardware runs database or data manager (DM) software,also called resource managers (RM). This type of configuration is illustrated in Figure 1.6, “Two-Tier Client/Server Environment”. (In all diagrams, all lines are actually bidirectional, even when represented otherwise for clarity. Fora given transaction, the initial action is typically from left to right.) In Figure 1.6, “Two-Tier Client/Server Environment”, Application Presentation and Business Logic are the first tier, and the Database Server is the second tier.

Further separation into three tiers is achieved by separating presentation software from business logic on two systems,and retaining a third physical system for interaction with the database. This is illustrated in Figure 1.7, “Three-Tier Client/Server Environment”, where Presentation and User Interface are the first tier, the Application Server and Business Logic are the second tier, and the Database Server is the third tier.

RTR extends the three-tier model, which is based on hardware, to a multilayer, or multicomponent software model.

RTR SoftwareComponents

RTR provides a multicomponent software model where clients running on frontends, routers, and servers running on backends cooperate to provide reliable service and transactional integrity. Application users interact with the client (presentation layer) on the frontend node that forwards messages to the current router. The router in turn routes the messages to the current, appropriate backend, where server applications reside, for processing. The connection to the current router is maintained until the current router fails or connections to it are lost.

All RTR software components can reside on a single node but are typically deployed on different nodes to achieve modularity,scalability, and redundancy for availability. During initial application development, it can be convenient to use a single physical node for all RTR roles and application software.

With different physical systems, if one node goes down or offline, another router or backend node can take over application processing. In a slightly different configuration, you could have an application that uses an external applet component running on a browser that connects to a client running on the RTR frontend. Such a configuration is shown in Figure 1.8, “Browser Applet Configuration”. In the figure, the applet is separate from but connects to the client application written to work directly with RTR.

The RTR client application could be an ASP (Active Server Page) script or a process interfacing to the webserver through a standard interface such as CGI (Common Gateway Interface) script.

RTR provides automatic software failure tolerance and failure recovery in multinode environments by sustaining transaction integrity in spite of hardware, communications, application, or site failures. Automatic failover and recovery of service can exploit redundant or underutilized hardware and network links.

For example, you could use an underutilized system as a standby server in certain configurations.

As you modularize your application and distribute its components on frontends and backends, you can add new nodes, identify usage bottlenecks, and provide redundancy to increase availability. Adding backend nodes can help divide the transactional load and distribute it more evenly. For example, you could have a single node configuration as shown in Figure 1.9: RTR with Browser, Single Node, and Database. A single node configuration can be useful during development, but would not normally be used when your application is deployed.

When applications are deployed, often the frontend is separated from the backend and router, as shown in Figure 1.10, “RTR Deployed on Two Nodes”.

In this example, the frontend with the client application resides on one node, and the router with the server application reside a node that has both the router and backend roles. This is a typical configuration where routers are placed on backends rather than on frontends. A further separation of workload onto three nodes is shown in Figure 1.11, “RTR Deployed on Three Nodes”. However, in this configuration, there remain several single points of failure where one node/role or a network outage can disrupt processing of transactions.

While this three-node configuration separates transaction load onto three nodes, it does not provide for continuing work if one of the nodes fails or becomes disconnected from the others. In many applications, there is a need to ensure that there is a server always available to access the database.

Standby server

In this case, a standby server will do the job. A standby server(see Figure 1.12, “Standby Server Configuration”) is a process or application that can take over when the primary server is not available, due to hardware failure, application software failure or network outage.

Both the primary and the standby server have the capability to access the same database, but the primary processes all transactions unless it is unavailable. On the other hand, the standby processes transactions only when the primary becomes unavailable. When not being used to process transactions, the standby CPU can do other work.

The standby server is usually placed on a node other than the node where the primary server runs, and should be, to avoid being a single point of failure. Network capability, clustering or disk-sharing technology, and appropriate software must be available on both primary and standby backend systems when running RTR.

Shadow Server and Transactional Shadowing

To increase transaction processing availability, transactions can be shadowed with a shadow server, as shown in Figure 1.13, “Transactional Shadowing Configuration”.The system where the shadow server runs can be made available with clustering technology. A shadow server eliminates the single point of failure that is evident in Figure 1.12, “Standby Server Configuration”. In a shadow configuration, the second database of Figure 1.13, “Transactional Shadowing Configuration” is available even when the first is not.

Use of a shadow server is called transactional shadowing and is accomplished by having a second location, often at a different site, where transactions are also recorded. Data are recorded in two separate data stores or databases. The router knows about both backends and sends all transactions to both backends. RTR provides the server application with the necessary information to keep the two databases synchronized.

RTR Journal

In the RTR environment, one data store (database or data file) is elected the primary, and a second data store is made the shadow. The shadow data store is a copy of the data store kept on the primary. If either data store becomes unavailable, all transactions continue to be processed and stored on the surviving data store. At the same time, RTR makes a record of (remembers) all transactions stored only on the shadow data store in the RTR journal by the shadow server.

When creating the configuration used by an application and defining the nodes where a facility has its frontends, routers,and backends, the setup must also define which nodes will have journal files. Each backend in an RTR configuration must have a journal file to capture transactions when other nodes are unavailable. When the primary server and data store become available again, RTR replays the transactions in the journal to the primary data store through the primary server. This brings the data store back into synchronization.

For full redundancy to assure maximum availability, a configuration could employ disk shadowing in clusters at separate sites coupled with transactional shadowing across sites. Disk shadowing used in specific cluster environments copies data to another disk to ensure data availability. Transactional shadowing copies only transactional data.

Additionally, an RTR configuration typically deploys multiple frontends running client applications with connections to several routers to ensure continuing operation if a particular router fails.

These are described in the next few paragraphs. You specify server types to your application in RTR API calls.

RTR server types help to provide continuous availability and a secure transactional environment.

Standby server

The standby server remains idle while the RTR primary backend server performs its work, accepting transactions and updating the database. When the primary server fails, the standby server takes over, recovers any in-progress transactions, updates the database, and communicates with clients until the primary server returns. There can be many instances of a standby server. Activation of the standby server is transparent to the user.

A typical standby configuration is shown in Figure 1.12: Standby Server Configuration. Both physical servers running the RTR backend software are assumed by RTR to connect to the same database. The primary server is typically in use, and the standby server can be either idle or used for other applications, or data partitions, or facilities. When the primary server becomes unavailable, the standby server takes over and completes transactions as shown by the dashed line. Primary server failure could be caused by server process failure or backend (node) failure.

Standby in a cluster

The intended and most common use of a standby server is in a recognized cluster environment. In a noncluster or unrecognized cluster environment, seamless failover of standbys is not guaranteed. For RTR, clusters supported by OpenVMS and Tru64 UNIX are recognized clusters, whose processing is controlled by a lock manager. Windows and Sun clusters can use disk-sharing, unrecognized cluster technology.

Standby servers are “spare” servers which automatically take over from the main backend if it fails. This takeover is transparent to the application.

Figure 1.14, “Standby Servers” shows a simple standby configuration. The two backend nodes are members of a cluster environment, and are both able to access the database.

For any one key range, the main or primary server (Server application) runs on one node while the standby server (Standby application) runs on the other node. The standby server process is running, but RTR does not pass any transactions to it. Should the primary node fail, RTR starts passing transactions to the Standby application.

Note that one node can contain the primary servers for one key range and standby servers for another key range to balance the load across systems. This allows the nodes in a cluster environment to act as standby for other nodes without having idle hardware. When setting up a standby server, both servers must have access to the same journal.

Transactional shadow server

The transactional shadow server places all transactions recorded on the primary server on a second database. The transactional shadow server can be at the same site or at a different site, with networking capability available.

When one member of a shadow set fails, RTR remembers the transactions executed at the surviving site in a journal,and replays them when the failed site returns. Only after all journaled transactions are recovered does the recovering site fully process new online transactions. During recovery, new transactions are processed at the surviving site and added to the journal for the recovering site.

Transactional shadowing is done by partition. A transactional shadow configuration can have only two members of the shadowset.

Shadow servers are servers on separate backends that handle the same transactions in parallel on identical copies of the database.

Figure 1.15, “Shadow Servers” shows a simple shadow configuration. The main backend server application at Site 1 and the shadow server(Shadow application) at Site 2 both receive every transaction for the data partition they are servicing. Should Site 1 fail,Site 2 continues to operate without interruption. Sites can be geographically remote, for example, available at separate locations in a wide area network (WAN).

Concurrent server

The concurrent server is an additional instance of a server application running on the same node. RTR delivers transactions to a free server from the pool of concurrent servers. If one server fails, the transaction in process is replayed to another server in the concurrent pool. Concurrent servers are designed primarily to increase throughput and can exploit Symmetric Multiprocessing (SMP) systems. Figure 1.16: Concurrent Servers, illustrates the use of concurrent servers sending transactions to the same partition on a backend, the partition A-N.

Concurrent servers allow transactions to be processed in parallel to increase throughput. Concurrent servers deal with the same database partition, and may be implemented as multiple channels within a single process or as one channel in separate processes. The application designer must determine if transactions can be processed concurrently by the database or server application. Deadlocks can occur if every transaction competes for the same database lock outside the RTR server application.

Callout server

The callout server enables message authentication on transaction requests made in a given facility, and could be used, for example, to provide audit trail logging. A callout server can run on either backend or router nodes. A callout server receives a copy of all messages in a facility. Because the callout server votes on the outcome of each transaction it receives, it can veto any transaction that does not pass its security checks.

A callout server is facility based, not partition based; any message arriving at the facility is routed to both the server and the callout. A callout server is enabled when the facility is defined. Figure 1.17, “A Callout Server” illustrates the use of a callout server that authenticates every transaction in a facility.

To authenticate any part of a transaction, the callout server must vote on the transaction, but does not write to the database. RTR does not replay a transaction that is only authenticated.

Authentication

RTR callout servers provide partition-independent processing for authentication. For example, a callout server can enable checks to be carried out on all requests in a given facility.

Callout servers run on backend or router nodes. They receive a copy of every transaction either delivered to or passing through the node.

Since this technique relies on backing out unauthorized transactions, it is most suitable when only a small proportion of transactions are expected to fail the security check, so as not to have a performance impact.

Partition

When working with database systems, partitioning the database can be essential to ensuring smooth and untrammeled performance with a minimum of bottlenecks. When you partition your database, you locate different parts of your database on different disk drives to spread both the physical storage of your database onto different physical media and to balance access traffic across different disk controllers and drives.

For example, in a banking environment, you could partition your database by account number, as shown in Figure 1.18, “Bank Partitioning Example”. A partition is a segment of your database.

Key range

Once you have decided to partition your database, you use key ranges in your application to specify how to route transactions to the appropriate database partition. A key range is the range of data held in each partition. For example, the key range for the first partition in the bank partitioning example goes from 00001 to 19999.

You can assign a partition name in your application program or have it set by the system manager. Note that sometimes the terms key range and partition are used as synonyms in code examples and samples with RTR, but strictly speaking, the key range defines the partition. A partition has both a name, its partition name, and an identifier generated by RTR — the partition ID. The properties of a partition (callout, standby, shadow, concurrent, key segment range) can be defined by the system manager with a CREATE PARTITION command. For details of the command syntax, see the VSI Reliable Transaction Router System Manager’s Manual.

A significant advantage of the partitioning shown in the bank example is that you can add more account numbers without making changes to your application; you need only add another server and disk drive for the new account numbers. For example, say you need to add account numbers from 90,000 to 99,999 to the basic configuration of Figure 1.18: Bank Partitioning Example. You can add these accounts and bring them on line easily. The system manager can change the key range with a command, for example, in an overnight operation, or you can plan to do this during scheduled maintenance.

A partition can also have multiple standby servers.

Standby Server Configurations

A node can be configured as a primary server for one key range and as a standby server for another key range. This helps to distribute the work of the standby servers. Figure 1.19, “Standby with Partitioning” illustrates this use of standbys with distributed partitioning. As shown in Figure 1.19, “Standby with Partitioning”, Application Server A is the primary server for accounts 1 to 19,999 and Application Server B is the standby for these same accounts. Application Server B is the primary for accounts 20,000 to 39,999 and Application Server A can be the standby for these same accounts (not shown in the figure). For clarity, account numbers are shown only for primary servers and one standby server.

Anonymous clients

RTR supports anonymous clients, that is, clients can be set up in a configuration using wildcarded node names.

Tunnel

RTR can also be used with firewall tunneling software, which supports secure internet communication for an RTR connection, either client-to-router, or router-to-backend.

Depending on operating system, RTR uses TCP/IP or DECnet as underlying transports for the virtual network (RTR facilities) and can be deployed in both local area and wide area networks. PATHWORKS 32 is required for DECnet configurations on Windows NT.

RTR is based on a three-tier physical architecture consisting of frontend (FE) roles, backend (BE) roles and router (TR) roles. The roles are shown in Figure 2.1, “The Multitier Model”. (In this and subsequent diagrams, rectangles represent physical nodes, ovals represent application software, and cylinders represent the disks storing the database. The nodes connected to the actual database usually run the database software that controls the database.)

In addition to the physical configuration where RTR is deployed, software plays a critical part, extending the tier concept to more than three tiers. On certain pieces of hardware, client application software runs, and on others, server application software runs. Users can connect to nodes that are running the frontend role with appropriate non-RTR software. For example, a user can have a PC where RTR runs; in this case, the PC has the frontend role. Or a user could use a PC running, say Pathworks, to connect to another node that has the frontend role and run the RTR client application from there. This would be a multitier configuration.

Client application processes run on nodes defined to have the frontend role. This tier allows computing power to be provided locally at the end-user site for transaction acquisition and presentation.

The router tier contains no application software unless running callout servers. This tier reduces the number of logical network links required on frontend and backend nodes and helps ensure good performance even in an unstable network. It also decouples the backend tier from the frontend tier so that configuration changes in the (frequently changing) user environment have little influence on the transaction processing and database (backend) environment.

The three-tier model can be mapped to any system topology. More than one role may be assigned to any particular node. For example, on a system with few frontends, the router and backend tiers can be combined in the same nodes. During application development and test, all three roles can be combined in one node.

The nodes used by an application and their configuration roles are specified using RTR configuration commands. RTR lets application code be completely location and configuration independent.

Many applications can use RTR at the same time without interfering with one another. This is achieved by defining a separate facility for each application. A facility can be thought of as an application network.

When an application calls the rtr_open_channel() routine to declare a channel as a client or server, it specifies the name of the facility it will use.

Refer to the VSI Reliable Transaction Router System Manager’s Manual for information on how to define facilities.

Sometimes an application has a requirement to send unsolicited messages to multiple recipients.

An example of such an application is a commodity trading system, where the clients submit orders and also need to be informed of the latest price changes.

The RTR broadcast capability meets this requirement.

Recipients subscribe to a class of broadcasts; a sender broadcasts a message in this class, all interested recipients receive the message. However, broadcast reception is not guaranteed; network or node outages can cause a particular client to fail to receive a broadcast message.

RTR permits clients to broadcast messages to one or more servers, or servers to broadcast to one or more clients. If a server needs to broadcast a message to another server, it must open a second channel as a client.

This means you do not need to provide spare capacity to allow for growth.

RTR also allows parallel execution. This means that different parts of a single transaction can be processed in parallel by multiple servers.

RTR provides a comprehensive set of monitoring tools to help you evaluate the volume of traffic passing through the system. This can help you respond to unexpected load changes by altering the system configuration dynamically.

RTR greatly simplifies the design and coding of distributed applications, because, with RTR, database actions can be bundled together into transactions.

An atomic transaction is all or nothing; that is, either the entire transaction is totally committed or totally rolled back. A consistent transaction either creates a new, valid state of data,or, from any failure, returns all data to its state as it was before the start of the transaction. An isolated transaction does not cause changes to shared resources until commitment of the transaction. A durable transaction survives system and media failures after transaction commitment. A durable transaction is thus both persistent and stable.

For more detail on these properties and their use in transaction processing, refer to the VSI Reliable Transaction Router Application Design Guide.

One goal in designing for high transaction throughput is reducing the time that users must wait for shared resources.

This competition can be alleviated by spreading the database across several backend nodes, each node being responsible for a subset of the data, or partition. RTR enables you to implement this partitioned data model, shown roughly in Figure 2.2, “Partitioned Data Model” where the database has three partitions. RTR routes messages to the correct partition on the basis of an application-defined key. For a more complete description of partitioning as provided with RTR, refer to the VSI Reliable Transaction Router Application Design Guide.

Each RTR API provides the capability to use partitions. For specific information on declaring and using partitions, refer to the RTR documentation for the system manager and the applications programmer.

Java objects and the RTR the C++ foundation classes map traditional RTR functional programming concepts into an object-oriented programming model. Using the power and features of these foundation classes requires a basic understanding of the differences between functional and object-oriented programming concepts. Table 2.1, “Functional and Object-Oriented Programming Compared” compares the worlds of functional programming and object-oriented programming.

Dog.h:
class Dog
{ ...
};
main.cpp:
#include "Dog.h"
main()
{
   Dog King;
   Dog Fifi;
}

RTR clients and servers can be Java applications that obtain the benefits of high availability, fault tolerance and scalability provided by RTR. RTR clients and servers employing Java technology use standard Java and J2EE interfaces for transaction management, data input/output, and database access.

For additional information, see the VSI Reliable Transaction Router Getting Started manual and associated online documentation.

Within its C API, RTR provides the capability of using the XA interface to work with XA-compliant database systems. 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 used by TM-to-RM exchanges to coordinate a transaction from within an application program.

If your database application supports XA, you have less to implement in your application environment; use of XA can also increase the portability of your application.

For details on using XA with RTR, refer to the VSI Reliable Transaction Router C Application Programmer’s Reference Manual and the VSI Reliable Transaction Router Application Design Guide.

Reliability in RTR is enhanced by the use of:

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

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

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

This section describes how RTR recovers from different hardware and software failure. For additional information on failure and recovery scenarios, refer to the VSI Reliable Transaction Router Application Design Guide.

The RTR Administrator lets you manage RTR, its facilities, nodes, and network links, with a point-and-click interface. It contains extensive help, both as inline popups, as linked help, and as links to current information. For example, inline popups describe short headings more fully, and the system manager can view many types of status as RTR and the applications under its control run.

Figure 4.1, “RTR Administrator” shows the RTR Adminstrator screen where you select whether to use the RTR Manager or the RTR Explorer.

The RTR CLI contains all RTR system manager commands and calls to all RTR C API routines such as rtr_open_channel or rtr_create_facility. You can use either the RTR Manager or the RTR CLI to manage your RTR configuration. You can also use the command line interface to write short RTR C applications for testing and experimentation. The CLI is described in the VSI Reliable Transaction Router System Manager’s Manual. Its use is illustrated in this chapter.

Figure 4.2, “RTR Command Line Interface” shows the RTR command line interface.

RTR provides several programming or application development interfaces for design and implementation of transaction processing programs. They include the following:

The RTR application programming interfaces, where available, are identical on all hardware and operating system platforms that support RTR. The object-oriented C++ API is fully described in the VSI Reliable Transaction Router C++ Foundation Classes manual. The C-programming API is fully described in the VSI Reliable Transaction Router C Application Programmer’s Reference Manual. Both APIs are used in examples in the VSI Reliable Transaction Router Application Design Guide. The Java J2EE interface is described in the JTA material in the RTR JRTR kit. The XA interface is described in materials from X/Open.

The transaction processing environment poses special challenges for the development of applications, challenges best addressed by following a defined methodology such as the software development life cycle or object-oriented design fleshed out with use cases.

The software development life cycle consists of the following phases that are to be viewed as iterative:

Many books are available to assist the developer with both design and development, including:

Object-oriented methods and practice are described and elaborated on in many books, including:

Table 4.1, “RTR Interfaces and their Use” summarizes the RTR interfaces and their typical use.

You can manage RTR from several locations:

4.4.2. RTR Manager

Figure 4.3, “RTR Manager” shows the first RTR Manager screen through which you manage RTR and RTR applications. Not all RTR CLI commands are accessible from the RTR Manager RTR Command link; those rarely used are available only through the RTR CLI command window. The RTR Manager provides help for input screens, logging windows, and links between displays.

4.4.3. RTR Explorer

Figure 4.4, “RTR Explorer: View of All Facilities” shows a sample screen of the RTR Explorer with several defined facilities. The RTR Explorer lets the system manager or administrator view the entire RTR configuration by facility and by node, and assess the state of the RTR network and the state of any individual node or facility in the network.

The All Facilities View (Figure 4.4, “RTR Explorer: View of All Facilities”) shows all facilities by name, with icons showing status of normal or one of three levels of alert (warning, error, or fatal). Additional views either by facility or node enable the manager to drill down, with a simple point-and-click, to the facility or node of interest.

Information available for each facility includes the facility name, the alerts associated with nodes participating in the facility, and the state of the facility. Information for each node includes its name, role, cluster name, partition names, partition states, node state, and alerts.

Additional views either by facility or by node enable the administrator to zoom, with a simple point-and-click, to the facility or node of interest. From the node view, the administrator can open the RTR Manager for the node. Hence, RTR Explorer enables the administrator to both view and manage the state of every facility and node.

Nodes can monitor themselves for alerts. Each alert can be set at progressive levels of severity – first Warning, second Error, and third Fatal. The severity of an alert indicates the urgency of the alert. Warning means RTR may or may not be operating normally, but something needs to be looked at. Error means that RTR is likely not operating normally, but may be able to continue operating. Fatal means that RTR cannot continue to operate unless the alert is resolved. See the REMEMBER EXPRESSION command in the VSI Reliable Transaction Router System Manager’s Manual for how to define alerts.

The state of a facility shown by its icon in a view of all facilities (see Figure 4.4, “RTR Explorer: View of All Facilities”) indicates the worst severity for all defined alerts for all nodes in that facility. Similarly, the state of a node or group of nodes shown by its icon in a view of a single facility (see Figure 4.5, “RTR Explorer: View of One Facility”) is the worst severity of all alerts for that node or group of nodes. If there are no flags, the node or group is operating normally.

$ RTR
Copyright 1994, 2003 Hewlett-Packard Development Company, L.P.
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

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.]

$ 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

%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.

4.5.1. RTR Java Object-Oriented Interface

You can use Java and J2EE technology to write applications that use RTR. For additional information on these technologies, see the documentation that is part of the JRTR downloadable kit. This documentation includes the JRTR Getting Started manual and other supplementary materials, including a sample application.

Java Technology

The following Java technology is used by:

RTR Clients	RTR Servers
UserTransaction Interface	InputStreams
	OutputStreams

J2EE Technology

The following J2EE technology is used by RTR servers:

• a database and a JDBC driver that supports the JDBC 2.0 Optional Package javax.sql (required)

• a JNDI service provider (optional)

Figure 4–6 illustrates the required connection that must be defined for a service provider, with the links to the connection pool and the JDBC driver that are set up by the system administrator. The application program needs only to know about the service provider to use the connection.

RTR Java J2EE-based applications need to be able to locate and access database resources external to the application. The J2EE JDBC 2.0 javax.sql package addresses these needs through datasources, connections and connection pooling. For any particular database, the database vendor must provide a JDBC driver which supports the JDBC 2.0 Optional Package (formerly known as the JDBC 2.0 Standard Extension). This package defines datasources and connection pools.

A database resource is represented by a datasource object. For the application to locate the datasource representing the database resource, a naming service that implements the Java Naming and Directory Interface (JNDI) must be present. Registering a datasource with the JNDI service enables the RTR Java J2EE-based application to locate the datasource and connect to its corresponding database. Once the datasource is located and the datasource object is instantiated, the datasource method getConnection( ) is called to obtain a connection object.

Sample Java server code

The sample Java code from a server Java application illustrates Java use of a datasource and a connection pool.

// Get a datasource that has been configured by the administrator
   DataSource ds = (DataSource)LookupFromJNDI("myDataSource");

// Get a connection to the database
   Connection con = ds.getConnection();

Some complex applications require multiple connections to one or more databases. Connection pooling allows applications to offload the high overhead of time and computing resources involved in creating and maintaining multiple connections to one or more databases. This is accomplished by using connectionpool objects. Connection pools (like datasources) are registered with a JNDI service. For more information on JDBC, refer to the Sun Java web site link for the JDBC Standard Extension API.

//
// 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();

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

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

//Start RTR.

RTR rtr;
rtr.Start();

//Create facility named "myFacility".

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

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

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

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

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, or from the command line using the RTR CLI. From a management station using a network browser, processes use the http protocol for communication.

See the commands REMEMBER EXPRESSION and SET NODE /DETECTION_INTERVAL in the VSI Reliable Transaction Router System Manager’s Manual for more details on controlling the behavior of RTR’s problem detection.

Figure 5.1, “RTR System Management Environment”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. It could alternatively be running the RTR CLI.

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

Figure 5.2, “RTR Runtime Environment” 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.