HP OpenVMS Systems Documentation

POLYCENTER Software Installation Utility Developer's Guide

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.

6.3 Testing and Debugging Tips

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:

• /LOG qualifier
• /TRACE qualifier
• /DEBUG=CONFLICT 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:

• 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.3.2 The /TRACE Qualifier

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 an interactive subprocess created by LIB$SPAWN where input and output is directed to the user's terminal.
• In a noninteractive subprocess created by SYS$CREPRC where input and output is performed through mailboxes under the control and monitoring of the POLYCENTER Software Installation utility.

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:

• 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 noninteractive 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.

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

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