[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

POLYCENTER Software Installation Utility Developer's Guide


Previous Contents Index


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 Version 7.3, the bootstrap block statement is obsolete and its use is reserved to HP. 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 HP 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 an =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 HP AXPVMS TCPIP >) and
             (not <software HP 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 previous PDL statements, 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 the 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.


execute install...remove

The execute install...remove statement is a compound statement that performs two distinct actions:
  • The "install" portion specifies commands to execute when the product is installed or reconfigured.
  • The "remove" portion specifies commands to execute when the product is removed, but not when the product is upgraded.

Note

The remove 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 remove "" .

Syntax

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


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 the 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 install...remove statement is a compound statement consisting of an "install" portion and a "remove" portion.

The install portion specifies commands to execute when the product is installed or reconfigured. These commands are run after all product material has been placed on the target disk (that is, after all directory, file, and module statements have been processed).

The remove portion specifies commands to execute when the product is removed. These commands are run before any product material is deleted from the target disk. The execute ...remove statement has no effect when the product is upgraded. To execute commands when the product is upgraded by another version of the product, use the execute upgrade statement.

Note

Previous versions of this manual incorrectly stated that execute install...remove commands are also run when the product is upgraded.

You specify the install and remove actions to perform by including one or more DCL command lines in the execute install...remove 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 want your commands to prompt the user and accept the user's input, specify the execute install...remove 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 install statement, specify them in the uses option or in separate file statements. However, if you need files for the execute remove statement, you must provide them with file statements so that they are available on the user's system for use when the product is removed. 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 install...remove 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.

    Note

    The PCSI$SOURCE logical name is available only for the execute install operation. You cannot use it for an execute remove operation.
  • 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 install...remove statement is a utility directive and does not specify a managed object.

See Also Section 6.1
file

Example


file [SYSUPD]UNLOAD_LOADABLE_IMAGE.COM ;
execute
   install "@PCSI$SOURCE:[SYSUPD]LOAD_LOADABLE_IMAGE.COM"
   remove "@PCSI$DESTINATION:[SYSUPD]UNLOAD_LOADABLE_IMAGE.COM"
   uses ([SYSUPD]LOAD_LOADABLE_IMAGE.COM) ;
      

In this example, the execute install...remove statement sets up command procedures to run when the product is installed and removed. The uses option specifies the file name of the command procedure for use on installation of the product. The file is deleted after use. The file statement specifies the file name of the command procedure for use on removal of the product. This file is placed in the user's destination directory tree during installation and executed during removal.


Previous Next Contents Index