![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
Revision/Update Information: This guide supersedes the POLYCENTER Software Installation Utility Developer's Guide, Version 6.1
Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1
Digital Equipment Corporation Maynard, Massachusetts
Digital Equipment 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 Digital or an authorized sublicensor.
Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.
© Digital Equipment Corporation 1996. All rights reserved.
The following are trademarks of Digital Equipment Corporation: Bookreader, DDIF, DEC Fortran, DEC Rdb, DECdirect, DECnet, DECprint, DECwindows, Digital, MicroVAX I, OpenVMS, POLYCENTER, RSX, VAX, VAX DOCUMENT, VAXcluster, VMS, and the DIGITAL 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.
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.
This guide is organized as follows:
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 on the Open Systems Software Group (OSSG) products and services, access the Digital OpenVMS World Wide Web site. Use the following URL:
http://www.openvms.digital.com
Digital 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 881-0120, Attention: OSSG Documentation, ZKO3-4/U08 |
|
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd. Nashua, NH 03062-2698 |
Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).
The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.
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 guide:
| ... |
Horizontal ellipsis points in examples indicate one of the following
possibilities:
|
| ( ) | In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. |
| [ ] | 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, braces indicate a required choice of options; 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.
This style is also used to show user input in Bookreader versions of the guide. |
| 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 device-name contains up to five alphanumeric characters). |
| UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. |
| - | A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows. |
| numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated. |
| parameters | Unless otherwise noted, all parameters that you use with product description language (PDL) statements are strings either enclosed in quotation marks or not enclosed in quotation marks. |
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, installation options, and answers to questions that are asked during the installation process.
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.
For software providers, the POLYCENTER Software Installation utility simplifies the task of packaging software because:
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:
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.
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.
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.
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.
Create a product description file (PDF) with a text editor. This step is described in Chapter 3. PDF files:
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? The following example shows a sample product description file. Subsequent chapters describe the PDF statements in line-by-line detail.
product DEC VAXVMS TNT V2.0 full ;
software DEC VAXVMS VMS version minimum V6.1 ;
execute
start "@SYS$STARTUP:TNT$STARTUP.COM"
stop "@SYS$STARTUP:TNT$SHUTDOWN.COM" ;
execute release "@pcsi$source:[sysupd]tnt$version61" uses [sysupd]tnt$version61.com ;
execute test "@SYS$TEST:TNT$IVP.COM" ;
directory [SYSTEST.TNT] ;
directory [TNT] ;
file [SYSHLP]TNT020.RELEASE_NOTES release notes ;
remove ;
file [SYSHLP]TNT010.RELEASE_NOTES ;
file [SYSHLP]TNT015.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 ;
file [SYS$STARTUP]TNT$SHUTDOWN.COM
release execute "@PCSI$DESTINATION:[SYS$STARTUP]TNT$SHUTDOWN.COM" ;
file [SYSUPD]TNT$VERSION61.COM ;
file [SYSMGR]TNT$UTILITY.COM ;
file [SYSTEST]TNT$IVP.COM ;
file [SYSEXE]TNT$SERVER.EXE ;
file [SYSEXE]TNT$UTILITY.EXE ;
file [SYSEXE]TNT$EXCLUDED_SYMBIONTS.DAT generation 1 ;
file [SYSTEST.TNT]TNT$SERVER_IVP.EXE ;
execute
postinstall "@PCSI$DESTINATION:[SYSMGR]TNT$UTILITY.COM UPDATE PRINTERS"
uses ([SYSMGR]TNT$UTILITY.COM) ;
end product ;
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.
The following example shows a product text file.
=product DEC VAXVMS TNT V2.0 full 1 'PRODUCT =prompt DEC OpenVMS Management Station The OpenVMS Management Station is a client-server application that provides OpenVMS system management capabilities via a client application on a Personal Computer running Microsoft Windows; the server application runs on OpenVMS systems. 1 'NOTICE =prompt © Digital Equipment Corporation 1994,1995,1996. 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 'LICENSE =prompt This product uses the PAK: VAX-VMS This product is contained within the Product Authorization Key for OpenVMS VAX. 1 'PRODUCER =prompt Digital Equipment Corporation This software product is sold by Digital Equipment Corporation. 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:TNT015.RELEASE_NOTES. 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.
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.
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.
This chapter defines some key terms and concepts. You should read this chapter before starting to create your installable kit.
This chapter describes the following topics:
If you are already familiar with the POLYCENTER Software Installation utility terms and concepts, begin with Chapter 3.
The product database (PDB) is a set of binary files located in SYS$SYSDEVICE:[VMS$COMMON] with a file extension of .PCSI$DATABASE. The POLYCENTER Software Installation utility automatically creates the PDB the first time a product is installed or registered on the system, such as when the OpenVMS operating system is installed. Once created, the utility simply updates the database as operations are performed to install, reconfigure, register, or remove products.
The PDB is the single source of information about operations performed on products using the POLYCENTER Software Installation utility. Information includes a history of operations performed, which products are installed, which files and other managed objects are owned by each product, software dependencies among products, and so forth.
The PDB consists of three permanent files:
A product specific database file is created each time a product kit is installed or registered, and deleted when the product is removed. For example, the layered product TNT V2.0 for OpenVMS VAX distributed by Digital might have a database file named DEC-VAXVMS-TNT-V0200--1.PCSI$DATDABASE.
Note
The format and content of the database files are controlled by the POLYCENTER Software Installation utility. If an OpenVMS system manager uses the POLYCENTER Software Installation utility to install your product, the utility will expect the database file to exist from that point on.Caution your product's users not to delete these files or the POLYCENTER Software Installation utility will not be able to detect and manage your product.
As a software provider, you can use PDL statements to query the product database to dynamically determine the version of an installed product, the history of a product, and what configuration choices were made. For example, the following example makes installation choices based on the installed version of OpenVMS on an Alpha system:
if (<software DEC AXPVMS VMS version minimum V6.2> AND
<software DEC AXPVMS VMS version maximum V6.2-999ZZZ>) ;
file [SYSEXE]TNT$SERVER.EXE generation 5
source [000000]TNT$SERVER_V62.EXE ;
file [SYSEXE]TNT$UTILITY.EXE generation 1
source [000000]TNT$UTILITY_V62.EXE ;
file [SYSTEST.TNT]TNT$SERVER_IVP.EXE generation 5
source [000000]TNT$SERVER_IVP_V62.EXE ;
end if;
if (<software DEC AXPVMS VMS version minimum V7.0> AND
<software DEC AXPVMS VMS version maximum V7.1-999ZZZ>) ;
file [SYSEXE]TNT$SERVER.EXE generation 5
source [000000]TNT$SERVER_V70.EXE ;
file [SYSEXE]TNT$UTILITY.EXE generation 1
source [000000]TNT$UTILITY_V70.EXE ;
file [SYSTEST.TNT]TNT$SERVER_IVP.EXE generation 5
source [000000]TNT$SERVER_IVP_V70.EXE ;
end if;
OpenVMS users can use the DCL command PRODUCT SHOW to query the product database to show what products are installed and the dependencies between them, to list the files and other objects that make up each product, or to show the history of installation and upgrade activity.
If your installation procedure or the OpenVMS user removes a product, information about the files and objects associated with the product are removed from the database. However, the history of the product's activity from installation to removal is retained in the database.
Your product is automatically registered in the database when it is installed by the POLYCENTER Software Installation utility. However, it is possible that your product might have a dependency on another product that was not installed by the POLYCENTER Software Installation utility. In this case, you must make sure that this other product is also registered in the database.
You might also want to register a prior version of your product that already exists on the OpenVMS system.
To register a product, have your customer use the command procedure SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM to register only the name of the product in the database. This allows your product to reference it. Note that you need to provide the customer with the producer, base, name, and version of the product, as described in subsequent sections.
The installable kit (also called a software product kit) you create can be in one of two POLYCENTER Software Installation utility formats:
Figure 2-1 shows how the package operation uses the PDF, PTF, and product material (that is, your actual software product) to create a reference or sequential copy.
Figure 2-1 Package Operation
The POLYCENTER Software Installation utility requires you to follow certain naming conventions for software product kits. Specifically, a software product kit packaged in sequential copy format has a .PCSI file of the following format:
producer-base-product-version-kit_type.PCSI
There is no .PCSI file in a reference copy kit. A software product kit packaged in reference copy format has a product description file in the root directory named in the following format:
producer-base-product-version-kit_type.PCSI$DESCRIPTION
The subfields in a kit name are position dependent and provide useful information about the kit. There are a few general naming rules:
The subfields are defined as follows:
The version of the software product kit is in the format tmmnn-ue. This format is described in Table 2-1.
| t | The type of version (a single uppercase alphabetic character). |
| mm | The major version number (decimal integer 01 through 99). |
| nn | The minor version number (decimal integer 00 through 99). |
| - | The hyphen is required in all cases. When both update level (u) and maintenance edit level (e) are omitted, the version will end with a hyphen and the file name will have a double hyphen (- -) preceding the kit type. |
| u | The update level (decimal integer 1 through 999). The level is optional. |
| e | The maintenance edit level (one or more alphanumeric characters beginning with an alphabetic character). This level is optional. |
The tmmnn-ue format used in file names is very similar to the format used to display versions to OpenVMS users, or as entered by the OpenVMS user with the /VERSION qualifier.
However, when the POLYCENTER Software Installation utility displays a version to the OpenVMS user:
The following version information is contained in the OpenVMS System Manager's Manual. However, it's worth repeating the information here to make sure that you know how the product version is interpreted:
The POLYCENTER Software Installation utility supports seven kit types. You will probably find that you use Full and Partial the most often. The kit types are described in Table 2-2.
| Value | Type of Kit | Description |
|---|---|---|
| 1 | Full | Layered product application software (complete kit). |
| 2 | Operating system | Operating system software (complete kit). Unless you are providing an operating system, you will not need this kit type. |
| 3 | Partial | An update to currently installed software that replaces or provides some of the product's files. The version is changed. |
| 4 | Patch | A correction to currently installed software. The version is not changed. |
| 5 | Platform | An integrated set of software products (product suite). |
| 6 | Transition | Used to register a product that was not installed by the POLYCENTER Software Installation utility. Transition kits include only a product definition file and (optionally) a product text file; they do not provide product material. |
| 7 | Mandatory update | A required correction to currently installed software. Functionally the same as a patch kit. The version is not changed. |
The following examples show how the format is used for a sequential copy format kit and two reference copy format kits:
DEC-VAXVMS-SOFTWIN-V0101--1.PCSI
DEC-AXPVMS-VMS-V0601-1H2-2.PCSI$DESCRIPTION
When installing your product, system managers must specify a location where the software kit resides and a location in which to install the software. Two methods are available for identifying these locations:
5952P.HTM OSSG Documentation 3-DEC-1996 08:58:39.01
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.