HP OpenVMS Systems Documentation
POLYCENTER Software Installation Utility Developer's Guide
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 qualifier 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 noninteractive 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 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.
|PDL Statements||OpenVMS V7.1||OpenVMS V7.1-2(Alpha)
|apply to||New option: version above|
|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 intraproduct 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 intraproduct 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 HP, 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.
22.214.171.124 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. 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. If there are no qualifiers to pass, specify a null string (" "). 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.
In this example, the account statement creates the TEST account.
The apply to statement specifies a product or product version that you want to update with a patch or mandatory update kit.
You must include an apply to statement in a patch or mandatory update PDF to identify the product that is being updated. This statement is not valid in other types of PDFs.
producerIndicates the legal owner of the software product. This parameter must be a single quoted or an unquoted string.
baseIndicates the base hardware/software system on which the product is intended to be installed. This parameter must be a single quoted or an unquoted string. By convention, the string AXPVMS denotes an OpenVMS Alpha product, VAXVMS denotes an OpenVMS VAX product, and VMS denotes a product applicable for either OpenVMS Alpha or VAX.
nameIndicates the name of the product. This parameter must be a single quoted or an unquoted string. The combination of producer, base, and name parameters must be unique among products installed on the system.
version above versionEstablishes a lower version limit. The version identifier must be a single quoted or an unquoted string. Use this option to specify that the product version must be greater than (but not equal to) the specified version. You cannot use this option with either the version minimum or version required option. By default, there is no lower version limit.
version below versionEstablishes an upper version limit. The version identifier must be a single quoted or an unquoted string. Use this option to specify that the product version must be less than (but not equal to) the specified version. You cannot use this option with either the version maximum or version required option. By default, there is no upper version limit.
version maximum versionEstablishes an upper version limit. The version identifier must be a single quoted or an unquoted string. Use this option to specify that the product version must be less than or equal to the specified version. You cannot use this option with either the version below or version required option. By default, there is no upper version limit.
version minimum versionEstablishes a lower version limit. The version identifier must be a single quoted or an unquoted string. Use this option to specify that the product version must be greater than or equal to the specified version. You cannot use this option with either the version above or version required option. By default, there is no lower version limit.
version required versionEstablishes a required version. The version identifier must be a single quoted or an unquoted string. Use this option to specify that the product version must be equal to the specified version. You cannot use this option with either the version above, version below, version maximum, or version minimum option. By default, there is no required version constraint.
The apply to statement specifies the name of an installed product that a patch or mandatory update kit modifies. You can use options on this statement to limit the application of the patch or mandatory update either to a specific version of the product or to a range of versions. If you do not use version constraints, then you can modify any version of the product by installing a patch or mandatory update kit.See Also product
The apply to statement is a utility directive and does not specify a managed object.
product HP VAXVMS CSCPAT57 V1.0 patch ; apply to HP VAXVMS FORTRAN version required V2.0 ; patch image [SYSEXE]FORTRAN.EXE with CSCPAT57.PAT ; end product ;
This example shows part of the product description for a patch to HP Fortran. As shown in the apply to statement, you must have HP Fortran Version 2.0 installed to apply this patch.