POLYCENTER Software Installation Utility Developer's Guide

Document revision date: 30 March 2001

Order Number: AA--Q28MD--TK

April 2001

This guide describes how to package software products using the POLYCENTER Software Installation utility. It describes the product description language, product description files, product text files, and other relevant concepts.

Revision/Update Information: This guide supersedes the POLYCENTER Software Installation Utility Developer's Guide, Version 7.2

Software Version: OpenVMS Version 7.3

Compaq Computer Corporation Houston, Texas

Compaq, VAX, POLYCENTER, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS, Alpha, DDIF, DECdirect, DECnet, DIGITAL, and MicroVAX are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries.

All other product names mentioned herein may be the trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein.

The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

The following are third-party trademarks:

Motif and UNIX are trademarks of The Open Group in the United States and other countries.

NFS is a registered trademark of Sun Microsystems, Inc. in the United States and other countries.

ZK5952

The Compaq OpenVMS documentation set is available on CD-ROM.

This document was prepared using DECdocument, Version V3.3-1e.

Contents Index

Preface

Intended Audience

This guide is intended for individuals who are responsible for packaging software products. You do not need to be a programmer to package kits for software products, but you do need to understand POLYCENTER Software Installation utility commands and concepts.

Document Structure

This guide is organized as follows:

Chapter 1 provides an overview of the POLYCENTER Software Installation utility.
Chapter 2 defines some key terms and concepts.
Chapter 3 describes writing the product description file. It also contains sample product descriptions.
Chapter 4 describes writing the product text file. It also contains sample product text files.
Chapter 5 describes how to package your product and manipulate the kit.
Chapter 6 presents advanced topics such as use of command procedures and testing.
Chapter 7 provides detailed reference material on product description language statements and functions.
Appendix A contains information about migrating from the VMSINSTAL utility to the POLYCENTER Software Installation utility.
The Glossary lists and defines POLYCENTER Software Installation utility terminology.

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet openvmsdoc@compaq.com

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

The following conventions are used in this manual:

... A horizontal ellipsis in examples indicates one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you specify more than one.

[ ] In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.

| In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.

{ } In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.

text style This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text Monospace type indicates code examples and interactive screen displays.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Overview

The POLYCENTER Software Installation utility is a complete software installation and management tool for OpenVMS Alpha or VAX systems. It can package, install, remove, and manage software products on Alpha or VAX systems. It can also save information about software products such as system requirements and installation options.

The POLYCENTER Software Installation utility is intended for use both by those who create (package) kits for software products and by system managers who install and maintain these products. This guide describes how to package software products using the POLYCENTER Software Installation utility. It describes the product description language, product description files, product text files, and other relevant concepts.

System managers should refer to the OpenVMS System Manager's Manual for general use information.

1.1 Features for Software Providers

For software providers, the POLYCENTER Software Installation utility simplifies the task of packaging software because:

Installations require less packaging effort than most conventional installation methods. This results in performance gains and reduced development time over conventional installations.
You can include both brief and detailed installation text to guide users through an installation, resulting in a higher installation success rate.
Related products can easily be packaged as a product suite and installed in one operation.
The utility keeps track of which products (and versions) have been installed and removed in the execution environment. Using this information, you can design your installation procedure to check for and manage version dependencies.

1.2 Coexistence with VMSINSTAL

The POLYCENTER Software Installation utility is integrated into OpenVMS and coexists with the VMSINSTAL utility. Today, you use the POLYCENTER Software Installation utility to install the OpenVMS Operating System and many layered products on Alpha systems, and to install some layered products on VAX systems. The POLYCENTER Software Installation utility is the preferred installation mechanism for future layered product and OpenVMS releases.

The POLYCENTER Software Installation utility offers the following features:

Typically faster installation and upgrade operations as compared to the VMSINSTAL utility
Removal (deinstallation) of previously installed software products
A database of information on installed products that has query capabilities
Dependency checking of software products based on product version number

If you currently use VMSINSTAL to package your software product, see Appendix A for information about migrating from VMSINSTAL to the POLYCENTER Software Installation utility.

1.3 Creating an Installable Kit

As a software provider, you probably want to use the POLYCENTER Software Installation utility to create an installable kit for your software product. This kit might be a new software product or an update to an existing product; the POLYCENTER Software Installation utility has features for each case.

Your OpenVMS user will then be able to use the POLYCENTER Software Installation utility to install your product with a minimum of documentation and effort.

Generally, the installable kit you create will be packaged in one "container" file. This container file has the file extension .PCSI and is in the binary format recognized by the POLYCENTER Software Installation utility. The person installing your product will use the PRODUCT INSTALL command to install your kit on their OpenVMS system.

The sections that follow describe the main steps to create this installable .PCSI file.

1.3.1 Plan Ahead

Determine the required characteristics of the execution environment for your product or platform. For example, you must determine where files will be placed, if DCL tables or help libraries need to be updated, if system or process parameters need to be checked, and if you need to provide any command procedures to perform product specific tasks.

1.3.2 Gather the Product Material

Locate all product related files that will be installed on the user's system. Collect any command procedures you may have written to perform product specific tasks. These include command procedures that will remain on the user's system and those that will be executed from a temporary directory and then deleted. Together, the product files and any associated command procedures are called the product material.

Generally, you can organize the product material for input to the packaging operation in any way that is meaningful and convenient for you. For example, you can do the following:

Keep the product material in the directory structure used by the software engineering team.
Organize the product material into one or more staging directories that mirror the directory structure of the product on the user's disk after installation.
Place the product material in a single directory tree.

Each approach has its merits and limitations. However, if you have special Requirements, such as the need to install different files with the same name in different directories, then your options for organizing the files prior to packaging might be restricted.

1.3.3 Create a Product Description File

Create a product description file (PDF) with a text editor. This step is the subject of Chapter 3. PDF files do the following:

Identify all of the files and other objects (such as directories, accounts, library modules, etc.) that the product provides
Specify configuration choices the product offers, including default answers
Specify product requirements (such as dependencies on other software products, minimum hardware configurations, and system parameter values)

PDF files use Product Description Language (PDL) statements (described in Chapter 7) to convey all of the information the POLYCENTER Software Installation utility needs for installing either a software product or a set of software products.

What does a PDF file look like? Example 1-1 shows a sample product description file. Chapter 7 describes each PDL statement in detail.

1.3.4 Optionally, Create a Product Text File

Create a product text file (PTF) with a text editor. This optional step is described in Chapter 4. The PTF provides information about the product in brief and detailed formats. The information includes product identification, copyright notice, configuration choice descriptions, and message text used primarily during product installation and configuration operations.

What does a PTF file look like? The PTF file format is similar to that of modules used with the Librarian utility (LIBRARY) to create, modify, or describe a help library. Example 1-2 shows a product text file.

1.3.5 Package the Software Components

You package the software components to actually create the .PCSI file. This step is described in Chapter 5. You use the PRODUCT PACKAGE command and its various qualifiers to do this. This command determines if the PDF and PTF are syntactically correct and verifies that all listed product material files can be found.

1.3.6 Test and Debug the Installable Kit

Once a kit has been successfully produced, use the PRODUCT INSTALL, PRODUCT SHOW, and PRODUCT REMOVE commands to verify the installation and removal of the product. Check for correct file placement and protection, test user input, review message text, modify configuration options, verify that execution environment requirements are satisfied, and so forth.

You should test your installable kit to make sure that it properly handles any software version dependencies.

1.3.7 Example PDF and PTF for a Software Kit

Example 1-1 PDF for Software Kit TNT

product DEC VAXVMS TNT V3.0 full ; if (not <software DEC VAXVMS VMS version minimum V6.2>) ; error NOVMS ; end if ; execute install "@PCSI$SOURCE:[SYSUPD]TNT$BACKUP.COM" remove "" -- nothing special to do on remove uses [SYSUPD]TNT$BACKUP.COM ; -- will not leave file on system execute start "@PCSI$DESTINATION:[SYS$STARTUP]TNT$STARTUP.COM" stop "@PCSI$DESTINATION:[SYS$STARTUP]TNT$SHUTDOWN.COM" ; execute test "@PCSI$DESTINATION:[SYSTEST]TNT$IVP.COM" ; directory [SYSTEST.TNT] ; directory [TNT] ; file [SYSHLP]TNT030.RELEASE_NOTES generation 50084697 release notes ; remove ; file [SYSHLP]TNT010.RELEASE_NOTES ; file [SYSHLP]TNT015.RELEASE_NOTES ; file [SYSHLP]TNT020.RELEASE_NOTES ; file [SYSHLP]TNT021.RELEASE_NOTES ; file [SYSEXE]TNT$POPULATE.EXE ; file [SYSEXE]TNT$INITJOURNAL.EXE ; file [SYSEXE]TNT$DUMPACS.EXE ; file [SYSEXE]TNT$DUMPJOURNAL.EXE ; end remove ; information RELEASE_NOTES phase after ; information POST_INSTALL phase after ; file [SYS$STARTUP]TNT$STARTUP.COM generation 50084697 ; file [SYS$STARTUP]TNT$SHUTDOWN.COM generation 50084697 ; file [SYSMGR]TNT$UTILITY.COM generation 50084697 ; file [SYSTEST]TNT$IVP.COM generation 50084697 ; file [SYSEXE]TNT$SERVER.EXE generation 50084697 ; file [SYSEXE]TNT$HELPER.EXE generation 50084697 ; file [SYSEXE]TNT$UTILITY.EXE generation 50084697 ; file [SYSEXE]TNT$EXCLUDED_SYMBIONTS.DAT generation 50084697 ; file [SYSTEST.TNT]TNT$SERVER_IVP.EXE generation 50084697 ; execute postinstall "@PCSI$DESTINATION:[SYSMGR]TNT$UTILITY.COM UPDATE ALL" ; end product ;

Example 1-2 PTF for Software Kit TNT

=PRODUCT DEC VAXVMS TNT V3.0 Full 1 'LICENSE =prompt This product uses the PAK: VAX-VMS This product is contained within the Product Authorization Key for OpenVMS VAX. 1 'NOTICE =prompt Copyright 2001 Compaq Computer Corporation. All rights reserved. Unpublished rights reserved under the copyright laws of the United States. This software is proprietary to and embodies the confidential technology of Compaq Computer Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor. 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. 1 'PRODUCER =prompt Compaq Computer Corporation This software product is sold by Compaq Computer Corporation. 1 'PRODUCT =prompt CPQ OpenVMS Management Station The OpenVMS Management Station is a client-server application which provides OpenVMS system management capabilities via a client application on a Personal Computer running Microsoft Windows; the server application runs on OpenVMS systems. 1 NOVMS =prompt Minimum OpenVMS software not found on system, abort installation This kit requires a minimum OpenVMS version of V6.2. 1 POST_INSTALL =prompt See the installation guide for post installation information. Postinstallation tasks required for OpenVMS Management Station. For more information, refer to the installation guide. 1 RELEASE_NOTES =prompt Release notes for OpenVMS Management Station available The release notes for the OpenVMS Management Station are available in the file SYS$HELP:TNT030.RELEASE_NOTES.

Contents

Index

privacy and legal statement

5952PRO.HTML

Internet	openvmsdoc@compaq.com
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
\|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
text style	This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
`Monospace text`	Monospace type indicates code examples and interactive screen displays.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.