Document revision date: 30 March 2001

The following table lists the execute statements and summarizes information about them.

Figure 6-1 Execute Statement Summary

This section provides flow diagrams for the PRODUCT INSTALL, PRODUCT RECONFIGURE, and PRODUCT REMOVE commands. There is a separate diagram for a first time installation of a product and for an upgrade of a product.

These diagrams illustrate the processing of execute statements in relation to events that occur during the major phases of an operation. Shaded boxes show typical output from these commands to help establish the timeline of events.

The installation and reconfiguration operations are performed in three phases:

• Configuration
• Execution
• Post processing

In contrast, the remove operation has only an execution phase. Following are brief descriptions of the major phases of an operation.

Configuration Phase

During the configuration phase, the user selects any options the product might provide and answers any questions that might be asked to complete the configuration process. Informational messages from the kit may be displayed at this time.

Execution Phase

During the execution phase, in a new installation, upgrade, or reconfiguration operation, the utility analyzes managed objects supplied by the product for conflicts. The utility uses generation information to resolve these conflicts. Any conflicts that cannot be resolved cause the utility to terminate the operation. In a remove operation, the utility does not perform any conflict detection or conflict resolution.

For all operations, the next step in the execution phase is to place the objects from all participating products in execution order. The utility merges the requirements of all affected products to produce a sequenced list of actions to perform. Note that the order in which the utility performs installation tasks might not correspond to the order in which PDL statements appear in the PDF, even when only one product is participating in an operation.

Finally, the utility modifies the target disk according to the execution order of the objects. Directories are created as required. The utility moves files to their destination directories as new or replacement files and merges library modules into existing libraries. When all actions have been successfully completed, the utility updates the SYS$SYSTEM:*.PCSI$DATABASE files that make up the product database.

Post-Processing Phase

During the post-processing phase, actions such as running a functional test of the product or displaying informational messages to the user are performed. Since the post-processing phase occurs after the installation or reconfiguration operation has completed and the product database has been updated on disk, any errors that might occur during this phase (such as failure of the functional test) do not affect the state of the product. Also, any error that occurs during the post processing phase will not trigger an execute abort statement.

Figure 6-2 INSTALL Operation - Product Is Installed for the First Time

Figure 6-3 INSTALL Operation - Product Is Upgraded

Figure 6-4 RECONFIGURE Operation - Product Is Reconfigured

Figure 6-5 REMOVE Operation - Product Is Removed

The POLYCENTER Software Installation utility provides tools you can use to monitor an operation to ensure it functions as expected. This section provides information on the following tools:

• /LOG qualifier
• /TRACE qualifer
• /DEBUG=CONFLICT qualifer

When you want to verify that the contents of your product kit either have been placed in the proper directories or correctly deleted, use the /LOG qualifier.

Using the /LOG qualifer with the PRODUCT INSTALL, PRODUCT RECONFIGURE, and PRODUCT REMOVE commands displays an informational message whenever a file is created, modified, or deleted on the target disk. The information logged includes:

• Creation and deletion of directories
• Creation, deletion, and renaming of files
• Insertion and removal of modules from libraries
• File conflict detection and resolution when two or more products provide the same file (or two or more patches for a product provide the same file)
• Module conflict detection and resolution when two or more products provide the same module (or two or more patches for a product provide the same module)

Use the /LOG qualifier with the PRODUCT PACKAGE, PRODUCT COPY, and PRODUCT EXTRACT commands to list the files being processed.

6.2.2 The /TRACE Qualifier

The /TRACE qualifier displays input sent to the subprocess and output returned by the subprocess for command procedures (or individual DCL commands) that are processed in non-interactive mode. It is a useful debugging aid because it lets you see all output from commands executed in the subprocess as if you were running the commands manually from your terminal. You can use SET VERIFY to have commands echoed as they are executed and you can insert WRITE SYS$OUTPUT commands to provide additional information for debugging. Specifically, the /TRACE qualifier does the following:

• Identifies input to the subprocess by prefacing lines with the message: "%PCSI-I-PRCINPUT, input to subprocess follows..."
• Lists each command sent to the subprocess, including the definition of logical names for the subprocess environment such as PCSI$SCRATCH.
• Lists each command you specify in execute statements as it is sent to the subprocess.
• Identifies output from the subprocess by prefacing lines with the message: "%PCSI-I-PRCOUTPUT, output from subprocess follows..."
• Displays all output from DCL commands as they are executed, including status messages that are normally suppressed in non-interactive mode.
• Displays the output from the $SHOW SYMBOL $STATUS command that is sent to the subprocess to obtain final exit status from a command procedure; this value determines the success or failure of the execute statement.

The /TRACE qualifier does not provide any additional information for execute statements that use the interactive option. If you specify the interactive option, all output is automatically sent to the user's terminal.

6.2.3 The /DEBUG=CONFLICT Qualifier

If your product replaces files or library modules that are provided by another product (or if you have created patch kits that update the same objects), you can use the /DEBUG=CONFLICT qualifier with the /LOG qualifier to obtain detailed information on file and module conflict resolution. You can use the /DEBUG=CONFLICT qualifier with the PRODUCT INSTALL and PRODUCT RECONFIGURE commands. With this qualifier you can see:

• The generation numbers used in the comparison
• Whether the object is retained or replaced and the name of the product that supplies the object

The majority of products do not replace files from another product. However, if your product does this, it is your responsibility to work with the kit developer of the other product to decide how you will use generation numbers to determine which object takes precedence when there is a conflict.

For intra-product conflict, you need only coordinate the use of generation numbers by your full, partial, and patch kits so that your customers can apply updates to the product in any order. For example, if you do not use generation numbers in your patch kits for objects, then the objects from the current patch kit will supersede the others. To avoid having the order of patch kit installation affect the final results, Compaq recommends that you always assign generation numbers to files and modules provided by patch kits.

6.2.4 Installing Your Product on Older Versions of OpenVMS

The POLYCENTER Software Installation utility has evolved since it was first released with OpenVMS V6.1. New PDL statements and options have been added in subsequent releases and are summarized in Section 7.1. While backward compatibility is a strong goal, occasionally software corrections and improvements in internal algorithms have resulted in slight differences in behavior when a product kit is installed on different version of OpenVMS (specifically different versions of the POLYCENTER Software Installation utility).

For example, a change was made in the utility that ships with OpenVMS V7.3 that affects the file chosen in conflict detection when there is a tie in generation numbers. Previously, the file already installed on the target disk was retained; now the file from the kit replaces the file on the target disk. In both cases, the file is considered to be the same (because the non-zero generation numbers declare the files to be identical), but use of the /LOG qualifier would show procedural differences in how the conflict is handled.

Therefore, if your product is supposed to install on a range of versions of OpenVMS, Compaq strongly recommends that you verify the installation and removal of your kit on each version that you support. In particular, perform these operations with the /LOG and /TRACE qualifiers to ascertain that your files are processed as you intended.

This chapter contains descriptions of the individual product description language (PDL) statements and functions.

7.1 Product Description Language (PDL) Evolves Over Time

The POLYCENTER Software Installation utility is an integrated component of OpenVMS Version 6.1 and later. After its introduction, subsequent releases of the OpenVMS operating system have incorporated various enhancements to PDL statements and functions. It is likely that Compaq will make further enhancements over time.

Earlier versions of the OpenVMS operating system do not support the new utility features provided in later versions of the operating system. This creates a challenge for the developer who must devise a kit that will install as expected in a variety of customer environments.

You can write a product description file based on the earliest version of OpenVMS at your customer sites. If you choose this approach, you must have or acquire knowledge about customer environments. It means you can use only the statements and functions (and their parameters and options) available for the earliest customer installed version of OpenVMS.

Table 7-1 and Table 7-2 let you quickly see when new utility features were made available. Please note that bug fixes are not shown unless they impact the behavior of the utility. For more information on a specific feature, please refer to the appropriate section in this manual.

Table 7-1 Features by OpenVMS Version: Statements

PDL Statements	OpenVMS V7.1	OpenVMS V7.1-2(Alpha) OpenVMS V7.2(VAX)	OpenVMS V7.3
apply to		New option: version above
bootstrap block			Obsolete: not available for layered products
error	New option: abort	New behavior: performs action before the configuration dialog, when possible
execute abort		New statement
execute install.remove		New option: interactive
execute postinstall		New option: interactive	New behavior: runs also on reconfigure operation
execute preconfigure		New statement
execute release		New option: interactive	Obsolete: new kits should use execute upgrade or other execute statements
execute start.stop		New option: interactive New logical name: PCSI$DESTINATION
execute test		New option: interactive New logical name: PCSI$DESTINATION
execute upgrade			New statement
file		New behavior: supports intra-product conflict detection	New behavior: file from kit selected to resolve conflict on non-zero generation number tie
information	New option: with helptext
module		New behavior: supports intra-product conflict detection	New behavior: module from kit selected to resolve conflict on non-zero generation number tie
option	New option: with helptext
patch image			Obsolete: new kits should use file statement to replace file
patch text			Obsolete: new kits should use file statement to replace file
software		New option: version above
upgrade		New option: version above

Table 7-2 Features by OpenVMS Version: Functions

Function	OpenVMS V7.1	OpenVMS V7.1-2(Alpha) OpenVMS V7.2(VAX)	OpenVMS V7.3
logical name		New function
software		New behavior: detects whether or not a patch or mandatory update kit has been installed New options: installed before installed after kit accessible version above
upgrade		New option: version above	New behavior: version range checking fully supported

Another option you have is to require your customers to apply a software patch kit, available from Compaq, that back ports utility functionality to earlier versions of OpenVMS. With this strategy you can use the latest utility enhancements in your product installation.

After a customer installs the patch kit, the utility will be functionally equivalent to what is provided by OpenVMS Version 7.2 including all bug fixes through Version 7.2-1 as well as bug fixes developed after the release of Version 7.2-1.

7.1.0.1 Software Patch Kit Locations on the Internet

• VAX 6.2 through VAX 7.1
• VAX 7.2
• Alpha 6.2 through Alpha 7.1-2
• Alpha 7.2
• Alpha 7.2-1

The patch kits are current as of the writing of this book. They may be superseded by higher versions in the future. If a particular README file is not present, start with the Alpha support page or the VAX support page.

7.2 PDL Conventions

The PDL conventions used are described in the Preface. However, the syntax descriptions in this chapter make significant use of several conventions, and they are worth repeating here:

• Brackets ([ ]) indicate optional elements. You can choose one, none, or all of the options.
• Braces ({ }) indicate a required choice of options; you must choose one of the options listed.
• The vertical bar (|) separates optional elements. It functions as a logical OR between two options, as in A | B , or A | B | C .
• Horizontal ellipsis points ( ... ) in examples indicate that the preceding item or items can be repeated one or more times, or that additional parameters, values, or other information can be entered.
• The semicolon (;) in syntax diagrams is required syntax.
• Angle brackets (<>) in syntax diagrams are required syntax.
• A double hyphen (-
• Unless otherwise indicated, extra space and tab characters may be used freely between syntax elements for the purposes of formatting and readability.
• A statement may span more than one line.

The rest of this chapter describes each PDL statement in detail and provides examples of its use. The PDL statements are presented in alphabetical order. Certain statements can be used as functions in the evaluation of an if statement. The functional form of a statement is documented along with the definition of the statement.

The account statement uses a command procedure to create a system account.

Syntax

Parameters

name

Indicates the user name of the account as a 1- to 12-character string. The user 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 account. Each parameter must be a single unquoted or quoted string that specifies P2 through P8, in order. Refer to the Description section for the meaning of the parameters.

Description

The account statement uses a command procedure (SYS$UPDATE:PCSI$CREATE_ACCOUNT.COM) to create an account. The parameters that you pass to the command procedure that creates the accounts are:

• P1 specifies the user name of the account (using the name parameter).
• P2 specifies general AUTHORIZE qualifiers. If there are no qualifiers to pass, specify a null string " ".
• P3 specifies a comma-separated list of rights identifiers to grant to the user name. These identifers must already exist, or be created with a separate rights identifier statement.
• P4 through P8 specify other general AUTHORIZE qualifiers.

Certain AUTHORIZE qualifiers must be used with care. For example, /DIRECTORY=dir-name assigns a default directory name to be used by the account. However, the POLYCENTER Software Installation utility does not create this directory for you; you must make sure that it exists.

When you remove a product that created accounts, the utility uses a command procedure (SYS$UPDATE:PCSI$DELETE_ACCOUNT.COM) to delete accounts associated with your product. This happens regardless of whether the SYSUAF.DAT file 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 account statement specifies an account managed object that has the following characteristics:

• Its name is the value of the name parameter. The name must be unique among all account names.
• It has operating lifetime.
• Managed object conflict is not recoverable.

Example

account TEST with ("/priv=(tmpmbx, netmbx)",(1) "PCSI_TEST",(2) "/account=PCSI",(3) "/astlm=500/biolm=200/bytlm=96000", "/wsdefault=4000", "/flags=(nodisuser,genpwd)", "/pwdminimum=8");

In this example, the account statement creates the TEST account.

	privacy and legal statement
5952PRO_007.HTML