HP OpenVMS Systems Documentation

This chapter defines some key terms and concepts. Read this chapter before creating your installable kit.

This chapter describes the following topics:

• The product database ( Section 2.1)
• The format of software product kits ( Section 2.2)
• Software product name conventions ( Section 2.3)
• User-defined logical names ( Section 2.4)
• Utility-defined logical names ( Section 2.5)
• Managed objects ( Section 2.6)
• Creating an integrated platform ( Section 2.7)

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

2.1 The Product Database

The product database (PDB) is a set of binary files located in SYS$SYSDEVICE:[VMS$COMMON] with a .PCSI$DATABASE file extension. 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 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. This 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.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. The following example illustrates how installation choices are made 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 A7.1>) ;
        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 either 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.2 Software Product Kit Formats

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

• Sequential format. In this format, the PDF, the PTF, and all files that make up the product are packaged in a single container file with the .PCSI file extension. 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. Most layered products are distributed in sequential format.
• Reference format. In this format, the PDF, the PTF, and all files that make up the product are placed in a directory tree on a random-access device, such as a CD-ROM. The directory tree mirrors the directory structure of the product on the user's disk after installation. The top-level directory contains the PDF and PTF. OpenVMS is distributed in reference format on a CD-ROM.

Figure 2-1 shows how the package operation uses the PDF, PTF, and product material to create a product kit in reference or sequential format.

Figure 2-1 Package Operation

The POLYCENTER Software Installation utility adheres to the following file-naming conventions when either creating a software product kit or processing PDF and PTF files.

2.3.1 Sequential Format

A software product kit created in sequential format is a single file whose name is in the following format:

producer-base-product-version-kittype.PCSI

For example:

DEC-AXPVMS-DWMOTIF-V0102-6-1.PCSI

Note that the file name is constructed of components delimited by hyphens (-). The version component is further divided into subfields and includes an additional hyphen as explained in Section 2.3.4.

2.3.2 Reference Format

A software product kit created in reference format consists of a directory tree populated with product files used during installation. The directory structure mirrors the directory structure of the product on the user's disk after installation. The top-level directory contains the PDF and PTF. The presence of the PDF identifies this as a kit in reference format. There is no .PCSI container file for a kit in reference format. The PDF and PTF are named as follows:

producer-base-product-version-kittype.PCSI$DESCRIPTION
producer-base-product-version-kittype.PCSI$TLB

For example:

DEC-AXPVMS-DWMOTIF-V0102-6-1.PCSI$DESCRIPTION
DEC-AXPVMS-DWMOTIF-V0102-6-1.PCSI$TLB

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

• Each field 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 fields are defined as follows:

• producer is the legal owner of the software product. For HP software products this part of the PDF or sequential kit file name might be CPQ.
• base denotes the hardware and operating system 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. For example, DWMOTIF.
• version identifies the version of the software product expressed in tmn-ue format. For example, V0102-6 denotes V1.2-6. See Table 2-1 for more information.
• kittype identifies a kit type specified as a value from 1 through 7, as shown in Table 2-2.

The POLYCENTER Software Installation utility uses the version field to determine which kit is the most recent and therefore which kit supersedes another kit for the same product. The version field is in the format tmn-ue. This format is described in Table 2-1.

When the utility compares the file specifications of two kits for the same product to determine the latest version of the product, it examines the version strings as follows:

1. Compares the components of the version field in the following order:
   1. major version number (m)
   2. minor version number (n)
   3. update level (u)
   4. maintenance edit level (e)
   5. version type (t)
      It is important to note that version type (t) is the last component to be evaluated. Because it indicates the delivery status (internal, external, beta, and so on) of the product in the development cycle, it is considered the least important component.
2. Stops when it finds two components that are not equal, or determines that all five components are equal.
3. Evaluates alphabetic characters and numbers in ascending order.

Once you use an update level (u) or a maintenance edit level (e) in the product version field, that component must be carried throughout the release cycle of the product to ensure proper evaluation by the utility.

For example, if you release a test version of your product called E7.3-10 (expressed as E0703-10 in tmn-ue format) and then drop the update number in the final version V7.3, the utility will not recognize V7.3 as the latest version. This is what happens:

• The utility stops the comparison after it finds two components that are not equal. In this case it stops at the update level.
• Because the update level is not present in V7.3, it is evaluated as 0. Ten (10), the update level in E7.3-10, is greater than zero (0).
• Since version type is evaluated last, it is not a factor here.

Once the update level is established, as in E7.3-10, do not omit it (causing it to default to zero (0)) until you increase the major or minor version. Any of the following examples of version numbers would supersede E7.3-10:

• D7.3-10A, because A is greater than the null string.
• V7.3-10, because V is greater than E.
• A7.3-11, because 11 is greater than 10.

The tmn-ue format used in file names is 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 m and n.
• 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 is 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 (0) and the maintenance edit level is blank.

The POLYCENTER Software Installation utility supports the seven kit types described in Table 2-2.

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

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

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

  
  This format shows that the producer is DEC (HP), 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 kittype is 1 (full).
• A product description file in a reference format kit for OpenVMS Alpha has the following format:

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

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

Although you provide the product description file (PDF) and the product text file (PTF) as input to the package operation, they also exist in modified (output) form in the kit you create. You need to be aware that two versions of these files do exist and that they perform specific tasks.

You create the input version as input to the package operation, and the POLYCENTER Software Installation utility creates the output version for its own use.

The package operation changes the format of the output PTF file. For more information, see Section 4.2.

The output PDF is in the same format as the input PDF, but the package operation may modify statements in the output PDF. For example, the package operation adds the size option to file statements in the output PDF.

2.4 User-Defined Logical Names

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 Product Description Language (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.

With the introduction of the new qualifiers to the PRODUCT INSTALL and PRODUCT RECONFIGURE commands, namely /RECOVERY_MODE and /SAVE_RECOVERY_DATA, new logical names have been added to increase product developers' control over the product installation process. These new logical names are PCSI$$RECOVERY_MODE and PCSI$$SAVE_RECOVERY_DATA. The PCSI$$RECOVERY_MODE logical name represents the /RECOVERY_MODE qualifier while the PCSI$$SAVE_RECOVERY_DATA qualifier represents the /SAVE_RECOVERY_DATA command-line qualifier. They are defined in the system wide logical name table whenever the user specifies their equivalent qualifiers as follows.

For the /RECOVERY_MODE qualifier, the PCSI$$RECOVERY_MODE logical name is defined with a YES value. If the user specifies /NORECOVERY_MODE, the PCSI$$RECOVERY_MODE logical name is defined with a NO value. If the user does not use the /RECOVERY_MODE qualifier at all, the logical name is not defined either. The same process applies to the PCSI$$SAVE_RECOVERY_DATA logical name.

The /RECOVERY_MODE qualifier forces product installation to be performed in recovery mode, which allows recovery from a failed product installation or reconfiguration through a rollback of files and library modules displaced by the failed operation. By default, the installation and reconfiguration are not performed in recovery mode.

The /SAVE_RECOVERY_DATA qualifier applies to patch and mandatory update kits installation only. It is similar to /RECOVERY_MODE in that it forces files displaced during installation to be saved in a specially designated directory tree. Those saved objects can later be used to uninstall patch products by executing the PRODUCT UNDO PATCH command. By default, the patch kit installation does not trigger patch recovery data to be saved for future use. This is the reason the PCSI$$RECOVERY_MODE and PSCI$$SAVE_RECOVERY_DATA logical names have been introduced.

Using these logical names, the product developer can control whether the product installation is performed in recovery mode or whether the patch recovery data is being saved for potential patch kit removal. Using a command procedure supplied with the PDL statement EXECUTE PRECONFIGURE in your PDF, you can examine the logical names and determine if the user has specified the /RECOVERY_MODE or /SAVE_RECOVERY_DATA qualifiers.

If, for example, the user did not use the /SAVE_RECOVERY_DATA qualifier, and you believe that it is important that your patch kit be installed in a manner allowing its uninstallation in case of a problem, you can set the PCSI$$SAVE_RECOVERY_DATA logical name in your EXECUTE PRECONFIGURE command and force the recovery data to be saved for future use.