Order Number: AA-REPMB-TE

January 2001

This guide explains how to design application programs for use with Reliable Transaction Router.

Revision/Update Information: Revision/Update Information: This manual supersedes the Reliable Transaction Router Application Design Guide, for Version 3.2.

Software Version: Reliable Transaction Router V4.0

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, the Compaq logo, AlphaServer, TruCluster, VAX, and VMS Registered in U.S. Patent and Trademark Office.

DECnet, OpenVMS, and PATHWORKS are trademarks of Compaq Information Technologies, L.P.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation. Intel is a trademark of Intel Corporation. UNIX and The Open Group are trademarks of The Open Group.

All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein.

The information in this publication is subject to change without notice and is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH RECIPIENT. IN NO EVENT SHALL COMPAQ BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE FOREGOING SHALL APPLY REGARDLESS OF THE NEGLIGENCE OR OTHER FAULT OF EITHER PARTY AND REGARDLESS OF WHETHER SUCH LIABILITY SOUNDS IN CONTRACT, NEGLIGENCE, TORT, OR ANY OTHER THEORY OF LEGAL LIABILITY, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.

The limited warranties for Compaq products are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty.

Contents

Index

Purpose of this Manual

The goal of this document is to assist the experienced application programmer in designing applications for use with Reliable Transaction Router (RTR). Here you will find conceptual information and some implementation details to assist in:

• Creating new applications
• Updating existing applications

As an application programmer, you should be familiar with the following concepts:

• Distributed systems
• Client/server environment
• C or C++ programming
• Transaction processing

If you are not familiar with these software concepts, you will need to augment your knowledge by reading, taking courses, or through discussion with colleagues. You should also become familiar with the other books in the RTR documentation kit, listed in Related Documentation. Before reading this document, become familiar with the information in Reliable Transaction Router Getting Started.

This document is intended to be read from start to finish; later you can use it for reference.

Related Documentation

Other books that can be helpful in developing your transaction processing application include:

• Philip A. Bernstein, Eric Newcomer, Principles of Transaction Processing, Morgan Kaufman, 1997
• Jim Gray, Andreas Reuter, Transaction Processing: Concepts and Techniques, Morgan Kaufman, 1992
• Oracle8 and Oracle 8i Application Developer's Guides

A useful web site for tips and tutorials on Oracle SQL is http://photo.net/sql .

You will find additional information on RTR and existing implementations on the RTR web site http://www.compaq.com/rtr/ .

Reader's Comments

Conventions

Reading Path

Figure 1 shows the reading path to follow when using the Reliable Transaction Router information set.

Figure 1 Reading Path

This document is for the application programmer who is developing an application for use with Reliable Transaction Router (RTR). Here you will find information on using RTR in the design and development of an application. The main emphasis is on providing design suggestions and considerations for writing the RTR application. Example designs describing existing applications that use RTR show implementations exploiting RTR features, and provide real examples where RTR is in use.

The C++ object-oriented interface is new with RTR V4.0. Most of the material in this document is generic to RTR and not specific to either the C or C++ API (application programming interface)

However, some implementation specifics for each API are shown in appendices. Each API also has its own reference document, the RTR C++ Foundation Classes manual for the C++ API, and the RTR C Application Programmer's Reference Manual for the C API. This document also contains material specific to each API in separate chapters.

In designing your application, Compaq recommends that you use object-oriented analysis and design techniques, whether or not you are using the new object-oriented API. This methodology includes the following:

• Performing use-case analysis
• Tracing scenarios
• Determining actors and classes
• Establishing object interactions

Discussing this methodology is outside the scope of this document, but you can find more information in the following books, among others:

• James Rumbaugh, Michael Blaha, William Premerlani, Frederick Eddy, William Lorensen, Object-Oriented Modeling and Design , Prentice-Hall, 1991
• Martin Fowler, Kendall Scott, UML Distilled Applying the Standard Object Modeling Language , Addison-Wesley, 1997

When designing your application:

• Consider your application requirements fully.
• Work through the entire design and its operational results.
• Understand both the logical and physical design of your database, including any partitioning of your database.

A design flaw can be very expensive or impossible to correct in your application, so doing a thorough design, fully discussed and understood by your team, is essential to the ultimate success of your application in operation. One goal of this document is to help you understand some of the finer subtleties of the product, to help you design an optimum application.

Reliable Transaction Router

Reliable Transaction Router (RTR) is transactional messaging middleware used to implement highly scalable, distributed applications with client/server technologies. With RTR, you can design and implement transaction management applications, take advantage of high availability, and implement failure-tolerant applications to maximize uptime. RTR helps ensure business continuity across multivendor systems and helps maximize uptime.

Implementing an application to use RTR embeds high availability capabilities in the application. Furthermore, RTR greatly simplifies the design and coding of distributed applications because, with RTR, client-server interactions can be bundled together in transactions. In addition, RTR applications can easily be deployed in highly available configurations.

RTR supports applications that run on different hardware and different operating systems. RTR has not been built to work with any specific database product or resource manager (file system, communication link, or queuing product), and thus provides an application the flexibility to choose the best product or technology suited for its purpose. There are, however, some resource managers with which RTR provides tight coupling.

(For more information on using this tighter coupling, see the section in this manual on Using XA.) For specifics on operating systems, operating system versions, and supported hardware, see the Reliable Transaction Router Software Product Description for each supported operating system.

RTR provides several benefits for your application:

• High availability
  An application designed to work with RTR can take advantage of RTR failover capabilities and system availability solutions such as hardware clusters. Transactional shadowing and single input (no need to log on to another node after a failure) with input logging are additional features that provide RTR high availability. You can take advantage of configurations that tolerate process failure, node failure, network failure, and site failure.
• High security
  To protect your data and transactions against unauthorized tampering, you can make use of the authentication server (also known as the callout server available with RTR, as well as operating system security features and tunnels.
• Data retention
  To ensure against loss of data, you will use RTR transactional shadowing. Transactional shadowing can be done at a single site or at geographically separate sites. In deploying your application, you may need to locate sites in different cities or on different power grids to help ensure against data loss.
• High transaction performance
  To design your application for scalability, you can use a partitioned model that exploits RTR data-content routing. You will also consider hardware issues that constrain an application's high performance in processing transactions.

RTR Application Programming Interfaces

RTR provides programming interfaces for use in implementing applications that work with RTR, including:

• the C++ API
  The C++ API is described in the RTR C++ Foundation Classes manual and used in descriptions and examples in this manual. The C API is described in the RTR C Application Programmer's Reference Manual and used in examples in this manual.
• the C++ API
  The C++ API is an object-oriented application programming interface for RTR. With the C++ API, as an application developer, you can design and implement applications to take advantage of object-oriented (OO) design principles, including patterns and code reuse. The C++ API is backwards compatible and can be used for new applications or integrated into existing RTR applications.

As Figure 1-1 illustrates, the C++ API sits on top of the C API, which is a layer on top of RTR.

Figure 1-1 RTR Layers

Client applications and server applications can use both the C++ API and the C API or just the C++ API. The C++ API maps RTR data elements, data structures, and C API functionality into the object-oriented design world.

The C++ API:

• Is 100% compatible with existing applications.
• Provides the features of the flat C API, plus many more.
• Allows RTR applications to focus on their business logic instead of the details of RTR.
• Provides all the benefits of OO design.
• Allows existing applications to benefit from the new interface in many ways.

C++ API and RTR Technology

The C++ API provides an object-oriented framework through which you can implement fault-tolerant systems.

The C++ API code resides beneath application or business logic code. Thus, the C++ API interfaces directly with RTR while application code does not. This transparency simplifies the development and implementation of transaction processing solutions with RTR.

OO Benefits

The C++ API was created to assist RTR customers who:

• Need to create RTR system management routines.
• Are writing common application code.
• Can take advantage of the benefits of OO design and development.
• Write some form of OO wrapper to the existing API.

The benefits include:

• Higher quality software.
• Lower maintenance costs.
• Reduced development time.
• Ease of extensibility.

With the C++ API, applications can inherit functionality from RTR.

The C++ API Provides Ease of Use

The C++ API provides a simplified way for you to implement RTR solutions. With the C++ API:

• Each major RTR concept is represented by its own individual class.
• Class factory support is provided for data objects.
• Clients and servers connect through transaction controller objects (automates and hides C API channel use).
• You do not need to provide handling for all messages and events; default handling is provided.
• The sending and receiving of data is abstracted to a high level.
• Simple methods let you obtain RTR internal information without a need to know the internals of RTR.

C++ API Design

The C++ API upgrades RTR technology by providing a set of classes that streamlines the development and implementation of RTR transaction processing applications. The C++ API has been designed to:

• Provide 100% functional and binary compatibility (backward compatibility) with existing applications.
• Provide an object model that can be implemented in any OO language.
• Provide an object model from which new and existing applications can benefit.
• Perform "common" tasks for the application (for example, for an application to receive a message for a client/server connection).
• Provide default implementation for applications where appropriate.
• Provide an easy-to-use framework for handling messages and events that applications can extend to suit their own business logic.

Use of the C++ API

The C++ API can be used to:

• Develop entirely new applications.
• Upgrade existing applications on a single tier of their application - client or server.
• Integrate individual C++ API classes into existing applications. For example, existing applications can easily use the property classes.
• Develop system management routines for both new and existing applications.

The C++ API enables you to write management routines for both new and existing applications. Additionally, C++ API management classes simplify the process of moving from application design to implementation. For example, the RTRPartitionManager class enables you to write management routines for specifying server types, while methods such as CreateBackEndPartition enable you to specify the roles of servers for tolerating process and node failure.

• Add diagnostics to the application that can be viewed in an integrated display with RTR counters.

The C API

The C API enables applications to be written with RTR calls using the C programming language. The C API is described in the Reliable Transaction Router C Application Programmer's Reference Manual .