Updated: 11 December 1998

POLYCENTER Software Installation Utility Developer's Guide

This chapter contains descriptions of the individual product description language (PDL) statements and functions.

The conventions used in this chapter are described in the Preface. However, the syntax descriptions used 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.

The POLYCENTER Software Installation utility, hereinafter in this chapter called the utility, is an integrated component of OpenVMS Version 6.1 and later systems. The PDL statements and functions (and their parameters and options) described in this chapter are available beginning with OpenVMS Version 6.1, with the following exceptions:

New as of OpenVMS Version 7.1

• The with helptext option of the information and option statements
• The abort option of the error statement

If you use these features to package your product, your kit will require the version of the utility included in OpenVMS Version 7.1 and later.

New as of OpenVMS Version 7.1-2

• The execute abort statement
• The execute preconfigure statement
• The logical name function
• The interactive option of the following statements:
  • execute abort
  • execute preconfigure
  • execute install...remove
  • execute postinstall
  • execute release
  • execute start...stop
  • execute test
• The installed before, installed after, and kit accessible options of the software function
• The software function has been enhanced to detect whether or not a patch or mandatory update kit has been installed.
• The version above option of the following statements:
  • apply to
  • software (and software function)
  • upgrade (and upgrade function)
• The logical name environment for the execution of command procedures specified in execute statements has been enhanced. For example, the definition of PCSI$DESTINATION for the execute test statement is new.

If you use these features to package your product, your kit will require the version of the utility included in OpenVMS Version 7.2 and later.

The account statement uses a command procedure to create a system account.

Syntax

account name with (parameters,...) ;

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

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 mandatory update or patch kit.

Note You must include an apply to statement in a mandatory update or patch PDF to identify the product that is being patched or updated. This statement is not valid in other types of PDFs.

Syntax

apply to producer base name
[ { version above version |
version below version |
version maximum version |
version minimum version |
version required version |
version above version version below version |
version above version version maximum version |
version minimum version version below version |
version minimum version version maximum version } ] ;

Parameters

producer

Indicates the legal owner of the software product. This parameter must be a single quoted or 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 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 unquoted string. The combination of producer, base, and name parameters must be unique among products installed on the system.

Options

version above version

Indicates an invalid product version. Use this option to specify that the product version must be more than (but not equal to) the specified version. You cannot use this option with either the version minimum or version required options. By default, there is no largest invalid version.

version below version

Indicates an invalid product version. 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 options. By default, there is no smallest invalid version.

version maximum version

Indicates a maximum product version that must be available. 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 options. By default, there is no maximum version.

version minimum version

Indicates a minimum product version that must be available. 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 required or version above options. By default, there is no minimum version.

version required version

Indicates a required product version that must be available. Use this option to specify that a specific product version must be present. You cannot use this option with either the version above, version below, version maximum, or version minimum options. By default, there is no required version.

Description

The apply to statement specifies which versions of another product must be available for a valid installation operation. You can use options to this statement to define above, below, maximum, minimum, and required version constraints.

If your product references another product with an apply to statement, the referenced product will be installed earlier than, and removed later than, your product. If two or more products reference each other (creating a circular dependency loop), the utility issues an error message.

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

Example

product DEC VAXVMS CSCPAT57 V1.0 patch ; 
    apply to DEC 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 DEC Fortran. As shown in the apply to statement, you must have DEC Fortran Version 2.0 installed to apply this patch.

The bootstrap block statement specifies the file that the bootstrap block references.

Syntax

bootstrap block name image source ;

Parameters

name

Indicates the bootstrap file specification. You must define the file you specify in the same product description (with a file statement). You must also ensure that the file has bootstrap scope and product or assembly lifetime (using the scope statement).

image source

Indicates the file specification of the file that contains the bootstrap block image. The referenced file must be defined in the same product description (with a file statement), and it must also have product scope and product lifetime.

Description

The bootstrap block statement specifies the file that the bootstrap block references. You specify the name of the file as the name parameter.

The bootstrap block statement also specifies a bootstrap block managed object that has the following characteristics:

• It is unnamed and unique within the bootstrap scope.
• It has operating lifetime and bootstrap scope.
• Managed object conflict is not recoverable.

Example

scope bootstrap; 
  file [sysexe]vmb.exe; 
end scope; 
file [sysexe]bootblock.exe; 
   .
   .
   .
bootstrap block [sysexe]vmb.exe image [sysexe]bootblock.exe ; 
 
      

This example uses the bootstrap block statement to point the bootstrap block to the bootstrap file ([SYSEXE]VMB.EXE).

The directory statement creates the specified directory if it does not already exist.

Syntax

directory name
[ [no] access control (access-control-entry...) ]
[ owner name ]
[ protection { execute | private | public } ]
[ [no] version limit maximum ] ;

Parameter

name

Indicates the directory name.

Options

[no] access control (access-control-entry...)

Indicates the minimum access control entries (ACEs) that the directory will have. You must specify the ACEs as a quoted string. By default, directories have no added ACEs.

owner name

Indicates the account name that owns the directory. By default, the directory is owned by the SYSTEM account. If you specify a numeric value for name, you must enclose the string in quotation marks; for example "[11,7]".

protection execute

Sets the directory protection to (S:RWE, O:RWE, G:E, W:E) so that users have execute access.

protection private

Sets the directory protection to (S:RWE, O:RWE, G, W) so that users have no access.

protection public

Sets the directory protection to (S:RWE, O:RWE, G:RE, W:RE) so that users have read and execute access. This is the default.

[no] version limit maximum

Indicates the maximum number of file versions in the directory as an unsigned integer from 1 through 32767. The default is no version limit.

Description

The directory statement creates the specified directory if it does not already exist.

The directory statement specifies the name of a directory managed object. Check the other statements in your PDF to make sure the name you specify is unique among all directory, file, and link managed objects in all scopes.

The scope and lifetime of the directory managed object depend on whether it is lexically contained in a scope, end scope pair, as shown in Table 7-1. (See Chapter 6 for details about managed object scope and lifetime.)

Table 7-1 Directory Managed Object Scope and Lifetime

Type of Scope Group	Lifetime	Scope
Product	Product	Product
Global	Assembly	Global
Bootstrap	Operating	Bootstrap
Processor	Operating	Processor

If you use the access control option, the directory statement specifies one access control entry (ACE) managed object that references the directory managed object for each entry specified with the access control option. The ACE managed object has the following characteristics:

• It is unnamed.
• It has operating lifetime.
• It has the same scope as the directory.

Examples

directory [SYSHLP.EXAMPLES.FMS.MESSAGE] protection private 
     access control ("(IDENTIFIER=[FMS], ACCESS=READ)"); 
 
      

This example specifies the directory [SYSHLP.EXAMPLES.FMS.MESSAGE]. The protection private option specifies that no users have access to this directory. The access control option grants the user FMS read access to the directory.

directory [AL] owner PCSI$TEST version 3; 
      

In this example the directory [AL] is owned by the account PCSI$TEST and holds the maximum of three file versions.

directory [JIM] owner "[11,7]"; 
      

This example specifies the directory [JIM] owned by the account whose UIC is [11,7].

Ends a group of statements. For more information, see the corresponding opening statement.

Syntax

end
{ if |
option |
part |
product |
remove |
scope } ;

The error statement displays an error message during an installation or reconfiguration operation. The text is from a PTF text module.

Note The error statement must be contained within an if group.

Syntax

error name [ abort ] ;

Parameter

name

Indicates, as a quoted or unquoted string, the name of the associated PTF text module. The name you specify can be from 1 to 31 characters in length and must be unique among all names in the same product description.

Option

abort

Forces an unconditional termination of the operation. See Section 7.1 for usage constraints.

Description

The error statement specifies a text module you want to display during an installation or reconfiguration operation. The error statement must be contained within an if group.

The utility processes error statements in lexical order. The utility displays both prompt and help text during the validation phase (which follows the configuration phase).

During execution of an error statement that does not contain an abort clause, the utility prompts the user to continue or terminate the operation. If the abort clause is present, or the operation is not executed interactively, the error statement causes the operation to terminate unconditionally.

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

You must supply text in the associated product text module. The module must contain a =prompt directive line.

Examples

1. Suppose the product description file contains the following lines:

   if (<hardware processor model 7>) ; error UNSPROC ; end if ;

   
   The corresponding module in the PTF could contain the following lines:

   1 UNSPROC =prompt Not supported on MicroVAX I. This product is not supported on the MicroVAX I processor.

   
   If the processor model is 7, the system displays the following message:

   Not supported on MicroVAX I. This product is not supported on the MicroVAX I processor. Terminating is strongly recommended. Do you want to terminate? [YES]

2. You can also include text for the presence of certain software and issue an error message if it is missing:

   if (not <software DEC AXPVMS UCX>); error NOUCX; end if;

   
   The corresponding module in the PDF could contain the following lines:

   1 NOUCX =prompt No UCX software on your system. This product cannot be used without the UCX software. Please terminate this operation, install UCX, then install this product.

   
   If the UCX software is not present in the POLYCENTER Software Installation utility database during the installation of your product, the system displays the following message:

   No UCX software on your system. This product cannot be used without the UCX software. Please terminate this operation, install UCX, then install this product. Terminating is strongly recommended. Do you want to terminate? [YES]

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5952PRO_006.HTML