HP OpenVMS Systems Documentation
POLYCENTER Software Installation Utility Developer's Guide
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 files 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. The complete set of database files must be intact for the utility to access the information in the 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 TNT$SERVER_V62.EXE ; file [SYSEXE]TNT$UTILITY.EXE generation 1 source TNT$UTILITY_V62.EXE ; file [SYSTEST.TNT]TNT$SERVER_IVP.EXE generation 5 source 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 TNT$SERVER_V70.EXE ; file [SYSEXE]TNT$UTILITY.EXE generation 1 source TNT$UTILITY_V70.EXE ; file [SYSTEST.TNT]TNT$SERVER_IVP.EXE generation 5 source 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
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:
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:
The fields in a kit name are position dependent and provide useful information about the kit. There are a few general naming rules:
The fields are defined as follows:
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.
|t||The type of version (a single uppercase alphabetic character A through V; the letters W, X, Y, and Z are reserved for use by Compaq). Evaluated by ascending ASCII value. Usually pre-release versions of a product begin with the letters A through U and V is used to indicate the formal release version.|
|m||The major version number (decimal integer 01 through 99).|
|n||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 string 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 999999999). Optional. If not present, the utility evaluates this component as 0.|
|e||The maintenance edit level (up to 16 alphanumeric characters beginning with an alphabetic character). Optional. If not present, the utility evaluates this component as a null string.|
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:
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:
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:
The tmn-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 is worth repeating the information here to make sure that you know how the product version is interpreted:
The POLYCENTER Software Installation utility supports the seven kit types described in Table 2-2.
|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 (also known as a software 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.|
The following examples show how the format is used for a sequential format kit and a reference format kit:
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 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:
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.
When you package your product, the logical names PCSI$SOURCE and PCSI$DESTINATION are not used. You must use the /SOURCE and /DESTINATION qualifiers on the PRODUCT PACKAGE command.
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.
2.6 Managed Objects
Managed objects are the files, directories, accounts, network objects, and so forth that support the proper functioning of your product. The POLYCENTER Software Installation utility must directly create them.
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 includes command procedures in
execute statements 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.6.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.
directory [SYSTEST.FORTRAN] ; file [SYSTEST]FORT$IVP.COM ; file [SYSHLP]TNT030.RELEASE_NOTES release notes ; file [SYSHLP]HELPLIB.HLB generation 40069227 release merge ; module CPQC.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.
Use the PRODUCT SHOW OBJECT command to display the names of objects installed on a system. For example:
$ PRODUCT SHOW OBJECT *COPY* ----------------------------------------------- ----------------- ----- OBJECT NAME OBJECT TYPE STATUS ----------------------------------------------- ----------------- ----- [SYSEXE]COPY.EXE file OK [SYSHLP.EXAMPLES.DECW.UTILS]COPYRIGHT.H file OK COPY module OK