POLYCENTER Software Installation Utility Developer's Guide

Document revision date: 19 July 1999

Order Number: AA--Q28MC--TK

January 1999

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.1

Software Version: OpenVMS Alpha Version 7.2
OpenVMS VAX Version 7.2

Compaq Computer Corporation
Houston, Texas

January 1999

Compaq Computer 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 Compaq Computer Corporation or an authorized sublicensor.

Compaq Computer Corporation conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, DDIF, DEC Fortran, DECdirect, DECprint, DECwindows, DIGITAL, MicroVAX I, OpenVMS, POLYCENTER, VAX, VAX DOCUMENT, RSX, VAXcluster, VMS, and the Compaq logo.

The following are third-party trademarks:

Motif is a registered trademark of the Open Software Foundation, Inc.

NFS is a registered 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.

ZK5952

The OpenVMS documentation set is available on CD-ROM.

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.
Chapter 6 describes some advanced concepts such as managed object scope and lifetime.
Chapter 7 describes 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.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

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.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

In this manual, any reference to OpenVMS is synonymous with DIGITAL OpenVMS.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also 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 choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

text style This text style represents the introduction of a new term or 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.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- 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 some 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
Removal (deinstallation) of previously installed software products
A database of information on installed products that has query capabilities on the database
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 Gather All of the Product Files

Locate all of the files to be included in the software product kit. These files are called the product material. These files can remain in the directories generated by the software engineering team, you can copy them to one or more staging directories, or you can copy them to a directory tree as they would appear after installation.

1.3.2 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.3 Create a Product Description File

Create a product description file (PDF) with a text editor. This step is described in Chapter 3. PDF files:

Identify all of the files that the product provides
Can specify configuration choices the product offers, including default answers
Can 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. Subsequent chapters describe the PDF statements in line-by-line detail.

Example 1-1 PDF For an Application Software Kit

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 ;

1.3.4 Optionally, Create a Product Text File

Create a product text file (PTF). 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.

Example 1-2 PTF for an Application Software Kit

=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 © Digital Equipment Corporation 1997. 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 Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital 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 Digital Equipment Corporation This software product is sold by Digital Equipment Corporation. 1 'PRODUCT =prompt DEC 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.

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.

Contents

Index

privacy and legal statement

5952PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
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 choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[\|]	In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or 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. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	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.