Document revision date: 30 March 2001

## POLYCENTER Software Installation Utility Developer's Guide

Previous | Contents | Index

Avoiding Common Mistakes

A common mistake is for a layered product's PDF to include a software statement reference to a VMS (OpenVMS operating system) product, or to an OPENVMS platform (product suite that includes the OpenVMS operating system).

It is acceptable to reference the OpenVMS operating system from a software statement if your product relies on the presence of the library files supplied by the operating system. However, do not reference the OpenVMS platform from a software statement.

If you need to verify the OpenVMS operating system version before the installation of the layered product can proceed and complete successfully, use the software function instead:

       if ( < software DEC AXPVMS VMS version below V6.2 > ) ;
           error UNSUPP_VMS_VER abort ;
       else ;
           -- include your PDL statements here
       end if ;

If you do use the software statement, you should expect the following results:

- If the installed version of OpenVMS is different than the one specified by the software statement, and the OpenVMS product kit is not available, an error message prompting the user to terminate the session is issued. This might be the result you are trying to achieve, but the software function is still the better choice.
- If the installed version of OpenVMS is different than the one specified by the software statement, and an OpenVMS product kit satisfying the software reference criteria is available, the utility may attempt an upgrade of the operating system.
- If the installed version of OpenVMS is within constraints specified by the software statement, the installation of the layered product may complete successfully, but a permanent software reference is made in the database from the layered product to the OpenVMS operating system. This can lead to software reference conflicts if the OpenVMS operating system is upgraded in the future.
  Another drawback is that a significantly greater amount of memory is consumed and additional processing is done to check for software reference conflicts when processing the software statements, which leads to diminished performance.

See Also apply to
if
product
upgrade

### Examples

#1
    software DEC VAXVMS FORTRAN
        version minimum V3.0 version maximum V5.0 ;

> The software statement in this example specifies that this product requires Compaq Fortran software. The version must be between 3.0 and 5.0.

#2
    software DEC VAXVMS FORTRAN version below V5.0 ;

> The software statement in this example specifies that this product requires Compaq Fortran software. The version must be less than (but not equal to) 5.0.

#3
    if ( < software CPQ AXPVMS COOL_PRODUCT
              version minimum V3.0 kit accessible > ) ;
        software CPQ AXPVMS COOL_PRODUCT version minimum V3.0 ;
    else if ( < option NO_COOL_REFERENCE default YES with helptext > ) ;
        file [SYSEXE]COOL_SUBSTITUTE.EXE ;
    else ;
        error MISSING_COOL ;
    end if ;

> In this example, the software function is used to search the source directory for the COOL_PRODUCT kit. If the POLYCENTER Software Installation utility finds the software package with Version 3.0 or higher on the system, the reference to it is created with a separate software statement.

> If the COOL_PRODUCT V3.0 or higher is not found, an option to install its substitute ( `file [SYSEXE]COOL_SUBSTITUTE.EXE]` ) is offered to the user. If the user declines to accept the substitute image, an error is issued and the user is prompted to either terminate or continue the current session.

## system parameter

> The system parameter statement allows you to display a message to users that expresses system parameter requirements for your product.

> Note The utility does not change system parameters.

### Syntax

system parameter name
{ { consume | require } value |
maximum value |
minimum value |
minimum value maximum value } ;

### Parameter

> #### name

> Indicates the name of the system parameter. The parameter you specify must be valid on the system where the product executes.

### Options

> #### consume value

> Indicates that the system parameter must be increased by the specified value. Use this option when the product consumes a resource that is controlled by the system parameter. The value must be a single unquoted string that specifies an unsigned integer value. You cannot use this option with either the maximum, minimum, or require options.

> #### maximum value

> Indicates that the system parameter must have a value less than or equal to the specified value. The value must be a single unquoted string that specifies an integer value.

> #### minimum value

> Indicates that the system parameter must have a value greater than or equal to the specified value. The value must be a single unquoted string that specifies an integer value.

> #### require value

> Indicates that the system parameter must have the specified value. The value must be a single string that specifies a value of the parameter's type. This option is valid for any parameter data type. You cannot use this option with either the maximum, minimum, or consume options.

### Description

> The system parameter statement displays a message to users about system parameter requirements for your product after the installation. Note that the utility does not adjust system parameters.

See Also information
process parameter

### Example

    system parameter vaxcluster require 1 ;
    system parameter tty_classname require "TT" ;
    system parameter pagedyn consume 200 ;

> The statements in this example display the following messages:

    This product requires the following system parameters
        VAXCLUSTER value 1

    This product requires the following system parameters
        TTY_CLASSNAME value TT

    This product requires the following system parameters
        PAGEDYN add 200

## upgrade

> The upgrade statement specifies the versions of the product that can be upgraded by the product kit being installed. If the product is currently installed but its version does not meet the version selection criteria in the upgrade statement, the installation is terminated. The upgrade statement has no effect when the product is being installed for the first time.

> The upgrade function tests whether a version of the product in the specified range is being upgraded by the current operation. If a version of the product in the specified range is currently installed, the function returns true; otherwise it evaluates to false. If no version criteria are given, the function tests whether any version of the product is currently installed.

### Statement Syntax

upgrade
{ version above version |
version below version |
version maximum version |
version minimum version |
version required version |
version above version version below version |
version above version version maximum version |
version minimum version version below version |
version minimum version version maximum version } ;

### Function Syntax

< upgrade
[ { version above version |
version below version |
version maximum version |
version minimum version |
version required version |
version above version version below version |
version above version version maximum version |
version minimum version version below version |
version minimum version version maximum version } ] >

### Options

> #### version above version

> Establishes a lower version limit. The version identifier must be a single quoted or unquoted string. Use this option to specify that the product version must be greater than (but not equal to) the specified version. You cannot use this option with either the version minimum or version required option. By default, there is no lower version limit.

> #### version below version

> Establishes an upper version limit. The version identifier must be a single quoted or unquoted string. Use this option to specify that the product version must be less than (but not equal to) the specified version. You cannot use this option with either the version maximum or version required option. By default, there is no upper version limit.

> #### version maximum version

> Establishes an upper version limit. The version identifier must be a single quoted or unquoted string. Use this option to specify that the product version must be less than or equal to the specified version. You cannot use this option with either the version below or version required option. By default, there is no upper version limit.

> #### version minimum version

> Establishes a lower version limit. The version identifier must be a single quoted or unquoted string. Use this option to specify that the product version must be greater than or equal to the specified version. You cannot use this option with either the version above or version required option. By default, there is no lower version limit.

> #### version required version

> Establishes a required version. The version identifier must be a single quoted or unquoted string. Use this option to specify that the product version must be equal to the specified version. You cannot use this option with either the version above, version below, version maximum, or version minimum option. By default, there is no required version constraint.

### Description

> Statement

> In a full, platform, or operating system PDF, the upgrade statement is optional. When present, the upgrade statement specifies the versions of the product that can be successfully upgraded by the product kit. If a version of the product is currently installed but does not meet the version selection criteria in the upgrade statement, the installation is terminated. The upgrade statement has no effect when the product is being installed for the first time. If an upgrade statement is not present in the PDF, the kit being installed is allowed to upgrade (or replace) any version of the product that might be installed. This includes a lower version, a higher version, or the same version of the product.

> In a partial PDF, the upgrade statement is required. The statement specifies which versions of the product must be installed for the partial kit to be applied successfully.

> You cannot use the upgrade statement for a patch, mandatory update, or transition PDF.

> Function

> The upgrade function tests whether a version of the product in the specified range is being upgraded by the current operation. If a version of the product in the specified range is currently installed, the function returns true; otherwise it evaluates to false. If no range is given, the function tests whether any version of the product is currently installed.

> The upgrade function is not meaningful for a patch, mandatory update, or transition PDF. If included in these PDFs, the upgrade function always evaluates to false.

See Also apply to
if
product
software

### Examples

#1
    product CPQ AXPVMS ABC V4.0 full ;
        upgrade version minimum V2.0 ;
       .
       .
       .
    end product ;

> The upgrade statement in this example does not allow product ABC V4.0 to upgrade versions of the product prior to V2.0. Product ABC, however, can upgrade to V2.0 or later of the product. Or, if a previous version of the product is not currently installed, it can perform a new installation.

#2
    product CPQ AXPVMS DEF V4.2 partial ;
        upgrade version required V4.1 ;
       .
       .
       .
    end product ;

> The upgrade statement in this PDF is required because this is a partial kit. It specifies that product DEF V4.1 must already be installed in order to apply this partial kit to upgrade the product to V4.2.

#3
    product CPQ VAXVMS JKL V2.5 full ;
        if (<upgrade>) ;
        information UPG_MSG ;
        end if ;
       .
       .
       .
    end product ;

> In this example, if any version of product JKL is currently installed, an informational message will be displayed to the user.

#4
    product CPQ VAXVMS JKL V2.5 full ;
        if (<upgrade version minimum A1.0 version below A2.0>) ;
        file [sysupd]jkl_convert.com ;
        end if ;
       .
       .
       .
    end product ;

> If version 1 of the product (from beta test through final release) is being upgraded, the upgrade function in this PDF is used to conditionally provide a file.

## Appendix A
Migrating from VMSINSTAL to the POLYCENTER Software Installation Utility

VMSINSTAL is an installation mechanism supplied by Compaq. This appendix contains information about VMSINSTAL options and callbacks and their POLYCENTER Software Installation utility equivalents.

## A.1 VMSINSTAL Options and Equivalents

Table A-1 lists some tasks that you may need to perform, the corresponding VMSINSTAL option, and the POLYCENTER Software Installation utility equivalent. Note that some VMSINSTAL options do not have an equivalent. In many cases, this is because the design of the POLYCENTER Software Installation utility eliminates the need for an equivalent.

Table A-1 VMSINSTAL Options and Equivalents
Task | VMSINSTAL Option | POLYCENTER Software Installation Utility Equivalent
--- | --- | ---
Creating a file that specifies answers to installation questions | OPTIONS A | Create a product configuration file (PCF). This is similar to an auto-answer file in VMSINSTAL.
Specifying a temporary work directory | OPTIONS AWD | Specify the /WORK qualifier to the PRODUCT command.
Starting the system | OPTIONS B 1 | No equivalent.
Tracing callbacks during installation | OPTIONS C 2 | Use the /LOG and /TRACE qualifiers to the PRODUCT command. You can also use the /NOCOPY qualifier when debugging a product description file (PDF) to prevent the product material from being copied into the reference copy.
Manipulating product kits | OPTIONS G | Use the COPY/FORMAT=REFERENCE and COPY/FORMAT=SEQUENTIAL commands to manipulate product kits (see Chapter 5).
Suppressing VMSINSTAL prompts | OPTIONS I 2 | No equivalent.
Debugging a kit | OPTIONS K 2 | Use the /LOG and /TRACE qualifiers to assist in debugging a PDF.
Providing a log of installation operations | OPTIONS L | Use the /LOG and /TRACE qualifiers. This provides more information than OPTIONS L with VMSINSTAL.
Displaying or printing release notes | OPTIONS N | Use the release notes option to the file statement and the PRODUCT EXTRACT RELEASE_NOTES command. The release notes are created in the file DEFAULT.PCSI$RELEASE_NOTES in the current directory.
Performing an installation in test mode | OPTIONS Q 2 | No equivalent.
Installing a product in an alternate root | OPTIONS R | Use the /DESTINATION qualifier.
Pausing the installation at various points | OPTIONS RSP 2 | No equivalent.
Compiling information about the installation | OPTIONS S 2 | Use the /LOG and /TRACE qualifiers to the PRODUCT command.

1OpenVMS startup use only
2Developer's use only

## A.2 VMSINSTAL Callbacks and Equivalents

To install a product using VMSINSTAL, you create a command procedure named KITINSTAL.COM that makes callbacks to VMSINSTAL. If you are migrating from VMSINSTAL to the POLYCENTER Software Installation utility, refer to Table A-2, which lists the VMSINSTAL callbacks and their equivalents.

Table A-2 VMSINSTAL Callbacks and Equivalents
Task | VMSINSTAL Callback | Option | POLYCENTER Software Installation Utility Equivalent
--- | --- | --- | ---
Adding an identifier to the rights database | ADD_IDENTIFIER |  | Use the rights identifier statement.
Prompting the installer for information | ASK |  | To confirm the completion of preinstallation tasks, use the confirm option to the information statement. The product text file (PTF) contains the prompt and help text.
Not recording responses to installation questions |  | A | No equivalent.
Forcing a Boolean answer |  | B | No equivalent.
Preceding a prompt with blank line |  | D | No equivalent.
Disabling terminal echo |  | E | No equivalent.
Displaying help text before the prompt |  | H | The information statement.
Requiring an integer as the answer |  | I | No equivalent.
Returning input in lowercase |  | L | No equivalent.
Returning input in the same case |  | M | No equivalent.
Indicating a null response is acceptable |  | N | No equivalent.
Ringing the terminal bell before the prompt |  | R | No equivalent.
Indicating the response can be a string |  | S | No equivalent.
Returning input in uppercase |  | U | No equivalent.
Indicating the response can be Ctrl/Z |  | A | No equivalent.
Determining whether a license for the product is installed on the system | CHECK_LICENSE |  | No equivalent. License management is outside the domain of the utility.
Determining whether the network is running | CHECK_NETWORK |  | No equivalent. If you use a statement that references the DECnet network, the utility ensures that the network is available.
Determining whether there is sufficient disk space on the target device | CHECK_NET_UTILIZATION |  | No equivalent. The utility ensures that sufficient disk space is available.
Determining whether a minimum version of software is present in the execution environment | CHECK_PRODUCT_VERSION |  | Use the version minimum option to the software function.
Limiting an installation to specified versions of the OpenVMS operating system | CHECK_VMS_VERSION |  | Use the version minimum and version maximum options to the software function, specifying DEC as the producer name, VAXVMS or AXPVMS as the base, and VMS as the product name.
Determining which is the most recent version of an image | COMPARE_IMAGE |  | You can manage file versions using the generation option to the file statement.
Determining whether the user has loaded the license for the product being installed on the system | CONFIRM_LICENSE |  | No equivalent. License management is outside the domain of the utility.
Providing for orderly exit from an installation | CONTROL_Y |  | No equivalent necessary; the utility provides this automatically.
Creating an account on the system | CREATE_ACCOUNT |  | Use the account statement.
Deleting obsolete files from a previous installation | DELETE_FILE |  | In full and operating system kits, the utility deletes files that are replaced during an upgrade. However, in a partial kit, you can remove obsolete files using the remove statement.
Locating files | FIND_FILE |  | If you want to determine whether an optional software product is available, use the software function. You do not need to determine whether a file is present before performing an operation that references it; the utility does this automatically.
Generating structure definition language (SDL) definition files | GENERATE_SDL |  | No equivalent.
Extracting the image file identification string for a file | GET_IMAGE_ID |  | If you want to determine the available version of a software product, use the software function.
Obtaining a password for an account | GET_PASSWORD |  | No equivalent necessary; the utility provides this function.
Placing requirements on system parameters | GET_SYSTEM_PARAMETER |  | Use the system parameter statement.
Displaying messages to the user | MESSAGE |  | Use the information statement to display information about pre- and postinstallation tasks. You do not need to provide error messages and progress information; the utility does this automatically.
Patching an image as part of the installation | PATCH_IMAGE |  | Use the patch image statement.
Moving a shareable image's symbol table to the system shareable image library when the patch is complete |  | I | No equivalent necessary. The image library option to the file statement controls its replacement in the image library.
Creating a journal file of patches |  | J | No equivalent.
Saving old versions of the image file |  | K | No equivalent necessary. The utility deletes existing versions.
Moving the file to the SYS$SPECIFIC directory |  | O | No equivalent necessary. The placement of the file statement that originally described the image within a scope group determines its placement.
Reinstalling the image when the patch is complete |  | R | No equivalent necessary; the utility does this automatically.
Queuing a print job to SYS$PRINT | PRINT_FILE |  | No equivalent.
Invoking a command procedure of product-specific callbacks | PRODUCT |  | No equivalent.
Adding a command to the system DCL table | PROVIDE_DCL_COMMAND |  | Use the module statement with the type command parameter. You do not need to reinstall the system command table as a known image; the utility does this automatically.
Adding help to the DCL help library | PROVIDE_DCL_HELP |  | Use the module statement with the type help parameter.
Adding a new file to the system | PROVIDE_FILE |  | Use the file statement.
Placing the file in more than one location |  | C | No equivalent necessary.
Preserving old versions |  | K | No equivalent necessary. The utility deletes existing versions.
Adding the file to the SYS$SPECIFIC directory |  | O | Enclose the file statement in a scope processor group.
Specifying an input file that contains a list of logical names for the source files and their respective destinations |  | T | No equivalent necessary. Use one file statement for each file.
Adding a new image to the system | PROVIDE_IMAGE |  | Use the file statement. The utility can distinguish whether a file is a valid executable image.
Placing the file in more than one location |  | C | No equivalent necessary.
Dynamically patching ECOs into the new image file |  | E | No equivalent necessary. You should package the file with the correct ECO numbers already set.
Moving a shareable image's symbol table to the system shareable image library |  | I | Use the image library option to the file statement.
Preserving old versions |  | K | No equivalent necessary. The utility deletes existing versions.
Moving the file to the SYS$SPECIFIC directory |  | O | Enclose the file statement in a scope processor group.
Specifying an input file that contains a list of logical names for the source image files and their respective destinations |  | T | No equivalent necessary. Use one file statement for each file.
Changing the file name and file type of all versions of a file | RENAME_FILE |  | Use the archive option of the file statement to preserve an existing version of a file during an upgrade.
Restoring save sets of a product that is divided among several save sets | RESTORE_SAVESET |  | No equivalent necessary.
Running an image during installation | RUN_IMAGE |  | Use the execute statement or the assemble execute option to the file statement.
Specifying a UIC or protection code for product files | SECURE_FILE |  | Use the owner and protection options to the directory and file statements.
Modifying the access control list (ACL) of a device, directory, or file | SET | ACL | Use the access control option of the file and directory statements.
Determining the default case (upper or lower) in which text from the installer is returned to the installation procedure | SET | ASK_CASE | No equivalent.
Running an installation verification procedure (IVP) | SET | IVP | No equivalent necessary. You can specify the execute test statement and invoke the functional test for a product with the /TEST qualifier to the PRODUCT INSTALL command.
Calling a product's installation procedure after files have been moved to their target directories | SET | POSTINSTALL | Depending on your application, you can use the execute postinstall statement.
Purging files replaced by an installation | SET | PURGE | No equivalent necessary. The utility deletes existing versions.
Rebooting the system after the installation | SET | REBOOT | No equivalent.
Ensuring a high level of installation success | SET | SAFETY | No equivalent necessary. The utility provides the necessary disk management and reliability features.
Rebooting the system after the installation | SET | SHUTDOWN | No equivalent.
Specifying a product-specific startup command procedure | SET | STARTUP | Use the execute start statement.
Editing text files | SUMSLP_TEXT |  | Use the patch text statement.
Identifying installation peculiarities | TELL_QA |  | No equivalent necessary.
Exiting the installation procedure | UNWIND |  | No equivalent necessary. The utility controls the flow of the installation.
Updating an existing user account | UPDATE_ACCOUNT |  | Use the account statement to modify existing user accounts.
Making a file available for updating by copying it to a working directory | UPDATE_FILE |  | No equivalent necessary.
Modifying an identifier in the rights database | UPDATE_IDENTIFIER |  | Use the rights identifier statement to modify an existing rights identifier.
Updating a library | UPDATE_LIBRARY |  | Use the module statement with the appropriate parameter for the type of library you are updating. To update the shareable image library, use the image library option to the file statement. No equivalent exists to update RSX libraries.

Previous | Next | Contents | Index

| privacy and legal statement |
5952PRO_015.HTML