OpenVMS Developer’s Guide to VMSINSTAL Order Number: AA–PWBXA–TE May 1993 This manual describes the VMSINSTAL command procedure and gives developers information about using VMSINSTAL to design their own installation procedures. Digital recommends that all installation procedures for products that layer on the OpenVMS operating system use VMSINSTAL. The OpenVMS Developer’s Guide to VMSINSTAL is available as an optional OpenVMS manual; it is not included in the standard OpenVMS documentation set. Revision/Update Information: This document supersedes the OpenVMS Developer’s Guide to VMSINSTAL, Version 5.5. It also supersedes the OpenVMS AXP Version 1.5. Operating System and Version: OpenVMS VAX Version 6.0 OpenVMS AXP Version 1.5 Digital Equipment Corporation Maynard, Massachusetts May 1993 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. © Digital Equipment Corporation 1993. All Rights Reserved. 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: Alpha AXP, AXP, Bookreader, DECnet, DECwindows, Digital, OpenVMS, VAX, VAX DOCUMENT, VMS, the AXP logo, and the DIGITAL logo. The following is a third-party trademark: PostScript is a registered trademark of Adobe Systems, Inc. All other trademarks and registered trademarks are the property of their respective holders. ZK4529 This document was prepared using VAX DOCUMENT, Version 2.1. Contents Preface ............................................................ vii 1 Introduction 1.1 Product Kits ................................................ 1–2 1.1.1 Files Included in a Product Kit .............................. 1–2 1.1.2 Building a Product Kit ..................................... 1–2 1.2 VMSINSTAL Functional Overview .............................. 1–5 1.3 Invoking VMSINSTAL ........................................ 1–6 1.4 Choosing VMSINSTAL Options . ................................ 1–8 1.4.1 Installer’s Options ........................................ 1–8 1.4.2 Developer’s Options ....................................... 1–11 1.5 VMSINSTAL History File (AXP Only) ............................ 1–12 1.6 VMSINSTAL Product Installation File (AXP Only) . ............... 1–12 1.7 List Installed Products Procedure (AXP Only) ...................... 1–12 1.8 Safety Mode ................................................ 1–13 1.9 Recovery from System Failure . ................................ 1–13 2 Guidelines and Conventions 2.1 Product Identification String . ................................ 2–1 2.2 Save Set Identification ........................................ 2–1 2.3 Volume Labeling ............................................ 2–2 2.3.1 Diskette Kits ............................................ 2–2 2.3.2 TU58 Cartridge Kits ...................................... 2–3 2.3.3 Magnetic Tape Kits ....................................... 2–3 2.4 Logical Names and Global Symbols .............................. 2–3 2.5 Error Handling ............................................. 2–3 2.6 Compatibility Mode (VAX Only) . ................................ 2–4 2.7 Referencing Other Products .................................... 2–4 2.8 Changing Global State ........................................ 2–4 2.9 Verifying Installation . ........................................ 2–4 2.10 Prompting the Installer for Input ............................... 2–5 2.11 Internationalization of VMSINSTAL Messages ..................... 2–5 2.12 Release Notes ............................................... 2–6 3 KITINSTAL Command Procedure 3.1 Guidelines for Writing a KITINSTAL Command Procedure ............ 3–1 3.1.1 Installation Phase ........................................ 3–1 3.1.2 IVP Phase .............................................. 3–2 3.2 Using Callbacks ............................................. 3–3 3.2.1 Accessing Files . ........................................ 3–4 3.2.2 Moving Files from the Kit’s Working Directory . ............... 3–4 iii 3.2.3 Updating Files ........................................... 3–4 3.2.3.1 Updating an Existing File Version ......................... 3–4 3.2.3.2 Updating a File by Creating a New Version .................. 3–4 3.2.4 Updating a Library . .................................... 3–5 3.2.5 Deleting a File ........................................... 3–5 3.2.6 Creating a Directory . .................................... 3–5 3.3 Summary of KITINSTAL Design Specifications . ................... 3–6 3.4 Basic KITINSTAL Command Procedure .......................... 3–7 4 VMSINSTAL Functional Description 4.1 Overview .................................................. 4–1 4.2 Functional Steps ............................................ 4–2 4.2.1 Step 1 .................................................. 4–2 4.2.2 Step 2 .................................................. 4–3 4.2.3 Step 3 .................................................. 4–4 4.2.4 Step 4 .................................................. 4–4 4.2.5 Step 5 .................................................. 4–5 4.2.6 Step 6 .................................................. 4–5 4.2.7 Step 7 .................................................. 4–6 4.2.8 Step 8 .................................................. 4–6 4.2.9 Step 9 .................................................. 4–6 4.2.10 Step 10 ................................................. 4–7 4.2.11 Step 11 ................................................. 4–7 4.2.12 All Done ................................................ 4–7 4.3 Special Steps . ............................................ 4–8 4.3.1 Step 12 ................................................. 4–8 4.3.2 Step 13 ................................................. 4–10 5 VMSINSTAL Callbacks 5.1 ADD_IDENTIFIER Callback ................................... 5–2 5.2 ASK Callback . ............................................ 5–2 5.3 CHECK_NETWORK Callback .................................. 5–5 5.4 CHECK_NET_UTILIZATION Callback ........................... 5–5 5.5 CHECK_PRODUCT_VERSION Callback .......................... 5–7 5.6 CHECK_VMS_VERSION Callback . ............................ 5–8 5.7 COMPARE_IMAGE Callback ................................... 5–9 5.8 CONTROL_Y Callback ........................................ 5–10 5.9 CREATE_ACCOUNT Callback .................................. 5–11 5.10 CREATE_DIRECTORY Callback ................................ 5–11 5.10.1 Creating a System Directory ................................ 5–12 5.10.2 Creating a System-Specific Directory .......................... 5–12 5.10.3 Creating a Common Directory . ............................ 5–13 5.10.4 Creating a User Directory .................................. 5–13 5.11 DELETE_FILE Callback . .................................... 5–14 5.12 FIND_FILE Callback ......................................... 5–15 5.13 GET_IMAGE_ID Callback . .................................... 5–16 5.14 GET_PASSWORD Callback .................................... 5–17 5.15 GET_SYSTEM_PARAMETER Callback ........................... 5–17 5.16 MESSAGE Callback .......................................... 5–18 5.17 PATCH_IMAGE Callback (VAX Only) ............................ 5–19 5.18 PRINT_FILE Callback ........................................ 5–20 5.19 PRODUCT Callback .......................................... 5–21 iv 5.20 PROVIDE_DCL_COMMAND Callback ........................... 5–21 5.21 PROVIDE_DCL_HELP Callback ................................ 5–22 5.22 PROVIDE_FILE Callback ..................................... 5–23 5.23 PROVIDE_IMAGE Callback . ................................ 5–24 5.24 RENAME_FILE Callback ..................................... 5–27 5.25 RESTORE_SAVESET Callback . ................................ 5–27 5.26 RUN_IMAGE Callback ....................................... 5–28 5.27 SECURE_FILE Callback ...................................... 5–29 5.28 SET Callback ............................................... 5–30 5.28.1 SET ACL Option . ........................................ 5–30 5.28.2 SET ASK_CASE Option .................................... 5–31 5.28.3 SET_FILE Option (AXP Only) ............................... 5–31 5.28.4 SET IVP Option . ........................................ 5–32 5.28.5 SET POSTINSTALL Option . ................................ 5–33 5.28.6 SET PRODUCT_NAME Option (AXP Only) ..................... 5–33 5.28.7 SET PURGE Option ....................................... 5–34 5.28.8 SET REBOOT Option ..................................... 5–35 5.28.9 SET SAFETY Option ...................................... 5–35 5.28.10 SET_SEMANTICS Option (AXP Only) . ....................... 5–36 5.28.11 SET SHUTDOWN Option . ................................ 5–36 5.28.12 SET STARTUP Option ..................................... 5–37 5.29 SUMSLP_TEXT Callback ..................................... 5–38 5.30 TELL_QA Callback . ........................................ 5–40 5.31 UNWIND Callback . .......................................