ObjectBroker__________________________________ Installation Guide December 1996 This guide provides information about how to install the ObjectBroker Version 2.7 software on Digital UNIX computers. Software Version: ObjectBroker Version 2.7 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1996. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: Alpha, DEC, DECnet, Digital, ObjectBroker, OpenVMS, PATHWORKS, ULTRIX, VAX, VMScluster, VMS, and the DIGITAL logo. The following are third-party trademarks: HP and HP-UX are registered trademarks of Hewlett- Packard Company. IBM and AIX are registered trademarks of International Business Machines Corporation. Intel is a trademark of Intel Corporation. Macintosh is a registered trademark of Apple Computer, Inc. Microsoft, MS-DOS, Visual Basic are registered trademarks and Windows and Windows NT are trademarks of Microsoft Corporation. Motif, OSF, and OSF/1 are registered trademarks and Open Software Foundation is a trademark of the Open Software Foundation, Inc. Novell is a registered trademark of Novell, Inc. OMG is a registered trademark and CORBA, COSS, OMG IDL, Object Request Broker, and ORB are trademarks of the Object Management Group. Sun is a registered trademark and SPARCstation is a trademark of Sun Microsystems, Inc. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. All other trademarks and registered trademarks are the property of their respective holders. This document was prepared using VAX DOCUMENT Version 2.1. ________________________________________________________________ Preface Purpose of This Manual This manual explains how to install ObjectBroker Version 2.7 on each supported platform. Intended Audience This manual is written for system administrators and system integrators who are responsible for installing the ObjectBroker software. Structure of This Manual This manual contains two chapters, as follows: o Chapter 1 provides an overview of the installation process. o Chapters 2 describes how to install ObjectBroker on Digital UNIX platforms. Conventions Table 1, General Coding and Operating System-Specific Conventions explains the conventions that are used throughout this guide. v Table 1 General Coding and Operating System-Specific ________Conventions_______________________________________ Convention__Meaning_______________________________________ ... A horizontal ellipsis indicates one of the following conditions: o The statement omits additional optional arguments. o You can repeat the preceding item or items one or more times. o You can enter additional parameters, values, or other information. . A vertical ellipsis indicates the omission of . items from a code example or from a command . format. The author omitted the items because they are not important to the topic being discussed. ( ) In syntax diagrams, parentheses indicate that if you choose more than one option, you must enclose the choices in parentheses. [ ] In syntax diagrams, brackets indicate that whatever is enclosed in the brackets is optional. { } In syntax diagrams, braces indicate that you must choose at least one of the options listed. | In syntax diagrams, a vertical bar inside brackets or braces indicates that you should choose one of the items listed. # The number sign represents the Digital UNIX prompt. (The UNIX prompt on your system may be different.) (continued on next page) vi Table 1 (Cont.) General Coding and Operating System- ________________Specific_Conventions______________________ Convention__Meaning_______________________________________ monospaced Monospaced text indicates ObjectBroker file text names, operations, values, routine names, attributes, command names (including command switches and switch parameters), and system output. Monospaced text also indicates text that you must enter from the keyboard. boldface Boldface text indicates arguments, field text names, and terms that are defined in the glossary. (The ObjectBroker Introduction and Glossary contains the glossary.) italic Italic text indicates either the author's text emphasis or information that can vary, such as a command parameter. UPPERCASE Uppercase letters indicate attribute names, text attribute values, error message names, data types, and flag values. lowercase Lowercase text in the monospace font indicate monospace UNIX command names and command switches. text UNIX________The_term_UNIX_refers_to_Digital_UNIX_systems._ For More Information For more information about ObjectBroker, CORBA, C++ bindings, and the OMG, see the following documents and World Wide Web sites: o ObjectBroker Introduction and Glossary-The entry point into the ObjectBroker information set for all audiences. o ObjectBroker Using QuickStart-Describes how to use the QuickStart development tool to generate the components needed for a client and server system. vii o ObjectBroker Guide to Examples-Describes how to use and build a set of progressive ObjectBroker examples in C; also includes an example in C++. This manual is a companion to ObjectBroker Designing and Building Applications. o ObjectBroker Designing and Building Applications- Contains detailed information about how to design, develop, and deploy an application using ObjectBroker. o ObjectBroker Installation Guide (this manual)-Describes how to install the ObjectBroker software. o ObjectBroker Administration Guide-Describes how to configure, administer, and troubleshoot the ObjectBroker software. o ObjectBroker Programming Reference-Contains routine descriptions for ObjectBroker's C, C++, and Visual Basic language bindings, as well as authentication routines and server management routines. This manual also includes information about the OMG IDL, IML, and MML definition languages, and ObjectBroker error messages. o ObjectBroker Commands and Utilities Reference-Describes the ObjectBroker commands and graphical user interface utilities. o Understanding CORBA-Describes the CORBA specification and explains how to design, develop, and deploy a CORBA application. This manual is vendor neutral; it describes how to create a CORBA client and server application using the vendor's CORBA product, not just Digital's ObjectBroker product. This manual is a companion to ObjectBroker Designing and Building Applications. o The Common Object Request Broker Architecture and Specification, Revision 2.0, published July 1995 by the Object Management Group. o ObjectBroker World Wide Web site at http://www.digital.com /info/objectbroker. o OMG World Wide Web site at http://www.omg.org. viii 1 ________________________________________________________________ Overview of the Installation Process This chapter gives a high-level overview of the ObjectBroker installation process for all supported platforms. ObjectBroker consists of two products: the run-time kit, and the development kit. Each product is available on a separate distribution volume. Use the following guidelines to determine which kit to install on a given computer. Run-time kit Install the ObjectBroker run-time kit on all licensed systems that run ObjectBroker applications. To deploy ObjectBroker, you must have the appropriate platform-specific ObjectBroker run-time license for each system included in the deployment. Development kit Install the ObjectBroker development kit on all licensed systems that you use for ObjectBroker application development. The development kit includes the run-time kit and example programs that demonstrate features and capabilities of the ObjectBroker software. To develop ObjectBroker applications, you must have the appropriate platform- specific ObjectBroker development license per computer on which ObjectBroker is used to develop, compile, and/or link applications. ________________________Note ________________________ You install only one kit on a given computer. Do not install both the run-time kit and the development kit on a single computer. You must also have the prerequisite operating systems, network transport(s), and compiler(s) (for Overview of the Installation Process 1-1 Overview of the Installation Process development) that are specified in the ObjectBroker Software Product Descriptions (SPDs). _____________________________________________________ The Release Notes, available only on line, contain important information about the software. ________________________Note ________________________ If your ObjectBroker kit is on a CD-ROM, you have the ability to read the Release Notes before installation, which we recommend that you do. (For other media types, such as tape or diskette, you must complete the ObjectBroker installation procedure before you can access the Release Notes.) On CD-ROM kits, the Release Notes are located in the docs directory in the file release.nts. Regardless of the media from which you install your ObjectBroker software, the Release Notes are copied into /usr/doc ObjectBroker027.release_notes. _____________________________________________________ After you complete the ObjectBroker installation process, refer to the ObjectBroker Administration Guide for details on customizing, configuring, and managing your ObjectBroker system. 1-2 Overview of the Installation Process 2 ________________________________________________________________ Installing ObjectBroker on Digital UNIX Systems 2.1 Disk Space Requirements The following table lists the disk space used by ObjectBroker Version 2.7 both during and after the installation procedure: __________________________________________________________ Used During ______________Installation_____Used_After_Installation____ Run-time kit 8.0 MB 6.6 MB Development 14.2 MB 12.7 MB kit_______________________________________________________ 2.2 Before You Begin Before you start the installation, answer the following questions: o Is your system running Digital UNIX Version 3.2 or later up to Version 4.0 with patch OSF400-019? o Do you have the required minimum amount of free disk space? o Do you have the prerequisite network transport and compiler(s) (if you are installing the development kit) that are specified in the ObjectBroker Software Product Description (SPD)? The SPD is included in every ObjectBroker kit. o Are you using TCP/IP (included with the base operating system) as your transport? o Have you backed up your system disk? Installing ObjectBroker on Digital UNIX Systems 2-1 Installing ObjectBroker on Digital UNIX Systems 2.2 Before You Begin o Do you have the Product Authorization Key (PAK) that contains the information you need to register the ObjectBroker license with the License Management Facility (LMF)? If the answer to any question is "No," you do not have the hardware or software required to use the product. Obtain the required hardware and software, and then proceed. If the answer to all of the questions is "Yes," complete the procedure explained in Section 2.4 to perform a local installation on a Digital UNIX system. 2.3 Upgrade Notes Please note the following information if you are upgrading to ObjectBroker Version 2.7 from an earlier version of ObjectBroker. o If you remove a previously installed version of ObjectBroker: If you first use the setld command with the -d (delete) option to remove the OBBBASE*250, OBBBASE*251, OBBBASE*252, OBBBASE*253, OBBBASE*260, or OBBBASE*261 subsets before you install ObjectBroker Version 2.7, you will lose your ObjectBroker system registries, the ObjectBroker system repository, and the system context object. o If you do not remove a previously installed version of ObjectBroker: If you do not use the setld command with the -d option to remove an earlier version of ObjectBroker before installing ObjectBroker Version 2.7, the installation procedure puts ObjectBroker Version 2.7 (subsets OBB*270) into its own directory tree (/usr/kits /OBB270), and retains all existing ObjectBroker system registries, the ObjectBroker system repository, and the system context object. At the end of the installation, the installation procedure asks if you want to remove the directory tree that contains the earlier version of ObjectBroker. 2-2 Installing ObjectBroker on Digital UNIX Systems Installing ObjectBroker on Digital UNIX Systems 2.3 Upgrade Notes If you lack adequate disk space on your computer to hold both the new and an earlier version of ObjectBroker, complete the following procedure to preserve the ObjectBroker system registries, the ObjectBroker system repository, and the system context object: 1. Stop the ObjectBroker agent, if you have not done so already, using the following steps: a. Use the obbmsho command to identify all active implementations. Note the identifiers that the system displays. b. Use the identifiers next to the label Inst UUID to stop the active implementation processes one by one, as shown in the following example: # obbmstp 56220ba949cc.0c.00.00.00.00.00.00.00 Redisplay the list of active implementations to verify that the process has been stopped. If the process still exists, re-enter the command using the -a (abort) option, as shown in the following example: # obbmstp -a 56220ba949cc.0c.00.00.00.00.00.00.00 Repeat until all active implementation processes have been stopped. You can use the obbmstp -p command to purge stopped implementations from memory, if desired. c. Stop the ObjectBroker agent itself by entering the following command: # obbmstp -A 2. Copy the /usr/var/adm/ObjectBroker directory, as shown in the following example: # cd /usr/var/adm # cp -r ObjectBroker obb_old 3. Verify that the copy of the directory contains the OBB* files, which hold the ObjectBroker system registries, the ObjectBroker system repository, and the system context object. For example: # ls /usr/var/adm/obb_old/OBB* Installing ObjectBroker on Digital UNIX Systems 2-3 Installing ObjectBroker on Digital UNIX Systems 2.3 Upgrade Notes Although there may be additional backup versions, at a minimum, you should see the following files listed: /usr/var/adm/obb_old/OBB_ADVERTISEMENT_REGISTRY /usr/var/adm/obb_old/OBB_SECURITY_REGISTRY /usr/var/adm/obb_old/OBB_SOFTWARE_REGISTRY /usr/var/adm/obb_old/OBB_SYSTEM_CONTEXT /usr/var/adm/obb_old/OBB_SYSTEM_REGISTRY /usr/var/adm/obb_old/OBB_SYSTEM_REPOSITORY 4. Use the setld command with the -d option to remove the earlier version of ObjectBroker from your system. For example: # setld -d OBBBASEDEV260 OBBMANDEV260 ________________________Note ________________________ To obtain the name of any old ObjectBroker files on your system, enter the following command: # setld -i | grep OBB* _____________________________________________________ 5. Rename the saved directory to /usr/var/adm/ObjectBroker: # mv obb_old ObjectBroker 2.4 Installation Complete the following steps to perform a local installa- tion on a Digital UNIX system: 1. Register your ObjectBroker license before you install the ObjectBroker software. ________________________Note ________________________ If you do not register the license and you do not load the appropriate Product Authorization Key, you will not be able to complete the installation, run the Installation Verification Procedure (IVP), or use ObjectBroker. Refer to the VAX/VMS Licence Management Facility manual for more information about registering 2-4 Installing ObjectBroker on Digital UNIX Systems Installing ObjectBroker on Digital UNIX Systems 2.4 Installation the license and loading the appropriate Product Authorization Key. _____________________________________________________ 2. Log in as superuser (login name root). 3. If any ObjectBroker implementations are running, or if the ObjectBroker agent is running, do the following. a. Use the obbmsho command to identify all active implementations. Note the identifiers that the system displays. b. Use the identifiers next to the label Inst UUID to stop the active implementation processes one by one, as shown in the following example: # obbmstp 56220ba949cc.0c.00.00.00.00.00.00.00 Redisplay the list of active implementations to verify that the process has been stopped. If the process still exists, re-enter the command using the -a (abort) option, as shown in the following example: # obbmstp -a 56220ba949cc.0c.00.00.00.00.00.00.00 Repeat until all active implementation processes have been stopped. You can use the obbmstp -p command to purge stopped implementations from memory, if desired. c. If the ObjectBroker agent is running, stop it by entering the following command: # obbmstp -A Note Stopping the server applications and the agent before the installation, as described in the preceding steps, is usually sufficient to ensure that none of the shared libraries replaced by the installation are in use. However, you may receive one or more error messages during the installation indicating that a file is in use. This may be caused by an ObjectBroker Graphical User Interface (GUI) application or by a VMS command-line facility that is accessing a shared library from a local or Installing ObjectBroker on Digital UNIX Systems 2-5 Installing ObjectBroker on Digital UNIX Systems 2.4 Installation remote node. In this case, you may need to ask the respective users to stop accessing those libraries and start the installation again. d. Delete outdated SAK files, if any exist: # rm /usr/adm/ObjectBroker/sak/* e. Make sure that you are at the root directory: # cd / 4. If you are installing from CD-ROM, mount the installa- tion media. Create the /mnt/cdrom directory, and then enter the following command, substituting your CD-ROM device number for n and using /mnt/cdrom for the mounting point: # mount -t cdfs -o rrip,noversion /dev/rznc /mnt/cdrom Note: you can use the following command to determine the device number of your CD-ROM drive: # file /dev/rrz?c _______________________ Notes _______________________ Without the rrip option, the setld subset names appear as lowercase letters, causing problems with the installation's dependency checking. This results in a failed installation, leaving the file system in a state where the software is not installed and setld -d cannot delete the software. If you installed ObjectBroker from the CD-ROM and the installation fails with the BASE is not installed message, check the contents of /usr/.smdb. /. If there are files named obbbasedev270.* and /or obbmandev270.* rather than OBBBASEDEV270.* and OBBMANDEV270.*, check the options that you used to mount the CD-ROM. _____________________________________________________ 5. Load the software from the distribution media, using the device file name. 2-6 Installing ObjectBroker on Digital UNIX Systems Installing ObjectBroker on Digital UNIX Systems 2.4 Installation If you are installing ObjectBroker from tape, enter the following command: # setld -l /dev/rmt0h If you are installing ObjectBroker from CD-ROM, enter the following command: # setld -l /mnt/cdrom/OBJBROKR/DEC_UNIX 6. The installation procedure displays the subset name for ObjectBroker. Select any optional subsets you want to install: 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) ObjectBroker Base System 2) ObjectBroker Man Pages Or you may choose one of the following options: 3) ALL of the above 4) CANCEL selections and redisplay menus 5) EXIT without installing any subsets Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6): 3 7. Verify your choice. For example, in response to the preceding prompt, your system displays: You are installing the following optional subsets: ObjectBroker Base System ObjectBroker Man Pages Is this correct? (y/n): y Enter y to load the selected subsets. Enter n to redisplay the subset selection menu if you did not select the correct subsets. Then, correct your choice of optional subsets and enter y to load the subsets you selected. Installing ObjectBroker on Digital UNIX Systems 2-7 Installing ObjectBroker on Digital UNIX Systems 2.4 Installation No more questions will be asked. Informational messages that report on the progress of the installation will appear. The installation takes 5 to 15 minutes, depending on your hardware. 2.5 After the Installation After you complete the ObjectBroker installation procedure, we recommend the following steps: 1. Review the Release Notes, which contain important information about this version of ObjectBroker. You can display the Release Notes by entering the following command: # more /usr/doc/ObjectBroker027.release_notes 2. Run the Installation Verification Procedure (IVP). For the ObjectBroker development kit, enter the following command: # setld -v OBBBASEDEV270 For the ObjectBroker run-time kit, enter the following command: # setld -v OBBBASERT270 Note that running the IVP automatically starts the ObjectBroker agent. 3. If your system mounts NFS disks that hold system context object files, ObjectBroker system repository files, and ObjectBroker system registry files that could be accessed by ObjectBroker and its utilities, enable the NFS file locking feature. 4. To have the ObjectBroker agent start automatically when your system is booted, create a symbolic link between the existing file /sbin/init.d/ObjectBroker and a new file named /sbin/rc3.d/S75obb, as in the following example: # ln -s /sbin/init.d/ObjectBroker /sbin/rc3.d/S75obb 5. To unload the CD-ROM, enter the following command : # umount /mnt/cdrom 2-8 Installing ObjectBroker on Digital UNIX Systems