Reliable Transaction Router Version 3.1D for OpenVMS_____________________________________________ Installation Guide Order Number: AA-R1WNB-TE December 1997 This guide describes how to install Reliable Transaction Router Version 3.1D for OpenVMS. Reliable Transaction Router, Version 3.1D is fault tolerant and transaction management middleware, used to implement large, distributed, transaction processing applications. Revision/Update Information: This is a revised manual. Software Version: Reliable Transaction Router, Version 3.1D Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ December, 1997 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1989, 1997. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: Alpha, DEC, DECdtm, DECnet, Digital, DNA, OpenVMS, PATHWORKS, Reliable Transaction Router, VAX, VAX DOCUMENT, VAX Pascal, VAX RMS, VAX Volume Shadowing, VMS, VMScluster, and the DIGITAL Logo. The following are Registered Trademarks of Borland International, Inc.: Turbo Pascal[R] The following is a Registered Trademark of Hewlett-Packard Company: HP-UX[R] The following is a Trademarks of Intel Corporation: Intel[TM] The following is a Registered Trademark of International Business Machines Corporation: IBM[R]. The following are Trademarks of International Business Machines Corporation: AIX[TM] and RISC System/6000[TM]. The following are Registered Trademarks of Microsoft Corporation: MS-DOS[R] MS[R] and Microsoft[R]. The following are Trademarks of Microsoft Corporation: Windows[TM], Windows NT[TM], Visual Basic[TM] and Visual C++ [TM] The following are Registered Trademarks of Oracle Corporation: ORACLE[R], SQL*Net[R] and SQL*Plus[R]. The following are Trademarks of Oracle Corporation: ORACLE7[TM] and PL/SQL[TM]. The following are Registered Trademarks of Sun Microsystems, Inc.: SUN[R] and Solaris[R]. The following are Trademarks of Sun Microsystems, Inc.: SPARCstation[TM] and SunOS[TM]. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. This document was prepared using DECdocument, Version 3.2. _________________________________________________________________ Contents Preface................................................... v 1 Installing Reliable Transaction Router Version 3.1D for OpenVMS 1.1 Preparing for Reliable Transaction Router Version 3.1D for OpenVMS Installation......... 1-1 1.1.1 Prerequisite and Optional Software........ 1-1 1.1.2 License Registration...................... 1-2 1.1.3 Required Disk Space....................... 1-3 1.1.4 System Parameters......................... 1-3 1.2 The Installation Procedure.................... 1-4 1.3 Running the Reliable Transaction Router Version 3.1D for OpenVMS PCSI Installation.... 1-4 1.4 After Installing Reliable Transaction Router .............................................. 1-6 1.4.1 Running the Installation Verification Procedure (IVP)........................... 1-6 1.4.2 Accessing Release Notes................... 1-6 1.4.3 Editing the System Files.................. 1-6 1.4.4 Removing Reliable Transaction Router...... 1-7 1.4.5 User Account Requirements................. 1-7 1.4.5.1 Quotas.................................. 1-7 1.4.5.2 Privileges.............................. 1-7 A Sample Listings A.1 Sample RTR for OpenVMS Installation .......... A-1 A.2 Sample RTR for OpenVMS Installation Verification Procedure ....................... A-2 iii B Files Installed B.1 Files Added................................... B-1 Tables 1 Conventions Used in this Guide ........... vi 1-1 Prerequisite and Optional Software........ 1-1 1-2 Disk Space Requirements................... 1-3 1-3 Minimum Required System Parameter Values.................................... 1-3 1-4 User Account Quotas for Using Reliable Transaction Router........................ 1-7 iv _________________________________________________________________ Preface This Guide explains how to install Reliable Transaction Router, Version 3.1D (RTR) on OpenVMS VAX and OpenVMS Alpha. Keep this guide with your distribution kit. You may need it to install maintenance updates or to reinstall RTR for any other reason. Structure of This Document This guide contains the following chapters and appendixes: o Chapter 1 describes installing Reliable Transaction Router, Version 3.1D on OpenVMS VAX and OpenVMS Alpha. o Appendix A contains sample listings for an interactive RTR installation and IVP on OpenVMS. o Appendix B lists the files added to your system by the installation. Associated Documents In addition to this guide, the RTR documentation set includes the following: o Reliable Transaction Router Version 3.1D, System Manager's Manual o Reliable Transaction Router Version 3.1D, Application Programmer's Reference Manual o A letter titled Reliable Transaction Router, Version 3.1D - Cover Letter or Reliable Transaction Router, Version 3.1D - Read Before Installing v Please read this letter; it contains important information about installing RTR that may not be included in this installation guide or in the release notes. Conventions Table 1 describes the conventions used in this guide. Table_1_Conventions_Used_in_this_Guide_____________________ Convention_____Meaning_____________________________________ 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. [y] In a prompt, square brackets indicate that the enclosed item is the default response. For example, [y] means the default response _______________is_Yes._____________________________________ vi 1 _________________________________________________________________ Installing Reliable Transaction Router Version 3.1D for OpenVMS This chapter describes how to install Reliable Transaction Router Version 3.1D for OpenVMS. The description applies to both the OpenVMS VAX and OpenVMS Alpha products. A step-by-step description of the installation procedure is given. 1.1 Preparing for Reliable Transaction Router Version 3.1D for OpenVMS Installation Before you start the installation procedures decribed in Section 1.2, you should complete the preparation tasks outlined in this section. 1.1.1 Prerequisite and Optional Software Table 1-1 provides information on the software that must be installed on your system before installing Reliable Transaction Router. The table also includes information about optional software that you can use with Reliable Transaction Router. The Software Product Description (SPD) contains a complete list of prerequisite and optional software and their required version numbers. Table_1-1_Prerequisite_and_Optional_Software_______________ Prerequisite_Products______Purpose_________________________ OpenVMS VAX Version 6.1 System Software to 7.1 or (continued on next page) Installing Reliable Transaction Router Version 3.1D for OpenVMS 1-1 Installing Reliable Transaction Router Version 3.1D for OpenVMS 1.1 Preparing for Reliable Transaction Router Version 3.1D for OpenVMS Installation Table_1-1_(Cont.)_Prerequisite_and_Optional_Software_______ Prerequisite_Products______Purpose_________________________ OpenVMS Alpha Version 6.1 System Software to 7.1 ___________________________________________________________ Optional_Products__________Purpose_________________________ DIGITAL TCP/IP Services Network Transport for OpenVMS (Version 4.0 or higher) DECnet or DECnet-Plus Network Transport (Version 6.3 ECO6 or higher)____________________________________________________ The Installation Verification Procedure (IVP) will complete successfully only if one or both of the supported network protocols (DECnet or TCP/IP) are installed. 1.1.2 License Registration You must register and load your license for Reliable Transaction Router before you start the installation in order to run the Installation Verification Procedure (IVP) and use the software. To register a license under OpenVMS, first log in to the system manager's account, SYSTEM. You then have a choice of two ways to perform the registration: 1. Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, respond with data from your License PAK. 2. At the DCL prompt, enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to License PAK information. If you plan to use Reliable Transaction Router on more than one node in a VMScluster, you will need to perform a license load on the other nodes after you complete this installation (or reboot the cluster). For complete information on using LMF, see the OpenVMS License Management Utility Manual. 1-2 Installing Reliable Transaction Router Version 3.1D for OpenVMS Installing Reliable Transaction Router Version 3.1D for OpenVMS for Reliable Transaction Router Version 3.1D for OpenVMS Installation 1.1.3 Required Disk Space Reliable Transaction Router's requirements for free disk storage space are different during installation and after installation. Table 1-2 summarizes the storage requirements. Table_1-2_Disk_Space_Requirements__________________________ Blocks During Blocks After Kit______________Installation__________Installation________ Reliable 5000 3600 Transaction Router for OpenVMS VAX Reliable 5000 3600 Transaction Router for OpenVMS_Alpha______________________________________________ To determine the number of free disk blocks on the current system disk, enter the following command at the DCL prompt: $ SHOW DEVICE SYS$SYSDEVICE 1.1.4 System Parameters Installing Reliable Transaction Router Version 3.1D for OpenVMS requires certain system parameter settings. Table 1-3 lists the minimum required system parameter values for the installation. Depending on the kinds of programs and applications running at your site, you may need higher values for some settings. Table_1-3_Minimum_Required_System_Parameter_Values_________ System_Parameter___________Minimum_Value___________________ GBLPAGES 4500 GBLSECTIONS 6 GBLPAGFIL__________________Same_as_GBLPAGES________________ Please refer to your OpenVMS documentation for guidance on how to change system parameters. Installing Reliable Transaction Router Version 3.1D for OpenVMS 1-3 Installing Reliable Transaction Router Version 3.1D for OpenVMS 1.2 The Installation Procedure 1.2 The Installation Procedure It is recommended that you log on to the System Manager's account to do the installation. The installation procedure takes about five minutes to complete. The Reliable Transaction Router installation procedure uses the POLYCENTER Software Installation Utility (PCSI). For details on using PCSI, refer to the OpenVMS System Manager's Manual, Section "Installing with the POLYCENTER Software Installation Utility". The logical name PCSI$SOURCE is used to define the location of the software kits you want to install. For example, if the Reliable Transaction Router software is located in DISK1:[KITS], enter the following at the DCL prompt (or include the line in the system manager's login command file): $ DEFINE PCSI$SOURCE DISK1:[KITS] When running the installation procedure for Reliable Transaction Router, you can choose whether to install the ODBC Over RTR Oracle7 Server. This is an RTR server used for supporting ODBC-enabled applications on Windows. You should not install the ODBC Over RTR Oracle7 Server unless you already have Oracle7 installed. 1.3 Running the Reliable Transaction Router Version 3.1D for OpenVMS PCSI Installation To start the installation, type the command:- $ PRODUCT INSTALL RTR You will see a display similar to the following:- The following product has been selected: DEC VAXVMS RTR V3.1-D165 Do you want to continue? [YES] Press . 1-4 Installing Reliable Transaction Router Version 3.1D for OpenVMS Installing Reliable Transaction Router Version 3.1D for OpenVMS Reliable Transaction Router Version 3.1D for OpenVMS PCSI Installation *** DEC VAXVMS RTR V3.1-D165: Reliable Transaction Router for OpenVMS Copyright Digital Equipment Corporation 1988, 1997. All rights reserved. This product uses the PAKs RTR-CL and RTR-SVR. Do you want all the default values for this product? [YES] If you do not want to install the optional software ODBC Over RTR Oracle7 Server, press . Do you want to view the values? [NO] y Press to execute the installation, or press y and if you want to view the installation values (the default values are shown here):- DEC VAXVMS RTR V3.1-D165: Reliable Transaction Router for OpenVMS Have all RTR processes on the system been stopped?: YES ODBC Over RTR Oracle7 Server: NO Run installation verification procedure: NO DECnet users:Have you read the Release Note regarding minimum version?: YES Are you satisfied with the values? [YES] Press to execute the installation, or reply n if you want to change any of the values. Execution phase starting ... The following product will be installed: DEC VAXVMS RTR V3.1-D165 %PCSI-I-VOLINFO, estimated space information for volume DISK$OPENVMS070 -PCSI-I-VOLSPC, 2811 required; 1318494 available; 1315683 net Portion done: 0%...10%...20%...30%...50%...60%...80%...90%...100% The following product has been installed: DEC VAXVMS RTR V3.1-D165 *** DEC VAXVMS RTR V3.1-D165: 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 $ Installing Reliable Transaction Router Version 3.1D for OpenVMS 1-5 Installing Reliable Transaction Router Version 3.1D for OpenVMS 1.4 After Installing Reliable Transaction Router 1.4 After Installing Reliable Transaction Router 1.4.1 Running the Installation Verification Procedure (IVP) You may run the Installation Verification Procedure (IVP) after installing RTR by entering the command:- $ @SYS$TEST:RTR$IVP If the IVP is successful, you will see the message:- $ The IVP has completed successfully See Appendix A for an example run of the IVP. 1.4.2 Accessing Release Notes To access the Reliable Transaction Router Release Notes, type the command:- $ PRODUCT EXTRACT RELEASE_NOTES RTR /file=rtr_relnotes.txt You should read the Release Notes before using Reliable Transaction Router. After installation, the Release Notes are available in [SYS$HELP]. 1.4.3 Editing the System Files You must edit the system startup and shutdown files to provide for automatic startup and the installation of Reliable Transaction Router images when your system is rebooted. Add the command line that starts Reliable Transaction Router to the system startup file, SYS$MANAGER:SYSTARTUP_ VMS.COM. Reliable Transaction Router cannot start until after the network has started. You must position this new command line after the line(s) that invokes the network startup command procedures. Add the command line that stops Reliable Transaction Router to the system shutdown file, SYS$MANAGER:SYSHUTDWN.COM. 1-6 Installing Reliable Transaction Router Version 3.1D for OpenVMS Installing Reliable Transaction Router Version 3.1D for OpenVMS 1.4 After Installing Reliable Transaction Router 1.4.4 Removing Reliable Transaction Router If you wish to remove Reliable Transaction Router, use the command $ PRODUCT REMOVE RTR 1.4.5 User Account Requirements To work with Reliable Transaction Router, user accounts on your system must have certain privileges and quotas. The next two sections contain information on these requirements. 1.4.5.1 Quotas Table 1-4 summarizes the required user account quotas. Table 1-4 User Account Quotas for Using Reliable __________Transaction_Router_______________________________ Account_Quota____Value_____________________________________ ASTLM At least 2000 BIOLM At least 2000 BYTLM At least 150000 [1] DIOLM At least 2000 TQELM At least 2000 [1]At_least_80000_for_accounts_running_RTR_applications.___ At least 150000 for accounts running the RTR ACP. This may need to be increased to accommodate large numbers of application programs and/or users. The formula to use is: 32K + 32K * n where n equals the number of application processes plus the number of users in the ACP's group. ___________________________________________________________ 1.4.5.2 Privileges To use the features of Reliable Transaction Router, each account must have the following privileges:- o NETMBX o TMPMBX o SYSLCK Installing Reliable Transaction Router Version 3.1D for OpenVMS 1-7 Installing Reliable Transaction Router Version 3.1D for OpenVMS 1.4 After Installing Reliable Transaction Router The RTR System Manager (that is, the account that starts up RTR and creates facilities) must also have either OPER privilege or have the Rights Identifier RTR$OPERATOR. Please refer to your OpenVMS documentation for guidance on how to change user account quotas and privileges. 1-8 Installing Reliable Transaction Router Version 3.1D for OpenVMS A _________________________________________________________________ Sample Listings This appendix provides sample listings for the following procedures: o An installation of RTR on OpenVMS using disk media. o An Installation Verification Procedure (IVP) for RTR on OpenVMS. A.1 Sample RTR for OpenVMS Installation $ define pcsi$source _DKA0:[KIT] $ product install rtr The following product has been selected: DEC VAXVMS RTR V3.1-D165 Do you want to continue? [YES] *** DEC VAXVMS RTR V3.1- D165: Reliable Transaction Router for OpenVMS Copyright Digital Equipment Corporation 1988, 1997. All rights reserved. This product uses the PAKs RTR-CL and RTR-SVR. Do you want all the default values for this product? [YES] Do you want to view the values? [NO] Execution phase starting ... The following product will be installed: DEC VAXVMS RTR V3.1-D165 %PCSI-I- VOLINFO, estimated space information for volume DISK$OPENVMS070 -PCSI-I-VOLSPC, 2811 required; 1318512 available; 1315701 net Portion done: 0%...10%...20%...30%...50%...60%...80%...90%...100% The following product has been installed: DEC VAXVMS RTR V3.1-D165 Sample Listings A-1 Sample Listings A.1 Sample RTR for OpenVMS Installation *** DEC VAXVMS RTR V3.1- D165: 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 $ A.2 Sample RTR for OpenVMS Installation Verification Procedure $ @SYS$TEST:RTR$IVP Starting RTR installation verification procedure. Copyright Digital Equipment Corporation 1988, 1997. All rights reserved. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt. III, as applicable. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Stopping RTR if previously started A-2 Sample Listings Sample Listings A.2 Sample RTR for OpenVMS Installation Verification Procedure %RTR-S-RTRSTART, RTR started on node BOVRIL %RTR-S-FACADDED, facility rtr$ivp_facility added %RTR-S-OK, normal successful completion %RTR-S-OK, normal successful completion %RTR-S-OK, normal successful completion channel name: SRVCHAN msgsb msgtype: rtr_mt_opened msglen: 8 message status: normal successful completion reason: 0x00000000 %RTR-S-OK, normal successful completion channel name: CLICHAN msgsb msgtype: rtr_mt_opened msglen: 8 message status: normal successful completion reason: 0x00000000 %RTR-S-OK, normal successful completion %RTR-S-OK, normal successful completion %RTR-S-OK, normal successful completion channel name: SRVCHAN msgsb msgtype: rtr_mt_msg1 msglen: 8 usrhdl: 000 tid: 0,0,0,0,0,f8742457,e70f2001 message offset bytes text 000000 52 54 52 5F 49 56 50 00 RTR_IVP. %RTR-S-OK, normal successful completion channel name: SRVCHAN msgsb msgtype: rtr_mt_accepted msglen: 8 usrhdl: 000 tid: 0,0,0,0,0,f8742457,e70f2001 message status: normal successful completion reason: 0x00000000 %RTR-S-OK, normal successful completion Sample Listings A-3 Sample Listings A.2 Sample RTR for OpenVMS Installation Verification Procedure channel name: CLICHAN msgsb msgtype: rtr_mt_accepted msglen: 8 usrhdl: 000 tid: 0,0,0,0,0,f8742457,e70f2001 message status: normal successful completion reason: 0x00000000 Copyright Digital Equipment Corporation 1994, 1997. All rights reserved. %RTR-S-OK, normal successful completion %RTR-S-OK, normal successful completion The IVP has completed successfully %RTR-S-RTRSTOP, RTR stopped on node BOVRIL %RTR-I-SRVDISCON, server disconnected on node BOVRIL $ A-4 Sample Listings B _________________________________________________________________ Files Installed This appendix lists the files added to your system by the installation on OpenVMS. B.1 Files Added [sys$startup]rtr$startup.com [sysexe]rtr.exe [sysexe]rtr$remote.com [sysexe]rtr_start_acp.com [syslib]rtr.h [syslib]librtr.exe [sysmgr]rtr$snapshot.com [sysmgr]rtr$shutdown.com [systest]rtr$ivp.com [syshlp]rtr_relnotes.txt [syshlp]rtr_relnotes.ps [syshlp]rtr.hlb Files Installed B-1 Files Installed B.1 Files Added [rtr]ACCFAIL.mon [rtr]ACP2APP.mon [rtr]ACTIVE.mon [rtr]APP2ACP.mon [rtr]CALLS.mon [rtr]CHANNEL.mon [rtr]CONGEST.mon [rtr]CONNECT.mon [rtr]CONNECTS.mon [rtr]DDTM.mon [rtr]DTX.mon [rtr]DTXREC.mon [rtr]FACILITY.mon [rtr]FLOW.mon [rtr]FRONTEND.mon [rtr]GROUP.mon [rtr]INBYTES.mon [rtr]INMESS.mon [rtr]INPACK.mon [rtr]IPC.mon [rtr]JCALLS.mon [rtr]JOURNAL.mon [rtr]LINK.mon [rtr]LOCKS.mon [rtr]OUTBYTES.mon [rtr]OUTMESS.mon [rtr]OUTPACK.mon [rtr]PARTIT.mon [rtr]QUEUES.mon [rtr]QUORUM.mon [rtr]RDM.mon [rtr]RECOVERY.mon [rtr]ROLEQUOR.mon [rtr]ROUTERS.mon [rtr]ROUTING.mon [rtr]RTR.mon [rtr]STALLS.mon [rtr]TPS.mon [rtr]TPSLO.mon [rtr]TRAFFIC.mon [rtr]TRANS.mon [rtr]V2CALLS.mon B-2 Files Installed Files Installed B.1 Files Added [sysmsg]oormsg.exe (optional component) [syslib]oorcmp.exe (optional component) [sysexe]ooro7v2.exe (optional component) Files Installed B-3