HP OpenVMS Systems Documentation
POLYCENTER Software Installation Utility Developer's Guide
6.1.4 Execute Statement Summary
Figure 6-1 Execute Statement Summary
6.1.5 Processing Execute Statements
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:
In contrast, the remove operation has only an execution phase. Following are brief descriptions of the major phases of an operation.
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.
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.
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
6.2 Testing and Debugging Tips
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:
6.2.1 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:
Use the /LOG qualifier with the PRODUCT PACKAGE, PRODUCT COPY, and
PRODUCT EXTRACT commands to list the files being processed.
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:
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.
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 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.
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.
|PDL Statements||OpenVMS V7.1||OpenVMS V7.1-2(Alpha)
|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|
New logical name: PCSI$DESTINATION
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|
|Function||OpenVMS V7.1||OpenVMS V7.1-2(Alpha)
|logical name||New function|
New behavior: detects whether or not a patch or mandatory update kit
has been installed
|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.
188.8.131.52 Software Patch Kit Locations on the Internet
You can find the software patch kit you need by clicking on the
appropriate customer environment in the following list. Please note
that software patch kits are provided in compressed format (as
indicated by the .PCSI-DCX file extension). The documentation at these
locations provides information on how to download and decompress the
kit as well as information on problems that have been corrected.
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:
The space is required between the [no] qualifier and its option, for example [no] access control. This differs from the standard DCL syntax.
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.
nameIndicates 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.
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:See Also rights identifier
- 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.
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.