Updated: 11 December 1998

POLYCENTER Software Installation Utility Developer's Guide

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 prior to installing this upgrade kit.
3. The keyword generation 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 V7.2. Previously, conflict detection only occurred between full, platform, and operating system products.

You 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 DEC AXPVMS TEST_A_ECO1 V1.0 patch ; apply to DEC AXPVMS TEST_A version minimum A2.0 version maximum V2.0 ; . . . end product ;

A patch kit has the following characteristics:

• It 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.
• A patch kit cannot be individually removed by a PRODUCT REMOVE command. Patches to a product are automatically removed when the product is removed or upgraded.
• 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.

Example 3-6 PDF for a Patch Kit

product DEC AXPVMS FORTECO_03 V1.0 patch ; (1) apply to DEC AXPVMS FORTRAN version required V7.1-1 ; (2) module [000000]DEC_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 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.)

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

Example 3-7 PDF for a Patch Kit that Modifies the Operating System

product DEC AXPVMS VMS61TO71U2_PCSI B1.0 patch ; (1) apply to DEC 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 (--) identifies a comment line.
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.

You 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 keyword mandatory update, an apply to statement, and an end product statement, as shown in the following example:

product DEC AXPVMS TEST_A_ECO1 V1.0 mandatory update ; apply to DEC 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 intended to be 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

You use a transition kit to register in the product database a product that was not installed by the POLYCENTER Software Installation utility. For example, you would 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 keyword transition and an end product statement as shown in the following example:

product DEC 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 DEC 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; 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.

Example 3-8 PDF for a Transition Kit

product DEC 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.

An alternative way to register a product (without providing a transition kit for the user to register with a PRODUCT REGISTER PRODUCT command) is to execute the SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM command procedure. This procedure prompts the user to enter product name, version, producer, and base system information, as shown in the following example:

$ @SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM Product name: FMS Version: V2.4 Producer [DEC] : Base System [AXPVMS] : . . . The following product has been registered: DEC AXPVMS FMS V2.4 Transition (registration)

Registering a product using the command procedure will allow another software product to reference this product with a software statement.

The product text file (PTF) is an optional component of a software product kit. However, most kits created using the POLYCENTER Software Installation utility include a PTF. You must supply a PTF to the kitting process if you want to use PDF statements that display text to users during product installation. The following PDF statements have corresponding text modules in the PTF:

• error
• information
• option
• part
• product

For each text module in the PTF you can provide both brief and detailed descriptions. With the exception of the error statement, the brief version of the text module is displayed by default. (See Chapter 7 to see how help text is displayed for each statement.) The user requests detailed explanations by including the /HELP qualifier on the PRODUCT INSTALL command line. If you choose to provide only brief text for a given text module and the user asks for detailed text, the brief version is displayed. By providing detailed descriptions and other informational help text, you should be able to reduce or eliminate hardcopy installation documentation.

The PTF you provide as input to the PRODUCT PACKAGE command:

• Must reside in the same directory as the PDF
• Must have the same file name as the PDF and a file type of .PCSI$TEXT

The following are examples of valid input PDF and PTF names:

TEST.PDF TEST.PCSI$TEXT ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.PCSI$DESC ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.PCSI$TEXT

The execution of the PRODUCT PACKAGE command transforms the input PTF into an output PTF. The input PTF is a text file containing header lines and text module lines. The output PTF is an OpenVMS library file. Its name consists of the product's stylized file name and a file type of .PCSI$TLB:

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

For example:

ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.PCSI$TLB

Note that you can convert the output PTF from an OpenVMS library file back to a text file by executing the command procedure PCSI$EXTRACT_TLB.COM, which is located in SYS$COMMON:[SYSUPD]. You must supply the PTF library file as a parameter to the procedure.

4.2 Structure of a PTF

A PTF is a text file that contains packaging directives, module header lines, and module text. The PTF must begin with the =product directive line that uniquely identifies the product and specifies the type of kit. The rest of the file contains one or more text modules. Each text module entry consists of:

• A module header line that identifies the name of the text module.
• An =prompt directive line that includes text for a brief display.
• Zero or more lines of text that are combined with the brief text to form the detailed display associated with the text module.

The user chooses whether to receive brief or detailed explanations by use of the /HELP qualifier on the PRODUCT INSTALL command.

Brief text format (the default) is restricted to one line of text; that is, the text in the =prompt directive line. To avoid carrying the single-line text over to the next line, try to keep your brief message to no more than 60 characters.

Detailed or help text can include any number of lines of text. The formatting of the information is preserved on output, except that the POLYCENTER Software Installation utility may indent the entire block of text displaying information about configuration options or software requirements.

Comment lines are not permitted in a PTF.

4.2.1 Specifying the Product Name

You must use the =product directive to specify product information in the PTF. The information that you specify with the =product directive must match the information you specify with the product statement in the PDF.

The =product directive has the following format:

=product producer base product version kit_type

See Section 2.3 for the naming conventions.

4.2.2 PTF Modules and the Relationship with the PDF

PTF text modules are text blocks that you want to present to the user. The POLYCENTER Software Installation utility does not process text blocks sequentially, so the order of the text modules in the PTF does not matter.

Text modules are identified by a module header line in the following format:

1 module-name

The module header line consists of the number 1, followed by a space or tab and the name of the module. The module-name must be from 1 to 31 ISO Latin-1 characters, excluding the horizontal tab, space, exclamation point (!), and comma (,) characters. For example:

1 SAMPLE

The POLYCENTER Software Installation utility uses the name of the module to associate the text module with a line from the PDF. For example, the SAMPLE module could correspond to an option in the PDF:

option SAMPLE ;

4.2.3 PTF Modules Not Related with the PDF

The utility also allows you to specify text modules that are not associated with statements in the PDF. These text modules are preceded by an apostrophe ('). Use the following module names to specify information about your product:

• The 'LICENSE module specifies licensing information.
• The 'NOTICE module specifies copyright, ownership, and similar legal information.
• The 'PRODUCER module specifies a brief description of the producer of the product.
• The 'PRODUCT module specifies a brief functional description of the product.

For example, a product might contain the following modules:

=product DEC VAXVMS C V1.0 full 1 'PRODUCT =prompt DEC C++ for OpenVMS DEC C++ for OpenVMS VAX is a native compiler that implements the C++ programming language and includes: o A C++ compiler that implements C++ as defined by The Annotated C++ Reference Manual, Ellis & Stroustrup, reprinted with corrections, May 1991. The compiler implementation includes templates but ex- cludes exception handling. DEC C++ generates optimized object code without employing an intermediate translation to C. o The DEC C++ Class Library, which consists of the following class li- brary packages: iostream, complex, generic, Objection, Stopwatch, String, task, messages, and vector. 1 'NOTICE =prompt © Digital Equipment Corporation 1992. All rights reserved. Unpublished rights reserved under the copyright laws of the United States. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt. III, as applicable. 1 'LICENSE =prompt This product uses the PAKs: <xxx> and <xxx-RT>. This software is furnished under the licensing provisions of Digital Equipment Corporation's Standard Terms and Conditions. For more in- formation about Digital's licensing terms and policies, contact your local Digital office. 1 'PRODUCER =prompt Digital Equipment Corporation This software product is sold by Digital Equipment Corporation.

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

5952PRO_004.HTML