Updated: 11 December 1998

POLYCENTER Software Installation Utility Developer's Guide

The scope statement specifies for certain managed objects a scope and lifetime other than its defaults. The scope and end scope statements form a scope group.

Syntax

scope
{ bootstrap |
global |
processor |
product } ;

[ PDL-statements ]

end scope ;

Option

PDL-statements

Any product description language statement or a group of statements described in this reference section, except the product and end product statements.

Description

The scope statement specifies for a managed object a scope and lifetime other than its defaults. You can nest scope statements. For more information about the scope and lifetime of managed objects, see Chapter 6.

Example

scope bootstrap ; 
    file [SYSEXE]SYSBOOT.EXE ; 
    file [SYSEXE]VMB.EXE ; 
    bootstrap block [SYSEXE]VMB.EXE image [SYSEXE]BOOTBLOCK.EXE ; 
end scope; 
      

The statements in this example specify that the files VMB.EXE and SYSBOOT.EXE must be placed on every bootstrap disk.

The software statement signals a software dependency on the specified product: the specified product must be installed prior to (or concurrently with) the installation of the product that contains the software statement. Upon successful installation, the software statement causes a permanent software reference to be recorded in the product database.

The software function tests for the presence of the specified product, including any version constraints that you may impose.

In contrast to the software statement, the software function does not create a permanent software reference to the specified product in the product database. The software function also does not cause the referenced product to be implicitly installed.

Note Please take note of the distinction between the software statement and the software function. The statement and function serve different purposes and are not interchangeable. See the Description section for a full discussion of the differences.

Statement Syntax

software producer base name
[ [no] component ]
[ { 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

< software producer base name
[ { 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 } ]
[ { installed before | installed after | kit accessible} ] >

Parameters

producer

Indicates the legal owner of the software product. This parameter must be a single quoted or unquoted string.

base

Indicates the base hardware/software system on which the product is intended to be installed. This parameter must be a single quoted or unquoted string. By convention, the string AXPVMS denotes an OpenVMS Alpha product, VAXVMS denotes an OpenVMS VAX product, and VMS denotes a product applicable for either OpenVMS Alpha or VAX.

name

Indicates the name of the product. This parameter must be a single quoted or unquoted string. The combination of producer, base, and name parameters must be unique among products installed on the system.

Options

[no] component

Indicates that if the product is copied (using the PRODUCT COPY command), the component products will be copied along with the product. The default is no component (the product does not need to be present during a copy operation).

version above version

Indicates the largest invalid product version. 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 options. By default, there is no largest invalid version.

version below version

Indicates the smallest invalid product version. 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 options. By default, there is no smallest invalid version.

version maximum version

Indicates a maximum product version. The version must be a single quoted or unquoted string that specifies a version identifier. The version of the product that is available must be less than or equal to the specified version. You cannot use this option with either the version below or version required options. By default, there is no maximum version.

version minimum version

Indicates a minimum product version. The version must be a single quoted or unquoted string that specifies a version identifier. The version of the product that is available must be greater than or equal to the specified version. You cannot use this option with either the version required or version above options. By default, there is no minimum version.

version required version

Indicates a required product version. The version must be a single quoted or unquoted string that specifies a version identifier. The version of the product that is available must be equal to the specified version. You cannot use this option with either the version above, version below, version maximum, or version minimum options. By default, there is no required version.

installed before

Indicates that the software product being tested must be present on the system before the current operation. This option is available only for the software function.

installed after

Indicates that the software product being tested must be present on the system after the current operation completes. This is a default option. It is available only for the software function.

kit accessible

Indicates that the product kit, either in a reference or sequential format, must be present in a specified source directory during the current operation. This option is available only for the software function.

Description

Software Statement

The software statement signals a software dependency on the specified product: the specified product must be installed prior to (or concurrently with) the installation of the product that contains the software statement. Upon successful installation, the software statement causes a permanent software reference to be recorded in the product database.

One of three situations may occur when a product with a software statement is installed:

• If the referenced product is already installed, the software dependency is satisfied, so no action is performed on the referenced product.
• If the referenced product is not installed, but a product kit is available in the source directory, the referenced product is implicitly installed to satisfy the software dependency.
• If the referenced product is not installed and the source directory does not contain a product kit for it, then and error message is displayed advising the user to terminate the installation process.
  If a referenced product is not available, Compaq recommends that users accept the default prompt and terminate the operation.

If you intend only to check whether a certain software product is installed on the system and alert the user if it is not, use the software function.

You use the software statement for the following purposes:

• To specify a software product that should be installed on the system to satisfy a software product dependency. For example, if Product A has a dependency on Product B, install Product B before installing Product A.
• To specify that a software product that is a part of a platform (product suite) is to be included in the platform product installation.
• To satisfy a special case use of the module statement when the following conditions are met:
  • The product updates (with a module statement) a library that is supplied by the referenced product
  • Both products could be installed concurrently
  
  Because it provides a library that another product updates, the referenced product must be installed first. The software statement forces the referenced product to be installed first when the products are installed together in one operation. (If the products were to be installed separately, you could use the software function to make sure that the referenced product was already installed.)
  For example, installing the OpenVMS platform product results in the installation of the OpenVMS operating system and, optionally, selected layered products such as DECwindows Motif. DECwindows Motif updates HELPLIB.HLB, which is originally provided by OpenVMS. Therefore, DECwindows Motif must use a statement such as

  software DEC AXPVMS VMS ;

  in its product description file to explicitly reference the OpenVMS operating system and guarantee that OpenVMS is installed before DECwindows Motif.

If two products reference each other (creating a circular reference list), the utility issues an error message.

If you use the component option, the utility creates a copy of the referenced product when you use the PRODUCT COPY command.

If the operation executes in batch mode and a referenced product is not available, the operation terminates.

Software Function

The software function tests for the presence of a product. You can also specify the version of the product that must be present. The software function, unlike the software statement, does not create a permanent software reference to another product and does not force the installation of the other product.

By default, the software function tests the state the product will be in when the operation finishes, not when the operation begins. The same effect is obtained when you include the installed after option. To test the state of the referenced product when the operation begins, you must specify the installed before option. If you specify the kit accessible option, the function tests whether the referenced product kit is present in the source directory.

Note The default option, installed after, is reliably tested only after the user configuration phase concludes and the utility is about to begin the execution phase. Use caution when including this option with the software function.

The function value is true if the following conditions exist; otherwise, the value is false:

• The product specified by the producer, base, and name parameters is available according to one of the following options: installed before; installed after; kit accessible.
• The version option is omitted, or the available version satisfies the specified constraints.

The software function is more appropriate than the software statement if you need only verify the existence of a certain product.

You use the software function in conjunction with the if statement, as shown in the following example:

if ( not < software DEC AXPVMS PROD_A version minimum V4.0 > ) ; information NO_PROD_A confirm ; file [SYSEXE]PROD_A_SUBSTITUTE.EXE ; end if ;

Using the software function in conjunction with the if statement gives you much more flexibility in forming expressions with other functions, and allows you to perform multiple actions in the form of groups of statements.

If the software function reference is not satisfied, you can create an error message with an error statement. This message allows a message of any size and contents. (Note that an error message induced by an unsatisfied software statement is rigid, short, and potentially less informative.)

You can use an error statement to unconditionally terminate the software function operation, while the failed software statement leaves the user with an option to continue the product installation.

if ( < software DEC AXPVMS PROD_B version below V7.0 > ) ; error NO_PROD_B abort ; end if ;

Summary of Differences Between the Statement and Function

Table 7-6 summarizes the differences between the software statement and the software function.

Table 7-6 Summary of software Statement and software Function Differences

Statement	Function
If the referenced product is not installed and its kit is available to the utility during the installation of the referencing product, it will be installed by the utility just prior to the referencing product.	If the referenced product is not installed, the function will evaluate to the boolean value FALSE (0). The referenced product will not be installed even though the kit may be available to the utility.
Causes the utility to create a permanent software reference in the database.	Does not create any reference from the referencing to the referenced product.
Creates a risk of software reference conflicts.	Since no permanent software reference is created, there is no risk of conflict.
Causes the utility to create a software reference and user interface related data structures in memory for the duration of the operation, thereby consuming additional system memory.	Does not cause the utility to create software reference or user interface related data structures in memory.
Requires additional processing to check for software reference conflicts and for processing error messages.	No additional processing other than searching for the presence of the referenced products.
If software reference cannot be satisfied, a one-sentence message is displayed to the user.	Allows any processing based on the value of the software function; error messages can be tailored in any desired way and size.
With the failure of a software reference, continuation of the operation is still possible.	With the failure of a software reference, processing may be unconditionally aborted with an "error <message> abort" statement.
Use only if you are willing to install the referenced product.	Use whenever you want only to check for the referenced product availability, but do not intend to install the referenced product.

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.

Examples

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

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

software DEC VAXVMS FORTRAN version below V5.0 ; 
      

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

if ( < software DEC AXPVMS COOL_PRODUCT 
          version minimum V3.0 kit accessible > ) ; 
    software DEC 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.

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 after the installation about system parameter requirements for your product. Note that the utility does not adjust system parameters.

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 
      

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

5952PRO_012.HTML