POLYCENTER Software Installation Utility Developer's
Guide
POLYCENTER Software Installation Utility Developer's
Guide
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
© 2001 Compaq Computer Corporation
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.
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.
Related Documents
The OpenVMS System Manager's Manual describes the tasks that system managers perform using
the POLYCENTER Software Installation utility. It explains operations
such as software installation and removal.
For additional information about Compaq OpenVMS products and
services, access the Compaq website at the following location:
http://www.openvms.compaq.com/
|
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.
|
| 
