# hp Reliable Transaction Router

# Installation Guide

Order Number: AA-Q88DG-TE

# February 2003

This guide describes how to install Reliable Transaction Router for all operating systems on which RTR is supported.

Revision/Update Information: This manual supersedes the Reliable Transaction Router Installation Guide, 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

# Preface

This guide explains how to install HP Reliable Transaction Router (RTR) on supported platforms. If you are installing RTR on only one platform, you need only read the sections that apply to that platform.

Keep this guide with your distribution kit. You may need it to install maintenance updates or to reinstall RTR for some other reason.

# Structure of this Document

This guide contains the following chapters and appendixes:

- Chapter 1 gives brief installation instructions for RTR on OpenVMS, Tru64 UNIX, Windows, and Sun Solaris. For a complete list of versions for each supported operating system, refer to the relevant Software Product Description (SPD). The brief installation instructions include sample installation output.
- Chapter 2 includes instructions on how to perform an upgrade to RTR.
- Chapter 3 describes a full installation for OpenVMS VAX and OpenVMS Alpha, including:
  - Preparing for installation
  - Installing RTR and reading the Release Notes
  - Completing RTR setup
- Chapter 4 describes a full installation for Tru64 UNIX including:
  - Preparing for installation
  - Installing RTR and reading the Release Notes
  - Completing RTR setup
- Chapter 5 describes a full installation for Windows including:
  - Preparing for installation
  - Installing RTR and reading the Readme
  - Completing RTR setup
- Chapter 6 describes a full installation for Sun Solaris including:
  - Preparing for installation
  - Installing RTR and reading the Release Notes
  - Completing RTR setup
- Appendix A provides information on recovering from errors.
- Appendix B provides instructions on how to remove (uninstall) RTR from your system.

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

1Distributed on software kit.
2Softcopy only.

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.

# Conventions

Table 2 describes the conventions used in this guide.

Table 2 Conventions Used in this Guide
Convention | Meaning
--- | ---
# | A number sign (#) is the default superuser prompt.
% | A percent sign (%) is the default user prompt for many UNIX systems.
$ | A dollar sign ($) is the default user prompt for OpenVMS systems.
`[Return]` | In examples, a boxed symbol indicates that you must press the named key on the keyboard.
Ctrl/C | This symbol indicates that you must press the Ctrl key while you simultaneously press another key (in this case, C).
`user input` | In interactive examples, this typeface indicates input entered by the user.
`filesystem` | In text, this typeface indicates the exact name of a command, routine, partition, pathname, directory, or file. This typeface is also used in interactive examples and other screen displays.
UPPERCASE lowercase | The UNIX operating system differentiates between lowercase and uppercase characters. Examples, syntax descriptions, function definitions, and literal strings that appear in text must be typed exactly as shown. Commands typed to the RTR CLI are not case sensitive unless enclosed in quotation marks.
`[y]` | In a prompt, square brackets indicate that the enclosed item is the default response. For example, `[y]` means the default response is Yes.

# 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

# Chapter 1
Quick Installation

This chapter gives brief instructions for installing Reliable Transaction Router on the following platforms:

- OpenVMS
- Windows 2000, Windows NT, Windows 98, Windows ME, Windows XP
- Tru64 UNIX
- Sun Solaris

User-Changed Monitor Files If you have changed any RTR monitor (*.mon) files, you must rename them or they will be overwritten during installation. To avoid this, always work from renamed copies of RTR monitor files when making local modifications.

# 1.1 Installing RTR for OpenVMS

Your Reliable Transaction Router for OpenVMS kit is supplied on CD-ROM. After installation, the Release Notes are located in the directory `SYS$COMMON:[SYSHLP]` ; you are advised to read the Release Notes before using RTR.

## 1.1.1 Disk and Time Requirements

The installation of the RTR base product requires about 53000 blocks during installation, and about 36000 blocks after installation is done. The installation takes less than five minutes to complete. For more detailed instructions, see Chapter 3.

## 1.1.2 Installation Procedure

1. If RTR is already installed on your system, see Section B.1, Uninstalling on OpenVMS, for information on uninstalling RTR and removing related processes.

   Retaining the RTR V2 Help File If you plan to keep the RTR V2 help file in addition to the help file for the current release, see Chapter 3 for instructions.

2. Log on to the System Manager's account.
3. Define the logical name for the location of the software kit, for example:

       $ DEFINE PCSI$SOURCE DISK1:[KITS]

4. Check disk space and system parameters GBLPAGES and GBLSECTIONS.
5. Start the installation with the following command:

       $ PRODUCT INSTALL RTR

## 1.1.3 Sample OpenVMS Installation

This sample installation includes running the IVP.

    $ product install rtr

    The following product has been selected:
        DEC AXPVMS RTR V4.2-320               Layered Product

    Do you want to continue? [YES] y

    Configuration phase starting ...

    You will be asked to choose options, if any, for each
    selected product and for
    any products that may be installed to satisfy software
    dependency requirements.

    DEC AXPVMS RTR V4.2-320: Reliable Transaction Router for OpenVMS

      Copyright 1994, 2003 Hewlett-Packard Development Company, L.P.

    Do you want the defaults for all options? [YES] n

        Have all RTR processes on the system been stopped? [YES] y
        Run installation verification procedure [NO] y
        DECnet users: Have you read the Release Note regarding
        minimum version?
        [YES] y
        Do you want the V2 programming kit Installed? [NO] yes

    Do you want to review the options? [NO] y

    DEC AXPVMS RTR V42-320: Reliable Transaction Router for OpenVMS
        Have all RTR processes on the system been stopped?: YES
        Run installation verification procedure: YES
        DECnet users: Have you read the Release Note regarding
        minimum version?: YES
        Do you want the V2 programming kit Installed ?: YES

    Are you satisified with these options? [YES]

    Execution phase starting ...

    The following product will be installed to destination:
        DEC AXPVMS RTR V4.2-320
       <logical for SYS$COMMON>

    Portion done: 0%
    ...10%
    ...20%
    ...30%
    ...40%
    ...50%
    ...60%
    ...70%
    ...80%
    ...90%
    ...100%

    The following product has been installed:
        DEC AXPVMS RTR V4.2-320                Layered Product

    %PCSI-I-IVPEXECUTE, executing test procedure for DEC AXPVMS RTR V4.2-320 ...
    %PCSI-I-IVPSUCCESS, test procedure completed successfully

    DEC AXPVMS RTR V4.2-320: Reliable Transaction Router for OpenVMS

        Insert the following lines in SYS$MANAGER:SYSTARTUP_VMS.COM:
            @sys$startup:rtr$startup.com
        Insert the following lines in SYS$MANAGER:SYSHUTDWN.COM:
            @sys$manager:rtr$shutdown

     See the Release Notes and documentation for use of the optional
     rtr$startup.com P1 parameter. (1)
    $

1. For information on the optional preferred protocol (P1) parameter, see Section 3.3.1.1.

For additional information, see Chapter 3, Full Installation on OpenVMS .

# 1.2 Installing RTR for Tru64 UNIX

Your Reliable Transaction Router for Tru64 UNIX kit is supplied on CD-ROM. After installation, the Release Notes are located in the directory /usr/opt/RTR420/hlp; you are advised to read the Release Notes before using RTR.

User-Changed Monitor Files If you have changed any RTR monitor (*.mon) files, you must rename them or they will be over-written during installation. To avoid this, always work from renamed copies of RTR monitor files when making local modifications.

TruCluster Restrictions To install RTR on a TruCluster, see the description in Section 4.2.1.

## 1.2.1 Disk and Time Requirements

The installation requires about 23 MB (megabytes), 5.6 MB for the `/rtr` area, and 2 MB for the RTR journal. The installation procedure takes about two minutes to complete.

## 1.2.2 Installation Procedure

1. Log in as user `root` or `su` to `root` .
2. Use the `setld` utility to check if you have a version of RTR already installed:

       # setld -i | grep RTR

3. If RTR is already installed on your system, see Section B.3, Uninstalling on Tru64 UNIX, for information on uninstalling RTR and removing related processes.
4. Install from the directory (disk or CD-ROM) where the kit is located, for example:

       # setld -l /cdrom/rtr4xx/kit

   Where "xx" is the version number, for example, `rtr420` .
5. Answer "1" and "y" to the questions from `setld` .
6. To run the IVP (Installation Verification Procedure) use the following command:

   Caution Do not run the IVP program on a production system, as it may alter the RTR journal or interrupt processing of transactions. You will be prompted to abort the IVP before it can do any damage. Consider your situation carefully before running the IVP.

       # setld -v RTRBASE4xx

   Where "xx" is the kit number, for example, `RTRBASE420` .
   Note that the Installation Verification Procedure requires a working C language compiler to run.

Requirements for Application Permissions If the RTR executable is modified after installation to no longer be `suid` root or the mode of the `/rtr` directory is changed, an application process (for example a client) can encounter a fatal error (Unable to locate a socket) when the client process finds it cannot create an `rtr_ipc_sock_*` file for the process ID (pid) in the `/rtr` directory. To avoid this, ensure that application processes run with user and group IDs that have access permission to create and remove files in this directory.

## 1.2.3 Sample Tru64 UNIX Installation

    # setld -l RTRBASE420

      Copyright 1994, 2003 Hewlett-Packard Development Company, L.P.

      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 standard
      commercial license.

    The subsets listed below are optional:

         There may be more optional subsets than can be presented on a
         single
         screen. If this is the case, you can choose subsets screen by
         screen
         or all at once on the last screen. All of the choices you make
         will
         be collected for your confirmation before any subsets are
         installed.

         1) RTR API & Management Utility

    Or you may choose one of the following options:

         2) ALL of the above
         3) CANCEL selections and redisplay menus
         4) EXIT without installing any subsets

    Estimated free diskspace(MB) in root:67.7 usr:198.8

    Press RETURN to display the next screen.

    Enter your choices or press RETURN to redisplay menus.

    Choices (for example, 1 2 4-6): 1

    You are installing the following optional subsets:

            RTR API & Management Utility

    Estimated free diskspace(MB) in root:67.7 usr:177.9

    Is this correct? (y/n): y

    Checking file system space required to install selected subsets:

    File system space checked OK.

    1 subsets will be installed.

    Loading subset 1 of 1 ...

      Reliable Transaction Router V4.2 for Tru64 UNIX

      Installation started at Wed Apr 10 16:08:17 EDT 2002.

      Installation proceeds automatically, and should complete in
      approximately
      1 minute.

    RTR API & Management Utility
       Copying from . (disk)
            Working....Wed Apr 10 16:08:29 EDT 2002
       Verifying

    1 of 1 subsets installed successfully.
    reusing existing /usr/doc/rtr directory
    /usr/doc/rtr//rtr_relnotes.txt: File exists
    /usr/doc/rtr//rtr_relnotes.ps: File exists
    mkdir: cannot create /var/opt/rtrjnl.
    /var/opt/rtrjnl: File exists

    Configuring "RTR API & Management Utility" (RTRBASE420)

      directory /var/run/rtr created

      reusing existing /rtr directory

      Copyright 1994, 2003 Hewlett-Packard Development Company, L.P.

      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 standard
      commercial license.

      Reliable Transaction Router V4.2 for Tru64 UNIX

      Installation completed at Wed Apr 10 16:09:31 EDT 2002.

      You can run the Installation Verification Procedure using this
      command:
                       setld -v RTRBASE420

      Release Notes are available in: /usr/opt/RTR420/hlp/rtr_relnotes.*
    #

## 1.2.4 Sample IVP Output

    # setld -v RTRBASE420
    RTR API & Management Utility (RTRBASE420)

      Copyright 1994, 2003 Hewlett-Packard Development Company, L.P.

      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 standard
      commercial license.

      Starting     Reliable Transaction Router V4.2  for Tru64 UNIX
      Installation Verification Procedure
    WARNING: This is not a first time install.
    WARNING: Please ensure that you have terminated *all* existing
    WARNING: rtr processes and rtr applications before continuing.

    Rtr will find and reuse any existing rtr journal files in the
    top level rtrjnl directory on each suitable filesystem, and will
    reuse any existing shared memory segment associated with
    /rtr/RTRENVPS
    Normally this is intended and should not cause any problems.

    WARNING: Any existing journal will be used and modified,
    otherwise
    WARNING: a new journal will be created on the default filesystem.
    WARNING: Facilities RTR_IVP_FACILITY and RTR$DEFAULT_FACILITY
    will be created.
    WARNING: Result may be affected by size and contents of any
    existing journal.
    WARNING: The sample client and server do not necessarily complete
    if they
    WARNING: encounter previously journalled transactions for their
    facilities.

    Would you like to abort the IVP? (y/n)
    n
    IVP continuing ...

      keeping any existing log file settings (RTR_DBG not set)
      starting RTR . . .
      creating a journal, if not already created  . . .
      creating test facility . . .
      stopping RTR.

      [OPTIONAL] attempting to compile and link rtr test applications . . .

      If this system is not configured with an application development
      environment, or the platform does not support threads, then some
      messages about application compilation not succeeding are normal.

      multithreaded server rtr application compiled
      single-threaded client rtr application compiled
      applications rtrreq and rtrsrv available
      starting rtr and creating default facility
    %RTR-I-NOLOGSET, logging not set
    %RTR-S-RTRSTART, RTR started on node nodea in group "root"
    %RTR-S-RTRSTOP, RTR stopped on node nodea in group "root"

      Copyright 1994, 2003 Hewlett-Packard Development Company, L.P.

          Reliable Transaction Router V4.2  for Tru64 UNIX

      Installation Verification Procedure successful

Next | Contents | Index