Updated: 11 December 1998

POLYCENTER Software Installation Utility Developer's Guide

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:

• The product database
• The format of software product kits
• Software product name conventions
• Version identification format
• Software product name examples
• Logical names
• Packaging a platform
• Managed objects

If you are already familiar with the POLYCENTER Software Installation utility terms and concepts, begin with Chapter 3.

2.1 Learn About the Product Database

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:

• PCSI$FILE_SYSTEM.PCSI$DATABASE
• PCSI$PROCESSOR.PCSI$DATABASE
• PCSI$ROOT.PCSI$DATABASE

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 V3.0 for OpenVMS VAX might have a database file named DEC-VAXVMS-TNT-V0300--1.PCSI$DATABASE.

As a software provider, you can use PDL statements to query the product database to dynamically determine the version of an installed product. 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 below A6.3>) ; 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 below A6.3>) ; 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.

2.1.2 Registering Products 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.

2.2 Are There Specific Formats for Installable Kits?

The installable kit (also called a "software product kit") you create can be in one of two POLYCENTER Software Installation utility formats:

• Sequential copy format. Most layered products are distributed in sequential copy format. In this form, the PDF, the PTF, and all files that comprise the product are packaged in a single container file with the file extension .PCSI. You can ship this .PCSI file either on a random-access device, such as a CD-ROM, or on a sequential access device, such as a magnetic tape.
• Reference copy format. In this form, the PDF, the PTF, and all files that comprise the product are placed in a directory tree on a random-access device, such as a CD-ROM. There is no .PCSI file. OpenVMS is distributed in reference copy format on CD-ROM.

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

2.3.1 What Do the Subfields in the Name Mean?

The subfields in a kit name are position dependent and provide useful information about the kit. There are a few general naming rules:

• Each subfield in the file name is separated by a hyphen.
• The length of the file name string (including all required hyphens) cannot exceed 39 characters.
• The producer-base-product portion of the string must uniquely identify the software product.

The subfields are defined as follows:

• producer is the legal owner of the software product. For Compaq software products this part of the PDF file name is DEC.
• base denotes the hardware and software combination that the product requires. For OpenVMS Alpha systems, use AXPVMS; for OpenVMS VAX systems, use VAXVMS; for products that can be installed on either OpenVMS Alpha or OpenVMS VAX, use VMS.
• product is the name of the software product.
• version identifies the version of the software product expressed in tmmnn-ue format. See Table 2-1 for more information.
• kit_type identifies a kit type specified as a value from 1 through 7, as shown in Table 2-2.

The version of the software product kit is in the format tmmnn-ue. This format is described in Table 2-1.

Table 2-1 Format of tmmnn-ue Version Identification

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.

2.3.3 What Version Information Will the OpenVMS User See?

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:

• Leading zeros are omitted in mm and nn.
• If neither u nor e is present, the hyphen (-) is omitted.

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:

• If a hyphen is present and the first character after the hyphen is a digit, then the leading digits after the hyphen are the update level. If nondigit characters are present, the maintenance edit level consists of the first nondigit character and all following characters. If nondigit characters are not present, the maintenance edit level is blank.
• If a hyphen is present and the first character after the hyphen is a nondigit character, the update level is zero (0) and the maintenance edit level consists of all of the characters after the hyphen.
• If no hyphen is present, the update level is zero and the maintenance edit level is blank.

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.

Table 2-2 PDF Kit Types and Values

Value	Type of Kit	Description
1	Full	Layered product (application) software.
2	Operating system	Operating system software.
3	Partial	An upgrade to currently installed software that replaces or provides new files. Installation of this kit changes the version of the product.
4	Patch	A correction to currently installed software that replaces or provides new files. Installation of this kit does not change the version of the product.
5	Platform	An integrated set of software products (product suite).
6	Transition	Product information used to register (in the POLYCENTER Software Installation database) a product that was installed by VMSINSTAL or other mechanism. This kit includes only a PDF and (optionally) a PTF; it does not provide product material.
7	Mandatory update	A required correction to currently installed software that replaces or provides new files. Installation of this kit does not change the version of the product. Functionally the same as a patch kit.

2.4 Looking at Software Product Name Examples

The following examples show how the format is used for a sequential copy format kit and a reference copy format kit:

• A sequential copy format kit for DEC Softwindows for OpenVMS VAX and that requires a double hyphen has the following format:

  DEC-VAXVMS-SOFTWIN-V0101--1.PCSI

  
  This format shows that the producer is DEC (Compaq), the base is VAXVMS (OpenVMS VAX), the product is SOFTWIN, and the version is V1.1. The type of version is V, the major and minor version numbers are each 1. There are no update or maintenance edit levels. The kit_type is 1 (full).

• A product description file in a reference copy format kit for OpenVMS Alpha has the following format:

  DEC-AXPVMS-VMS-V0601-1H2-2.PCSI$DESCRIPTION

  
  This format shows that the producer is DEC (Compaq), the base is AXPVMS (OpenVMS Alpha), the product is OpenVMS, and the version is V6.1-1H2. The type of version is V, the major version number is 6, the minor version number is 1, the update level is 1, and the maintenance edit level is H2. The kit_type is 2 (operating system).

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:

• Defining logical names
• Specifying /SOURCE and /DESTINATION qualifiers on the command line

The system manager can also define logical names, and then override them by using the /SOURCE and /DESTINATION qualifiers.

PCSI$SOURCE defines the location of the software kits to install. By default, the user's default device and directory are used. PCSI$DESTINATION defines the location in which to install the software.

If the system manager does not define PCSI$DESTINATION or use the /DESTINATION qualifier, the utility installs the software product in SYS$SYSDEVICE:[VMS$COMMON] and directories under it. If this is not appropriate for your product, make sure that your installation instructions describe how to specify the /DESTINATION qualifier, or how to define the PCSI$DESTINATION logical name.

Several PDL statements execute command procedures in the context of a subprocess. The POLYCENTER Software Installation utility defines the logical names PCSI$SOURCE, PCSI$DESTINATION, and PCSI$SCRATCH for use by these command procedures. Note that these logical names are accessible only within the subprocess and do not interfere with similar names that the user may have defined. Note also that the user's definition of PCSI$SOURCE is not the same as that defined by the utility for the command procedure. See the PDL statement definitions for additional information.

2.7 Managed Objects

Managed objects are the files, directories, accounts, network object and so forth that support the proper functioning of your product. The POLYCENTER Software Installation utility must directly create an object in order to manage it. That is, the term "managed object" refers only to objects that the POLYCENTER Software Installation utility directly creates.

As an example, if you use a PDF file statement to create a file, that file is considered to be a managed object.

However, if your product creates directories, files, and so forth after the installation is completed, the POLYCENTER Software Installation utility has no way to know about those files or directories and cannot manage them. For example, if your product dynamically creates an error log as a result of a specific error condition, the POLYCENTER Software Installation utility will not be able to manage (for example, remove) this log file. This means that if the OpenVMS user uses the POLYCENTER Software Installation utility to remove your software product, the user would have to delete the error log manually.

In addition, if your PDF file includes command procedures that create files, directories, accounts, and so forth, the POLYCENTER Software Installation utility has no way to know about these objects and cannot manage them.

2.7.1 Creating Managed Objects

How do you create managed objects? Using PDL statements, you can specify the names and properties of the managed objects that are necessary for your product. At installation time, the POLYCENTER Software Installation utility uses your product description file (PDF) to create the managed objects for your product and records information about these objects in the product database.

For example, you use the directory, file, and module statements to specify directory, file, and library module managed objects, as shown in the following example:

directory [SYSTEST.FORTRAN] ; file [SYSTEST]FORT$IVP.COM ; file [SYSHLP]TNT030.RELEASE_NOTES release notes ; file [SYSHLP]HELPLIB.HLB generation 40069227 release merge ; module [000000]DECC.CLD type command module CC ;

When the POLYCENTER Software Installation utility removes a software product, it uses the data in the product database to delete managed objects from the system.

2.7.2 Managed Object Conflict

Occasionally, your product will supply a managed object that conflicts with another managed object. For example, if you supply a file called foo.txt and a file by that name already exists in the directory, a conflict occurs. It's possible that this file is a remnant of an earlier instance of your software product and you can freely overwrite it. However, it is also possible that the existing file is owned by some other software product and you do not want to randomly replace it.

When the utility detects conflict, it displays an informational message. The following statements detect managed object conflict and display informational messages:

• account
• bootstrap block
• directory
• file
• link
• loadable image
• module
• network object
• patch image
• patch text
• register module
• rights identifier

In some cases, the POLYCENTER Software Installation utility allows you to anticipate and resolve conflict before it occurs. For example, the generation option to the file statement lets you resolve managed object conflict. During installation, if the utility attempts to create a file that already exists, it compares the generation numbers of the files (if present), preserving the file with the highest generation number.

The following statements provide some level of conflict resolution:

• directory
• file
• module
• register module

The description of these statements in Chapter 7 indicates how each one resolves managed object conflict.

2.7.4 Managed Object Replacement and Merging

As described in Section 2.7.2, managed objects occasionally have characteristics that conflict with each other. The POLYCENTER Software Installation utility handles this situation differently depending on the kit type:

• For full, operating system and platform kit types, the utility deletes the existing object and replaces it with the object and characteristics provided by the new version of the product.
• For partial, patch, and mandatory update kit types, the utility preserves the characteristics of existing objects. For example, the security environment you establish for your product is preserved when you install a partial, patch, or mandatory update kit.

If you want to provide new characteristics for a managed object in a partial, patch, or mandatory update kit, use the remove statement to delete the existing object and then respecify it with the desired characteristics.

For more information about kit types, see Table 2-2.

2.7.5 Managed Object Scope and Lifetime

The scope of a managed object defines the degree of sharing that the managed object permits. For example, some objects are available only to certain processes, and some can be shared by all processes. The utility usually ensures that managed objects have the correct scope.

Occasionally, you might need to use the scope statement to give a managed object a scope other than its default. For more information about specifying the scope of a managed object, see Chapter 6.

2.8 Optional Information --- Packaging a Platform

In addition to packaging individual products, the POLYCENTER Software Installation utility gives you the means to assemble integrated platforms. An integrated platform is a combination of several products, such as a suite of complementary management products that you might bundle together.

Functionally, a platform is the same as a full kit, except that it has the designation "PLATFORM." A platform is intended to reference other products, but it can also supply files.

Figure 2-2 shows an example of an integrated platform.

Figure 2-2 Integrated Platform Example

To package a platform, you create a platform PDF and platform PTF. In addition to other statements, the platform PDF contains software statements that specify the products that make up the platform. The individual products have their own PDFs and PTFs (independent of the platform PDF and PTF). For more information about platform PDFs, see Section 3.5.3.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5952PRO_001.HTML