Updated: 11 December 1998

POLYCENTER Software Installation Utility Developer's Guide

The POLYCENTER Software Installation utility supports seven kit types that can be grouped into three broad categories:

• Primary kit --- Used to install or upgrade a product. Primary kits can require prerequisite products to be installed before or concurrently. Kit types in this category include:
  • Full (layered product or application software)
  • Operating system
  • Platform (product suite)
• Secondary kit --- Used to upgrade or update installed products. Kits types in this category include:
  • Partial
  • Patch (maintenance update)
  • Mandatory update
• Transition kit --- Used to register a product that has been installed using VMSINSTAL or some method other than the DCL command PRODUCT INSTALL. The kit type in this category is as follows:
  • Transition

You use the PRODUCT PACKAGE command to package (or build) a product kit. The output of the packaging process is an installable kit (in either sequential copy format or reference copy format) that contains:

• Product material (usually present) --- The files that comprise the product. Usually, the installation of a product kit copies files to the target disk. However, there are exceptions:
  • A transition kit never provides files.
  • A platform kit references other products; it may or may not provide common files for the product suite.
  • Since product material is not a requirement for any type of kit, you may create "skeleton" kits for testing purposes that do not modify the target disk.
• A product description file (required) that drives the installation process --- It defines the managed objects that are provided or created and contains directives for the installation utility. In addition, it can include options for the installer to select, declare software references to other prerequisite products, and invoke command procedures you write to augment the installation process.
• A product text file (optional) that provides text modules for use during the installation process.
• Temporary files such as command procedures (optional) that are used during the installation process but are not left on the user's system.

The full product name (that is, the string producer-base-product) must be unique among all products installed on a system. This implies, for example, that there could be two FORTRAN compilers installed from different companies (such as DEC-AXPVMS-FORTRAN and XYZCORP-AXPVMS-FORTRAN), but there cannot be two patch kits with the same full name that are intended to apply to different products (such as ABC-VAXVMS-ECO1 for ABC-VAXVMS-COBOL and ABC-VAXVMS-ECO1 for ABC-VAXVMS-C).

The following sections describe each type of kit and provide examples of their product description files.

3.5.1 The Full Kit Type

A full kit provides layered product application software and is the most common type of kit. The PDF for a full kit must contain a product statement with the keyword full and an end product statement, as shown in the following example:

product DEC AXPVMS TEST_A V2.0 full ; . . . end product ;

The full kit has the following characteristics:

• It contains all of the material for the product. Therefore, it can be used to install the product for the first time or it can upgrade a previously installed version of the product.
• The product can be removed, configured, or reconfigured.
• Its PDF can contain option and software statements.

Example 3-1 shows a full kit that references another product.

Example 3-1 PDF for a Full Kit that References Another Full Kit

product DEC AXPVMS FORTRAN V7.1-1 full ; (1) if (not <software DEC AXPVMS VMS version minimum V7.1>) ;(2) software DEC AXPVMS FORRTL version minimum V7.1 ; end if ; information STARTUP_TASK phase after ; information RELEASE_NOTES phase after ;(3) file [SYSHLP]FORTRAN.RELEASE_NOTES release notes ;(4) file [SYSHLP]FORTRAN_RELEASE_NOTES.PS ; file [SYSHLP]FORTRAN_RELEASE_NOTES.DECW$BOOK ; if (<software DEC AXPVMS FORTRAN90>) ;(5) error REMFORT90 ; end if ; option FORTRAN_90 ;(6) file [SYSEXE]F90$MAIN.EXE generation 2 ; file [SYSMSG]F90$MSG.EXE generation 2 ; module [000000]F90CLD.CLD type command generation 2 module F90 ; module [000000]F90HELP.HLP type help generation 2 module F90 ;(7) end option ; option FORTRAN_77 ; file [SYSEXE]FORT$MAIN.EXE generation 1 ; file [SYSEXE]FORT$FSPLIT.EXE generation 1 ; file [SYSMSG]FORT$MSG.EXE generation 1 ; file [SYSMSG]FORT$MSG2.EXE generation 1 ; module [000000]DEC_FORTCLD.CLD type command generation 1 module FORTRAN ; module [000000]DEC_FORHELP.HLP type help generation 1 module FORTRAN ; end option ; file [SYSLIB]FORSYSDEF.TLB generation 5 ; file [SYS$STARTUP]FORT$STARTUP.COM generation 1 protection private ;(8) file [SYSTEST]FORT$IVP.COM generation 1 protection private ; execute test "@PCSI$DESTINATION:[SYSTEST]FORT$IVP.COM" ;(9) end product ;

1. The product statement identifies this as a complete layered product kit for installation of (or upgrade to) FORTRAN V7.1-1 on an OpenVMS Alpha system.
2. The if...end if group conditionally executes statements within the group based on the evaluation of the if function. In this example, the software statement is executed only if the system is running a version of OpenVMS earlier than V7.1. This software statement creates a software reference to the product FORRTL. If FORTRL V7.1 or later is already installed, the software dependency is satisfied; otherwise, FORRTL is automatically installed concurrently with FORTRAN.
3. This information statement causes a message to be displayed after the product has been installed. Text is obtained from the module RELEASE_NOTES in the PTF:

   1 RELEASE_NOTES =prompt Type HELP FORTRAN Release_notes for release notes location

4. This file statement copies file FORTRAN.RELEASE_NOTES to SYS$SYSDEVICE:[VMS$COMMON.][SYSHLP] (the same as SYS$COMMON:[SYSHLP]) unless the user specifies a different destination. The keyword phrase release notes tags this file in the kit so that the PRODUCT EXTRACT RELEASE_NOTES command can be used to extract this file from the kit.
5. This if statement determines whether or not the product FORTRAN90 is installed. If it is installed, text from the module REMFORT90 in the PTF is displayed and the user is asked if he wants to terminate the operation:

   1 REMFORT90 =prompt PRODUCT REMOVE FORTRAN90 before installing Digital Fortran The obsolete DEC Fortran 90 product must be removed before Digital Fortran is installed. To do this, use the command: PRODUCT REMOVE FORTRAN90

   
   Note that if the keyword abort had been used on the error statement, the operation would terminate unconditionally. abort was not used because the abort keyword was introduced in OpenVMS V7.1 and this kit can be installed on earlier versions of OpenVMS.

6. This option...end option group conditionally provides files and library modules associated with the Fortran 90 compiler. The user is asked a question from text module FORTRAN_90 in the PTF:

   1 FORTRAN_90 =prompt Digital Fortran 90 compiler This option selects the Digital Fortran 90 compiler.

   
   By default, the option statement displays only text from the prompt line. However, if the user specifies the /HELP qualifier on the PRODUCT INSTALL command, then both prompt and extended help text is displayed (two lines in this case).

7. The module statement installs the help text module F90 from the file F90HELP.HLP in the default help library [SYSHLP]HELPLIB.HLB. The file F90HELP.HLP is not left on the system because a file statement is not used.
8. The keyword phrase protection private on this file statement sets the file protection to (S:RWED, O:RWED, G, W), giving general users no access.
9. The execute test statement executes the functional test for the product (the installation verification procedure) after the product has been installed. If the test fails, the user is informed but the product is not removed. The user can use the PRODUCT REMOVE command to delete the product.

Example 3-2 shows the full kit referenced by Example 3-1.

Example 3-2 PDF for a Full Kit

product DEC AXPVMS FORRTL V7.1-427 full ;(1) if (<software DEC AXPVMS VMS version minimum V7.0>) ;(2) file [SYSLIB]FOR$DEC$FORRTL.EXE source [SYSLIB]FOR$DEC$FORRTL-V70.EXE ; file [SYSLIB]FOR$DEC$FORRTL.OBJ source [SYSLIB]FOR$DEC$FORRTL-V70.OBJ ; else ; file [SYSLIB]FOR$DEC$FORRTL.EXE source [SYSLIB]FOR$DEC$FORRTL-V61.EXE ; file [SYSLIB]FOR$DEC$FORRTL.OBJ source [SYSLIB]FOR$DEC$FORRTL-V61.OBJ ; end if ; if (<software DEC AXPVMS VMS version below V7.1>) ; file [SYSLIB]FOR$NXTAFTR.OBJ ; end if ; file [SYSUPD]FOR$INSTALL_FORRTL.COM ; file [SYSTEST]FOR$RTL_IVP.COM ; file [SYSTEST]FOR$RTL_IVP.OBJ ; file [SYSHLP]FORRTL.RELEASE_NOTES release notes ; information RELEASE_NOTES phase after ; information POST_INSTALL phase after ; execute install "@PCSI$DESTINATION:[SYSUPD]FOR$INSTALL_FORRTL INSTALL" remove "@PCSI$DESTINATION:[SYSUPD]FOR$INSTALL_FORRTL REMOVE";(3) execute test "@PCSI$DESTINATION:[SYSTEST]FOR$RTL_IVP" ; end product ;

1. The product statement identifies this as a complete layered product kit for installation of (or upgrade to) FORRTL V7.1-427 on an OpenVMS Alpha system.
2. The if...else...end if group conditionally executes statements within the group based on the evaluation of the if function. In this example, two files named [SYSLIB]FOR$DEC$FORRTL.EXE and [SYSLIB]FOR$DEC$FORRTL.OBJ are always provided. However, the contents of these files vary depending on the version of the VMS product that is installed. Notice the use of the source clause on the file statements to select the desired file from the kit to copy to the target disk.
3. The execute install...remove statement executes the command procedure PCSI$DESTINATION:[SYSUPD]FOR$INSTALL_FORRTL.COM during installation or upgrade of the product, and also during removal of the product. Instead of providing two command procedures, one is used and a parameter is passed to it to indicate the operation.

The operating system kit provides operating system software such as OpenVMS. The PDF for an operating system kit must contain a product statement with the keyword operating system and an end product statement as shown in the following example:

product DEC AXPVMS VMS V7.2 operating system ; . . . end product ;

The operating system kit has the following characteristics:

• It contains all of the material for the product. Therefore, it can be used to install the product for the first time or it can upgrade a previously installed version of the product.
• The product cannot be removed unless the PRODUCT REMOVE command contains the /REMOTE qualifier to remove the operating system on a disk that is not the running system.
• The product can be configured or reconfigured.
• Its PDF can contain option and software statements.
• There can be only one product of type operating system installed on a system disk.
• Except for the kit type designation, the structure of an operating system kit is the same as a full kit; all PDL statements that are allowed in a full kit can be used in an operating system kit.

Example 3-3 shows an operating system kit.

Example 3-3 PDF for an Operating System Kit

product DEC AXPVMS VMS V7.1 operating system ;(1) upgrade version version minimum V6.1 version below A7.2;(2) . . . directory [SYSEXE] ;(3) directory [SYSFONT] ; directory [SYSFONT.DECW] ; directory [SYSFONT.DECW.100DPI] ; . . . file [SYSEXE]COPY.EXE generation 40069227 ; (4) file [SYSEXE]CREATE.EXE generation 40069227 ; file [SYSEXE]CREATEFDL.EXE generation 40069227 ; file [SYSEXE]DCL.EXE generation 40069227 ; . . . file [SYSMGR]SYLOGIN.TEMPLATE generation 40069227 ; file [SYSMGR]SYLOGIN.COM generation 40069227 (5) source [SYSMGR]SYLOGIN.TEMPLATE write ; . . . option ACCOUNTING ; file [SYSEXE]ACC.EXE generation 40069227 ; end option ; option UTILITIES ; (6) option MAIL ; file [SYSEXE]MAIL.COM generation 40069227 ; file [SYSEXE]MAIL.EXE generation 40069227 ; file [SYSEXE]MAIL_OLD.EXE generation 40069227 ; file [SYSEXE]MAILEDIT.COM generation 40069227 ; file [SYSEXE]MAIL_SERVER.EXE generation 40069227 ; file [SYSHLP]MAILHELP.HLB generation 40069227 ; end option ; . . . option DUMP ; file [SYSEXE]DUMP.EXE generation 40069227 ; end option ; option HELP_LIBRARY ; scope global ; file [SYSHLP]HELPLIB.HLB generation 40069227 release merge ;(7) end scope ; end option ; end option ; . . . option REMOVE_OBSOLETE ; remove ; (8) file [SYSLIB]LIBOTS.OLB ; file [SYSLIB]EDTSHR_TV.EXE ; end remove ; end option ; end product ;

1. The product statement identifies this as a complete operating system kit for installation of (or upgrade to) OpenVMS V7.1 on an Alpha system.
2. The upgrade statement specifies that if this kit is being used to upgrade the VMS product then the previous version must be within the stated range of versions. However, if this is an initial installation of the operating system, the upgrade statement is ignored.
3. This directory statement creates the directory [SYS0.SYSCOMMON.SYSEXE], i.e., SYS$COMMON:[SYSEXE].
4. These file statements copy files to the target system disk. The VMS product places generation numbers on all objects that it provides to aid in object conflict detection and resolution when other products (or patch and partial kits to the operating system) that may replace these objects are installed.
5. This file statement provides [SYSMGR]SYLOGIN.COM from a template file. The write option indicates that customers are allowed to edit this file. On upgrade, if this file exists it will not be replaced.
6. This option...end option group demonstrates how options can be nested. The MAIL option is presented to the user only if the UTILITIES option is selected.
7. The file statement that provides [SYSHLP]HELPLIB.HLB is enclosed in a scope global...end scope group to allow other products to freely make updates to this library.
   The keyword phrase release merge indicates that library modules propagate during an upgrade. For example, if a layered product adds a module to HELPLIB.HLB, this module is automatically inserted into the new library file that is provided by the VMS product during an upgrade of the operating system.
8. The remove...end remove group within an option...end option group deletes all objects specified in the remove group if the user selects the option.

The platform kit installs a product suite, which is an integrated set of software products. It may provide files that are common to all products in the suite, or it may not provide any files. It does, however, contain software references to one or more other products. These references can be either required, optional, or a combination of required and optional. For example, the OPENVMS platform kit always installs the VMS product and asks whether to optionally install system integrated products such as DECwindows Motif and TCP/IP Services for OpenVMS.

The PDF for a platform kit must contain a product statement with the keyword platform and an end product statement, as shown in the following example:

product DEC AXPVMS OPENVMS V7.2 platform ; . . . end product ;

The platform kit has the following characteristics:

• It contains all of the material that is common to the product suite. Therefore, it can be used to install the product suite for the first time or it can upgrade a previously installed version of the platform. As stated, product material is optional for a platform kit. It should, however, contain one or more software statements to reference other products.
• Products referenced do not have to be present when the platform kit is packaged because referenced products are not bundled into the platform kit. However, when you copy a platform, products that are referenced by software statements with the component option must be present.
• The platform product can be removed, configured, or reconfigured.
• Its PDF can contain option and software statements.
• Except for the kit type designation, the structure of a platform kit is the same as a full kit; all PDL statements that are allowed in a full kit can be used in a platform kit.

Example 3-4 shows a platform kit.

Example 3-4 PDF for a Platform Kit

product DEC AXPVMS OPENVMS F7.1 platform ; (1) upgrade version version minimum A7.1 version below V7.2; (2) software DEC AXPVMS VMS version required F7.1 ; (3) option DWMOTIF_KIT ; (4) software DEC AXPVMS DWMOTIF version minimum V1.2-4 ; end option ; option DECNET_OSI_KIT ; software DEC AXPVMS DECNET_OSI version minimum K7.1 ; end option ; option UCX_KIT ; software DEC AXPVMS UCX version minimum V4.1-12 ; end option ; end product ;

1. The product statement identifies this as the OPENVMS F7.1 product suite for installation or upgrade on an OpenVMS Alpha system. The version type F indicates that this is a test version of the kit. The platform keyword indicates that the primary purpose of this product is to install other products.
   Note that VMS (the operating system product) is different from OPENVMS (the product suite).
2. The upgrade statement specifies that if this kit is being used to upgrade the OPENVMS product then the previous version must be within the stated range of versions. However, if the OPENVMS product is not currently installed, then the upgrade statement is ignored.
3. The software statement specifies that the operating system (OpenVMS F7.1) is a required component of the product suite that will be implicitly installed. Should the VMS F7.1 product kit not be accessible, an error message is displayed and the installation terminated before any files from any products are copied to the system.
4. The option...end option group conditionally executes statements within the group based on the user's response to a question. In this example, the option statement displays text associated with the label DWMOTIF_KIT from the PTF:

   1 DWMOTIF_KIT =prompt DECwindows Motif for OpenVMS Alpha This option installs DECwindows Motif for OpenVMS Alpha, which provides the X Window system graphical user interface.

   
   An affirmative response to the question causes the DWMOTIF V1.2-4 product to be installed (or upgraded if a version is already installed), otherwise the software statement is ignored. Should the DWMOTIF V1.2-4 product kit not be accessible when the platform is installed, this option is marked as unselectable and skipped over.

You use a partial kit to upgrade a currently installed product, including replacing some of the product's files, providing new files, or removing files. The PDF for a partial kit must contain a product statement with the keyword partial, an upgrade statement, and an end product statement as shown in the following example:

product DEC VAXVMS TEST_A V2.1 partial ; upgrade version required V2.0 ; . . . end product ;

A partial kit has the following characteristics:

• It does not contain all of the material for the product. Therefore, it can be used only to upgrade a previously installed version of the product.
• It can upgrade a full, operating system, or platform product. More than one partial kit can be applied to the same product.
• The full product name (the producer-base-product string) must be the same as the product it upgrades.
• After installation, the version of the product is changed to the one specified in the partial kit's PDF.
• The product can be removed, in which case the managed objects provided by the product's full and partial kits are deleted.
• The product can be configured or reconfigured.
• Its PDF can contain option and software statements.

Generally, a new version of a product is provided as a full kit instead of a partial kit because a full kit can be used for either an initial installation or for an upgrade of the product. A partial kit is limited to an upgrade path.

A partial kit, however, is usually much smaller in disk block size than its corresponding full kit. For a very large product, this reduction in size may significantly reduce the time it takes to distribute the kit over the network.

Example 3-5 shows a partial kit.

Example 3-5 PDF for a Partial Kit

product DEC AXPVMS FORTRAN V7.2 partial ; (1) upgrade version required V7.1-1 ; (2) information RELEASE_NOTES phase after ; information STARTUP_TASK phase after ; file [SYSHLP]FORTRAN.RELEASE_NOTES release notes ; file [SYSHLP]FORTRAN_RELEASE_NOTES.PS ; file [SYSHLP]FORTRAN_RELEASE_NOTES.DECW$BOOK ; file [SYSEXE]FORT$MAIN.EXE generation 4 ; (3) file [SYSMSG]FORT$MSG.EXE generation 4 ; file [SYSMSG]FORT$MSG2.EXE generation 4 ; module [000000]DEC_FORTCLD.CLD type command generation 4 module FORTRAN ;(4) execute test "@PCSI$DESTINATION:[SYSTEST]FORT$IVP" ; end product ;

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

5952PRO_003.HTML