HP OpenVMS Systems Documentation

POLYCENTER Software Installation Utility Developer's Guide

5.5 Extracting Files from the Kit

You can extract one or more files from a product kit using the PRODUCT EXTRACT and PRODUCT COPY commands. The PRODUCT EXTRACT command is often used with the PRODUCT LIST command to identify a file or a set of files to extract.

5.5.1 Extracting Files by Name

With the PRODUCT EXTRACT FILE command, you can obtain a single file by name or a set of files with a wildcard file specification from a product kit. For example:

$ PRODUCT EXTRACT FILE CHESS /SELECT=*.EXE /LOG

The following product has been selected:
    ABC_CO AXPVMS CHESS V1.0               Layered Product

Do you want to continue? [YES]

Portion done: 0%
%PCSI-I-CREFIL, created DISK$WORK7:[TEST.KIT.][000000]CHESS.EXE;1
Portion done: 100%
%PCSIUI-I-SUCEXTRFIL, EXTRACT FILE operation completed successfully

5.5.2 Extracting the PDF, PTF, or Release Notes

You can extract the PDF, PTF, or release notes file by name. If you do not know their names, use the folowing EXTRACT commands:

PRODUCT EXTRACT PDF
PRODUCT EXTRACT PTF
PRODUCT EXTRACT RELEASE_NOTES

Every product kit contains a PDF. A PTF and a file designated as the release notes are optionally present in a kit.

The following example illustrates how to obtain the PDF from a sequential kit:

$ SET DEFAULT [TEST.KIT]
$ PRODUCT EXTRACT PDF CHESS /DESTINATION=[TEMP] /LOG

The following product has been selected:
    ABC_CO AXPVMS CHESS V1.0               Layered Product

Do you want to continue? [YES]

Portion done: 0%
%PCSI-I-CREFIL, created
DISK$WORK7:[TEMP.][000000]ABC_CO-AXPVMS-CHESS-V0100--1.PCSI$DESCRIPTION;1
Portion done: 100%

Product Description File has been extracted from the following product:
    ABC_CO AXPVMS CHESS V1.0               Layered Product
%PCSIUI-I-SUCEXTRPDF, EXTRACT PDF operation completed successfully

When you extract the PTF, the following two files are produced:

The output form of the PTF as a text library file
A recreation of the input form of the PTF as a sequential text file

$ PRODUCT EXTRACT PTF CHESS /LOG

The following product has been selected:
    ABC_CO AXPVMS CHESS V1.0               Layered Product

Do you want to continue? [YES]

Portion done: 0%
%PCSI-I-CREFIL, created
DISK$WORK7:[TEST.KIT.][000000]ABC_CO-AXPVMS-CHESS-V0100--1.PCSI$TLB;1
%PCSI-I-CREFIL, created
DISK$WORK7:[TEST.KIT.][000000]ABC_CO-AXPVMS-CHESS-V0100--1.PCSI$TEXT;1
Portion done: 100%
Product Text File has been extracted from the following product:
    ABC_CO AXPVMS CHESS V1.0               Layered Product
%PCSIUI-I-SUCEXTRPTF, EXTRACT PTF operation completed successfully

Use the PRODUCT EXTRACT RELEASE_NOTES command to examine any release notes file that may be present in the kit. This command always places the release notes (named DEFAULT.PCSI$RELEASE_NOTES) in the user's default directory.

$ SET DEFAULT [TEMP]
$ PRODUCT EXTRACT RELEASE_NOTES CHESS /SOURCE=[TEST.KIT]

The following product has been selected:
    ABC_CO AXPVMS CHESS V1.0               Layered Product

Do you want to continue? [YES]

Portion done: 0%...100%

5.5.3 Converting a Sequential Kit into Reference Format

You can use the PRODUCT COPY command to extract files from a kit in sequential format and place them in reference format. This differs in a number of ways from extracting all files from a sequential kit into a specific directory using the PRODUCT EXTRACT FILE command. When copying a kit into reference format, the files are placed in a directory tree as they would appear after installation on the user's system. Unlike the installation of a sequential kit, however, temporary files from the kit are placed in the directory tree and files pertaining to all options are extracted.

You can also use the PRODUCT COPY command to convert a reference kit into sequential format, and for copying a kit while preserving its format.

5.6 Displaying Information from the Product Database

After the product kit is installed, you can use the PRODUCT SHOW PRODUCT command to list the products installed on the system. Use the /FULL qualifier for additional information about software references and patches that may have been applied to the products. Additional commands (not shown here) that are useful for obtaining more information about installed products are the PRODUCT SHOW HISTORY /FULL and PRODUCT SHOW OBJECT /FULL commands.

$ PRODUCT INSTALL CHESS  ! /LOG and /TRACE are useful for debugging
.
.
.
$ PRODUCT SHOW PRODUCT
----------------------------------- ----------- ------------
PRODUCT                             KIT TYPE    STATE
----------------------------------- ----------- ------------
ABC_CO AXPVMS CHESS V1.0            Full LP     Installed
DEC AXPVMS DECNET_PHASE_IV V7.1     Full LP     Installed
DEC AXPVMS DWMOTIF V1.2-4           Full LP     Installed
DEC AXPVMS VMS V7.1                 Transition  Installed
----------------------------------- ----------- ------------

4 items found

Chapter 6
Advanced Topics

This chapter contains information about the following advanced POLYCENTER Software Installation utility concepts:

Using command procedures
Testing and debugging

In addition, it presents flow diagrams depicting the execution of several PRODUCT commands.

6.1 Using Command Procedures in PDL Statements

The Product Description Language (PDL) provides statements that perform common kit installation tasks such as creating directories, copying files to the target disk, updating libraries, displaying informational messages, and so on. There are times, however, when you might need to perform tasks that are unique to your product. For example, a new version of a product might need to detect the existence of a data file from a previous version and convert it to a new format. Or, you might want to probe the operating environment or ask the user specific questions before an installation may proceed.

To support this type of customization, the PDL provides several execute statements. These statements let you include command procedures (or individual DCL commands) that are run during certain phases of a product install, upgrade, reconfigure, undo patch, or remove operation. These statements are:

execute abort
Runs error recovery commands just before the utility exits when an error condition causes the operation to terminate. For example, the following will activate the execute abort statement:
- An error or fatal error condition that results from running commands from an execute statement (except execute test).
- The user terminates the operation by pressing Ctrl/Y or Ctrl/C.
- After an error is reported during material placement on the target disk, the user answers YES to the question "Do you want to terminate?".
execute install...remove
Runs commands during the execution phase when changes are made to the target disk (such as creating directories and moving files).
- The install portion is performed during an installation, upgrade, or reconfiguration of the product after product material has been moved from the kit to the target disk.
- The remove portion is performed during removal of the product before any files are deleted from the target disk.
execute login
Does not run any commands. It only displays a predefined message telling users to update their LOGIN.COM file with the specified commands.
execute postinstall
Runs commands that perform additional tasks at the end of the execution phase of an installation, upgrade, or reconfiguration of the product.
execute post_undo
Runs commands that perform additional tasks at the end of a patch kit removal in the UNDO PATCH operation.
execute preconfigure
Runs commands after the user has selected the product for installation, upgrade, or reconfiguration, but before the utility begins the configuration phase where the user is asked to select options for the product. If you need to run a command procedure in preparation for installing your product, consider using an execute preconfigure statement. This lets you embed preconfiguration work in the kit and relieves users of performing this task themselves.
execute pre_undo
Runs commands that perform additional tasks at the beginning of a patch kit removal in the UNDO PATCH operation.
execute start...stop
Runs commands during the execution phase.
- The start commands are executed during an installation or upgrade. In addition, a predefined message is displayed telling the user to add these commands to their SYSTARTUP_VMS.COM file.
- The stop commands are executed when the product is removed or upgraded. In addition, a predefined message is displayed telling the user to add these commands to their SYSHUTDWN.COM file whenever the product is installed, upgraded, or reconfigured.
execute test
Runs an installation verification procedure (or functional test of the product) after the installation has completed. Prior to running the test, the product database is updated and closed. The user can prevent the running of the installation verification procedure by specifying the /NOTEST qualifier with the PRODUCT INSTALL command.
execute upgrade
Runs commands when the product is upgraded by another version of the product. Commands are run before product material from the previously installed version of the product is deleted.
assemble execute option of a file statement
Runs commands that create the specified file in a scratch directory at execution time, then copies the file to the target disk. This replaces the usual process of extracting a packaged copy of the file from the kit. A typical use of the assemble execute option is to dynamically link an image at installation time.

Table 6-1 lists the PDL statements you can use to run command procedures (or individual DCL commands) that you provide. The statements are listed in the order of their execution during an installation, reconfiguration, or remove operation. Note that the table distinguishes between a new installation and an upgrade installation. The term upgrade denotes replacement of an installed version of a product by a higher, lower, or the same version of the product.

**Table 6-1 Command Procedure Execution by Operation**
PDL Statements Listed in the Order of Execution	PRODUCT INSTALL 1st Time	PRODUCT INSTALL Upgrade	PRODUCT RECONFIGURE	PRODUCT REMOVE
execute preconfigure	yes	yes	yes	no
execute ...stop	no	yes ¹	no	yes
execute ...remove	no	no	no	yes
execute upgrade	no	yes ¹	no	no
file statement using assemble execute	yes	yes	yes ²	no
execute install...	yes	yes	yes	no
execute start...	yes	yes	no	no
execute postinstall	yes	yes	yes	no
execute test	yes	yes	yes	no
execute login	no ³	no ³	no ³	no
execute start...stop	no ³	no ³	no ³	no
execute abort	yes ⁴	yes ⁴	yes ⁴	no

¹Only commands from the execute statement of the product being removed are run.
²The file is created only if the statement is part of a configuration option that the reconfiguration operation selects for the first time.
³The only action performed at this time is to display a message to the user.
⁴Commands from the execute abort statement are run only when an error condition causes the operation to terminate.

6.1.1 Noninteractive and Interactive Mode

The mode (noninteractive or interactive) in which an execute statement runs determines the following:

The type of subprocess used to run your command procedures (or individual DCL commands)
How a command procedure interacts with the user

By default, an execute statement runs in noninteractive mode. You can specify interactive mode with the interactive option. For example, the following command sets up a command procedure to run in interactive mode when the product is installed:

execute postinstall "@PCSI$DESTINATION:[SYSUPD]CONFIGURE.COM" interactive ;

In both noninteractive and interactive modes, the utility checks the final exit status of a command procedure (or individual DCL command) to determine whether or not the execute statement completed successfully or failed. Although error messages generated by a command procedure are displayed to the user, this does not determine its success or failure. The utility bases this decision solely on the final exit status. It is the kit developer's responsibility to ensure that proper status is conveyed to the utility upon termination of any command procedure incorporated into the kit.

The following table compares noninteractive and interactive mode.

**Table 6-2 Noninteractive Versus Interactive Mode**
Noninteractive Mode (default)	Interactive Mode
Used when you do not specify the interactive option	Used when you specify the interactive option
At the start of processing a PRODUCT command, the utility creates a detached subprocess using the $CREPRC system service. This subprocess is reused to run the commands from all of the execute statements specified to run in noninteractive mode. ¹	The utility creates a new subprocess using the LIB$SPAWN run-time library routine for each execute statement whose commands are to run interactively. All the commands specified for the same execute statement are performed, then the subprocess is terminated.
Interaction with the user is not possible. The utility communicates with the subprocess through mailboxes. It filters all output from the subprocess, only displaying lines of output to the user that resemble error messages (that is, lines beginning with a percent sign). All other lines of output are discarded.	Communication with the subprocess is performed through the user's terminal connection. The utility does not monitor input to or output from the subprocess. This enables a command procedure to enter into a dialog with the user (that is, display text and solicit responses from the user).
The utility obtains exit status from the value of the $STATUS symbol received in response to a SHOW SYMBOL $STATUS command it sends to the subprocess. Status is queried in this manner for each DCL command you specify in the execute statement (for example, "@a.com", "show symbol $status", "@b.com", "show symbol $status",...). If the command refers to a command procedure (for example, "@c.com"), status is checked only when the command procedure exits.	Exit status is obtained from the final status value returned from the LIB$SPAWN routine (the value of the $STATUS symbol from the last DCL command executed). Since a new subprocess is created for the execution of each command procedure (or individual DCL commands) you specify, the same level of status checking is performed for interactive mode as is done for noninteractive mode, although the technique is different.

¹The utility may also perform other actions in the same subprocess, such as the updating of libraries using the LIBRARIAN command.

6.1.2 Packaging a Command Procedure

You can package command procedure files that run from execute statements in two ways:

With a separate file statement
For most execute statements you can specify a command procedure in a file statement. For example:
file [SYSUPD]EXEC_PREC.COM; execute install "@PCSI$DESTINATION:[SYSUPD]EXEC_PREC.COM";
This causes the utility to copy the command procedure to the target disk and execute it from there. The command procedure remains on the target disk.
The technique of using a file statement cannot be used for the execute preconfigure statement because execute preconfigure is processed before files are copied to the target disk.
With the uses option
For most of the execute statements, you can specify a command procedure with the uses option (instead of using a file statement). For example:
execute install "@PCSI$SOURCE:[000000]EXEC_PREC.COM" uses [000000]EXEC_PREC.COM;
In this case, the utility extracts the command procedure from the kit and places it in a temporary directory (pointed to by the logical name PCSI$SOURCE) where it is executed. Afterwards, the command procedure is automatically deleted.
The uses option also lets you list additional files needed by the command procedure. For example, if you link an image during the installation, you can use the uses option to package required object files for the link operation. They are also placed in the temporary directory and deleted after the statement is processed.

Keep the following rules in mind:

Do not use a file statement and the uses option to specify the same file. Specifying both results in the file being packaged twice in the kit.
The uses option is not available for execute statements that are run when the product is removed (because the product kit is not referenced).
Do not use the uses option when the customer may run the command procedure at a later time (for example, a startup command procedure).

6.1.3 Logical Names for Subprocess Environments

In preparation for running command procedures (or individual commands) specified in execute statements, the utility defines up to three logical names:

PCSI$SOURCE
PCSI$DESTINATION
PCSI$SCRATCH

Command procedures use these logical names in the context of the subprocess in which they are run. The logical name environment differs depending on the execute statement being used. For more information, see the descriptions for individual execute statements in Chapter 7.

6.1.4 Execute Statement Summary

Figure 6-1 lists the execute statements and summarizes information about them.

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:

Configuration
Execution
Postprocessing

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.

Postprocessing Phase

During the postprocessing phase, actions such as running a functional test of the product or displaying informational messages to the user are performed. Since the postprocessing 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 postprocessing phase will not trigger an execute abort statement.

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