HP OpenVMS System Manager's Manual, Volume 1:...

Installing, Upgrading, and Updating Software

Selecting VMSINSTAL.COM Options

Installing with the POLYCENTER Software Installation utility

Using the POLYCENTER Software Installation utility  

Perform POLYCENTER Software Installation utility operations from the DCL prompt. Use the following command format to invoke each operation:

$ PRODUCT subcommand product-name[/qualifier1,...]

$ PRODUCT INSTALL COBOL/VERSION=2.2,FORTRAN [Return] 

The following products have been selected:
    DEC AXPVMS COBOL V2.2           Layered Product
    DEC AXPVMS FORTRAN V7.0         Layered Product

Do you want to continue? [YES] [Return] 

You can enter PRODUCT commands at the DCL prompt ($) or in a DCL command procedure. Refer to the HP OpenVMS System Management Utilities Reference Manual: M--Z for subcommand syntax information.

To run the POLYCENTER Software Installation utility as a batch job, see Performing the Installation as a Batch Job.

DCL Commands and Descriptions lists DCL commands the POLYCENTER Software Installation utility can perform and describes each of them.

Table 3   DCL Commands and Descriptions

DCL Command	Description
PRODUCT CONFIGURE	Creates a product configuration file (PCF)
PRODUCT COPY	Copies a software product kit or converts it to another format
PRODUCT DELETE RECOVERY_DATA	Deletes one or more patch recovery data sets
PRODUCT EXTRACT FILE	Retrieves a specified file or files from a software product kit
PRODUCT EXTRACT PDF	Retrieves the product description file (PDF) from a software product kit
PRODUCT EXTRACT PTF	Retrieves the product text file (PTF) from a software product kit
PRODUCT EXTRACT RELEASE_NOTES	Retrieves the release notes from a software product kit
PRODUCT FIND	Displays the name of product kits found in a specified directory
PRODUCT INSTALL	Installs one or more software products and updates the product database
PRODUCT LIST	Lists a file or files contained in a specified product kit that is packaged in sequential format
PRODUCT PACKAGE	Creates a software product kit in either sequential or reference format
PRODUCT RECONFIGURE	Modifies the configuration of an installed product and updates the product database
PRODUCT REGISTER PRODUCT	Records information in the product database about one or more installed products that are not yet registered in the database
PRODUCT REGISTER VOLUME	Records a change in volume label in the product database
PRODUCT REMOVE	Uninstalls one or more software products and updates the product database
PRODUCT SHOW HISTORY	Displays in chronological order the operations performed on software products
PRODUCT SHOW OBJECT	Displays information about objects created during software product installation
PRODUCT SHOW PRODUCT	Displays information about installed products
PRODUCT SHOW RECOVERY_DATA	Displays patch recovery data sets in chronological order
PRODUCT SHOW UTILITY	Displays information about the POLYCENTER Software Installation utility
PRODUCT UNDO PATCH	Uninstalls one or more patches for which recovery data has been saved

Privileges Required

The POLYCENTER Software Installation utility requires specific privileges to perform certain operations, as shown in Privileges Required by the POLYCENTER Software Installation Utility.

Table 4   Privileges Required by the POLYCENTER Software Installation Utility

Operations	Privileges Required
COPY, DELETE, EXTRACT, FIND, LIST, PACKAGE	None
CONFIGURE, SHOW	SYSLCK
REGISTER	SYSLCK and SYSPRV (or a system UIC)
INSTALL, RECONFIGURE, REMOVE, UNDO	SYSLCK, SYSPRV (or a system UIC), TMPMBX, and CMKRNL

Some commands might also require BYPASS or NETMBX privileges.

The execution of command procedures from the kit you are installing might require additional privileges. Check the installation guides that you receive with product kits for these privileges.

Product Files and Databases  

The following files are used by the POLYCENTER Software Installation utility:

• The product description file (PDF), is provided by the software manufacturer. It contains all the information the POLYCENTER Software Installation utility needs for installing either a software product or a set of software products. The PDF includes a list of configuration choices the product offers, default choices, and product requirements (such as minimum hardware configurations and system parameter values).



• A product text file (PTF), is optionally supplied by the software manufacturer. It provides information about the product. The information includes product name, producer, configuration choice descriptions, and message text used during product installation.



• A product configuration file (PCF), is optional. It may be supplied by software manufacturer, or you can create it by using the CONFIGURE operation. A PCF contains responses to some or all of the installation questions for a product. It can provide default or required choices, which may differ from the default choices provided in the PDF.



• The product database (PDB), is created automatically by the POLYCENTER Software Installation utility. When products are installed, the files and other objects that make up the product, such as directories and accounts, are recorded in the PDB. The configuration choices made during installation are also recorded.
  
  You can access the PDB to show what products are installed and the dependencies between them. You can also list the files and other objects that make up each product, or the history of installation and upgrade activity.



• Patch recovery data sets are created automatically by the POLYCENTER Software Installation utility. When products are installed in recovery mode or when patch kits are installed with a request to save recovery data, the files and other objects that are displaced by the current installation are saved in a specially designated directory tree for future use.
  
  You can display information about recovery data sets and learn which patch kits can be uninstalled using the SHOW RECOVERY_DATA operation.

Format of Software Product Kits  

Software products compliant with the POLYCENTER Software Installation utility are distributed in one of three formats:

• Compressed format. In this form, a data compression technique has been applied to a sequential kit. A compressed kit has a .PCSI$COMPRESSED file type.



• Sequential format. In this form, the PDF, the PTF, and all files that comprise the product are packaged in a single container file. This container file can be placed either on a random-access device, such as a compact disc, or on a sequential access device, such as a magnetic tape. Most layered products are distributed in sequential format.



• Reference 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. OpenVMS is distributed in reference copy format on CD-ROM.

Software Product Name Conventions  

A software product kit packaged in sequential copy format has a container file named in the following format:

producer-base-product-version-kit_type.PCSI

producer-base-product-version-kit_type.PCSI$DESCRIPTION

• producer is the legal owner of the software product (for example, DEC)



• base is the base system that specifies the hardware and software platform on which the product runs (for example, AXPVMS or VAXVMS).



• product is the name of the software product.



• version identifies the version according to the format tmmnn-ue, described in Version Identification Format.



• kit_type identifies a kit type specified as a value from 1 through 7, as shown in PDF Kit Types and Values.

Table 5   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.

Version Identification Format  

The version of the software product kit is in the format tmmnn-ue. This format is described in Format of tmmnn-ue Version Identification.

Table 6   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.

The following table of examples shows how to use the format:

Example	Description
V6.1	In this example: Version type: V Major release: 06 Minor release: 01 Update level: 0 (implicit) No edit level
V6.1-1H2	In this example: Version type: V Major release: 06 Minor release: 01 Update level: 1 Edit level: H2
T6.2-FT2	In this example: Version type: T Major release: 06 Minor release: 02 Update level: 0 (implicit) Edit level: FT2

Software Product Name Examples  

The following examples show how the format is used for one sequential and two reference copy format kits:

• A sequential format kit for DEC 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 (DIGITAL), 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 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 (DIGITAL), 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 1, the update level is 1, and the maintenance edit level is H2. The kit_type is 2 (operating system).



• A compressed kit for HP Kerberos has the following format:

  HP-AXPVMS-KERBEROS-V0200-6-1.PCSI$COMPRESSED

  This format shows that the producer is HP, the base is AXPVMS (OpenVMS Alpha), the product is KERBEROS, and the version is V2.0-6. The type of version is V, the major version number is 2, the minor version number is 0, and the update level is 6. There is no maintenance edit level. The kit_type is 1 (full).

Creating a Product Configuration File (PCF)  

You can create a PCF before or during an installation. You can also create more than one PCF for each product, thereby helping you to customize software installations for unique hardware situations or for different usage patterns within a group.

If a PCF is present and it contains a response for a configuration choice, the default for that choice comes from the PCF. The PCF specifies whether the choice can be changed or whether it is required.

If a PCF is not present or does not contain a response for a configuration choice, the default choice comes from one of two places:

• If the product database (PDB) contains an entry for the choice that was made in a previous installation, then the PDB entry becomes the default configuration choice. It can be changed.



• If the PDB does not contain an entry for the choice, either because the product was not previously installed or because this is a new choice, then the default configuration choice comes from the PDF. It can be changed.

Configuration Options  

Some options available for customizing the PCF are:

• Saving your answer. You can specify that your response to a question (rather than the current default value) be stored in the PCF.



• Not saving your answer. When creating a PCF during an installation, you can answer a question without recording your answer in the PCF. This is useful for responding to questions that are specific to a single system or installation.



• Deferring a question so that it is asked again during a future installation. For example, you might want an installer to verify that a particular response is still valid for the systems on which each installation is being performed.



• Preventing a question from being asked again. If you do not defer a question when you create a PCF, the response recorded in the PCF is used during future installations. The installer is not prompted for the information. This reduces the length and complexity of the actual installation procedure.

Configuration Commands  

To create a PCF, use the PRODUCT CONFIGURE command. For example:

$ PRODUCT CONFIGURE CHESSMASTER

Recording Configuration Choices  

After defining the PCF, the POLYCENTER Software Installation utility prompts you with questions about the product. Determine how and whether your responses are recorded in the PCF by responding to the questions and using two predefined function keys. The following table shows how your responses configure the PCF:

Key	Action by the POLYCENTER Software Installation utility
Return	Accepts the default or explicitly entered choice for the current operation and for entry into the PCF, and then moves to the next choice. If the Defer option is in effect, this entry can be changed when the PCF is used for future installations or upgrades. If the Defer option is not in effect, this entry cannot be changed when the PCF is used for future installations or upgrades. If the Write option is in effect, this entry, including the Defer option, is written into the PCF and used when the PCF is used for future installations or upgrades. If the Write option is not in effect, this entry, including the Defer option, is not written into the PCF and is not used when the PCF is used for future installations or upgrades. In this case, the default for the future installation or upgrade will come from the PDF or PDB.
F17	Toggles the Defer option. By default, the Defer option is not in effect.
F18	Toggles the Write option. By default, the Write option is in effect.

Press the Return key after each response.

Sample Procedure for Creating a PCF shows how to use keys F17 and F18 in the PCF. Note that this is an example only and does not necessarily represent an actual PCF for a product. A description of the callouts follows the example.

Example 1  Sample Procedure for Creating a PCF

$ PRODUCT CONFIGURE VMS/SOURCE=SYS$SYSDEVICE:[VMS$COMMON]/LOG - _$ /CONFIGURATION=(OUTPUT=MYPCF) [Return] The following product has been selected: DEC AXPVMS VMS V7.2 [Available] Do you want to continue [YES] [Return] Configuration phase starting ... You will be asked to choose options, if any, for each selected product and for any products that may be installed to satisfy software dependency requirements. *** DEC AXPVMS VMS V7.2: OpenVMS Operating System Copyright © 1998 Compaq Computer Corporation Compaq Computer Corporation Do you want the defaults for all options? [YES] N Return [1] Accounting Log Report Generator Utility [YES] F17 [2] %PCSIUI-I-DEFER, that item has been deferred; please set the default value Accounting Log Report Generator Utility [YES] F17 [3] %PCSIUI-I-UNDEFER, that item is no longer deferred; please set the value Accounting Log Report Generator Utility [YES] F17 [3] %PCSIUI-I-DEFER, that item has been deferred; please set the default value. Accounting Log Report Generator Utility [YES] [Return] [4] Access Control List Utilities [YES] F18 [5] %PCSIUI-I-UNWRITE, that item will not be written to configuration file; please set the value. Access Control List Utilities [YES] [Return] [6] Print and Batch Queue Utilities [YES] NO [7] DECdtm Distributed Transaction Manager [YES] [Return] [8] Do you want the defaults for all suboptions? [YES] NO . . . Programming Support [YES] Return Do you want the defaults for all suboptions? [YES] NO . . . Do you want to review the options ?[NO] Return [9] %PCSI-I-WRICON, writing configuration file SYS$SYSDEVICE:[VMS$COMMON]MYPCF.PCSI$CONFIGURATION;1 [10] %PCSIUI-I-SUCCONFIG, CONFIGURE operation completed successfully $

The callouts in the example mark the following actions:

1. Chooses to select values for individual options instead of accepting default values for all of the options.
2. Requests (by using the defer key, F17) that the installer be given the choice of whether or not to install the optional example files.
3. Toggles the defer option (twice to illustrate the toggle effect).
4. Records the default response [Yes] in the PCF. Because the defer option was in effect, when the PCF is used during a future installation, the installer can select the Accounting Log Report Generator utility by default, or can choose not to select it.
5. Requests the nowrite option key (F18) so that this choice will not be written to the PCF.
6. Chooses not to install the Access Control List utilities. Because the nowrite option is in effect, this choice is not written to the PCF.
7. Chooses not to install the Print and Batch Queue utilities. Because the nowrite option is not in effect (by default) and the defer option is in effect (by default), this choice is written to the PCF and the question is not asked again when the PCF is used during a future installation.
8. Accepts the default to install the DECdtm Distributed Transaction Manager. Because the nowrite option is not in effect (by default) and the defer option is in effect (by default), this choice is written to the PCF, and the question is not asked again.
9. Requests that the configuration options be displayed.
10. Displays the name of the PCF that has been created, MYPCF.PCSI$CONFIGURATION. The POLYCENTER Software Installation utility displays this message only when you enable message logging by using /LOG with PRODUCT CONFIGURE.

When you use a single DCL command to install or configure more than one product and write the responses to a PCF, the information for all the products that are installed or configured is in a single PCF. Use separate operations to install or configure a set of products when you want to keep each product's configuration values in its own PCF.

Modifying an Existing PCF  

You can use DCL to modify an existing file. Specify the name of the PCF to be modified and the name of the PCF to be created. Include both the INPUT and the OUTPUT keywords with the /CONFIGURATION qualifier on the PRODUCT CONFIGURE command line. For example, read the default values in the file PRODUCTA_REV1.DAT, make changes to the file, and save the changes to PRODUCTA_REV2.DAT, the output file:

$ PRODUCT CONFIGURE -
_$ /CONFIGURATION=(INPUT=PRODUCTA_REV1.DAT,OUTPUT=PRODUCTA_REV2.DAT) -
_$ PRODUCTA  

Using a Product Database  

The POLYCENTER Software Installation utility automatically stores information about product installation, configuration choices, and objects, such as files and directories, that make up the product in the product database. The product database is useful for recalling information about products installed on your system and for detecting and tracking product dependencies.

Adding Information to the Database  

Although the POLYCENTER Software Installation utility stores product information for you automatically, you can also add your own information. When you perform a task, you can include a remark---a comment to be recorded in the product database---along with the other information about the task being performed.

To add a remark to the product database, use the /REMARK qualifier with any of the following DCL commands:

• PRODUCT RECONFIGURE



• PRODUCT INSTALL



• PRODUCT REMOVE



• PRODUCT REGISTER PRODUCT

Refer to the HP OpenVMS System Management Utilities Reference Manual: M--Z for information about this command and the /REMARK qualifier.

Registering a Noncompliant Product  

To register a product that was installed with a tool other than the POLYCENTER Software Installation utility, enter PRODUCT REGISTER PRODUCT. This command records information that a PDF provides. For example:

$ PRODUCT REGISTER PRODUCT TOOLCHEST

$ @SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM

Because PCSI$REGISTER_PRODUCT.COM creates only a minimal PDF, it cannot register with the POLYCENTER Software Installation utility database all the information about the product. For this reason, if a PDF for the product is available, use it.

Although a transition PDF is intended specifically for PRODUCT REGISTER PRODUCT, you can also register full and operating system PDFs.

Detecting and Tracking Software Dependencies  

Some software products depend on other software products to work correctly. For example, a product might work only when a specific version of another product is installed on the system. The POLYCENTER Software Installation utility detects and tracks the dependencies of the products that you install. The utility also attempts to satisfy the requirements of multiple products. In some instances, the POLYCENTER Software Installation utility is unable to resolve product dependency issues. In such instances, the utility provides feedback on the nature of the conflict and asks you to decide how to proceed.

Understanding Recovery Data Sets  

You can use recovery data sets in the following circumstances:

• When the installation of a patch kit fails



• When you want to undo (or uninstall) one of more patch kits that have been installed using the POLYCENTER Software Installation utility

A recovery data set is, in a sense, an extension of the POLYCENTER Software Installation utility product database. A recovery data set consists of the following types of files:

• Saved product files



• Supplementary data files that catalog actions that reverse the effect of installing a patch kit



• Database files as they were at the beginning of the installation of the patch kit

A recovery data set is, in other words, a combination of the directories and files that are replaced by newer ones when a patch kit is installed. Recovery data set files are saved in a designated directory for possible future use. The data files that describe the replaced files and directories and their contexts are also saved.

Recovery data sets are stored in the following directory tree on the same system disk as the product database files, where nnn is the recovery data set number:

 [PCSI$UNDO_nnn]

The two major uses of recovery data sets are discussed in the next two sections.

Recovering from a Failed Installation of a Patch Kit  

To be able to recover completely from a failed installation of a patch kit, you must install the kit using the following command:

$ PRODUCT INSTALL/RECOVERY_MODE 

When you enter this command, the POLYCENTER Software Installation utility installs the patch kit in what is called recovery mode. When you install a kit in recovery mode, the files that the installation modifies or replaces are saved; they make up a recovery data set. If an error condition interrupts the installation or if you intentionally terminate the installation, the POLYCENTER Software Installation utility can use the recovery data set to roll back the original files. This action restores the product environment that existed prior to the interrupted installation.

Once the rollback completes, the POLYCENTER Software Installation utility destroys the recovery data set. The utility also destroys the recovery data set at the end of a successful product installation or reconfiguration. You can, however, prevent the deletion of the recovery data set by using the /SAVE_RECOVERY_DATA qualifier with the PRODUCT INSTALL command. The next section explains how to do this.

Undoing One or More Patch Kit Installations  

You can create a recovery data set when you install a patch kit, and, at the same time, explicitly request the POLYCENTER Software Installation utility to save recovery data. You do this by entering the following command:

$ PRODUCT INSTALL/SAVE_RECOVERY_DATA

When you enter this command, the POLYCENTER Software Installation utility permanently saves the files that the installation of the patch has removed. You can subseqently use the recovery data set to uninstall the patch product; you enter the PRODUCT UNDO PATCH command to do this. However, once you use the recovery data set to uninstall the patch product, the POLYCENTER Software Installation utility deletes it, and you cannot use recovery data set files again.

The POLYCENTER Software Installation utility also destroys the recovery data set when you enter any of the following (unrelated) DCL commands:

$ PRODUCT INSTALL (without the /SAVE_RECOVERY_DATA qualifier)

$ PRODUCT RECONFIGURE

$ PRODUCT REGISTER PRODUCT

$ PRODUCT REMOVE

Using Other Recovery Data Set Commands    

You can use the following PRODUCT commands to view and delete recovery data sets:

• To view information in a recovery data set, enter the following command:

  $ PRODUCT SHOW RECOVERY_DATA




• To delete selected recovery sets (if you are concerned that the recovery data takes up too much space), enter the following command:

  $ PRODUCT DELETE RECOVERY_DATA

  By deleting one or more recovery data sets, you do not disturb your current product environment. However, you cannot uninstall the patch products that correspond to the recovery data that you delete.

Selecting VMSINSTAL.COM Options

Installing with the POLYCENTER Software Installation utility