HP OpenVMS Systems Documentation

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], that is, 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 release merge keyword phrase 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 OpenVMS operating system product and asks whether to optionally install system integrated products such as HP DECwindows Motif and HP 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 HP 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.

product HP AXPVMS OPENVMS F7.1 platform ; (1)
    upgrade version minimum A7.1 version below V7.2; (2)
    software HP AXPVMS VMS version required F7.1 ; (3)
    option DWMOTIF_KIT ; (4)
        software HP AXPVMS DWMOTIF version minimum V1.2-4 ;
    end option ;
    option DECNET_OSI_KIT ;
        software HP AXPVMS DECNET_OSI version minimum K7.1 ;
    end option ;
    option UCX_KIT ;
        software HP 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 OpenVMS 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 HP 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.

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 partial keyword, an upgrade statement, and an end product statement as shown in the following example:

product HP AXPVMS 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.

product HP 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.COM" ;(5)
end product ;

1. The product statement identifies this as a partial kit for the FORTRAN product that will upgrade FORTRAN to V7.2 on an OpenVMS Alpha system.
2. The upgrade statement (required for a partial kit) specifies that FORTRAN V7.1-1 must be installed before installing this upgrade kit.
3. The generation keyword in this file statement is used to supply sequencing information to aid file conflict detection and resolution should a patch kit for this product or another product supply the same file name.
4. The module statement installs the command definition module FORTRAN from the file DEC_FORTCLD.CLD in the default command library [SYSLIB]DCLTABLES.EXE. The file DEC_FORTCLD.CLD is not left on the system because a file statement is not used to place it there. (In Example 3-7 a CLD file is put into DCLTABLES and a copy of the file is left on the target disk.)
   Note that if this partial kit is installed after the patch kit in Example 3-6, the module FORTRAN from this partial kit will supersede the module FORTRAN from the patch kit because it has the higher generation number.
   Conversely, if the patch kit is installed after this partial kit, the module will not be updated. Conflict detection between patch kits and between patch and partial kits for the same product is new for OpenVMS Version 7.2. Previously, conflict detection only occurred between full, platform, and operating system products.
5. FORT$IVP.COM already exists on the system disk, provided earlier by the full version of FORTRAN V7.1-1.

Use a patch kit to apply a correction to a currently installed product. It can replace files, provide new files, or remove files. The PDF for a patch kit must contain a product statement with the keyword patch, an apply to statement, and an end product statement as shown in the following example:

product HP AXPVMS TEST_A_ECO1 V1.0 patch ;
    apply to HP AXPVMS TEST_A version minimum A2.0 version maximum V2.0 ;
   .
   .
   .
end product ;

A patch kit has the following characteristics:

• It usually does not contain all of the material for the product. Therefore, it can be used only to modify a previously installed version of the product.
• It can modify a full, operating system, or platform product. Also, it can modify a product that has been upgraded by a partial kit. More than one patch kit can be applied to the same product.
• Its full product name (the producer-base-product string) must be different than the full product name of the product it updates. Further, its full product name must be unique among all products and patches installed on the system.
• After installation, the version of the product that it modifies is not changed. Use the PRODUCT SHOW PRODUCT /FULL command to display all patch kits that have been installed on the system.
• Because it is not a product, you cannot remove a patch kit individually using a PRODUCT REMOVE command. Patches to a product are automatically removed when the product is removed or upgraded. They can also be uninstalled using the PRODUCT UNDO PATCH command, but only if they were installed with the /SAVE_RECOVERY_DATA qualifier and the recovery data is intact.
• The patch kit cannot be configured or reconfigured, but the product that it modifies can be configured or reconfigured.
• Its PDF cannot contain option or software statements.
• Patch kits are intended for making small updates to a product. Since the installation of a patch kit does not change the version number of the product, you should distribute a new version of the product kit (full, operating system, or platform) or a partial kit to make large updates or functional enhancements.

Example 3-6 shows a patch kit.

product HP AXPVMS FORTECO_03 V1.0 patch ; (1)
    apply to HP AXPVMS FORTRAN version required V7.1-1 ; (2)
    module [000000]FORTCLD.CLD type command generation 3 module FORTRAN ;(3)
end product ;

1. The product statement identifies this as V1.0 of a patch kit named FORTECO_03. The name of this kit must be unique among all products and patches applied to the system.
2. The apply to statement (required for a patch kit) specifies that this patch can be applied only to the installed product FORTRAN V7.1-1.
3. The module statement installs the FORTRAN CLD module in the default command library [SYSLIB]DCLTABLES.EXE. The file FORTCLD.CLD is not left on the system because a file statement is not used to place it there. (In Example 3-7 a CLD file is put into DCLTABLES and a copy of the file is left on the target disk.)

Example 3-7 shows a patch kit that modifies the operating system.

product HP AXPVMS VMS61TO71U2_PCSI B1.0 patch ; (1)
    apply to HP AXPVMS VMS version minimum V6.1 version below A7.2 ; (2)

--  This patch kit provides the entire POLYCENTER Software Installation(3)
--  facility built from OpenVMS V7.2 sources that can be installed on OpenVMS
--  V6.1 through V7.1-n systems.  Installation of this patch extends the
--  capabilities of the DCL command PRODUCT, enhances the utility's user
--  interface, and corrects problems.  In addition, the availability of this
--  patch enables product developers to use new product description language
--  syntax introduced in OpenVMS V7.1 and V7.2 in their product kits for
--  deployment on older OpenVMS systems that have this patch installed.
--
--  Although this kit could have been packaged as a layered product, it was
--  more appropriate to package it as a patch to the operating system because
--  it replaces a facility that is bundled with OpenVMS.  Finally, the use
--  of generation numbers on files and library modules provides information
--  used during object conflict detection and resolution should other patches
--  for this facility be distributed in the future that update these objects.

    file [SYSEXE]PCSI$MAIN.EXE generation 50000000 ;
    file [SYSLIB]PCSI$SHR.EXE generation 50000000 ;
    file [SYSUPD]PCSI.CLD generation 50000000 ; (4)
    module [SYSUPD]PCSI.CLD type command generation 50000000 module PRODUCT ;
    module [SYSUPD]PRODUCT.HLP type help generation 50000000 module PRODUCT ;
    file [SYSUPD]PCSI$CREATE_RIGHTS_IDENTIFIER.COM generation 50000000 ;
    file [SYSUPD]PCSI$DELETE_RIGHTS_IDENTIFIER.COM generation 50000000 ;
    file [SYSUPD]PCSI$CREATE_ACCOUNT.COM generation 50000000 ;
    file [SYSUPD]PCSI$DELETE_ACCOUNT.COM generation 50000000 ;
    file [SYSUPD]PCSI$CREATE_NETWORK_OBJECT.COM generation 50000000 ;
    file [SYSUPD]PCSI$DELETE_NETWORK_OBJECT.COM generation 50000000 ;
    file [SYSUPD]PCSI$REGISTER_PRODUCT.COM generation 50000000 ;
    file [SYSUPD]PCSI$EXTRACT_TLB.COM generation 50000000 ;
    remove ;(5)
        file [SYSLIB]PCSI$MOTIFSHR.EXE ;  -- obsolete file as of VMS V7.2
    end remove ;
end product ;

1. The product statement identifies this as B1.0 (a field test version) of a patch kit named VMS61TO71U2_PCSI. The name of this kit must be unique among all products and patches applied to the system.
2. The apply to statement (required for a patch kit) specifies that this patch can be applied only to versions V6.1 through V7.1-2 of the VMS product.
3. The double hyphen (-
4. This file statement provides [SYSUPD]PCSI.CLD. The following module statement installs the command definition module PRODUCT from this file in the default command library [SYSLIB]DCLTABLES.EXE. A file statement is not required to provide the file specified in the module statement unless you want the file left on the system.
5. This remove...end remove group deletes the obsolete file [SYSLIB]PCSI$MOTIFSHR.EXE.

Use a mandatory update kit to apply a correction to a currently installed product. It can replace files, provide new files, or remove files. The PDF for a mandatory update kit must contain a product statement with the mandatory update keyword, an apply to statement, and an end product statement, as shown in the following example:

product HP AXPVMS TEST_A_ECO1 V1.0 mandatory update ;
    apply to HP AXPVMS TEST_A version minimum A2.0 version maximum V2.0 ;
   .
   .
   .
end product ;

A mandatory update kit is functionally identical to a patch kit except for its kit type designation. It is used for corrections that must be applied to the product.

The characteristics of a mandatory update kit are the same as for a patch kit, as described in Section 3.5.5.

3.5.7 The Transition Kit Type

Use a transition kit to register in the product database a product that was not installed by the POLYCENTER Software Installation utility. For example, use a transition kit to register products installed by the VMSINSTAL utility. The PDF for a layered product transition kit must contain a product statement with the transition keyword and an end product statement as shown in the following example:

product HP AXPVMS FMS V2.4 transition ;
   .
   .
   .
end product ;

To register an operating system product, the keyword operating system is added to the keyword transition as shown in the following example:

product HP VAXVMS VMS V7.2 transition operating system ;
   .
   .
   .
end product ;

In contrast to OpenVMS Alpha, the OpenVMS VAX operating system is not installed by the POLYCENTER Software Installation utility. The OpenVMS VAX installation procedure uses the PRODUCT REGISTER PRODUCT VMS command to register the operating system in the product database.

The transition kit has the following characteristics:

• It cannot be installed with a PRODUCT INSTALL command; instead, it is registered with a PRODUCT REGISTER PRODUCT command.
• Optionally, it can reference managed objects such as files, directories, modules, and so forth. However, none of these objects is created or modified when the kit is registered, nor does the installation utility verify that any of these objects actually exist on the system.
• Files specified in file statements do not need to be present when a transition kit is packaged because product material is not included in this type of kit.
• The registered product can be removed with the PRODUCT REMOVE command. If the transition kit references any managed objects, these objects will be removed as if the transition kit had been a full kit.
• The registered product cannot be configured or reconfigured.
• The infer statement can be used only in a PDF for a transition kit.

There are several benefits of registering a product:

• The product name is displayed with the PRODUCT SHOW PRODUCT and PRODUCT SHOW HISTORY commands.
• Other software products that require this product as a prerequisite can specify it in a software statement and have this software dependency satisfied.
• If all of the managed objects for the product are specified in the transition kit, then the product can be completely removed with a PRODUCT REMOVE command.

Example 3-8 shows a transition PDF for the FMS product.

product HP AXPVMS FMS V2.4 transition ; (1)
    infer version from [SYSLIB]FDVSHR.EXE ; (2)
    file [SYSLIB]FDVSHARE.OPT ; (3)
    module [SYSUPD]FDV.OBJ type object module FDV ; (4)
    module [SYSUPD]FDVMSG.OBJ type object module FDVMSG ;
    module [SYSUPD]FDVDAT.OBJ type object module FDVDAT ;
    module [SYSUPD]FDVERR.OBJ type object module FDVERR ;
    module [SYSUPD]FDVTIO.OBJ type object module FDVTIO ;
    module [SYSUPD]FDVXFR.OBJ type object module FDVXFR ;
    module [SYSUPD]HLL.OBJ type object module HLL ;
    module [SYSUPD]HLLDFN.OBJ type object module HLLDFN ;
end product ;

The following list describes the statements in this example:

1. The transition keyword to the product statement indicates that this is a transition PDF.
2. The infer version statement tests the execution environment to determine whether the file FDVSHR.EXE is present. If it is, the utility infers the version that is installed.
3. The file statement indicates that the [SYSLIB]FDVSHARE.OPT file is part of the FMS kit.
4. The module statements describe object modules in the default object library [SYSLIB]STARLET.OLB that are part of the FMS kit.