HP OpenVMS Systems Documentation

The execute start...stop statement is a compound statement that performs two distinct actions:

• The "start" portion either specifies commands to execute when the product is installed for the first time or upgrades a previously installed version of the product.
• The "stop" portion specifies commands to execute when the product is either removed or upgraded by another version of the product.

The execute start...stop statement also displays a message at the successful conclusion of the operation, advising the user to add the specified commands to the appropriate system-wide startup or shutdown command procedure.

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

Syntax

Parameter

(command,...)

Indicates the commands 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...stop statement is a compound statement consisting of a "start" portion and a "stop" portion.

The "start" portion either specifies commands to execute when the product is installed for the first time or upgrades a previously installed version of the product. These commands are run after any execute install... statements have been processed, but before any execute postinstall statements. In addition, a message is displayed at the end of the operation telling users to add these commands to their SYSTARTUP_VMS.COM file.

The "stop" portion specifies commands to execute when the product is either removed or upgraded by another version of the product. These commands are run before any product material is deleted from the target disk and before any execute ...remove statements are processed. In addition, a message is displayed at the end of the operation telling users to add these commands to their SYSHUTDWN.COM file.

If you need files for the execute start...stop statement, you must provide them with file statements so that they are available on the user's system for use after the installation completes.

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.

The execute upgrade statement causes the POLYCENTER Software Installation utility to define a logical name for use by the subprocess that executes the specified commands. It defines PCSI$DESTINATION as 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 an installation verification procedure to run after the product has been successfully installed or reconfigured to perform a functional test of the product.

Syntax

Parameter

(command,...)

Indicates the commands 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 an installation verification procedure to run after the product has been successfully installed or reconfigured to perform a functional test of the product. Prior to running this test, the product database is updated and closed. The product remains installed or reconfigured even if the functional test fails.

The user can prevent the running of the installation verification procedure by specifying the /NOTEST qualifier on the PRODUCT INSTALL or PRODUCT RECONFIGURE command.

You specify test actions to perform by including one or more DCL command lines in the execute test 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.

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.

The execute test statement causes the POLYCENTER Software Installation utility to define a logical name for use by the subprocess that executes the specified commands. It defines PCSI$DESTINATION as a root directory specification that points to the root directory for the current scope where product material will be placed.

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

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 execute upgrade statement specifies the commands to execute when the product is upgraded by another version of the product.

Syntax

Parameter

(command,...)

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

Option

interactive

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

Description

The execute upgrade statement specifies the commands to execute when the product is upgraded by another version of the product. These commands are run for the version of the product that is being replaced, not for the new version of the product. To run commands when the product is removed (but not upgraded by another version), use the remove portion of the execute install...remove statement to specify the commands.

If you need files for the execute upgrade statement, you must provide them with file statements so that they are available on the user's system when the product is upgraded.

The execute upgrade statement causes the POLYCENTER Software Installation utility to define a logical name for use by the subprocess that executes the specified commands. It defines PCSI$DESTINATION as a root directory specification that points to the root directory for the current scope where product material will be placed.

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

Example

 file [sysupd]UPG_TASKS.COM ;
 execute upgrade "@PCSI$DESTINATION:[SYSUPD]UPG_TASKS.COM" interactive ;
      

In this example, the file statement places the command procedure UPG_TASKS.COM on the destination disk during the product installation. The execute upgrade statement specifies that this command procedure is run only when this product is upgraded by the installation of the same or different version of the product. In the future, if an upgrade of the product is performed, this command procedure is run before any product material is deleted from the destination disk. Use of the interactive option on the execute upgrade statement allows the command procedure to interact with the user via the SYS$INPUT and SYS$OUTPUT I/O channels.

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

Syntax

[ [no] access control (access-control-entry...) ]
[ [no] archive ]
[ assemble execute (command,...) [ assemble uses (file,...) ] ]
[ [no] generation generation ]
[ image library ]
[ owner owner ]
[ protection { execute | private | public } ]
[ release merge ]
[ release notes ]
[ size size ]
[ source source ]
[ [no] write ] ;

Parameter

name

Specifies the name of the file object to install on the user's system. The name consists of a relative file directory specification, file name, and file type. File version is ignored because the utility determines the file version to use at installation time.

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. Note that the utility does not keep track of archived files as managed objects, or delete them when the product is upgraded or removed.

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

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

Specifies the name of the file to package that supplies the contents for the file specified in the name parameter of the file statement. The source file name consists of a relative directory specification, file name, and file type of a file in the materials directory path. File version number is not used because the file with the highest version is packaged. Use this option when the input file for the package operation has a different relative file specification than the output file your kit installs on the user's system. By default, the name of the input file for the package operation is the same as the output file created in the execution environment when the kit is installed.

[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 option.

Description

The file statement creates a file object on the target disk. You specify a file managed object with either the name parameter or the source option. The file must be supplied as product material, unless the assemble execute option is used to dynamically create the file. The link and loadable image statements can also specify references to a file managed object.

File Conflict

Two types of file conflict can occur:

• An inter-product file conflict occurs when two or more products provide a file with the same name in the same directory. (Note, files with the same name can co-exist in different directories.)
• An intra-product file conflict occurs when two or more patch or partial kits for a product update the same file.
  Example: OpenVMS provides the file DUDRIVER.EXE. If you install two different remedial kits for a particular version of OpenVMS that both update this file, an intra-product file conflict results.
  Intra-product file conflict detection and resolution was introduced in the version of the utility that shipped with OpenVMS Alpha V7.1-2 and OpenVMS VAX V7.2. This enhancement allows patch and partial kits to be installed "out-of-order" while providing the most up-to-date files. Prior to this change, files from patch or partial kits always superseded the previously installed files.

The utility resolves a file conflict by comparing the generation numbers of the files involved.

Do not confuse generation numbers with file versions. A generation number is an optional attribute you supply on a file statement using the generation option. A generation number can be any integer in the range of 0 to 4294967295. For example:

file [SYSEXE]ABC.EXE generation 100;

If you do not specify a generation number, its default value is 0. Table 7-4 shows how the utility resolves a file coflict.

Table 7-4 Resolving File Conflict with Generation Numbers

If the generation numbers	Then
Are different	The file with the largest non-zero number is selected.
Are the same and are not zero	V6.1-V6.2: The file from the kit replaces the previously installed file. V7.0-V7.2: The previously installed file is retained. V7.3: The file from the kit replaces the previously installed file.
Are zero	Unresolvable file conflict, an error is reported to the user. Note that in V7.1, file conflict is not detected and the file from the kit is selected. This behavior was corrected in OpenVMS Alpha V7.1-2 and OpenVMS VAX V7.2.

Generation information is not used for intra-product conflict detection when a product is upgraded. In this case, all files from the old version are deleted, and new files from the kit are placed on the target disk. However, generation information is used during an upgrade for inter-product conflict detection when any files from the product conflict with files from another product.

Logical Names

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 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 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. This logical name is defined for the subprocess in which product-supplied commands execute. It is not the same PCSI$DESTINATION logical name pointing to the target disk that can be defined by a user in the user's process.
• 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.

Scope and Lifetime

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

Table 7-5 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

Access Control Managed Object

You can include an access control option in a file statement to control access to a file managed object. Each access control entry (ACE) you specify creates an ACE managed object with 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.

Image Library Managed Object

For a file statement that provides a shareable image, you can specify the image library option to direct the utility to insert the file's symbols into the system shareable image symbol table library. This action creates an image library module object with 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 ;

      

---

Previous

Next

Contents

Index