|
|
Updated:
11 December 1998
|
POLYCENTER Software Installation Utility Developer's
Guide
2.9 A Word About Input and Output Versions of Files
Although you provide the product description file (PDF) and product
text file (PTF) as input to the package operation, they also exist in
modified (output) form in the kit you create. You need to be aware that
two versions of these files do exist and perform specific tasks.
Basically, you create the input version as input to the package
operation, and the POLYCENTER Software Installation utility creates the output version for its own
use.
The package operation changes the format of the output PTF file. For
more information, see Section 4.2.
The output PDF is in the same format as the input PDF, but the package
operation may modify statements in the output PDF. For example, the
package operation adds the size option to
file statements in the output PDF.
Chapter 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:
- Specifies all files that comprise the product.
- Identifies configuration options that are presented to the user at
installation time.
- Specifies any dependencies the product may have on other software
products.
- 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 copy.
- 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
Please take note of the distinction between the software
statement and the software function. The statement and
function serve different purposes and are not interchangeable. The
software 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.
The 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 does not store information
about the product unless you register a full or transition
product description. For more information about creating
transition product descriptions, see Section 3.5.7.
- If you are creating a platform, what software products
comprise the platform?
If you are creating a platform, you
must specify the software products that make up the platform. To
specify the products that comprise your platform, use the
software statement with the component option.
- Does your product require specific hardware
devices?
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
models?
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
directories?
All the files, images, and directories that
your product requires should be expressed in file or
directory statements.
- Does your product require a special account on the
system?
Some products require a dedicated account on the
system. If this is the case for your product, use the account
statement to supply the account.
- Does your product require network objects?
Some products require network objects on the system. If this is the
case for your product, and your object is designed for DECnet Phase IV,
use the network object statement to supply the required
network objects. For DECnet-Plus (Phase V) 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?
If
you want to set up rights identifiers for your product, use the
rights identifier statement.
- Does your product supply an image to the system loadable
images table?
To supply an image to the system loadable
images table, use the loadable image statement.
- Does your product have several options that the user can
choose?
Although it is a good practice to limit the number
of options that the user can choose, you may need to present the user
with options during installation. To present options to the user, use
the option statement.
- Do you need to patch an executable image?
To
patch an executable image, use the patch image statement (VAX
only).
- Do you need to patch a text file?
To patch a
text file, use the patch text statement.
- Does your product have specific security
requirements?
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
statement.
- Does your product require certain values for system
parameters?
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
parameters?
If your product requires certain values for
process parameters, use the process parameter statement to
display these requirements to users.
- Does your product require certain values for process
privileges?
If your product requires certain process
privileges, use the process privilege statement to display
these requirements to users.
- Do you want to include a functional test with your
product?
If you have a functional test for your product,
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
Installation utility?
If you have commands that your
installation procedure needs to execute that have no POLYCENTER
Software Installation utility equivalent, use the execute
statement.
- Does your product have specific pre- or postinstallation
tasks?
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
statement.
- What happens to existing product files?
You
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
statement options.
- Does your product require documentation?
You
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
file statement.
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.
When you execute the PRODUCT PACKAGE command, it creates an output PDF.
(See Section 2.9 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:
producer-base-product-version-kit_type.PCSI$DESCRIPTION.
|
For example:
ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.PCSI$DESCRIPTION
|
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 vaxvms 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
groups.
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 a Boolean value of a function or expression as a condition to
process enclosed statements or a group of statements.
- option and end option
The following statement groups unconditionally process all
statements at their inner level:
- part and end part
- product and end product
- remove and end remove
- scope and end scope
- Statements that create or modify managed objects include:
- account
- bootstrap block
- directory
- file
- link (create an alias directory entry)
- loadable image
- module
- network object
- patch image
- patch text
- register module
- rights identifier
- Statements that enforce software dependencies and hardware
requirements by testing the execution environment and taking
appropriate action include:
- apply to
- hardware device
- hardware processor
- infer
- software
- upgrade
- 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:
- error
- information
- process parameter
- process privilege
- system parameter
- Statements that cause producer-supplied command procedures to
execute or instruct the user to manually perform a task include:
- execute abort
- execute install...remove
- execute login
- execute postinstall
- execute preconfigure
- execute release
- execute start...stop
- execute test
Many software products require only the use of a small subset of these
PDL statements to create their PDF. Commonly used statements are as
follows:
- product and end product (required in every PDF)
- file
- directory
- module
- software
- option and end option
- if and end if
- execute install...remove
- execute test
3.4.2 PDL Statement Syntax
A PDL statement consists of:
- A keyword phrase that identifies the statement (required).
- Zero or more parameter values (which may be expressions in certain
contexts).
- Zero or more options each specified as a keyword phrase and value
pair.
- A semicolon (;) that terminates the statement (required).
Additional Syntax Rules
- Statements can span multiple lines and whitespace can be used
freely to improve readability or show relationship through indentation
levels.
- Case is not significant, except within a quoted string.
- A keyword phrase consists of one or more keywords as defined by the
PDL statement.
- A comment is a sequence of two consecutive hyphens - - followed by
characters up to and including end-of-line.
When a string
containing consecutive hyphens is passed as a parameter or option
value, enclose the string in quotes. For example,
"a--b.dat". This prevents the hyphens from being
parsed as the start of a comment.
- Lexical element separators are used to set off keywords, values,
expressions, and so on. They include end-of-line, comment, and the
following characters (except when they appear within a quoted string):
space, horizontal tab, form feed, and vertical tab.
- Delimiters are required syntax in many situations. They consist of
the following characters: semicolon (;), comma (,), left parenthesis
((), right parenthesis ()), left angle bracket (<), and right angle
bracket (>).
When a string contains a delimiter character that
is passed as a parameter or option value, enclose the string in quotes.
For example, to pass the numeric UIC string [1,1] as an option value,
use the quoted string form of "[1,1]" because it contains a
comma character.
3.4.3 PDL Function Syntax and Expressions
Certain PDL statements have a function form that tests for a condition
in the execution environment and returns a Boolean value of true or
false. A function is syntactically similar to its corresponding
statement except that a function is enclosed in left and right angle
brackets (<...>) instead of being terminated by a semicolon (;).
The following statements have corresponding functions:
- hardware device
- hardware processor
- option
- software
- upgrade
The logical name function does not have a corresponding
statement form.
Expressions are used in if statements to produce a Boolean
value for the if-condition test. An expression is delimited by opening
and closing parentheses ((...)). It contains one or more functions and,
optionally, one or more of the keywords AND, OR, and NOT, which are
used as logical operators.
An expression has one of the following forms, where each term is either
another expression or a function:
- (term)
- (term AND term)
- (term OR term)
- (NOT term)
The following example shows an if statement using a compound
expression:
if ( (not <hardware device MUA0:>) and
(<software ABC VAXVMS TEST version below 2.0>) ) ;
.
.
.
end if ;
|
3.4.4 PDL Data Types and Values
The PDL has several base data types that you must use when passing
parameters to the PDL statements listed in Chapter 7. Table 3-1
describes the PDL base data types and their values. PDL statements may
restrict the range of values that can be used as parameters.
Table 3-1 Base Data Types and Values
Data Type |
Values |
Boolean
|
The number
0 (false), the number
1 (true), the keywords
false,
true,
no, and
yes.
|
String
|
A sequence of 0 to 255 ISO Latin-1 characters. In the context of PDF
language statements,
-
abc is an unquoted string.
-
"abc" is a quoted string.
-
""double_quoted_string"" is a quoted
string that maintains original quotation marks.
You must use the quoted string form if the string contains any PDL
delimiters (open/close parenthesis, comma, open/close angle brackets,
and semicolons) or lexical element separators (double hyphen, space,
horizontal tab, form feed, or vertical tab). For example,
"/privilege=(tmpmbx, netmbx)".
Table 3-2 lists the additional constraints on PDL strings.
|
Signed integer
|
Specifies a positive, negative, or zero integral value in the range of
-2147483648 to 2147483647.
|
Unsigned integer
|
Specifies a zero or positive integral value in the range of 0 through
4294967295.
|
Version identifier
|
See the description in Section 2.3.
|
Text module name
|
Specifies a unique name for a text module using the printable ISO
Latin-1 characters, excluding horizontal tab, space, exclamation point,
and comma. The name can be from 1 to 31 characters in length.
|
Table 3-2 describes additional constraints on the string data type.
Table 3-2 String Data Type Constraints
String Type |
Values |
Examples |
Unconstrained
|
None; any character may appear in any position.
|
|
Access control entry (ACE)
|
Specifies an ACE for a directory or file.
|
"(IDENTIFIER=[KM],ACCESS=READ)"
|
Command
|
Specifies an operating system command that you want to execute during a
specific operation.
|
@PCSI$DESTINATION:[SYSTEST]
PROD$IVP.COM
|
Device name
|
Specifies the name of a hardware device.
|
DUB6:
|
File name
|
Specifies a file name (without a device or directory specification).
|
STARTUP.DAT
|
Identifier name
|
Specifies a rights identifier.
|
DOC
|
Module name
|
Specifies the name of a module in a library.
|
FMSHELP
|
Processor model name
|
Specifies the model identification of a particular computer system.
|
7
|
Relative directory specification
|
Specifies the directory name and, if necessary, the directory path,
relative to the root directory specification.
|
[MY_PRODUCT]
|
Relative file specification
|
Specifies the directory path and file name, relative to the root
directory path.
|
[MY_PRODUCT]DRIVER.DAT
|
Root directory specification
|
Specifies the directory name and a trailing period (.). If you specify
a directory name and omit the period, it is inserted. If necessary, you
can add the device name.
|
[TEST.]
SYS$SYSDEVICE:[VMS$COMMON.]
|