# hp Reliable Transaction Router
Getting Started

Previous | Contents | Index

# Flexibility and Growth

RTR allows you to cope easily with changes in:

- Network demand
- User access patterns
- Volume of data

Because an RTR-based system can be built using multiple systems at each functional tier, it easily lends itself to step-by-step growth, avoiding unused capacity at each stage. With your system still up and running, it is possible to:

- Create and delete concurrent server processes.
- Add or remove nodes (frontend, router or backend).

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. These tools can help you respond to unexpected load changes, making you aware of system degradation that you can sometimes alleviate by altering the system configuration dynamically.

# Transaction Integrity

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

To ensure that your application deals with transactions correctly, its transactions must have the ACID properties, fundamental properties of transaction processing systems. A transaction that has the ACID properties is:

- Atomic
- Consistent
- Isolated
- Durable

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 Reliable Transaction Router Application Design Guide.

# The Partitioned Data Model

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

While many elements of a transaction processing system can be duplicated, one resource that must be shared is the database. Users compete for a shared database in three ways:

- For use of the disk
- For locks on database records
- For the CPU resources needed to access the database

This competition can be alleviated by spreading the database across several backend nodes, where each node is responsible for a subset of the data contained in a partition. RTR enables you to implement this partitioned data model, shown roughly in Figure 2-2 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 Reliable Transaction Router Application Design Guide.

Figure 2-2 Partitioned Data Model

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

# Object-Oriented Programming

The RTR C++ foundation classes map traditional RTR functional programming routines 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 compares the worlds of functional programming and object-oriented programming.

Table 2-1 Functional and Object-Oriented Programming Compared
Functional Programming | Object-Oriented Programming
--- | ---
A program consists of data structures and algorithms. | A program consists of a team of cooperating objects.
The basic programming unit is the function, that when run, implements an algorithm. | The basic programming unit is the class, that when instantiated, implements an object.
Functions operate on elemental data types or data structures. | Objects communicate by sending messages.
An application's architecture consists of a hierarchy of functions and sub-functions. | An applications architecture consists of objects that model entities of the problem domain. Objects' relationships can vary.

## Objects

In the object-oriented environment, a program or application is a grouping of cooperating objects. The basic programming unit is the class. Instantiating, or declaring, an instance of, a class implements an object. RTR provides object-oriented programming capabilities with the C++ API, described in the Reliable Transaction Router C++ Foundation Classes manual. Objects are instances of a class. In a transaction class, each transaction is an object. An object is an instantiated (declared) class. Its state and behavior are determined by the attributes and methods defined in the class. An object or class is defined by its:

- State (attributes)
- Behavior (methods)
- Identity (name at instantiation)

The name given at object declaration is its identity. In Example 2-1, the two dog objects King and Fifi are instances of Dog. The Dog class is declared in a header (Dog.h) file and implemented in a .cpp file.

Example 2-1 Objects-Defined Sample

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

## Messages

Objects communicate by sending messages. This is done by calling an object's methods.

Some principal categories of messages are:

- Constructors: Create objects
- Destructors: Delete objects
- Selectors: Return part or all of an object's state. For example, a Get method
- Modifiers: Change part or all of an object's state. For example, a Set method
- Iterators: Access multiple element objects within a container object. For example, an array.

## Class Relationships

Classes can be related in the following ways:

- Simple association: One class is aware of another class. For example, "Dog object is associated with a Master object." This is a "Knows a" relationship.
- Composition: One class contains another class as part of its attributes. For example, "Dog objects contains Leg objects." This is a "Has a" relationship.
- Inheritance: A child class is derived from one or more parent, or base, classes. For example, "Mutt object derives from Collie object and Boxer object which both derive from Dog object." This is an "Is a" relationship. Inheritance enables the use of polymorphism.

## Polymorphism

Polymorphism is the ability of objects, inherited from a common base or parent class, to respond differently to the same message. This is done by defining different implementations of the same method name within the individual child class definitions. For example: A DogArray object, "DogArray OurDogs[2];" refers to two element objects of class Dog, the base class:

- King, of class Doberman, is a derived or child class of Dog.
- Fifi, of class Minipoodle, is a derived or child class of Dog.

If, in a program, OurDogs[n]->Bark() is called in a loop, then:

- In iteration one ([1]), method King::Bark() is called.
- In iteration two ([2]), method Fifi::Bark() is called.

King's bark does not sound like Fifi's bark because each Bark() call is a separately defined method within its child object definition. The virtual parent class (Dog) method Bark() is defined in the class definition of Dog.

## Object Implementation Benefits

The benefits of creating RTR solutions with objects 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.

# XA Support

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

# Chapter 3
Reliability Features

This chapter addresses:

- RTR server types
- Failover and recovery
- Recovery scenarios

# RTR Server Types

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.
  When transaction throughput is constrained by your server application, consider adding a second instance of your server application with a concurrent server.
- Shadow servers handle the same transactions and run on different nodes.
  When there is concern that your database is a single point of failure, add a shadow server, if possible at a different physical location.
- Standby servers provide a node that can take over processing on a data partition when the primary server or node fails.
  When there is concern that your server application or the node where it is running is a single point of failure in your configuration, configure a standby server to be ready to take over.
- 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.
  Use a callout server to add processing logic (authentication or logging) to your transactions without modifying your server application.

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

# Failover and Recovery

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 that are lost in transit are resent 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.

# Recovery Scenarios

This section describes how RTR recovers from different hardware and software failure. For additional information on failure and recovery scenarios, refer to the Reliable Transaction Router 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 rerouted 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.

# Chapter 4
RTR Interfaces

RTR provides interfaces for system management and for development of transaction processing and management applications.

> Management Interfaces

The management interfaces are:

- The RTR Manager, a web browser interface
- The command line interface or CLI

The RTR web browser interface, called the RTR Manager, 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 shows the RTR web browser interface.

Figure 4-1 RTR Manager Interface

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 Reliable Transaction Router System Manager's Manual. Its use is illustrated in this chapter.

Figure 4-2 shows the RTR command line interface.

Figure 4-2 RTR Command Line Interface

> Programming Interfaces

RTR provides several programming interfaces for development of transaction processing programs. They include the following:

- The object-oriented API for C++ programming
  Available with RTR Version 4.0, you can use this API for new development and, where appropriate, for new work with existing applications. An application can contain both object-oriented classes and Portable API calls. The C++ API can be used to implement both management and transaction processing applications on all platforms supported by RTR.
- The RTR API for C programming
  Available with RTR V3, this interface was formerly called the Portable API because it was the first multiplatform API available with RTR.
- An interface that enables use of an X/Open Distributed Transaction Processing-conformant resource manager
  Available with RTR Version 4.1, this interface, invoked through the RTR management interfaces, enables RTR applications to be used with X/Open-compliant resource managers such as Oracle8.
- The OpenVMS API containing OpenVMS calls, available with RTR V2
  This API, supported on OpenVMS only, is obsolete for new development. To take advantage of new RTR features and capabilities, such applications can be rewritten with one of the newer APIs. Older applications will continue to run with later versions of RTR.

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 Reliable Transaction Router C++ Foundation Classes manual. The C-programming API is fully described in the Reliable Transaction Router C Application Programmer's Reference Manual. Both APIs are used in examples in the Reliable Transaction Router Application Design Guide. The XA interface is described in materials from X/Open.

> Application Development

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:

- Gathering requirements (what is needed?)
- Developing a high-level design (what will the transaction processing application do?)
- Constructing a detailed design (explicitly, what will each part of the application do and what are its intended results?)
- Coding and unit testing
- Integration and system testing/deployment
- Maintenance

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

- J. Gray, A. Reuter, Transaction Processing: Concepts and Techniques, Morgan Kaufmann, San Mateo, CA, 1992
- Philip A. Bernstein, Eric Newcomer, Principles of Transaction Processing, Morgan Kaufmann, San Francisco, CA, 1997

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

- James Rumbaugh, Michael Blaha, William Lorenson, Object-Oriented Modeling and Design, Prentice Hall, Englewood CLiffs, NJ, 1991
- Martin Fowler with Kendall Scott, UML Distilled, Addison-Wesley, Reading, MA 1997

Table 4-1 summarizes the RTR interfaces and their typical use.

Table 4-1 RTR Interfaces and their Use
With this interface: | You can write:
--- | ---
RTR C++ Foundation Classes | application programs system management programs
RTR C programming interface | application programs

# RTR Management Station

You can manage RTR from several locations:

- from a node on which RTR is running
- from a remote node from which you send RTR commands to a node running RTR
- from a web browser that can be on or access a node running RTR

The node where you enter commands, interact with the browser, or view results is your management station.

## RTR Manager

Figure 4-1 shows the first screen of the RTR Manager as you may view it from your management station. Not all RTR CLI commands are accessible from the RTR Manager; those rarely used are available only through the command window. The RTR Manager provides help for input screens, logging windows, and links between displays.

## 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. Figure 4-2 shows the RTR CLI interface. For example, the commands shown in Examples 4-1 to 4-4 start RTR and exchange a message between a client and a server.

Note The channel identifier identifies the application process to the ACP. The client and server process must each have a unique channel identifier. In this example, the channel identifier for the client is C and for the server is S. Both use the facility called DESIGN.

The examples that follow show 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, refer to the Reliable Transaction Router System Manager's Manual.

Note The `rtr_receive_message` command waits or blocks if no message is currently available. When using the `rtr_receive_message` command in the RTR CLI, use the /TIME=0 qualifier or TIMEOUT to poll for a message, if you do not want your `rtr_receive_message` command to block.

##

### Examples

> Example 4-1 The user issues the following commands on the server application where RTR is running on the backend.

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

> Example 4-2 When the next command is issued, RTR waits for the message from the client, which does not appear until after the client sends it (Example 4-3).

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

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

> Previous | Next | Contents | Index