Document revision date: 30 March 2001

## POLYCENTER Software Installation Utility Developer's Guide

Previous | Contents | Index

1. Parameter P2 specifies the TMPMBX and NETMBX privileges to be assigned to the TEST account.
2. Parameter P3 is a rights identifier. This name must exist on the system prior to executing the account statement. It can be created with a rights identifier statement.
3. Parameters P4 to P8 assign certain values to the TEST account.

## apply to

> The apply to statement specifies a product or product version that you want to update with a patch or mandatory update kit.

> Note You must include an apply to statement in a patch or mandatory update PDF to identify the product that is being updated. This statement is not valid in other types of PDFs.

### Syntax

apply to 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 } ] ;

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

> #### 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\bold) 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

> The apply to statement specifies the name of an installed product that a patch or mandatory update kit modifies. You can use options on this statement to limit the application of the patch or mandatory update either to a specific version of the product or to a range of versions. If you do not use version constraints, then you can modify any version of the product by installing a patch or mandatory update kit.

> The apply to statement is a utility directive and does not specify a managed object.

See Also product
software
upgrade

### Example

    product DEC VAXVMS CSCPAT57 V1.0 patch ;
        apply to DEC VAXVMS FORTRAN version required V2.0 ;
        patch image [SYSEXE]FORTRAN.EXE with [000000]CSCPAT57.PAT ;
    end product ;

> This example shows part of the product description for a patch to Compaq Fortran. As shown in the apply to statement, you must have Compaq Fortran Version 2.0 installed to apply this patch.

## bootstrap block (VAX only)

> The bootstrap block statement updates the bootstrap block on the system disk to reference the bootstrap file.

> Note Starting with OpenVMS V7.3, the bootstrap block statement is obsolete and its use is reserved to Compaq. This statement is to be used by an operating system product, not by a layered product or other application. Documentation of the bootstrap block statement may be discontinued in a future release of this manual.

### Syntax

bootstrap block name image source ;

### Parameters

> #### name

> Indicates the bootstrap file specification. You must provide this file with a file statement. You must also ensure that the file has bootstrap scope and product or assembly lifetime (using the scope statement).

> #### image source

> Indicates the file specification of the file that contains the bootstrap block image. You must provide this file with a file statement, and it must also have product scope and product lifetime.

### Description

> The bootstrap block statement specifies the file that the bootstrap block references and updates the bootstrap block on the system disk.

> The bootstrap block statement also specifies a bootstrap block managed object that has the following characteristics:

> - It is unnamed and unique within the bootstrap scope.
> - It has operating lifetime and bootstrap scope.
> - Managed object conflict is not recoverable.

See Also file
scope

### Example

    scope bootstrap;
      file [sysexe]vmb.exe;
    end scope;
    file [sysexe]bootblock.exe;
       .
       .
       .
    bootstrap block [sysexe]vmb.exe image [sysexe]bootblock.exe ;

> This example uses the bootstrap block statement to point the bootstrap block to the bootstrap file ([SYSEXE]VMB.EXE).

## directory

> The directory statement creates the specified directory if it does not already exist.

### Syntax

directory name
[ [no] access control (access-control-entry...) ]
[ owner name ]
[ protection { execute | private | public } ]
[ [no] version limit maximum ] ;

### Parameter

> #### name

> Indicates the directory name.

### Options

> #### [no] access control (access-control-entry...)

> Indicates the minimum access control entries (ACEs) that the directory will have. You must specify the ACEs as a quoted string. By default, directories have no added ACEs.

> #### owner name

> Indicates the account name that owns the directory. By default, the directory is owned by the SYSTEM account. If you specify a numeric value for name, you must enclose the string in quotation marks, for example `"[11,7]"` .

> #### protection execute

> Sets the directory protection to (S:RWE, O:RWE, G:E, W:E) so that users have execute access.

> #### protection private

> Sets the directory protection to (S:RWE, O:RWE, G, W) so that users have no access.

> #### protection public

> Sets the directory protection to (S:RWE, O:RWE, G:RE, W:RE) so that users have read and execute access. This is the default.

> #### [no] version limit maximum

> Indicates the maximum number of file versions in the directory as an unsigned integer from 1 through 32767. The default is no version limit.

### Description

> The directory statement creates the specified directory if it does not already exist. You use the directory statement to create a directory and to specify characteristics about the directory such as ownership and protection. However, use of the directory statement is optional because the file statement will implicitly create a directory, if it does not already exist, to contain the file it provides.

> The directory statement specifies the name of a directory managed object. Check the other statements in your PDF to make sure the name you specify is unique among all directory, file, and link managed objects in all scopes.

> The scope and lifetime of the directory managed object depend on whether it is lexically contained in a scope, end scope pair, as shown in Table 7-3. (See the scope statement for additional information.)

> Table 7-3 Directory Managed Object Scope and Lifetime
> Type of Scope Group | Lifetime | Scope
> --- | --- | ---
> Product | Product | Product
> Global | Assembly | Global
> Bootstrap | Operating | Bootstrap
> Processor | Operating | Processor

> If you use the access control option, the directory statement specifies one access control entry (ACE) managed object that references the directory managed object for each entry specified with the access control option. The ACE managed object has the following characteristics:

> - It is unnamed.
> - It has operating lifetime.
> - It has the same scope as the directory.

See Also file
scope

### Examples

#1
    directory [SYSHLP.EXAMPLES.FMS.MESSAGE] protection private
         access control ("(IDENTIFIER=[FMS], ACCESS=READ)");

> This example specifies the directory [SYSHLP.EXAMPLES.FMS.MESSAGE]. The protection private option specifies that no users have access to this directory. The access control option grants the user FMS read access to the directory.

#2
    directory [AL] owner PCSI$TEST version limit 3;

> In this example the directory [AL] is owned by the account PCSI$TEST and holds the maximum of three file versions.

#3
    directory [JIM] owner "[11,7]";

> This example specifies the directory [JIM] owned by the account whose UIC is [11,7].

## end

> The end statement terminates a statement group.

### Syntax

end
{ if |
option |
part |
product |
remove |
scope } ;

### Parameter

> #### None

### Options

> #### None

### Description

> The end statement terminates a statement group. See the statement referenced by the end statement for information about the statement group.

See Also if
option
part
product
remove
scope

### Example

    product CPQ AXPVMS TEST V1.0 full ;
        .
        .
        .
    end product ;

> The end product statement identifies the end of the product group.

## error

> The error statement displays an error message during an installation or reconfiguration operation. The text is from a PTF text module.

> Note The error statement must be contained within an if group.

### Syntax

error name [ abort ] ;

### Parameter

> #### name

> Indicates, as a quoted or unquoted string, the name of the associated PTF text module. The name you specify can be from 1 to 31 characters in length and must be unique among all names in the same product description.

### Option

> #### abort

> Forces an unconditional termination of the operation when the error statement is executed. See Section 7.1 for usage constraints.

### Description

> The error statement specifies a text module you want to display during an installation or reconfiguration operation. The error statement must be contained within an if group.

> The utility processes error statements in lexical order. The utility displays both prompt and help text during the validation phase. The validation phase occurs before and after the configuration of a product.

> During execution of an error statement that does not contain an abort option, the utility prompts the user to continue or terminate the operation. If the abort option is present, or the operation is executed in batch mode, the error statement causes the operation to terminate unconditionally.

> The error statement is a utility directive and does not specify a managed object.

> You must supply text in the associated product text module. The module must contain a =prompt directive line.

See Also hardware device
hardware processor
if
logical name
software
upgrade

### Examples

> 1. Suppose the PDF for a product contains the following lines:

>        if (<hardware processor model 7>) ;
>            error UNSPROC abort ;
>        end if ;

>    The corresponding module in the PTF contains the following lines:

>        1 UNSPROC
>        =prompt This product is not supported on a MicroVAX I processor.
>        Please read the installation guide that accompanies the software
>        to determine minimum system requirements for running this product.

>    If the user attempts to install the product on processor model 7, the following message is displayed and the installation is terminated:

>        This product is not supported on a MicroVAX I processor.

>        Please read the installation guide that accompanies the software
>        to determine minimum system requirements for running this product.

>        %PCSI-E-S_OPFAIL, operation failed
>        %PCSIUI-E-ABORT, operation terminated due to an unrecoverable error
>        condition

> 2. The following PDF fragment illustrates how to check for prerequisite software and issue an error message if the requirement is not met.

>        if (not <software DEC AXPVMS TCPIP >) and
>                 (not <software DEC AXPVMS UCX version minimum V4.0>) ) ;
>                error TCPIP_NOT_INSTALLED ;
>        end if;

>    The corresponding module in the PTF contains the following lines:

>        1 TCPIP_NOT_INSTALLED
>        =prompt TCPIP software is not installed on your system.
>        This product requires TCPIP networking software.  Please terminate
>        this operation, install any version of TCPIP (or UCX version V4.0
>        or higher), then install this product.

>    On installation of the product containing the PDL statements above, if neither the TCP/IP nor the UCX product is already installed (or will not be installed at the completion of the current operation), the following messages are displayed:

>        TCPIP software has not been installed on your system.

>        This product requires TCPIP networking software.  Please terminate
>        this operation, install any version of TCPIP (or UCX version V4.0
>        or higher), then install this product.

>        Terminating is strongly recommended.  Do you want to terminate? [YES]
>        %PCSI-E-S_OPCAN, operation cancelled by request
>        %PCSIUI-E-ABORT, operation terminated due to an unrecoverable error
>        condition

>    Since the abort option is not used on the error statement, the user was given the opportunity to continue installation of the product. Use of the abort option would have caused unconditonal termination of the installation as shown in the first example.

## execute abort

> The execute abort statement specifies commands to execute when an error condition causes an installation or reconfiguration operation to terminate.

### Syntax

execute abort (command,...) [ interactive ] [ uses (file,...) ] ;

### Parameter

> #### (command,...)

> Indicates the commands that the utility passes to the command interpreter whenever the operation fails.

### Option

> #### interactive

> Allows communication between the user and specified command or commands executing in a subprocess.

> #### uses (file,...)

> Indicates the files required to execute the commands you specified in the command parameter. Use a separate file statement to specify required files that are permanently placed in the user's destination directory tree. Use the uses option to specify required files that are placed in a temporary directory and deleted after use. By default, this statement does not require files.

### Description

> The execute abort statement specifies commands to execute when an error condition causes an installation or reconfiguration operation to terminate. For example, the following conditions activate the execute abort statement:
> - An error or fatal error condition returned as the final status from the subprocess in which commands are run from an execute statement, excluding the execute test statement.
> - The user terminates the operation by pressing CTRL+Y or CTRL+C.
> - The user answers YES to the question "Do you want to terminate?" Typically, this question is asked after an error is reported during material placement on the target disk.

> You specify recovery actions to perform by including one or more DCL command lines in the execute abort statement. These commands are passed for execution to the DCL interpreter running in a subprocess. Enclose each action, whether specified as a single DCL command or a command procedure, in double
> quotes (" "). If more than one action is given, use parentheses to enclose the list.

> Enclosing the execute abort statement in a scope group (consisting of scope and end scope statements) has no effect on the way execute abort commands are processed.

> If you want your commands to prompt the user and accept the user's input, specify the execute abort statement with the interactive option. The interactive option causes all output from DCL to be displayed, unless you prevent it. In contrast, when the interactive option is not specified, output generated by DCL commands is displayed only for lines that are interpreted as DCL messages; that is, those beginning with a percent sign (%) in column one.

> If you need files for the execute abort statement, specify them in the uses option. Each file you specify with the uses option must be present in the product material.

> Note that the uses option will not cause the listed files to be placed permanently in your file system. As soon as the installation operation completes, the files listed with the uses option are deleted. For this reason, you must use the file statement for this execute operation, and any other operation, in which you want your execute command procedures placed permanently in your file system.

> The execute abort statement causes the utility to define logical names for use by the subprocess that executes the specified commands. The commands should use these logical names to reference files, as follows:

> - PCSI$SOURCE is a subdirectory in the root format under the user's login directory that points to the location of the files specified by the uses option. This logical name is defined for the subprocess in which product-supplied commands execute. It is not the same PCSI$SOURCE logical name that can be defined by a user, in the user's process, pointing to the location of a product kit.
> - PCSI$DESTINATION is a root directory specification that points to the root directory where product material will be placed. The PCSI$DESTINATION logical is available except when the execute abort statement is called when the execute preconfigure statement fails. The PCSI$DESTINATION logical is not available until the configuration phase.
> - PCSI$SCRATCH is a subdirectory under the user's login directory that can be used by commands for temporary working space. This directory and any files placed in it are automatically deleted at the end of the operation.

> The execute abort statement is a utility directive and does not specify a managed object.

See Also Section 6.1
execute install...remove
execute postinstall
execute preconfigure
execute start...stop
execute upgrade
file

### Example

    execute install "@PCSI$SOURCE:[SYSUPD]EXEC_INSTALL.COM"
                 remove "" uses [SYSUPD]EXEC_INSTALL.COM ;
    execute abort "@PCSI$SOURCE:[SYSUPD]EXEC_ABORT.COM"
                 uses [SYSUPD]EXEC_ABORT.COM ;

> In this example, the execute abort statement sets up a command procedure to run whenever the operation fails after the execute install command has been executed. It is intended to clean the user environment in case the commands supplied by execute install have left the user's system modified. The uses option specifies the file name of the command procedure that is deleted after use.

Previous | Next | Contents | Index

| privacy and legal statement |
5952PRO_008.HTML