HP OpenVMS Systems Documentation

POLYCENTER Software Installation Utility Developer's Guide

The POLYCENTER Software Installation utility is a complete software installation and management tool for OpenVMS systems. It can package, install, remove, and manage software products on Alpha, Itanium® 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 to be used by people creating (packaging) 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

The POLYCENTER Software Installation utility improves the task of packaging software for software providers in the following ways:

• Reduces effort
  Installations require less packaging effort than most conventional installation methods---resulting in performance gains and reduced development time over conventional installations.
• Provides more user information
  You can include both brief and detailed installation text to guide users through an installation--- resulting in a higher installation success rate.
• Simplifies installation
  Related products can easily be packaged as a product suite---resulting in one operation installation.
• Version tracking
  The utility tracks which products and which product versions have been installed and removed. You can design your installation procedure to check for and manage version dependencies---resulting in easy version tracking.

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 and I64 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 than the VMSINSTAL utility
• Removal (deinstallation) of previously-installed software products
• A query-capable database of information on installed products
• Dependency checking of software products based on the 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 can use the POLYCENTER Software Installation utility to create an installable kit for your software product. This kit may be either a new software product or an update to an existing product; the POLYCENTER Software Installation utility provides features for each case.

Once you have created an installable kit, your OpenVMS user will 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 is packaged in one "container" file. This container file has a file extension of .PCSI and is in the binary format recognized by the POLYCENTER Software Installation utility. The person installing your product issues the PRODUCT INSTALL command to install the .PCSI file on their OpenVMS system.

The following sections describe the main steps to create an installable kit.

1.3.1 Step 1: Make A Plan

To create an installable .PCSI file, you must determine the required characteristics of the execution environment for your product or platform. Questions you need to consider:

• Where will the files be placed?
• Will DCL tables or help libraries need to be updated?
• Will system or process parameters need to be checked?
• Will you need to provide any command procedures to perform product specific tasks?

When you have the answers to these questions, proceed to Section 1.3.2.

1.3.2 Step 2: Gather the Product Material

Next, you need to gather all 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.

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 organize the material in one of the following ways:

• 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, your options for organizing the files before packaging might be restricted.

1.3.3 Step 3: Create a Product Description File

Create a product description file (PDF) using a text editor. This step is discussed in more detail in Chapter 3. PDF files do the following:

• Identify all of the files and other objects (such as directories, accounts, library modules, and others) 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.

Example 1-1 shows a sample PDF. Chapter 7 describes each PDL statement in detail.

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 ;

Create a product text file (PTF) with a text editor. This optional step is fully 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.

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.

=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 2003 Hewlett-Packard Company. 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
Hewlett-Packard Company.  Possession, use, or copying of this software
and media is authorized only pursuant to a valid written license from HP
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 Hewlett-Packard Company
This software product is sold by Hewlett-Packard Company.
1 'PRODUCT
=prompt HP 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.