POLYCENTER Software Installation Utility Developer's
2.6.2 Managed Object Conflict
Occasionally, your product will supply a managed object that conflicts
with another managed object. For example, if you supply a file called
FOO.TXT and a file by that name was also provided (in the same
directory) by another product, a conflict occurs. The existing file
will be overwritten under the following circumstances:
- If it was provided by an earlier instance of your product.
- If it was not created by the PRODUCT command. (It is not a managed
object in the product database.)
However, if the file is a managed object identified in the product
database, and is owned by some other product, it might not be
appropriate to replace it.
The following two types of managed object conflict can occur:
- An inter-product conflict occurs when two or more
products provide an object with the same name in the same directory.
(Files with the same name can coexist in different directories.)
- An intra-product conflict occurs when two or more
patch or partial kits for a product update the same object.
When the utility detects conflict, it displays an informational
message. The following statements detect managed object conflict and
display informational messages:
2.6.3 Preventing Managed Object Conflict
In some cases, the POLYCENTER Software Installation utility allows you
to anticipate and resolve conflict before it occurs. The following
statements provide some level of conflict resolution:
Managed object conflict is resolved differently depending on what type
of object is involved. The description of these statements in
Chapter 7 indicates how each one resolves managed object conflict.
For example, some statements provide a generation
option that lets you assign a generation number to an object. During
installation, if the utility attempts to create an object that already
exists, it compares the generation numbers of the objects, selecting
the object with the highest generation number.
When two or more products provide the same file or module, the one with
the highest generation number must implement a superset of the
capabilities found in the objects having lower generation numbers. This
is required so that all products installed that use this object will
continue to function properly.
When one of these products is removed, the POLYCENTER Software
Installation utility retains the object with the highest generation
number and reassigns the ownership of the object to the product
remaining on the system.
Thus, when products update one or more objects in common (indirectly
modify each other), removal of one product might result in not
restoring the other product to its former state. This is because the
objects with the highest generation numbers are left on the system.
For example, the product description files for products TEST1 and TEST2
are as follows:
product CPQ AXPVMS TEST1 V1.0 full;
file [SYSEXE]TEST.EXE generation 100;
product CPQ AXPVMS TEST2 V1.0 full;
file [SYSEXE]TEST.EXE generation 200;
If you first install product TEST1 and then install TEST2, file
TEST.EXE with generation number 200 will supersede the previously
installed file TEST.EXE with generation number 100. However, if you
subsequently remove product TEST2, the utility will retain generation
200 of file TEST.EXE and list product TEST1 as its owner. It is assumed
that the file having the higher generation number is a functional
superset of the file with the lower generation number and thus product
TEST1 will continue to work properly. To restore product TEST1 to its
original state, you will need to re-install it. This will remove all
files installed associated with the product and replace them with files
from the kit.
2.6.4 Managed Object Replacement and Merging
As described in Section 2.6.2, managed objects occasionally have
characteristics that conflict with each other. The POLYCENTER Software
Installation utility handles this situation differently depending on
the kit type:
- When upgrading a product using a full operating system or platform
kit, the utility deletes the existing object and replaces it with the
object and characteristics provided by the new version of the product.
- When upgrading a product using a partial kit or modifying a product
using a patch or mandatory update kit, the utility preserves the
characteristics of existing objects. For example, the security
environment you establish for your product is preserved when you
install a partial, patch, or mandatory update kit.
If you want to provide new characteristics for a managed object in a
partial, patch, or mandatory update kit, use the remove
statement to delete the existing object and then respecify the object
with the desired characteristics.
For more information about kit types, see Table 2-2.
2.6.5 Managed Object Scope and Lifetime
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 utility usually ensures that managed objects have the
Occasionally, you might need to use the scope statement to
give a managed object a scope other than its default. For more
information about specifying the scope of a managed object, refer to
the description of the scope statement in Chapter 7.
2.7 Creating a Platform (Product Suite)
In addition to packaging individual products, the POLYCENTER Software
Installation utility gives you the means to assemble integrated
platforms. An integrated platform is a combination of several
products, such as a suite of complementary management products that you
might bundle together.
Functionally, a platform is the same as a full kit, except that it has
the designation "PLATFORM." A platform is intended to
reference other products, but it can also supply files.
Figure 2-2 shows an example of an integrated platform.
Figure 2-2 Integrated Platform Example
To package a platform, you create a platform PDF and
platform PTF. In addition to other statements, the
platform PDF contains software statements that specify the
products that make up the platform. The individual products have their
own PDFs and PTFs (independent of the platform PDF and PTF). For more
information about platform PDFs, see Section 3.5.3.
Creating the Product Description File
The product description file (PDF) is a required component of any
software product kit that you create using the POLYCENTER Software
Installation utility. The PDF does the following:
- Specifies all files that make up the product.
- Identifies configuration options that are presented to the user at
- Specifies any dependencies the product may have on other software
- Defines various actions that must be performed during installation.
3.1 General Guidelines
The POLYCENTER Software Installation utility is intended to simplify
the job of system managers, making products quick and easy to install
and manage. Use the following guidelines when writing PDFs:
- Minimize installation activity (such as linking images and building
databases). Instead, include all material required for product
execution on the reference.
- Make your products adapt to the target environment at execution
time rather than installation time. This practice keeps products
consistent across varying configurations.
- Avoid requiring system parameter settings on the target system that
would require rebooting the system.
- Minimize configuration choices at installation time.
- Ensure that the PDF expresses all the known requirements that your
product needs to execute. Use the checklist in Section 3.2 to define
the requirements for the target environment.
3.2 Defining Your Environment
To define the environment for your product, use the following
checklist. (Chapter 7 of this guide describes each PDL statement.)
- Does your product depend on other software?
For example, your product may require a specific version of the
operating system or optional software products. To express these
software requirements, use the software function or statement.
Note the distinction between the software statement and the
software function. The statement and function serve different
purposes and are not interchangeable.
statement specifies a software product that should be installed on the
system to satisfy a software product dependency. It also specifies a
software product that is a part of a platform (product suite) and
should be included in the platform product installation.
software function tests for the presence of a product. You can
also specify the version of the product that must be present. The
software function, unlike the software statement,
does not create a permanent software reference to another product and
does not force the installation of the other product.
Note that software you reference with a software
statement must be registered in the product database to be recognized
by the POLYCENTER Software Installation utility. If you install a
product using a mechanism other than the POLYCENTER Software
Installation utility, the product database will not contain information
about the product unless you register it using a full or transition
PDF. For more information about creating transition product
descriptions, see Section 3.5.7.
- If you are creating a platform, what software products make
up the platform?
If you are creating a platform, you must
specify the software products that make up the platform. To specify the
products that make up your platform, use the software
statement with the component option.
- Does your product require specific hardware
For example, your product may require that the
system have access to certain peripheral devices, such as a compact
disc drive or printer. To display a message to users expressing these
hardware requirements, use the hardware device statement.
- Does your product run only on specific computer
Some products run only on certain computer models.
For example, recent versions of the OpenVMS operating system are no
longer supported on the VAX--11/725 computer. If this is the case with
your product, use the hardware processor statement to display
a message to users.
- Does your product require specific images, files, or
All the files, images, and directories that
your product requires should be expressed in file or
- Does your product require a special account on the
Some products require a dedicated account on the
system. Use the account statement to supply the account.
- Does your product require network objects?
Some products require network objects on the system. If your object is
designed for DECnet Phase IV, use the network object statement
to supply the required network objects. For DECnet-Plus you might want
to use a different mechanism. For example, supply an NCL script with a
PDL file statement.
- Do you want to set up rights identifiers?
the rights identifier statement.
- Does your product supply an image to the system loadable
Use the loadable image statement.
- Does your product have several options that the user can
Although it is a good practice to limit the number
of user options, you may need to present the user with options during
installation. To present options to the user, use the option
- Do you need to patch an executable image?
the patch image statement (VAX only).
- Do you need to patch a text file?
patch text statement.
- Does your product have specific security
If the files and directories for your
product require special protection or access controls, you can express
this in the product description. See the descriptions of the
directory statement and the file statement. You can
also supply a rights identifier using the rights identifier
- Does your product require certain values for system
Many software products require that system
parameters have certain values for the product to function properly.
Use the system parameter statement to display system parameter
requirements to users.
- Does your product require certain values for process
Use the process parameter statement
to display these requirements to users.
- Does your product require certain values for process
Use the process privilege statement
to display these requirements to users.
- Do you want to include a functional test with your
You can include it in the product material to
verify that your product installed correctly. To execute the functional
test for your product, use the execute test statement.
- Are there commands that your installation procedure needs
to execute that are outside the domain of the POLYCENTER Software
Use the execute statement.
- Does your product have specific pre- or postinstallation
You can use the POLYCENTER Software Installation
utility to automate these tasks; however, there may be some tasks you
want users to perform that are outside the capabilities of the utility.
You can inform users of such tasks using the information
statement. You can also use several of the execute statements
to perform these tasks.
- Does your product require command, help, macro, object, or
text library modules?
You should express the following
types of modules in your PDF:
- DIGITAL Command Language (DCL) command definition modules
- DCL help modules
- Macro modules
- Object modules
- Text modules
You can express these types of modules using the module
- What happens to existing product files?
should make sure that your product's files are handled correctly during
an installation or upgrade. The POLYCENTER Software Installation
utility deletes obsolete files that are replaced when you install a
full, operating system, or platform kit. In partial, patch, and
mandatory update kits, the existing files are preserved. To remove
obsolete files, use the remove statement and file
- Does your product require documentation?
may want to include online documentation (such as release notes) with
your product. To express the documentation requirements for your
product, use the release notes option to the
3.3 PDF File Naming Conventions
You supply the PDF as input to the PRODUCT PACKAGE command. The PDF can
have any valid OpenVMS file name and file type. Compaq recommends that
you give the input PDF file the extension .PCSI$DESC. For example:
When you execute the PRODUCT PACKAGE command, it creates an output PDF.
(See Section 2.3.8 for the distinction between input and output files.)
The output PDF file format is the same as the input PDF; that is, a
sequential file containing PDL statements. The contents of the output
PDF, however, may differ slightly from that of the input PDF. For
example, the POLYCENTER Software Installation utility adds the size
option to every file statement and supplies the actual size of
the file in disk blocks.
The name of the output PDF consists of the product's stylized file name
and a file type of .PCSI$DESCRIPTION:
For example, the output PDF for product BLACKJACK V2.1-17 might be
See Section 2.3 for a description of the product naming syntax.
3.4 Structure of a PDF
A PDF is a text file that contains a sequence of PDL statements. A PDF
must begin with a product statement and end with an
end-product statement. The product statement uniquely
identifies the product and specifies the type of kit to build (full,
partial, patch, and so forth). Each file that is part of the product
material must be specified with a file statement. The
following example shows a complete PDF for a product that places one
file named test.exe in SYS$COMMON:[SYSEXE].
product DEC axpvms test v1.0 full ;
file [sysexe]test.exe ;
end product ;
3.4.1 Overview of PDL Statements
The product description language consists of statements that are
defined in Chapter 7 of this manual. As an overview, these
statements are listed below in classes according to their main function.
- Statement groups are defined by a pair of opening and closing
statements; by convention the closing statement is the keyword
end followed by the keyword of the opening statement.
Statement groups operate on statements lexically contained within their
begin-end pair. Many statement groups can be nested within other
The following statement groups are used to conditionally
process other statements:
- if and
end if (else and else if statements
optionally can be used within the statement group). Used to evaluate
the Boolean value of a statement function or expression as a condition
to process enclosed statements or a group of statements.
and end option.
The following statement groups unconditionally process all
statements at their inner level:
- Statements that create or modify managed objects include:
- Statements that enforce software dependencies and hardware
requirements by testing the execution environment and taking
appropriate action include:
- Statements whose main purpose is to display a message to the user
and in some cases query the user for a response are as follows:
- Statements that cause producer-supplied command procedures to
execute or instruct the user to manually perform a task include:
- Statement functions that are used to provide a Boolean value when
evaluated in the expression part of an if statement:
- <hardware device>
- <hardware processor>
- <logical name>
Many software products require only the use of a small subset of these
PDL statements to create their PDF. Commonly used statements are as