DEC ODA Compound Document Architecture (CDA) Gateway_______________________________________ Installation Guide Order Number: AA-PB6JA-TE April 1991 This document contains instructions for installing the DEC ODA Compound Document Architecture (CDA) Gateway on the VMS operating system. Revision Update Information: This is a new guide. Operating System and Version: VMS Version 5.4 Software Version: DEC ODA Compound Document Architecture (CDA) Gateway Version 1.0 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ April 1991 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 1991. All Rights Reserved. Printed in Ireland. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: CDA, DDIF, DEC, DECchart, DECdecision, DECimage, DECnet, DECpaint, DECUS, DECwindows, DECwrite, DIGITAL, DTIF, LiveLink, MASSBUS, PDP, PrintServer 40, Q-bus, ReGIS, ScriptPrinter, ULTRIX-32, ULTRIX Worksystem Software, UNIBUS, VAX, VAXcluster, VAX RMS, VAXstation, VMS, VT, XUI, and the DIGITAL logo. Lotus 1-2-3 is a registered trademark of Lotus Development Corporation. Helvetica and Times are registered trademarks of Linotype Company. This guide is available on CDROM. This document was prepared using VAX DOCUMENT, Version 1.2. ________________________________________________________________ Contents Preface.................................................. v 1 Before You Install the ODA CDA Gateway 1.1 Prerequisite Software........................ 1-1 1.2 Accessing the Online Release Notes........... 1-1 1.3 Installation Procedure Requirements.......... 1-1 1.4 User Account Quotas and Privileges........... 1-2 1.5 VMS License Management Facility.............. 1-2 1.6 Using VMSINSTAL.............................. 1-3 2 Installing the ODA CDA Gateway 2.1 Installation Procedure....................... 2-1 2.2 Running the Installation Verification Procedure Separately on VMS.................. 2-8 2.3 Error Conditions on VMS...................... 2-9 2.4 Sample Installation on VMS................... 2-10 A Maintenance Updates B Determining and Reporting Problems iii Index Tables 2-1 Files Created or Modified by the Installation............................. 2-7 iv ________________________________________________________________ Preface This guide describes the installation of the DEC ODA Compound Document Architecture (CDA) Gateway on the VMS operating system. ________________________Note ________________________ The DEC ODA Compound Document Architecture (CDA) Gateway is referred to as the ODA CDA Gateway in this guide. _____________________________________________________ Purpose of This Guide The purpose of this guide is to describe how to install the ODA CDA Gateway. This guide also describes the preparations that are necessary before you install the ODA CDA Gateway. Who Should Use This Guide This guide is intended for system managers. Keep this guide with your distribution kit. You will need it to install maintenance updates or to reinstall the ODA CDA Gateway. Structure of This Guide This guide has two chapters, two appendixes, and an index. o Chapter 1 describes the prerequisites for installing the ODA CDA Gateway. o Chapter 2 describes the installation procedure for the ODA CDA Gateway and contains a sample installation. v o Appendix A describes the version numbering system for maintenance updates to the ODA CDA Gateway. o Appendix B describes how to determine and report problems with the ODA CDA Gateway. Associated Documents For more information about the ODA CDA Gateway, see the DEC ODA Compound Document Architecture (CDA) Gateway User's Guide. Related Documents The following documents also contain useful information: o VMS Authorize Utility Manual o VMS License Management Utility Manual o VMS System Messages and Recovery Procedures Reference Volume Conventions The following conventions are used in this guide: vi __________________________________________________________ Convention____________Description_________________________ In examples and syntax, a key name enclosed in a rectangle indicates that you press that key. Ctrl/x Ctrl/x indicates that you hold down the Ctrl key while you press another key (indicated here by x). [] In system prompts, the default value for the prompt is enclosed in brackets. Note A note contains information that is of special importance to the reader. Color Text in color indicates user input. UPPERCASE Command names in text are shown in uppercase. italic type Italic type emphasizes a word or phrase, and indicates the complete titles of other documents. monospace type Monospace type indicates text ______________________displayed_by_the_system.____________ vii 1 ________________________________________________________________ Before You Install the ODA CDA Gateway This chapter describes the preparations and requirements necessary for installing the ODA CDA Gateway. 1.1 Prerequisite Software The ODA CDA Gateway Version 1.0 requires VMS Version 5.4. 1.2 Accessing the Online Release Notes The ODA CDA Gateway provides online release notes. The prompt to display or print the release notes during the installation is displayed in step 4 of the installation procedure (see Section 2.1), when you invoke VMSINSTAL with the OPTIONS N parameter. To access the release notes after you complete the instal- lation, type or print the file SYS$HELP:ODA010.RELEASE_ NOTES. 1.3 Installation Procedure Requirements The installation takes about four minutes, depending on the type of media and the system configuration. Before installing the ODA CDA Gateway, you must have the following privileges and resources: o SETPRV privileges, or CMKRNL, WORLD, and SYSPRV privileges o A minimum of 4000 blocks of free disk space during the installation; 1800 blocks are used after the installation Before You Install the ODA CDA Gateway 1-1 1.4 User Account Quotas and Privileges To use the ODA CDA Gateway, each account must have TMPMBX and NETMBX privileges and must meet the following requirements: o AST limit (ASTLM) 24 (minimum) o Buffered I/O quota (BIOLM) 18 (minimum) o Buffered I/O byte count quota (BYTLM) 18 000 (minimum) o Direct I/O quota (DIOLM) 18 (minimum) o Enqueue quota (ENQLM) 30 (minimum) o Open file limit (FILLM) 40 (minimum) o Paging file quota (PGFLQUOTA) 10 240 pages (minimum) o Subprocess creation quota (PRCLM) 0 (minimum) o Working set size (WSDEF) 256 pages (minimum) Use the VMS Authorize Utility (AUTHORIZE) to compare the current values of these quotas with the requirements for the ODA CDA Gateway. For example, the account used in the following example is the SYSTEM account: $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> SHOW SYSTEM To change the values of these quotas, use the VMS Authorize Utility's MODIFY command. For more information, see the VMS Authorize Utility Manual. 1.5 VMS License Management Facility You must register the ODA CDA Gateway license, using the VMS License Management Facility (LMF) in accordance with the license agreement signed by your site. The license registration information you want is contained in the Product Authorization Key (PAK) that is shipped with the ODA CDA Gateway. The PAK is a paper certificate containing information about the license you have to run a particular piece of software. 1-2 Before You Install the ODA CDA Gateway During the installation, the system asks you whether you have registered the ODA CDA Gateway license and loaded the appropriate PAK. To use the software, you must register and load your license for the ODA CDA Gateway before you start the installation. To register a license under VMS, first log in to the system manager's account, SYSTEM. Then choose one of the following ways of registering the ODA CDA Gateway: o Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, enter data from your PAK. o At the DCL prompt, enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to the PAK information. If you intend to use the ODA CDA Gateway on more than one node in a VAXcluster system, you must load the license on the other nodes after you complete the installation. For more information on using LMF, see the VMS License Management Utility Manual. 1.6 Using VMSINSTAL After you log in to a privileged account to install the ODA CDA Gateway, invoke VMSINSTAL. VMSINSTAL is the command procedure that installs this product. An example of invoking VMSINSTAL is shown in steps 1 and 2 of Chapter 2. The VMSINSTAL command procedure has the following syntax: $ @SYS$UPDATE:VMSINSTAL ODA010 ddcu: [OPTIONS N] You can also type an asterisk (*) instead of ODA010. If you are installing the product from magnetic tape, you can use an asterisk to save installation time. The asterisk causes the ODA CDA Gateway to be installed with a minimum of tape passes. ddcu: Represents a device name. The distribution volumes will be mounted for the ODA CDA Gateway installation media, where dd is the device code, c is the controller code, and u is the unit number. Before You Install the ODA CDA Gateway 1-3 You do not have to use the console drive to install the ODA CDA Gateway. If you do use the console drive, and if you removed any media from the drive, you must replace the media. MUA0: is the device name used in examples in this guide. OPTIONS N Is an optional parameter. You must specify this parameter if you want to be prompted to display or print the release notes. If you do not specify the OPTIONS N parameter, VMSINSTAL does not prompt you to display or print the release notes. VMSINSTAL has several other options. For more information on the other options, see the processor- specific installation or operations guide. If you do not specify the product and device names, VMSINSTAL prompts you for them. If you want to be prompted for the product and device names, and if you want to display or print the release notes, enter the following: $ @SYS$UPDATE:VMSINSTAL When you invoke VMSINSTAL, it checks the following: o Whether you logged in to a privileged account. Digital recommends that you install software from the system manager's account with the default device and directory set to SYS$UPDATE. o Whether you have adequate quotas to install the software. VMSINSTAL checks for the following quota values: _ ASTLM = 24 _ BIOLM = 18 _ BYTLM = 20 480 _ DIOLM = 18 _ ENQLM = 200 _ FILLM = 40 1-4 Before You Install the ODA CDA Gateway VMSINSTAL then checks whether users are logged in to the system. If VMSINSTAL detects that users are logged in, the system asks you whether you want to continue the installation. If you want to continue, type YES. If you do not want to continue the installation, press Return. Before you begin the installation, register the infor- mation contained in the PAK that is shipped with the ODA CDA Gateway. Use either the VMS License command procedure (VMSLICENSE) or the LICENSE REGISTER and LICENSE LOAD commands, as described in the VMS License Management Utility Manual, to register the PAK information. Before You Install the ODA CDA Gateway 1-5 2 ________________________________________________________________ Installing the ODA CDA Gateway This chapter describes the installation procedure for the ODA CDA Gateway and contains a sample installation. 2.1 Installation Procedure This section lists the steps in the installation procedure. Step 1: Log in to a privileged account and set your default device and directory to SYS$UPDATE. Username: SYSTEM Password: $ SET DEFAULT SYS$UPDATE Step 2: Invoke VMSINSTAL. Invoke VMSINSTAL to start the installation procedure. To abort the installation procedure, press Ctrl/Y. When you press Ctrl/Y, the installation procedure deletes all the files it has created up to that point and then returns you to the DCL prompt. If you want to retry the installation procedure after pressing Ctrl/Y, you must continue from step 2. $ @VMSINSTAL ODA010.A MUA0: OPTIONS N VAX/VMS Software Product Installation Procedure V5.4 It is dd-mmm-yyyy at hh:mm. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? Installing the ODA CDA Gateway 2-1 If you are satisfied with the backup of your system disk, press Return. If you are not satisfied, type NO and press Return to stop the installation. 2-2 Installing the ODA CDA Gateway Step 3: Insert the first installation kit volume. Please mount the first volume of the set on MUA0:. * Are you ready? YES The following products will be processed: ODA V1.0 Beginning installation of ODA V1.0 at hh:mm %VMSINSTAL-I-RESTORE, Restoring product saveset A... If you want to continue the installation, mount volume 1, type YES, and press Return. Step 4: Choose a release notes option. This step applies only if you specified OPTIONS N in step 2. Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes * Select option [3]: The release notes options are as follows: o Option 1-When you choose this option, VMSINSTAL displays the release notes. To stop the display, press Ctrl/C. o Option 2-When you choose this option, VMSINSTAL prompts you for a queue name. Either type a queue name or press Return to send the file to the default print device. * Queue name [SYS$PRINT]: o Option 3-When you choose this option, VMSINSTAL displays the release notes. To stop the display, press Ctrl/C. Installing the ODA CDA Gateway 2-3 VMSINSTAL then prompts you for a queue name. Either type a queue name or press Return to send the file to the default print device. VMSINSTAL then copies the ODA CDA Gateway release notes to SYS$HELP:ODA010.RELEASE_ NOTES. o Option 4-When you choose this option, VMSINSTAL immediately copies the release notes to SYS$HELP. o Option 5-When you choose this option, VMSINSTAL does not display, print, or copy the release notes. You choose this option when you want to stop the installation. If you choose this option, and you do not want to stop the installation, you must install the kit again to access the release notes. ________________________Note ________________________ The version of the release notes file installed by VMSINSTAL indicates the current product name and version number. Do not delete the release notes for previous versions of the ODA CDA Gateway. _____________________________________________________ VMSINSTAL then displays the following message: * Do you want to continue the installation [N]?: Y If you want to continue the installation, type YES and press Return. If you do not want to continue the installation, type NO or press Return. In either case, VMSINSTAL copies the release notes to SYS$HELP. %VMSINSTAL-I-RELMOVED, The product release notes have been successfully moved to SYS$HELP. Step 5: Respond to the license registration queries. The ODA CDA Gateway supports the VMS License Management Facility (LMF). The installation procedure displays license information about your product. It then asks you if you have registered and loaded your PAK for the ODA CDA Gateway. The following is an example of license information: 2-4 Installing the ODA CDA Gateway Product: ODA-CDA-GATEWAY Producer: DEC Version: 1.0 Release Date: 26-MAR-1991 * Does this product have an authorization key registered and loaded? If you have not registered and loaded your PAK, you must type NO. You must register and load your PAK to successfully complete the installation. If you have not done so, stop the installation, register and load your PAK. Then restart the installation. Step 6: Choose the installation options. * Do you want to purge files replaced by this installation [YES]? The directories SYS$LIBRARY, SYS$MESSAGE, and SYS$TEST may contain earlier versions of the ODA CDA Gateway files. These files are replaced with new files during the installation. The earlier versions of the files are not automatically purged. However, purging is recommended. In response to the purging prompt, press Return to purge the files, or type NO to keep them. * Do you want to run the IVP after the installation [YES]? The Installation Verification Procedure (IVP) runs tests that check whether the installation procedure was successful. Press Return to run the IVP after the installation. If you do not want to run the IVP, type NO in response to the prompt. Step 7: Read the informational messages. The ODA CDA Gateway installation procedure displays informational messages that report on the progress of the installation. If the installation procedure is successful, the new or modified files are moved to their target directories. The success of the installation is indicated by the following message: %VMSINSTAL-I-MOVEFILES, files will now be moved to their target directories... Installing the ODA CDA Gateway 2-5 Table 2-1 lists the files created or modified by the installation of the ODA CDA Gateway. If you typed YES in response to the prompt that requests a file purge in step 6, earlier versions of the ODA CDA Gateway files are now purged. 2-6 Installing the ODA CDA Gateway Table_2-1_Files_Created_or_Modified_by_the_Installation___ Directory________File_Name________________________________ sys$library ddif$read_oda.exe sys$library ddif$write_oda.exe sys$message ddif$read_oda_messages.exe sys$message ddif$write_oda_ messages.exe sys$message ddif$read_oda_cgm_ messages.exe sys$message ddif$write_oda_cgm_ messages.exe sys$library ddif$read_oda_cgm.exe sys$library ddif$write_oda_cgm.exe sys$library oda$q112_handler.exe sys$library oda$q111_handler.exe sys$library oda$text_handler.exe sys$library oda$raster_handler.exe sys$library oda$geometric_handler.exe sys$library odif$$toolkit.exe sys$test oda$ivp.com sys$test_________oda$test_doc.oda_________________________ Installing the ODA CDA Gateway 2-7 Step 8: Observe the Installation Verification Procedure (IVP). If you chose to run the IVP in step 6, VMSINSTAL now calls the IVP to verify that the ODA CDA Gateway was installed successfully. %ODA-I-BEGINIVP, Beginning 1.0-000 IVP. %ODA-S-IVP,ODA CDA GATEWAY 1.0-000 IVP completed successfully This IVP can be rerun. At this point in the installation procedure, earlier versions of the ODA CDA Gateway files are purged if you type YES in response to the prompt that requests a file purge. Step 9: End the installation procedure. When the installation procedure is complete, you can choose to install more products, or press Return to exit from VMSINSTAL. If you removed media from the console drive before beginning the installation, replace it now. Installation of ODA V1.0 completed at hh:mm Enter the products to be processed from the next distribution volume set. * Products: VMSINSTAL procedure done at hh:mm $ LOGOUT SYSTEM logged out at dd-mmm-yyyy hh:mm:ss.ss VMSINSTAL deletes or changes entries in the process symbol tables during the installation. So, if you want to continue using the system manager's account and if you want to restore these symbols, log out and log in again. 2.2 Running the Installation Verification Procedure Separately on VMS You usually run the IVP when you install a product. If you want to run the IVP separately to ensure the integrity of the installed files, enter the following command: $ @sys$test:oda$ivp 2-8 Installing the ODA CDA Gateway If the IVP fails for any reason, a message like the following is displayed: %ODA-F-IVP, ODA CDA Gateway 1.0 IVP has failed 2.3 Error Conditions on VMS If the installation procedure fails for any reason, a message like the following is displayed: %VMSINSTAL-E-INSFAIL, The installation of ODA V1.0 has failed. An error during the installation may occur if one or more of the following conditions exist: o Operating system version is incorrect o Prerequisite software version is incorrect o Quotas necessary for successful installation are insufficient (see Section 1.3) o Process quotas required by VMSINSTAL are incorrect (see Section 1.6) o The product was registered incorrectly or not registered For descriptions of the error messages generated by these conditions, see the following: o VMS System Messages and Recovery Procedures Reference Volume o Your processor-specific installation or operations guide o VMS License Management Utility Manual If you are notified that some of these conditions exist, take the appropriate action as described in the message. If the installation fails, you must restart the instal- lation procedure from step 2. If the installation fails because of an IVP failure, contact a Digital field service representative. Installing the ODA CDA Gateway 2-9 2.4 Sample Installation on VMS This section contains a sample installation of the ODA CDA Gateway. Sometimes the installation procedure is modified during maintenance updates of the product. Because this installation guide is not usually revised for maintenance updates, read the Read Before Installing the DEC ODA Compound Document Architecture (CDA) Gateway letter before you install this product. This letter lists the significant changes in the installation procedure that vary from the sample installation. Sample ODA CDA Gateway Installation Procedure $ @SYS$UPDATE:VMSINSTAL VAX/VMS Software Product Installation Procedure V5.4 It is 20-JAN-1991 at 18:54. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? * Where will the distribution volumes be mounted: disk$:[oda] Enter the products to be processed from the first distribution volume set. * Products: ODA * Enter installation options you wish to use (none): The following products will be processed: ODA V1.0 Beginning installation of ODA V1.0 at 18:54 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. +----------------------------------------------+ | Installation of DEC ODA CDA Gateway 1.0-000 | +----------------------------------------------+ The installation can be aborted at any time by pressing CTRL/Y. 2-10 Installing the ODA CDA Gateway Product: ODA-CDA-GATEWAY Producer: DEC Version: 1.0 Release Date: 26-MAR-1991 * Does this product have an authorization key registered and loaded? Y This kit contains an Installation Verification Procedure (IVP) to verify the correct installation of the DEC ODA CDA Gateway. It can be run prior to the conclusion of this procedure by answering "YES" to the IVP prompt or invoked after the installation as follows: @SYS$TEST:ODA$IVP * Do you want to run the IVP after the installation [YES]? * Do you want to purge files replaced by this installation [YES]? No further questions will be asked. The DEC ODA CDA Gateway installation will now continue for approximately 5 to 15 minutes, depending on your type of media and your system configuration. %VMSINSTAL-I-RESTORE, Restoring product save set B ... Files placed on the system for the DEC ODA CDA Gateway are: sys$library:ddif$read_oda.exe sys$library:ddif$write_oda.exe sys$message:ddif$read_oda_messages.exe sys$message:ddif$write_oda_messages.exe sys$message:ddif$read_oda_cgm_messages.exe sys$message:ddif$write_oda_cgm_messages.exe sys$library:ddif$read_oda_cgm.exe sys$library:ddif$write_oda_cgm.exe sys$library:oda$q112_handler.exe sys$library:oda$q111_handler.exe sys$library:oda$text_handler.exe sys$library:oda$raster_handler.exe sys$library:oda$geometric_handler.exe sys$library:odif$$toolkit.exe sys$test:oda$ivp.com sys$test:oda$test_doc.oda %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... %ODA-I-BEGINIVP, Beginning 1.0-000 IVP. %ODA-S-IVP,ODA CDA GATEWAY 1.0-000 IVP completed successfully Installing the ODA CDA Gateway 2-11 This IVP can be rerun. Installation of ODA V1.0 completed at 18:56 Enter the products to be processed from the next distribution volume set. * Products: VMSINSTAL procedure done at 18:57 $ LOGOUT SYSTEM logged out at 20-JAN-1991 18:57:36.33 2-12 Installing the ODA CDA Gateway A ________________________________________________________________ Maintenance Updates This appendix describes the version numbering system for maintenance updates to the ODA CDA Gateway. This guide applies to the ODA CDA Gateway Version 1.0 and all maintenance updates in that version. A major version number is indicated by the digits to the left of the decimal point, and a maintenance update version number is indicated by the digits to the right of the decimal point. Digital may periodically issue maintenance updates of the ODA CDA Gateway. Each update consists of an installation kit. Install the kit as described in this document or in the documentation with the maintenance update. Each time a maintenance update is released, the version number changes. For example, if the current version is 1.0, the version number of the first maintenance update will be 1.1. In addition, each maintenance update includes new release notes. The release notes describe the changes that have been made to the ODA CDA Gateway since the previous release. The updated release notes are on line. It is recommended that you read the release notes when you first install the ODA CDA Gateway. You can also access them after the product is installed. For information on reading the release notes when you are installing the ODA CDA Gateway on VMS systems, follow steps 1, 2, 3, and 4 of the installation procedure in Chapter 2. To locate the release notes after the ODA CDA Gateway is installed on VMS, display or print the file SYS$HELP:ODA010.RELEASE_ NOTES. Maintenance Updates A-1 B ________________________________________________________________ Determining and Reporting Problems This appendix describes how to determine and report problems with the ODA CDA Gateway. If an error occurs while you are using the ODA CDA Gateway and you think the error is caused by a problem with the ODA CDA Gateway, take one of the following actions: o If you bought the ODA CDA Gateway within the past 90 days and you think the problem is caused by a software error, submit a Software Performance Report (SPR). o If you have a Basic or DECsupport Software Agreement, call your Customer Support Center. With these services, you receive telephone support that provides high-level advisory and remedial assistance. For more information, contact your local Digital representative. o If you have a Self-Maintenance Software Agreement, submit a Software Performance Report (SPR). If you find an error in the ODA CDA Gateway documentation, fill out and submit a Reader's Comments form from the end of the document in which the error was found. Include the section and page number where you found the error. Determining and Reporting Problems B-1 ________________________________________________________________ Index A__________________________ M__________________________ Authorize Utility, 1-2 Maintenance updates, A-1 E__________________________ O__________________________ Error conditions, 2-9 Online release notes accessing, 1-1 F__________________________ Files P__________________________ created or modified PAK, 1-2 during installation, Prerequisite software, 1-1 2-6 Problems determining and reporting I__________________________ , B-1 Installation procedure, 2-1 Product Authorization Key to 2-8 See PAK Installation procedure requirements, 1-1 R__________________________ Installation Verification Release notes Procedure accessing, 1-1 See IVP IVP, 2-5 S__________________________ running on VMS, 2-8 Sample installation, 2-10 L Software ___________________________ prerequisite, 1-1 License Management Facility (LMF), 1-2 Index-1 U__________________________ User account quotas and privileges, 1-2 V__________________________ VMSINSTAL using, 1-3 Index-2