Document revision date: 30 March 2001

## POLYCENTER Software Installation Utility Developer's Guide

Previous | Contents | Index

## remove

> The remove statement deletes objects from the user's system. The remove and end remove statements form a remove group.

> Note You cannot use the remove statement in a transition PDF.

### Syntax

remove ;

[ PDL-statements ]

end remove ;

### 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.

### Required Terminator

end remove ;

### Description

> The remove group is used to delete objects from the user's system. Statements that normally provide managed objects (such as file and directory statements) cause these objects to be deleted when the statements are enclosed in a remove group.

> By using the remove group in a partial, patch, or mandatory update kit, you can eliminate obsolete files from a previous version of your product. By using the remove group in a full kit, you can eliminate objects provided by a previous installation mechanism (for example, VMSINSTAL). You can also use a remove group to delete objects that were created by a previous version of your product, but which were not recorded in the product database as managed objects. These include archived files (those saved as *.*_OLD) and files created by command procedures invoked through execute statements.

> Statements that do not provide managed objects function normally within a remove group.

> You can nest remove, end remove within scope, end scope, if necessary.

### Examples

#1
    remove ;
      directory [SYSHLP.EXAMPLES.FOO] ;
      file [SYSHLP.EXAMPLES.FOO]SMLUS.COM ;
      file [SYSHLP.EXAMPLES.FOO]SMLUT.COM ;
      file [SYSHLP.EXAMPLES.FOO]SMLUU.COM ;
    end remove ;

> The statements in this example remove some files and a directory (if they exist) from the product database and the running system.

#2
    scope bootstrap ;
        remove ;
            file [SYSEXE]PROD_PROC.EXE ;
        end remove ;
        file [SYSEXE]PROD_PROC_V2.EXE ;
    end scope ;

> The statements in this example remove a file in the bootstrap scope and then provide a new file.

## rights identifier

> The rights identifier statement uses a command procedure to create a rights identifier.

### Syntax

rights identifier name with (parameters,...) ;

### Parameters

> #### name

> Indicates the name of the rights identifier. The rights identifier name is passed to the command procedure as P1.

> #### with (parameters,...)

> Indicates the list of parameters that are passed to the command procedure that creates the rights identifier. Each parameter must be a single quoted string that specifies P2 and P3, in order. Refer to the Description section for the meaning of the parameters.

### Description

> The rights identifier statement invokes a command procedure (SYS$UPDATE:PCSI$CREATE_RIGHTS_IDENTIFIER.COM) to create rights identifiers. This command procedure runs the AUTHORIZE utility to perform the function. The utility passes the following parameters to the command procedure:
> - P1 specifies the name of the rights identifier (using the name parameter).
> - P2 specifies the optional qualifiers to use with the AUTHORIZE command ADD/IDENTIFIER.
> - P3 specifies the /VALUE qualifier to use with the AUTHORIZE command ADD/IDENTIFIER. You can specify this parameter only if the identifier does not already exist on the system.

> When you remove a product that created rights identifiers, the POLYCENTER Software Installation utility uses a command procedure (SYS$UPDATE:PCSI$DELETE_RIGHTS_IDENTIFIER.COM) to delete rights identifiers associated with your product. This happens regardless of whether the SYSUAF.DAT is shared by another system disk.

> Note In a future version, the utility may create and delete these managed objects directly without the use of command procedures. If this is the case, these statements will continue to function, but the command procedures may not be maintained or shipped with future versions of the utility.

> The rights identifier statement specifies a rights identifier managed object that has the following characteristics:

> - Its name is the value of the name parameter. The name must be unique with respect to all rights identifier names in the operating scope.
> - It has operating lifetime.
> - It does not recover from managed object conflict.

See Also account

### Example

    rights identifier PCSI_TEST
           with ("/attributes=DYNAMIC",
                 "/value=IDENTIFIER:14600926") ;

> In this example, the rights identifier statement creates a rights identifier named PCSI_TEST with a value of 14600926.

## scope

> The scope statement establishes the scope of one or more managed objects. 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.

### Required Terminator

end scope ;

### Description

> The scope statement establishes the scope of one or more managed objects. The scope of a managed object defines the degree of sharing that the managed object permits. For example, some objects are available only to certain processes; whereas others are shared by all processes.

> The scope and end scope statements form a scope group. The type of scope indicated in the scope statement pertains to all objects within the scope group. You can nest scope groups.

> Note In almost all cases, the POLYCENTER Software Installation utility defaults establish the correct scope for each type of managed object. Because using scope statements unnecessarily or incorrectly can cause problems, Compaq recommends that you use explicit scope statements only when you are sure product scope is not sufficient, as explained below or stated in the description of certain PDL statements.

> The different types of scope that a managed object can have are described below:

> - Global scope is the largest scope in which a single POLYCENTER Software Installation utility operation can have an effect. A single file that must be shared by every process in the computing facility must exist in global scope. Modules in system object libraries are examples of managed objects that must be in global scope. Writable databases might be in global scope.
>   When placing file or modules in global scope, please review Section 2.6 and the descriptions of the file and module statements regarding conflict resolution and the generation option.
> - Bootstrap scope managed objects function during system bootstrap when operating system facilities are unable to locate and use larger scopes. Drivers and loadable images that must be present before startup executes are examples of files that should be in the bootstrap scope.
>   Use bootstrap scope for products that use device drivers, especially those drivers that must be read by the primitive file system. Because files in bootstrap scope are read by the primitive file system, they are read when not synchronized with the file system on other cluster members that might access the same disk. Therefore, those files must retain stable positions as long as the disk is in use by any system and must not be manipulated by online disk defragmentation operations, including those that use the MOVEFILE primitive.
> - Product scope managed objects are product specific. Most managed objects for a product reside in product scope. Product scope is the default scope for most objects; therefore, it is not necessary to specify product scope. Product scope managed objects for different products can be stored together or separately.
> - Processor scope managed objects exist in all processes executing on a single computer. For example, a logical name might exist in processor scope.

> When you update your product with a partial, patch, or mandatory update kit, you can either explicitly state the scope of the file managed objects you are updating or let the utility determine the scope of the file managed objects:

> - You can use the scope statement to ensure that the utility looks in a specific scope for the file managed object you want to update.
> - If you do not use the scope statement, the utility searches the execution environment for a file managed object with the same name. If the utility finds the object, it replaces the object; if the utility does not find the file managed object, it provides a new file in product scope.

> If you use the patch statement, the object you are updating must have been provided by your product. If you use the module statement, the object you are updating either must have been provided by your product or must be in global or bootstrap scope.

See Also directory
file
infer
link

### 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.

## software

> 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).

> #### installed after

> Directs the utility to test whether the specified software product will be installed on the system at the conclusion of the current operation. This option is available only for the software function. You cannot use this option with either the installed before or kit accessible option. This option is the default when neither the installed before nor the kit accessible option is used.

> #### installed before

> Directs the utility to test whether the specified software product was installed on the system before the current operation began. This option is available only for the software function. You cannot use this option with either the installed after or kit accessible option. Take special note of the fact that installed before is not the default. When neither the installed before nor the installed before option is used, the default is installed after. Therefore, if you want to determine if a product is already installed, you must use the installed before option.

> #### kit accessible

> Directs the utility to test whether the specified software product kit, either in sequential or reference format, is present in the source directory. This option is available only for the software function. You cannot use this option with either the installed after or installed before option. By default, availability of the kit is not tested.

> #### 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

> 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 for it 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 an 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 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.

> You can use different options to determine whether the specified product:

> - Is currently installed
> - Will be installed on successful completion of the operation
> - Has a product kit in the source directory

> 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, or 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 with the if statement, as shown in the following example:

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

> Using the software function 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 display 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 the abort option on 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 CPQ AXPVMS PROD_B version below V7.0 > ) ;
>            error NO_PROD_B abort ;
>        end if ;

> Summary of Differences Between the Statement and Function

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

> Table 7-10 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. | Requires 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.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5952PRO_014.HTML