Order Number: AA-REPMC-TE

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

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

Software Version: Reliable Transaction Router Version 4.2

Hewlett-Packard Company
Palo Alto, California

© 2003 Hewlett-Packard Development Company, L.P.

Microsoft, MS-DOS, Windows, and Windows NT are US registered trademarks of Microsoft Corporation.

Intel is a US registered trademark of Intel Corporation.

UNIX is a registered trademark of The Open Group.

Confidential computer software. Valid license from HP and/or its subsidiaries 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 commercial license.

Neither HP nor any of its subsidiaries shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an 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

Table 1 describes RTR documents and groups them by audience.

Table 1 RTR Documents

Document	Content
For all users:
Reliable Transaction Router Release Notes 1	Describes new features, changes, and known restrictions for RTR.
Reliable Transaction Router Getting Started	Provides an overview of RTR technology and solutions, and includes the glossary that defines all RTR terms.
Reliable Transaction Router Commands	A pocket-sized handbook that lists all RTR commands, their qualifiers and defaults.
Reliable Transaction Router Software Product Description	Describes product features.
For the system manager:
Reliable Transaction Router Installation Guide	Describes how to install RTR on all supported platforms.
Reliable Transaction Router System Manager's Manual	Describes how to configure, manage, and monitor RTR.
Reliable Transaction Router Migration Guide 2	Explains how to migrate from RTR Version 2 to RTR Version 3 or 4 (OpenVMS only).
For the application programmer:
Reliable Transaction Router Application Design Guide	Describes how to design application programs for use with RTR, with both C++ and C interfaces.
Reliable Transaction Router C++ Foundation Classes	Describes the object-oriented C++ interface that can be used to implement RTR object-oriented applications.
Reliable Transaction Router C Application Programmer's Reference Manual	Explains how to design and code RTR applications using the C programming language and the RTR C API. Contains full descriptions of the basic RTR API calls.

You can find additional information about RTR, including the Software Product Descriptions, on the RTR website found through http://www.hp.com links to middleware products or at http:://www.hp.com/go/rtr.

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 web search for "Oracle SQL" can provide tutorial and other useful references.

Reader's Comments

HP welcomes your comments on this manual. Please send us your comments by email to rtrdoc@hp.com. Please include the following with your comments or suggestions: the title of the manual, date from the title page, section and page numbers.

Conventions

Reading Path

The reading path to follow when using the Reliable Transaction Router information set is shown in Figure 1.

Figure 1 RTR 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.

RTR provides both a C++ object-oriented application programming interface (API) and a C API. Most of the material in this document is generic to RTR and not specific to either interface. However, some implementation specifics for each API are shown in separate chapters and appendices.

Each API also has its own reference document, the Reliable Transaction Router C++ Foundation Classes manual for the C++ API, and the Reliable Transaction Router C Application Programmer's Reference Manual for the C API.

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

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 in addition 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 use the authentication server (also known as the callout server) that is available with RTR, and operating system security features and tunnels.
• Data retention
  To ensure against loss of data, you can use RTR transactional shadowing. Transactional shadowing can be done at a single site or at geographically separate sites. In deploying your application, you can locate sites in different cities or on different power grids to protect against data loss.
• High transaction performance
  To design your application for scalability, you can use a partitioned model to exploit RTR data-content routing, and you should evaluate hardware constraints that may limit an application's 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 Reliable Transaction Router C++ Foundation Classes manual and shown in this manual.
• The C API
  The C API is described in the Reliable Transaction Router C Application Programmer's Reference Manual and shown 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. 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. 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.