[Digital logo]
[HR]

POLYCENTER Software Installation Utility Developer's Guide


Previous | Contents

The Package command is documented in the OpenVMS System Management Utilities Reference Manual.


Chapter 6
Advanced PDF Concepts

This chapter contains information about some advanced PDF concepts such as managed object scope and lifetime.

6.1 Defining the Scope of a Managed Object

The scope of a managed object defines the degree of sharing that the managed object permits. For example, some objects are available only to certain processes, and some can be shared by all processes. The POLYCENTER Software Installation utility usually ensures that managed objects have the correct scope.

You might need to give a managed object a scope other than its default. Using the scope statement, you can ensure that the managed object is placed in the correct area on the system and that processes that need to can access it.

This section describes the different scopes that managed objects have:

6.2 Updating Files

When you update your product with a partial, patch, or mandatory update kit, you can either explicitly state the scope of the file managed objects you are updating or let the utility determine the scope of the file managed objects:

If you use the patch statement, the object you are updating must have been provided by your product. If you use the module statement, the object you are updating either must have been provided by your product or must be in global or bootstrap scope.

6.3 Managed Object Lifetimes

The lifetime of a managed object defines the duration or time period in which the managed object exists. For example, some managed objects are created each time a product is started; others are created before the product starts.

This section lists the lifetimes that a managed object receives as a result of its scope:


Chapter 7
Product Description Language Statements

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:

7.1 A Word About Using New Features

The POLYCENTER Software Installation 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:

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


account

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:

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 POLYCENTER Software Installation utility uses a command procedure (SYS$UPDATE:PCSI$DELETE_ACCOUNT.COM) to delete accounts associated with your product.


Note

In a future version, the POLYCENTER Software Installation 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:

See Also rights identifier

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.

apply to

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 below version |
version maximum version |
version minimum version |
version required version |
version minimum version version below version |
version minimum version version maximum version } ] ;


PARAMETERS

producer

Indicates the legal onwer of the software product. This paramater 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 paramater 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 paramater 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 below version

Indicates the smallest 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 the version required option. 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 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 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.

See Also product
software
upgrade

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.


bootstrap block

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:

See Also file
scope

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 thebootstrap block statement to point the bootstrap block to the bootstrap file ([SYSEXE]VMB.EXE).


directory

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:

See Also scope

Examples

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

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

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

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


end

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

Syntax

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

;

error

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 POLYCENTER Software Installation 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.

See Also hardware device
hardware processor
if
software

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] 
    

execute install...remove

The execute install statement specifies commands that you want to execute when the product is installed. The remove part of the statement indicates commands you want to execute when the product is removed from the execution environment, or is upgraded to a new version of the product.

Note

The remove part of the statement is required even if there are no commands you want to execute when the product is removed. To indicate no command, use remove "".


Syntax

execute install (command,...) remove (command ,...) [uses (file,...) ] ;


PARAMETER

(command,...)

Indicates the command that the POLYCENTER Software Installation utility passes to the command interpreter in the execution environment.

OPTION

uses (file,...)

Indicates the files required to execute the commands you specified in the command parameter. Use a separate file statement to specify required files that are permanently placed in the user's destination directory tree; use the uses option to specify required files that are placed in a temporary directory and deleted after use. By default, this statement does not require files.

DESCRIPTION

The execute install...remove statement specifies commands that you want to execute when the product is installed. The remove part of the command indicates commands that execute when the product is removed from the execution environment. You specify actions by entering a command line, which the utility passes to the DIGITAL Command Language (DCL) interpreter running in a subprocess.

Enclose each action, whether specified as a single DCL command or a command procedure, in double quotes (" "). If more than one action is listed, use parentheses.

The scope statement controls the execution of the commands; the commands execute once in each scope.

If you need files for the execute install statement, specify them in the uses option or in separate file statements. However, if you need files for the execute remove statement, they must be specified in separate file statements. Each file you specify with the uses option must be present in the product material.

Note that the uses option will not cause the listed files to be placed permanently in your file system. As soon as the installation operation completes, the files listed with the uses option are deleted. For this reason, you must use the file statement for this execute operation, and any other operation, in which you want your execute command procedures placed permanently in your file system.


Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]

[HR]

  5952P003.HTM
  OSSG Documentation
   3-DEC-1996 08:58:44.77

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal