Updated: 11 December 1998

POLYCENTER Software Installation Utility Developer's Guide

The execute release statement specifies commands to execute when the existing product version is replaced with a later version.

Syntax

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

Parameter

(command,...)

Indicates the commands the utility passes to the command interpreter in the execution environment.

Option

interactive

Allows communication between the user and specified command or command procedure 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 release statement specifies commands that execute when the existing product version is replaced with a later version. However, it is important to remember that these commands will also execute when the product is installed for the first time. You specify actions by entering a command line, which the utility passes to the DIGITAL Command Language (DCL) interpreter running in a subprocess.

If you want your commands to prompt the user and accept the user's input, specify the execute release 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.

Enclose each action, whether specified as a single DCL command or a command procedure, in double quotes (" "). If more than one action is listed, use parentheses.

If you need files for the execute release statement, specify them in the uses option or in separate file statements. 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.

If you specify the execute release statement in your PDF along with other types of execute statements, the statements are processed in the following order:

1. execute preconfigure
2. execute ...stop (if an upgrade)
3. execute install...
4. execute release
5. execute start...
6. execute postinstall
7. execute test

The execute release statement causes the POLYCENTER Software Installation 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 for the current scope where product material will be placed.
• 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 release statement is a utility directive and does not specify a managed object.

Example

execute release "@pcsi$source:[sysupd]config.com" uses [sysupd]config.com ; 
      

In this example, the execute release statement sets up a command procedure to run when the product is upgraded. The uses option specifies the file name of the command procedure that is deleted after use.

The execute start statement displays a message to users indicating commands they should execute when the product is made available on the processor to which it is bound. On installation or upgrade (prior version being removed) of the product, these commands are also executed. The stop part of the statement indicates commands they should execute when the product is made unavailable on the processor to which it is bound. On removal of the product, or when it is upgraded, these commands are also executed.

Note The stop part of the statement is required even if there are no commands you want to execute when the product is removed. To indicate no command, use stop "".

Syntax

execute start (command,...) stop (command,...) [ interactive ] ;

Parameter

(command,...)

Indicates the command that the utility displays in a message to the user and also passes to the command interpreter in the execution environment.

Option

interactive

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

Description

The execute start statement displays a message to users indicating commands they should execute when the product is made available on the processor to which it is bound. On installation or upgrade of the product, these commands are also executed. The stop part of the statement indicates commands they should execute when the product is made unavailable on the processor to which it is bound. On removal of the product, or when it is upgraded, these commands are also executed.

If you need files for the execute start...stop statement, you must provide them with file statements.

If you want your commands to prompt the user and accept the user's input, specify the execute start 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 specify the execute start...stop statement in your PDF along with other types of execute statements, the statements are processed in the following order:

1. execute preconfigure
2. execute ...stop (if an upgrade)
3. execute install...
4. execute release
5. execute start...
6. execute postinstall
7. execute test

PCSI$DESTINATION is a root directory specification that points to the root directory for the current scope where product material will be placed.

The execute start...stop statement is a utility directive and does not specify a managed object.

Examples

file [SYS$STARTUP]PRODUCT_STARTUP.COM ; 
file [SYS$STARTUP]PRODUCT_SHUTDOWN.COM ; 
execute 
    start "@sys$startup:product_startup.com" 
    stop "@sys$startup:product_shutdown.com" ; 
 
      

In this example, the execute start...stop statement displays a message to users about command procedures they should run to start and stop the product:

Insert the following lines in SYS$MANAGER:SYSTARTUP_VMS.COM: @SYS$STARTUP:PRODUCT_STARTUP.COM Insert the following lines in SYS$MANAGER:SHUTDOWN.COM: @SYS$STARTUP:PRODUCT_SHUTDOWN.COM

The PRODUCT_STARTUP.COM command procedure is executed during the installation. The PRODUCT_SHUTDOWN.COM command procedure is executed during the REMOVE operation or during a product upgrade.

file [SYS$STARTUP:]ABS_STARTUP.COM ; 
execute 
    start "@sys$startup:abs_startup.com" 
    stop "" ; 
 
      

In this example, the execute start...stop statement displays a message to users about command procedures they should run to start the product. Note that there are no commands executed when the product is stopped. The command procedure ABS_STARTUP.COM executes during the INSTALL operation, then the following message is issued:

Insert the following lines in SYS$MANAGER:SYSTARTUP_VMS.COM: @SYS$STARTUP:ABS_STARTUP.COM

The execute test statement specifies commands that execute during the functional test of the product.

Syntax

execute test (command,...) [ interactive ] ;

Parameter

(command,...)

Indicates the command that the utility passes to the command interpreter in the execution environment.

Option

interactive

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

Description

The execute test statement specifies commands that execute during the functional test of the product. You specify actions by entering a command line, which the utility passes to the DIGITAL Command Language (DCL) interpreter running in a subprocess.

If you need files for the execute test statement, you must provide them with file statements.

If you want your commands to prompt the user and accept the user's input, specify the execute test 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 specify the execute test statement in your PDF along with other types of execute statements, the statements are processed in the following order:

1. execute preconfigure
2. execute ...stop (if an upgrade)
3. execute install...
4. execute release
5. execute start...
6. execute postinstall
7. execute test

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

PCSI$DESTINATION is a root directory specification that points to the root directory for the current scope where product material will be placed.

Example

file [SYSTEST]PROD$IVP.COM ; 
execute 
    test "@sys$test:prod$ivp.com" ; 
      

In this example, the execute test statement runs a command procedure to perform an installation verification test of the product.

The file statement creates a file in the execution environment. If a file of the same name already exists, the POLYCENTER Software Installation utility might replace the file, depending on the options specified.

Syntax

file name

Parameter

name

Indicates the relative file specification of the file, relative to the destination root directory tree. For example, if the destination is SYS$SYSDEVICE:[VMS$COMMON.], then the file [SYSEXE]TEST.EXE is placed in SYS$SYSDEVICE:[VMS$COMMON.SYSEXE]TEST.EXE.

Options

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

Indicates the minimum access control entries (ACEs) that the file will have. By default, files have no added ACEs (no access control).

[no] archive

Allows you to preserve existing files during an upgrade. The POLYCENTER Software Installation utility appends _OLD to the end of the file type. For example, if you archived an existing file named STARTUP_TEMPLATE.SYS, the utility would rename it STARTUP_TEMPLATE.SYS_OLD.

If there are several versions of the existing file, the utility renames the latest file type before deleting all of the remaining file versions. By default, the POLYCENTER Software Installation utility does not preserve existing file versions (no archive). You cannot use this option with the release merge or write options.

assemble execute (command,...)

Establishes the contents of the file by executing the specified commands. Specify the command lines as quoted or unquoted strings.

assemble uses (file,...)

Indicates a list of additional files required by the assemble execute option. You must include the relative file specification. Files specified by this option are placed in a temporary directory for use by the assemble execute command and are automatically deleted after use. By default, the assemble execute option does not require additional files.

[no] generation generation

Indicates that the file has an explicit generation number. Specify the number as an unsigned integer in the range 0 through 4294967295. Refer to the Description section for the meaning of this value. By default, the file does not have an explicit generation number (no generation), which is equivalent to 0.

image library

Indicates that the file's symbols are inserted into the system shareable image symbol table library. The file must be a shareable image.

owner owner

Indicates the account name that owns the file. By default, the file 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 file protection to (S:RWED, O:RWED, G:E, W:E) giving general users execute access.

protection private

Sets the file protection to (S:RWED, O:RWED, G, W), giving general users no access.

protection public

Sets the file protection to (S:RWED, O:RWED, G:RE, W:RE), giving general users read and execute access. This is the default.

release merge

Indicates that library modules propagate during a version upgrade. If modules are present in the existing library but not in the new library, they are propagated to the new library. The file you specify with the name parameter must be a library. You cannot use this option with the archive, release replace, or write options.

release replace

Indicates that previous versions of the file are replaced during a version upgrade. You cannot use this option with the release merge option.

release notes

Indicates that the file is a release notes file. Users can extract the release notes to a file using the DCL command PRODUCT EXTRACT RELEASE_NOTES. The release notes are created in the file DEFAULT.PCSI$RELEASE_NOTES in the current directory, or in the file specified by the user with the /FILE qualifier.

size size

Do not specify this option in your PDF. When you package your product, the utility calculates the size (in blocks) of the files you specify and provides this option in the output PDF. If you specify this option in the input PDF to a PRODUCT PACKAGE command, the option is ignored.

source source

Indicates the relative file specification of the file in the reference copy as a single quoted or unquoted string. Use this option when you want to give a file a different name in the execution environment. When users install your product, the utility uses this source file in the reference copy to create the file you specify with the name parameter. By default, the file in the reference copy and the file created in the execution environment have the same file specification.

[no] write

Indicates that you expect that users will modify the file during system operation. If you specify this option, during a version upgrade if the file already exists, it remains the active version. For example, the OpenVMS operating system PDF uses this option for [SYSMGR]SYLOGIN.COM. The default is no write. You cannot use this option with the archive or release merge options.

Description

The file statement creates a file in the execution environment. If a file of the same name already exists, the utility determines which file to preserve by comparing the generation numbers of the files.

If both files have generation numbers, the utility preserves the file with the higher generation number. If one file does not have a generation number or has a generation number of zero, the utility preserves the file that has a nonzero generation number. If both files have the same nonzero generation number, they are considered to be equivalent and either one may be used. Finally, if neither file has a nonzero generation number, a file conflict error is reported to the user.

The file statement specifies a file managed object. You specify the name of the file managed object using the name parameter. The name is a multicomponent name qualified by the relative directory path.

The bootstrap block, link, and loadable image statements can also specify references to a file managed object.

The file specified by the source option, if present, or otherwise by the name parameter, must be supplied as product material unless the assemble execute option is used to dynamically create the file.

The assemble execute option 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 root directory specification under the user's login directory. It is used for temporary placement of the files specified by the assemble uses option. This logical name is set 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 under the user's login directory used as a staging area. The commands specified in the assemble execute option are responsible for creating a file in this directory tree whose name matches the one specified in the file name parameter. After the commands are executed, the utility moves the file to the product's destination directory for the current scope.
• 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.

Each file specified by the assemble uses option must be supplied as product material (that is packaged with the /MATERIAL qualifier pointing to the directory that contains the assemble uses files).

The scope and lifetime of the file managed object depend on whether it is contained within a scope, end scope pair as shown in Table 7-2.

Table 7-2 File Managed Object Scope and Lifetime

Type of Scope Group	Lifetime	Scope
Product 1	Product	Product
Global	Assembly	Global
Bootstrap	Operating	Bootstrap
Processor	Operating	Processor

If you specify the access control option, the file statement specifies one access control entry (ACE) managed object that references the file 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 file managed object.
• The system resolves managed object conflict by managed object collection.

If the image library option is in effect, it specifies an image library module managed object that references the file managed object. The image library module managed object has the following characteristics:

• It must be unique within the global scope.
• It has assembly lifetime and global scope.
• Managed object conflict is not recoverable.

Examples

file [SYSMGR]PROD01.DAT 
      access control ("(IDENTIFIER=[TEST],ACCESS=READ)", 
                      "(IDENTIFIER=[PROD_USER],ACCESS=READ+WRITE)", 
                      "(IDENTIFIER=*,ACCESS=NONE)") write;    
 
      

The file statement in this example specifies that the file PROD01.DAT cannot be accessed by any user account other than TEST, which is allowed to read it, and PROD_USER, which is allowed to read and write the file.

file [SYSLIB]FDVSHR.EXE image library ; 
 
      

The file statement in this example specifies that the symbols for the shareable image [SYSLIB]FDVSHR.EXE are inserted into the system shareable image symbol table library.

file [SYSMGR]DECW$STARTUP.COM protection public ; 
      

The file statement in this example creates the file [SYSMGR]DECW$STARTUP.COM, giving users read and execute access.

file [SYSMGR]DECW$SYLOGIN.COM protection public 
      source [SYSMGR]DECW$SYLOGIN.TEMPLATE ; 
 
      

The file statement in this example creates the file [SYSMGR]DECW$SYLOGIN.COM in the execution environment using the contents of the file [SYSMGR]DECW$SYLOGIN.TEMPLATE from product material packaged in the kit. You do not have to specify the source file with a separate file statement. The PACKAGE command always requires a /MATERIAL qualifier.

file [SYSMGR]DECW$SYSTARTUP.COM generation 56 archive ; 
      

The file statement in this example creates the file [SYSMGR]DECW$SYSTARTUP.COM, preserving the existing copy. It also assigns a generation number to the file for conflict resolution. For example, if a version of the file already exists with a generation number of 60, the utility will preserve the copy with generation number 60 and will not create a new one.

file [SYSEXE]CALIBRATE.EXE 
      assemble execute "@PCSI$SOURCE:[TEMP]CALIBRATE_LINK.COM" 
      assemble uses ("[TEMP]CALIBRATE.OBJ", 
                     "[TEMP]CALIBRATE_LINK.COM") ;     
 
      

The file statement in this example creates the file [SYSEXE]CALIBRATE.EXE in the execution environment by executing a command procedure to link the image. The link command procedure and object file are obtained from product material packaged in the kit. The link command in CALIBRATE_LINK.COM uses the link qualifier /EXECUTABLE=PCSI$DESTINATION:[SYSEXE]CALIBRATE.EXE to create the image file.

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

5952PRO_008.HTML