1 _________________________________________________________________ Installing BASEstar Graphics Enabler on Digital UNIX Systems This chapter describes how to install the BASEstar Graphics Enabler. Before starting the installation procedures, you should complete the preparation requirements. You will need to know about and be aware of your installation options and information related to the installation procedure. Preparing for BASEstar Graphics Enabler Installation The following sections provide the necessary information to make your installation run smoothly, and will help you determine the following: o How to read the online release notes. o How to register your License Product Authorization Key (PAK). o How to determine if your distribution kit is complete. o What superuser privileges you need for the system on which you will be installing the BASEstar Graphics Enabler. o If the system on which you will install BASEstar Graphics Enabler meets the BASEstar Graphics Enabler hardware, software, and disk space requirements. o Which optional BASEstar Graphics Enabler subsets you should install. o How much disk space you will need. o Whether you have to back up your system disk. BASEstar Graphics Enabler User's Guide 1-1 Installing BASEstar Graphics Enabler on Digital UNIX Systems Reading the Online Release Notes BASEstar Graphics Enabler provides online release notes. Digital strongly recommends that you read the release notes before using the product. The release notes may contain information about changes to the application. Your documentation also includes the Read Before Installing letter. This letter provides information that is important for you to know before installing the BASEstar Graphics Enabler. After BASEstar Graphics Enabler installation, you can access the online release notes contained in the /usr/opt/bge230/doc directory. In addition, this directory contains files having the .ps extension (PostScript files) and files with the .txt extension (text files). Registering Your Software License The BASEstar Graphics Enabler includes support for the License Management Facility (LMF). You must register your License Product Authorization Key (License PAK) in the License Database (LDB) order to use BASEstar Graphics Enabler on a newly licensed node. The License PAK may be shipped along with the kit if you ordered the license and media together; otherwise, it is shipped separately to a location based on your license order. If you are installing BASEstar Graphics Enabler as an update on a node already licensed for this software, you have already completed the License PAK registration requirements. If you are installing prerequisite or optional software along with BASEstar Graphics Enabler, review the PAK status and install the PAKs for any prerequisite or optional software before you install BASEstar Graphics Enabler. To register a license under the Digital UNIX system, first log in as superuser. At the superuser prompt, edit an empty PAK template with the lmf register command and include all the information on your License PAK as follows: # lmf register 1-2 BASEstar Graphics Enabler User's Guide Preparing for BASEstar Graphics Enabler Installation After you register your license, use the following lmf reset command to copy the license details from the License Database (LDB) to the kernel cache: # lmf reset For complete information on using the License Management Facility, see the Guide to Software License Management or the lmf(8) reference page. Checking the Software Distribution Kit If you are installing the software from media, use the bill of materials (BOM) to check the contents of your software distribution kit. The kit includes includes this user's guide and the TK50 tape cartridge, labeled BASEstar Graphics Enabler for systems with TK50 or TK70 tape cartridge drives. Your distribution kit includes a letter titled Read Before Installing BASEstar Graphics Enabler. This letter provides information that is important for you to know before installing BASEstar Graphics Enabler and may not be included in this installation guide. Please find this letter and read it now. Installation Procedure Requirements This section discusses various requirements for installing BASEstar Graphics Enabler. Installing BASEstar Graphics Enabler and running the Installation Verification Procedure (IVP) on your target system takes 5 to 15 minutes. Checking Login Privileges You must have superuser privileges on the system where you are installing BASEstar Graphics Enabler. Hardware Requirements To perform the installation, you need the following hardware: o Software distribution device (if installing from media) BASEstar Graphics Enabler User's Guide 1-3 Installing BASEstar Graphics Enabler on Digital UNIX Systems You need a distribution device that corresponds with the software distribution media. For example, if you have a TK50 software kit, you need a TK50 or TK70 tape drive. The documentation for the tape or disk drive that you are using explains how to load the media on the drive. o Terminal You can use a hardcopy or video terminal to communicate with the operating system and respond to prompts. Software Requirements BASEstar Graphics Enabler Version 2.3 requires that Digital UNIX Version 3.0 or higher be installed. In addition, BASEstar Graphics Enabler requires that the following software subsets be loaded on the system where you install BASEstar Graphics Enabler: o OSFX11 - Basic X Environment (Windowing Environment) The following BASEstar software is optional for the BASEstar Graphics Enabler: o BASEstar Open Version 3.0 If you are installing BASEstar Graphics Enabler in a local (node-specific) environment, perform the following steps to determine whether the preceding subsets are loaded: 1. Log in to the system where you plan to install BASEstar Graphics Enabler as root or become superuser. 2. Enter the following command: # /usr/sbin/setld -i | grep OSFX11 Check the displayed rows for the relevant subset names and for any related patch names. The word installed appears in a row after the subset identifier code when a subset is loaded. If the word installed does not appear (the second column in a row is blank), the subset or patch is not loaded. In this case, you must load the missing software before installing BASEstar Graphics Enabler. 1-4 BASEstar Graphics Enabler User's Guide Preparing for BASEstar Graphics Enabler Installation Determining Which Subsets to Load You may load the following BASEstar Graphics Enabler subsets, none of which are required: o BASEstar Graphics Enabler Development Component Contains the graphical editor and tools for developing models. The subset identifier is BGEDEV230. o BASEstar Graphics Enabler Runtime Component Contains the utility for running models and connecting to BASEstar data. The subset identifier is BGERT230. o BASEstar Graphics Enabler Programming Component Contains SL-GMS include files and programming support tools. The subset identifier is BGEPROG230. BASEstar Graphics Enabler User's Guide 1-5 Installing BASEstar Graphics Enabler on Digital UNIX Systems o BASEstar Graphics Enabler Demo Component Contains the SL-GMS demos. The subset identifier is BGEDEMO230. o BASEstar Graphics Enabler Release Notes Contains the release notes. The subset identifier is BGEREL230. Determining Disk Space Requirements Table 1-1 lists the disk space requirements for loading BASEstar Graphics Enabler software subsets. This table specifies disk space requirements by file system for the convenience of doing installations on systems where these file systems are mount points for different disk partitions. Table_1-1_Worksheet_for_Subset_Sizes_(in_Megabytes)________ Subset Subset_Title__________Name________/usr/opt/usr/var/opt_____ BASEstar Graphics BGEDEV 28.3 0 Enabler BGERT 3.8 0 BGEPROG 0.7 0 BGEDEMO 12.0 0 BGEREL 0.3 0 Totals:___________________________45.1____0________________ Using the disk space requirements in Table 1-1, total the values for the subsets that you plan to load in each file system. Compare the space required for subsets with the free space currently on the disks where BASEstar Graphics Enabler files will reside. To determine the current amount of free space for a directory path, log in to the system where you plan to install the BASEstar Graphics Enabler. 1-6 BASEstar Graphics Enabler User's Guide Preparing for BASEstar Graphics Enabler Installation You can check which file systems are mounted and where they are by displaying the file /etc/fstab. For example: # more /etc/fstab /dev/rd0a:/:rw:1:1:ufs:: /dev/rd0g:/usr:rw:1:2:ufs:: The display indicates that /usr (mounted to /dev/rd0g ) is the only mount point that affects where BASEstar Graphics Enabler files will reside. The system has only one local disk drive, and the /usr/opt and /usr/var/opt file systems reside in the g partition of the disk on that drive. Enter the df command to determine total space and free space for the one or two file systems where BASEstar Graphics Enabler files will reside. Based on the previous display of the /etc/fstab file, which shows that only /usr is a mount point, you would only need to inspect free space in the /usr file system. For example: # df -k /usr Filesystem Total kbytes kbytes % node kbytes used free used Mounted on /dev/rd0g 122598 54447 55892 49% /usr The display indicates that there are 55892 Kbytes free. This free space must accommodate subset requirements listed in Table 1-1 for both the /usr/opt and /usr/var/opt file systems. On systems where /usr/opt and /usr/var/opt are mounted to different devices from /usr, enter the following command: # df /usr/opt /usr/var/opt In this case, you compare space required for BASEstar Graphics Enabler files in /usr/opt to the free space displayed in the first line of the df output list, and you compare the space required for BASEstar Graphics Enabler files in /usr/var/opt to the free space displayed in the second line of that list. BASEstar Graphics Enabler User's Guide 1-7 Installing BASEstar Graphics Enabler on Digital UNIX Systems Increasing Disk Space Available for BASEstar Graphics Enabler Installation The BASEstar Graphics Enabler installation procedure creates the following directories and loads files into subordinate directories: # /usr/opt/bge230 If the bge230 directory node in the previous paths does not exist, the installation procedure creates it. If the bge230 node in the previous paths does exist, the installation procedure uses it. If you find that there is insufficient disk space for the BASEstar Graphics Enabler subsets, and know that you have additional space on alternative disks or disk partitions for your system, perform the following steps before installing BASEstar Graphics Enabler: 1. Log in as root or become superuser. 2. Create the directory /usr/opt/bge230. 3. Specify in the /etc/fstab file that one or more of the newly created directories are mount points to new disk partitions where there is additional space. 4. Enter the mount -a command so that the new mount points take effect. Backing Up Your System Disk Digital recommends that you back up your system disk before installing any software. For details on performing a system disk backup, see your Digital UNIX documentation. Stopping the Installation You can stop the installation procedure any time by using Ctrl/C. However, files created up to this point are not deleted automatically. You must delete these files interactively. Table 1-2 lists the files and directories created during the installation procedure. 1-8 BASEstar Graphics Enabler User's Guide Preparing for BASEstar Graphics Enabler Installation Error Recovery If errors occur during the installation, the system displays failure messages. If the installation fails due to insufficient disk space, a message such as the following appears: There is not enough file system space to install the specified subsets. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o The prerequisite software version is incorrect. For descriptions of error messages generated by these conditions, see the Digital UNIX documentation on system messages, recovery procedures, and Digital UNIX software installation. For information on system software requirements, see the section titled Software Requirements. If an error occurs while using BASEstar Graphics Enabler and you believe the error is caused by a problem with BASEstar Graphics Enabler, take one of the following actions: o If you have a basic or DECsupport Software Agreement, call your Customer Support Center (CSC). The CSC provides telephone support for high-level advisory and remedial assistance. o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). o If you purchased BASEstar Graphics Enabler within the last 90 days and you think the problem is caused by a software error, you can submit an SPR. If you find an error in the BASEstar Graphics Enabler documentation, fill out and submit one of the Reader's Comments forms at the back of the document containing the error. Include the section and page number where the error occurred. BASEstar Graphics Enabler User's Guide 1-9 Installing BASEstar Graphics Enabler on Digital UNIX Systems Installing BASEstar Graphics Enabler This section describes the installation procedures for BASEstar Graphics Enabler. Starting the Installation Procedure Start the installation procedure as follows: 1. Mount the media on the appropriate tape drive. 2. Log in as superuser (login name root) to the system where you are installing BASEstar Graphics Enabler. 3. Enter the following command to ensure that you are at the root (/) directory: # cd / 4. Enter a setld command that specifies the -l (load) function and the device special file name for the tape drive where the media is mounted. For example, if you load a magnetic tape on tape unit 0, enter the following command: # /usr/sbin/setld -l /dev/rmt0h The installation procedure displays the following information and prompt: Please make sure your installation tape is mounted and on-line. Are you ready (y/n)? After all tape rewind and wind operations are complete and the tape drive indicates online status, enter y. 1-10 BASEstar Graphics Enabler User's Guide Installing BASEstar Graphics Enabler Selecting Subsets After you enter the setld command for local (node-specific) installations or after you start the dms or ris utility for server installations, the installation procedure displays the names of the BASEstar Graphics Enabler subsets and asks you to specify the subsets that you want to load: *** Enter Subset Selections *** The subsets listed below are optional: 1) BGE Development Component 2) BGE Runtime Component 3) BGE Programming Component 4) BGE Demo Component 5) BGE Release Notes 6) All of the Above 7) None of the Above 8) Exit without installing subsets Enter your choice(s): 6 When installing from a RIS server, note that the subset numbers may vary depending on what products are available in the RIS area. If you specify more than one number at the prompt, separate each number with a space, not a comma. Next, the script lets you verify your choice. For example, if you enter 2 in response to the previous prompt, you will see the following display: You are installing the following subsets: BGE Development Component BGE Runtime Component BGE Programming Component BGE Demo Component BGE Release Notes Is this correct? (y/n): Y If the displayed subsets are not the ones you intended to choose, enter n. In this case, the subset selection menu is again displayed, and you can correct your choice of optional subsets. BASEstar Graphics Enabler User's Guide 1-11 Installing BASEstar Graphics Enabler on Digital UNIX Systems If the displayed subsets are the ones you want to load, enter y. 1-12 BASEstar Graphics Enabler User's Guide Installing BASEstar Graphics Enabler Monitoring Displays During the Subset Loading Process The procedure displays a message that the installation is starting: BGE Development Component (BGEDEV230) Copying from . (disk) Working....Thu Mar 14 17:30:32 EST 1996 Verifying Working....Thu Mar 14 17:32:51 EST 1996 BGE Runtime Component (BGERT230) Copying from . (disk) Working....Thu Mar 14 17:33:33 EST 1996 Verifying BGE Programming Component (BGEPROG230) Copying from . (disk) Verifying BGE Demo Component (BGEDEMO230) Copying from . (disk) Working....Thu Mar 14 17:35:00 EST 1996 Verifying Working....Thu Mar 14 17:37:00 EST 1996 BGE Release Notes (BGEREL230) Copying from . (disk) Verifying The section titled Completing the Installation discusses the postinstallation requirements specified in the final informational messages from the procedure. If, during the course of the installation, you encounter errors from the setld utility, see the Diagnostics section of the setld(8) reference page for an explanation of the error and the appropriate action to take. If the verification process fails, you can look in the file /usr/var/adm/fverify to find information that can help you diagnose the problem. BASEstar Graphics Enabler User's Guide 1-13 Installing BASEstar Graphics Enabler on Digital UNIX Systems Files Created During Installation Table 1-2 describes the contents of BASEstar Graphics Enabler directories. The directories are created under the installation directory (default /usr/opt/bge230. There are other files supplied by SL-GMS. Table_1-2_BASEstar_Graphics_Enabler_Installation_Files___________ Directory_____File__________Description__________________________ bin bgebind Executables distributed with BASEstar bgerun Graphics Enabler. bgeui lib bge_msgs.msf Binary message file. bge_msgf.cat ASCII message file. libbgerun.a Library to link when incorporating user-written callable functions. bgeui.uid BASEstar Graphics Enabler user interface description file. demo *.* Demo files. doc release_ Release notes formatted in text notes.txt output, suitable for displaying on a terminal or printing from a line printer. release_ Release notes formatted in PostScript notes.ps output. etc bgeusers.csh BASEstar Graphics Enabler setup ______________bgeusers.sh___script.______________________________ Completing the Installation The following sections explain what you need to do following the installation to make BASEstar Graphics Enabler ready for use. 1-14 BASEstar Graphics Enabler User's Guide Completing the Installation Executing the BASEstar Graphics Enabler User Script The BASEstar Graphics Enabler installation creates two scripts, bgeusers.csh and bgeusers.sh, in the system directory /etc. These scripts set up the environment for using the BASEstar Graphics Enabler. Depending on which shell you are using, BASEstar Graphics Enabler users will execute the appropriate .csh or .sh script before using the BASEstar Graphics Enabler features from an Digital UNIX account. Environment Variables The BASEstar Graphics Enabler uses the following environment variables: o BGE_DOMAIN - Specifies the BASEstar Open domain to be used. You can also use BGE_PREFIX. o BGE_ENBOX - Provides a name for a BASEstar Open Enbox object which will be created when a model is run. If this variable is not set, a unique Enbox name will be created. o BGE_MODELS-Provides a directory search list for locating model and binding files, in addition to the current default directory. This search list is used when creating binding files and when running models. If this logical name is not defined, only the current working directory will be used. o BGE_PREFIX - Provides a string which is preappended to the names of source objects. This can also be used to specify the Domain. o BGE_DB - Makes the INGRES and ORACLE databases known to the operating system. o BGE_WCPF-Provides an integer value to specify a World Coordinate Pixel Factor for all data sources. BASEstar Graphics Enabler User's Guide 1-15