HP OpenVMS Systems Documentation

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:

• /LOG qualifier
• /TRACE qualifier
• /DEBUG=CONFLICT qualifier

When you want to verify that the contents of your product kit either have been placed in the proper directories or correctly deleted, use 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:

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

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:

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

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.

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

This chapter describes the individual Product Description Language (PDL) statements and functions.

7.1 PDL Evolution

The POLYCENTER Software Installation utility is an integrated component of OpenVMS Version 6.1 and later. After its introduction, subsequent releases of the OpenVMS operating system have incorporated various enhancements to PDL statements and functions. It is likely that we will make further enhancements over time.

Earlier versions of the OpenVMS operating system do not support the new utility features provided in later versions of the operating system. This creates a challenge for the developer who must devise a kit that will install as expected in a variety of customer environments.

You can write a product description file based on the earliest version of OpenVMS at your customer sites. If you choose this approach, you must have or acquire knowledge about customer environments. It means you can use only the statements and functions (and their parameters and options) available for the earliest customer installed version of OpenVMS.

Table 7-1 and Table 7-2 let you quickly see when new utility features were made available. Note that bug fixes are not shown unless they impact the behavior of the utility. For more information on a specific feature, see the appropriate section in this manual.

<bootstrap block\\\Obsolete: not available for layered products)

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.

7.1.0.1 Software Patch Kit Locations on the Internet

• VAX 6.2 through VAX 7.1
• VAX 7.2
• Alpha 6.2 through Alpha 7.1-2
• Alpha 7.2
• Alpha 7.2-1

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:

• Brackets ([ ]) indicate optional elements. You can choose one, none, or all of the options.
• Braces ({ }) indicate a required choice of options; you must choose one of the options listed.
• The vertical bar (|) separates optional elements. It functions as a logical OR between two options, as in A | B , or A | B | C .
• Horizontal ellipsis points ( ... ) in examples indicate that the preceding item or items can be repeated one or more times, or that additional parameters, values, or other information can be entered.
• The semicolon (;) in syntax diagrams is required syntax.
• Angle brackets (<>) in syntax diagrams are required syntax.
• A double hyphen (- rest of the line is a comment.
• Unless otherwise indicated, extra space and tab characters may be used freely between syntax elements for the purposes of formatting and readability.
• A statement may span more than one line.

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.

Syntax

Parameters

name

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

Description

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:

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

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

Example

account TEST with ("/priv=(tmpmbx, netmbx)",(1) "PCSI_TEST",(2) "/account=PCSI",(3) "/astlm=500/biolm=200/bytlm=96000", "/wsdefault=4000", "/flags=(nodisuser,genpwd)", "/pwdminimum=8");

In this example, the account statement creates the TEST account.

1. Parameter P2 specifies the TMPMBX and NETMBX privileges to be assigned to the TEST account.
2. Parameter P3 is a rights identifier. This name must exist on the system prior to executing the account statement. It can be created with a rights identifier statement.
3. Parameters P4 to P8 assign certain values to 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.

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

Syntax

Parameters

producer

Indicates the legal owner of the software product. This parameter must be a single quoted or an unquoted string.

base

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

name

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

Options

version above version

Establishes 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 version

Establishes 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 version

Establishes 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 version

Establishes 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 version

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

Description

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.

The apply to statement is a utility directive and does not specify a managed object.

Example

product HP VAXVMS CSCPAT57 V1.0 patch ;
    apply to HP VAXVMS FORTRAN version required V2.0 ;
    patch image [SYSEXE]FORTRAN.EXE with [000000]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.