HP OpenVMS Systems Documentation
POLYCENTER Software Installation Utility Developer's Guide
6.2 Forcing Operation Termination from A Command Procedure
There may be times when the command procedure you have included in your PDF determines during execution that the product processing environment is inadequate and cannot successfully complete the operation. In this case, you may want to abort the execution. You may do this by exiting your command procedure with the status code %X053D9301.
This status code is intercepted by the installation utility and gracefully and cleanly aborts the operation. It is recommended that you include an appropriate message explaining why the operation is being terminated in your command procedure.
This status code is recommended for prcedures run with the EXECUTE
PRECONFIGURE and EXECUTE PRE_UNDO statements. It may also be
successfully used with the EXECUTE INSTALL, EXECUTE POSTINSTALL,
EXECUTE START, and EXECUTE UPGRADE statements, but it is important the
operation is run with the /RECOVERY_MODE qualifier. The abort code is
ignored by the installation utility when used in the command procedure
run with the EXECUTE TEST statement.
The POLYCENTER Software Installation utility includes features you can use to monitor an operation to ensure it functions as expected. This section provides information on the following topics:
6.3.1 The /LOG Qualifier
The /LOG qualifier for the PRODUCT INSTALL, PRODUCT RECONFIGURE, PRODUCT REMOVE, and PRODUCT UNDO PATCH commands causes an informational message to be displayed whenever a file is created, modified, or deleted on the destination disk. Using this qualifier, you can verify that product material from your kit has been placed in the proper directories, and that files have been correctly deleted, modified, or renamed. 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 for the PRODUCT INSTALL, PRODUCT RECONFIGURE, PRODUCT REMOVE, and PRODUCT UNDO PATCH commands is used to display information about the execution of DCL commands run in the context of a subprocess during the processing of the PRODUCT command.
Most EXECUTE statements in the PDF result in the execution of one or more DCL commands or entire command procedures. Depending on whether the INTERACTIVE option is used on the EXECUTE statement, these commands are run in one of the following ways:
In addition, the utility performs certain actions (such as library updates) by sending commands to a noninteractive subprocess. See Section 6.1 for more information about interactive and noninteractive modes of execution.
For interactive mode, the /TRACE qualifier logs the creation and deletion of the subprocess used to run the command, identifies the command line being executed, and displays the final exit status of the subprocess. Any output that DCL produces is displayed with or without the use of /TRACE.
For noninteractive mode, the /TRACE qualifier logs the creation and deletion of the subprocess used to run commands, identifies commands the utility sends to the subprocess to set up the environment, identifies commands sent from the EXECUTE statement, and displays the completion code of each command processed. It also directs the utility to send all mailbox output to the user's terminal.
Normally in noninteractive mode, the utility monitors all output from the subprocess and suppresses any output that does not appear to be an error message. However, use of the /TRACE qualifier directs the utility to display all output from the subprocess. This allows you to use SET VERIFY in command procedures that are run in noninteractive mode to have their commands echoed as they are executed. Also, you can insert WRITE SYS$OUTPUT commands to provide additional information for debugging. Specifically, the /TRACE qualifier does the following to log input and output for noninteractive mode:
6.3.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 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 intraproduct 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, we recommend 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 Version 7.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 nonzero 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, we strongly recommend 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.