HP Reliable Transaction Router Getting Started Order Number: AA-RLE1C-TE June 2005 This document introduces HP Reliable Transaction Router and describes its concepts for the system manager, system administrator, and applications programmer. Revision/Update Information: Software Version: Hewlett-Packard Company Palo Alto, California...
Page 2
The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
Page 4
3 Reliability Features RTR Server Types ........Failover and Recovery .
Page 5
Commands and system response at client....4–3 The following lines arrive at the client from RTR after the 4–4 user enters commands at the server....Creating a Facility with the C++ API .
Page 6
RTR Service Provider ....... 4–6 RTR System Management Environment ....5–1 RTR Runtime Environment .
Purpose of this Document The goal of this document is to assist an experienced system manager, system administrator, or application programmer to understand the Reliable Transaction Router (RTR) product. Document Structure This document contains the following chapters: • Chapter 1, Introduction, provides information on RTR technology, basic RTR concepts, and RTR terminology.
Related Documentation Table 1 describes RTR documents and groups them by audience. Table 1 RTR Documents Document For all users: HP Reliable Transaction Router Release Notes HP Reliable Transaction Router Getting Started HP Reliable Transaction Router Software Product Description For the system manager:...
Page 9
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 . Reader’s Comments HP welcomes your comments on this manual. Please send comments to either of the following addresses: Internet Postal Mail Content...
Page 10
Conventions This manual adopts the following conventions: Convention New term User input Terms and titles Refer to . . . See . . . Reading Path The reading path to follow when using the Reliable Transaction Router information set is shown in Figure 1. Description New terms are shown in bold when introduced and defined.
Figure 1 RTR Reading Path System Manager Installation Guide System Manager’s Manual RTR Help (Online Only) Release Notes Getting Started = Glossary Application Programmer Application JRTR Design Getting Guide Started (Online Only) If C C Application Programmer’s Foundation Reference Classes Manual = Tutorial If Java...
This document introduces RTR and describes RTR concepts. It is intended for the system manager or administrator and for the application programmer who is developing an application that works with Reliable Transaction Router (RTR). Reliable Transaction Router Reliable Transaction Router (RTR) is failure-tolerant transactional messaging middleware used to implement large, distributed applications with client/server technologies.
Page 14
Server, Sybase, and Informix. For specifics on operating systems, operating system versions, and supported hardware, refer to the HP Reliable Transaction Router Software Product Description for each supported operating system. RTR can be deployed in a local or wide area network and can use Networking either TCP/IP or DECnet for its underlying network transport.
WAN deployability RTR also ensures that transactions have the ACID properties that have been established as crucial in a transaction processing environment. A transaction with the ACID properties is: • Atomic • Consistent • Isolated Reliable Transaction Router Introduction 1–3...
Durable For more details on transactional ACID properties, see the brief discussion later in this document in the section Transaction Integrity and refer to the HP Reliable Transaction Router Application Design Guide. RTR Terminology In addition to the terms previously defined, the following terms are either unique to RTR or redefined when used in...
• Standby server • Transactional shadowing • RTR journal • Partition • Key range • An RTR application is user-written software that executes RTR Application 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.
RTR Terminology A server is always a server application, one that reacts to a Server 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.
A node that runs client applications is called a frontend Roles (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.
RTR Terminology Figure 1–4 Facility Symbol A facility name is mapped to specific physical nodes and their roles using the CREATE FACILITY command. Figure 1–5 shows the logical relationship between client application, server application, frontends (FEs), routers (TRs), and backends (BEs) in the RTR environment at a specific location.
Page 21
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.
Page 22
RTR Terminology 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.
Figure 1–6 Two-Tier Client/Server Environment Application Presentation and Business Logic (ODBC Model) Figure 1–7 Three-Tier Client/Server Environment Presentation/User Interface RTR extends the three-tier model, which is based on hardware, to a multilayer, or multicomponent software model. RTR provides a multicomponent software model where client RTR Software applications running on frontends, combined with routers and Components...
RTR Terminology 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.
RTR Terminology 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 identify usage bottlenecks, add new nodes, and provide redundancy to increase availability.
RTR Terminology 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.
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.
RTR Terminology Figure 1–13 Transactional Shadowing Configuration In the RTR environment, one data store (database or data RTR Journal 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.
Transactional shadowing shadows only transactions controlled by RTR. 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.
Page 30
RTR Server Types The standby server remains idle while the RTR primary Standby server 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.
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.
RTR Server Types Transactional shadowing is done by partition. A transactional shadow configuration can have only two members of the shadow set. Shadow servers are servers on separate backends that handle the same transactions in parallel on identical copies of the database.
The concurrent server is an additional instance of a server Concurrent 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.
RTR Server Types The callout server enables message authentication on Callout server 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.
Page 35
RTR callout servers provide facility-based processing for Authentication authentication. For example, a callout server can enable verification 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 facility.
CREATE PARTITION command. For details of the command syntax, refer to the HP 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;...
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. A node can be configured as a primary server for one key range Standby Server and as a standby server for another key range.
RTR Networking Capabilities RTR Networking Capabilities 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.
Architectural Concepts This chapter introduces concepts on basic transaction processing and RTR architecture. The Three-Tier Architecture 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. (In this and subsequent diagrams, rectangles represent physical nodes, ovals represent application software, and cylinders represent the disks storing the database.
The Three-Tier Architecture Figure 2–1 The Multitier Model Terminals 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. Server application processes (represented by ‘‘Server application’’ in Figure 2–1) run on nodes defined to have the backend role.
RTRFacilityManager to manage a channel or the C API rtr_open_channel( ) server, it specifies the name of the facility it will use. Refer to the HP Reliable Transaction Router System Manager’s Manual for information on how to define facilities. The Three-Tier Architecture routine to declare a channel as a client or Architectural Concepts 2–3...
Broadcasts Broadcasts 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.
A durable transaction is thus both persistent and stable. For more detail on these properties and their use in transaction processing, refer to the HP Reliable Transaction Router Application Design Guide. Flexibility and Growth Architectural Concepts 2–5...
For a more complete description of partitioning as provided with RTR, refer to the HP Reliable Transaction Router Application Design Guide. Each RTR API provides the capability to use partitions. For specific information on declaring and using partitions, see the...
Instantiating, or declaring, an instance of, a class implements an object. RTR provides object-oriented programming capabilities with the C++ API, described in the HP Reliable Transaction Router C++ Foundation Classes manual and the Java API, described in the JRTR Getting Started manual.
Example 2–1 Objects-Defined Sample Dog.h: class Dog { ... main.cpp: #include "Dog.h" main() Dog King; Dog Fifi; Objects communicate by sending messages. This is done by Messages calling an object’s methods. Some principal categories of messages are: • Constructors: Create objects •...
Object-Oriented Programming Polymorphism is the ability of objects, inherited from a common Polymorphism 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];"...
XA can also increase the portability of your application. For details on using XA with RTR, refer to the HP Reliable Transaction Router C Application Programmer’s Reference Manual and the HP Reliable Transaction Router Application Design Guide.
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: •...
RTR Server Types 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...
This section describes how RTR recovers from different hardware and software failure. For additional information on failure and recovery scenarios, refer to the HP Reliable Transaction Router Application Design Guide. If standby or shadow servers are available on another backend...
Recovery Scenarios If a frontend is lost: Frontend Recovery • 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. 3–4 Reliability Features...
RTR provides interfaces for system management (the management interfaces) and for development of transaction processing and management applications (the programming or application development interfaces). The management interfaces are: Management Interfaces • The RTR Administrator, a browser interface. This interface includes: •...
RTR C applications for testing and experimentation. The CLI is described in the HP 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 RTR provides several programming or application development Programming interfaces for design and implementation of transaction Interfaces processing programs. They include the following: • The object-oriented RTR Java interface You can use this API for new development, and, where appropriate, for new development with existing applications.
Page 58
The C-programming API is fully described in the HP Reliable Transaction Router C Application Programmer’s Reference Manual. Both APIs are used in examples in the HP Reliable Transaction Router Application Design Guide. The Java J2EE interface is described in the JTA material in the RTR JRTR kit.
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: •...
RTR Management RTR Management 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 With the RTR Administrator, you have a network-browser- like display from which you can view RTR status and issue Administrator...
Figure 4–3 RTR Manager http://nodename nodename nodename Figure 4–4 shows a sample screen of the RTR Explorer with RTR Explorer 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.
RTR Management Figure 4–4 RTR Explorer: View of All Facilities 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.
Figure 4–5 RTR Explorer: View of One Facility http://nodename Mode: Navigation Design Facility nodename 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.
RTR Management or group of nodes. If there are no flags, the node or group is operating normally. The command line interface (CLI) to the RTR API enables the RTR Command programmer to write short RTR applications from the RTR Line Interface command line.
Page 65
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 HP Reliable Transaction Router System Manager’s Manual. Note...
Page 66
RTR Management 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 "...
Page 67
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: usrhdl: Tid:...
Page 68
RTR Management 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/partition=des_1 %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:...
Page 69
Example 4–4 The following lines arrive at the client from RTR after the user enters commands at the server. %RTR-S-OK, normal successful completion channel name: C msgsb msgtype: rtr_mt_reply msglen: usrhdl: tid: 63b01d10,0,0,0,0,2e59,43ea2002 message offset bytes 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 RTR>...
Application Programming Interfaces Application Programming Interfaces You write application programs and management applications with the RTR application programming interfaces. You can use Java and J2EE technology to write applications RTR Java that use RTR. For additional information on these technologies, Object-Oriented see the documentation that is part of the JRTR downloadable Interface...
Figure 4–6 RTR Service Provider JRTR Server Application 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.
C++ applications that use RTR. For more information on the C++ Object-Oriented object-oriented programming interface, refer to the HP Reliable Programming Transaction Router C++ Foundation Classes manual and the HP Interface Reliable Transaction Router Application Design Guide. The following example illustrates object creation in a program Sample C++ client that is to act as an RTR client application.
Page 73
void CombinationOrderProcessor::StartProcessingOrdersAtoL() // Create an RTRKeySegment for all ASCII values between "A" and "L." m_pkeyRange = new RTRKeySegment (rtr_keyseg_string, //To process strings. 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();...
Page 74
Application Programming Interfaces Example 4–5 Creating a Facility with the C++ API // Use the C++ interface to create an RTR facility RTRFacilityManager::CreateFacilityWithAllRoles_3() bool bOverallResult = true; //Create facility manager, abort if creation fails RTRFacilityManager * pFacilityManager; pFacilityManager = new RTRFacilityManager; if ( IsFailure(pFacilityManager != NULL) ) return false;...
Application Programmer’s Reference Manual and the HP Reliable Transaction Router Application Design Guide. Snippets from client and server programs using the RTR C- programing API follow and are more fully shown in the HP Reliable Transaction Router Application Design Guide. Application Programming Interfaces "router",...
Page 76
CPU or a multiple CPU machine, and on your overall design goals and implementation requirements. For a more complete discussion of application designs, refer to the HP Reliable Transaction Router Application Design Guide. 4–22 RTR Interfaces...
The RTR environment has two parts: • System management environment • Runtime environment The RTR System Management Environment You manage your RTR environment from a management station, which can be on a node running RTR or on some other node. You can manage your RTR environment either from your management station running a network browser using the RTR Administrator, Manager and Explorer or from the command line...
Page 78
The RTR System Management Environment • Sends messages between nodes • Handles all transactions and recovery RTRACP handles interprocess communication traffic, network traffic, and is the main repository of runtime information. ACP processes operate across all RTR roles and execute certain commands both locally and at remote nodes.
SHOW commands that also let you view status are snapshots, giving you a view at one moment in time. A full list of RTR Monitor pictures is available in the HP Reliable Transaction Router System Manager’s Manual ‘‘RTR Monitoring’’ chapter and in the help file under Using_Monitoring.
The RTR System Management Environment Figure 5–1 RTR System Management Environment RTRACP RTRD RTR COMSERV RTR COMSERV RTR CLI Management Station Running Browser Software The RTR transaction is the heart of an RTR application, Transaction and transaction state characterizes the current condition of a Management transaction.
For more details on use of SHOW and SET commands, refer to the HP Reliable Transaction Router System Manager’s Manual. As illustrated in Figure 1–18, you can use key ranges in your...
For more details on managing partitions and their use in applications, refer to the chapter on ‘‘Partition Management’’ in the HP Reliable Transaction Router System Manager’s Manual. RTR Runtime Environment When all RTR and application components are running, the RTR runtime environment contains: •...
Figure 5–2 RTR Runtime Environment LIBRTR/RTRDLL LIBRTR/RTRDLL Client application RTRACP RTRD RTR COMSERV RTR COMSERV RTR CLI Optional External Applet Not Running RTR What’s Next? This concludes the material on RTR concepts and capabilities that all users and application designers and implementors should know.
Page 84
What’s Next? If you are: a system manager, system administrator, or software installer If you are: an applications or system management designer, developer, programmer, or software engineer 5–8 The RTR Environment Read these documents in this order: 1. RTR Release Notes 2.
Glossary ACID Transaction properties supported by RTR: atomicity, consistency, isolation, durability. For additional information, see the section on Transaction Integrity in Chapter 2. The RTR Application Control Process. Application programming interface. applet A small application designed for running on a browser. application User-written software that employs RTR.
Page 86
bank An establishment for the custody of money, which it pays out on a customer’s request. branch A subdivision of a bank; perhaps in another town. broadcast A nontransactional message. callout server A server process used for transactional authentication. Common Gateway Interface channel A logical port opened by an application with an identifier to exchange messages with RTR.
Page 87
commit sequence number (CSN) A sequence number assigned to an RTR commit group, established by the vote window, the time interval during which transaction response is returned from the backend to the router. All transactions in the commit group have the same CSN and lock the database.
Page 88
deadlock Deadly embrace, a situation that occurs when two transactions or parts of transactions conflict with each other, which could violate the consistency ACID property when committing them to the database. disk shadowing A process by which identical data are written to multiple disks to increase data availability in the event of a disk failure.
Page 89
facility The mapping between nodes and roles used by RTR and established when the facility is created. facility manager A C++ API management class that creates and deletes facilities. facility member A defined entity within a facility. A facility member is a role and node combined.
Page 90
JNDI Java Naming and Directory Interface, an API providing such functions to applications written in the Java programming language. Connection pools and datasources are registered with a JNDI service. key range An attribute of a key segment, for example a range A to E or F to K.
Page 91
multichannel An application that uses more than one channel. A server is usually multichannel. multithreaded An application that uses more than one thread of execution in a single process. MS DTC Microsoft DTC; see DTC. network partition A network partition, usually inadvertently, separates a network into disconnected parts.
Page 92
polymorphism The ability of objects inherited from a common parent class to respond differently to the same message. The object responds depending on where it is in the inheritance hierarchy. primary The state of the partition servicing the original data store or database.
Page 93
roles Roles are defined for each node in an RTR configuration based on the requirements of a specific facility. Roles are frontend, router, or backend. rollback When a transaction has been committed on the primary database but cannot be committed on its shadow, the committed transaction must be removed or rolled back to restore the database to its pretransaction state.
Page 94
In other contexts, a server may be a physical node, but in RTR and in this document, physical servers are called backends or nodes. server classes C++ foundation classes used for implementing server applications. serviceprovider A context or initial context implementation used by a JNDI client for dynamic connection to JNDI.
Page 95
transaction An operation performed on a database, typically causing an update to the database. Analogous in many cases to a business transaction such as executing a stock trade or purchasing an item in a store. A business transaction may consist of one or more than one RTR transaction.
Page 96
transactional shadowing A process by which identical transactional data are written to separate disks often at separate sites to increase data availability in the event of site failure. See also disk shadowing. two-phase commit A database commit/rollback concept that works in two steps: 1. The coordinator asks each local recovery manager if it is able to commit the transaction.