HP OpenVMS Systems Documentation

POLYCENTER Software Installation Utility Developer's Guide

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 (Hewlett-Packard), 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 (Hewlett-Packard), 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.

This section discusses the logical names defined by the POLYCENTER Software Installation utility for use by kit-supplied command procedures.

2.5.1 PCSI$SOURCE, PCSI$DESTINATION, and PCSI$SCRATCH

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 Figure 6-1 and the descriptions of various EXECUTE statements in the PDL reference section for additional information.

2.5.2 PCSI$$RECOVERY_MODE and PCSI$$SAVE_RECOVERY_DATA

With the introduction of the /RECOVERY_MODE and /SAVE_RECOVERY_DATA qualifiers to the PRODUCT INSTALL and PRODUCT RECONFIGURE commands for OpenVMS Version 7.3-2, the utility defines logical names 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 and are deassigned when the PRODUCT command terminates.

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. 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 operations are not performed in recovery mode.

The /SAVE_RECOVERY_DATA qualifier applies only to the installation of patch and mandatory update kits. 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 PCSI$$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.

2.5.3 PCSI$$COMMAND_LINE

Starting with OpenVMS Version 8.2, the utility defines the logical name PCSI$$COMMAND_LINE to be the DCL command line entered by the user that initiated the PRODUCT command. This logical name is defined in the system-wide logical name table and is deassigned when the PRODUCT command terminates.

2.5.4 PCSI$$CONFIRM

Starting with OpenVMS Version 8.2, the utility defines the logical name PCSI$$CONFIRM with a NO value when the user specifies the /OPTIONS=NOCONFIRM qualifier on the command line. This logical name is defined in the system-wide logical name table and is deassigned when the PRODUCT command terminates.

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 manually delete the error log.

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.