The system manager can also define logical names, and then override them by using the /SOURCE and /DESTINATION qualifiers.
PCSI$SOURCE defines the location of the software kits to install. By default, the user's default device and directory are used. PCSI$DESTINATION defines the location in which to install the software.
If the system manager does not define PCSI$DESTINATION or use the /DESTINATION qualifier, the utility installs the software product in SYS$SYSDEVICE:[VMS$COMMON] and directories under it. If this is not appropriate for your product, make sure that your installation instructions describe how to specify the /DESTINATION qualifier, or how to define the PCSI$DESTINATION logical name.
Note
When you package your product, the logical names PCSI$SOURCE and PCSI$DESTINATION are not used. You must use the /SOURCE and /DESTINATION qualifiers.
Several PDL statements execute command procedures in the context of a subprocess. The POLYCENTER Software Installation utility defines the logical names PCSI$SOURCE, PCSI$DESTINATION, and PCSI$SCRATCH for use by these command procedures. Note that these logical names are accessible only within the subprocess and do not interfere with similar names that the user may have defined. Note also that the user's definition of PCSI$SOURCE is not the same as that defined by the utility for the command procedure. See the PDL statement definitions for additional information.
Managed objects are the files, directories, accounts, network object and so forth that support the proper functioning of your product. The POLYCENTER Software Installation utility must directly create an object in order to manage it. That is, the term "managed object" refers only to objects that the POLYCENTER Software Installation utility directly creates.
As an example, if you use a PDF file statement to create a file, that file is considered to be a managed object.
However, if your product creates directories, files, and so forth after the installation is completed, the POLYCENTER Software Installation utility has no way to know about those files or directories and cannot manage them. For example, if your product dynamically creates an error log as a result of a specific error condition, the POLYCENTER Software Installation utility will not be able to manage (for example, remove) this log file. This means that if the OpenVMS user uses the POLYCENTER Software Installation utility to remove your software product, the user would have to delete the error log manually.
In addition, if your PDL file includes command procedures that create files, directories, accounts, and so forth, the POLYCENTER Software Installation utility has no way to know about these objects and cannot manage them.
How do you create managed objects? Using PDL statements, you can specify the names and properties of the managed objects that are necessary for your product. At installation time, the POLYCENTER Software Installation utility uses your product description file (PDF) to create the managed objects for your product and records information about these objects in the product database.
For example, you use the file statement to specify a file managed object, as shown in the following example:
directory [SYSTEST.TNT] ; directory [TNT] ; file [SYSHLP]TNT020.RELEASE_NOTES release notes ; remove ; file [SYSHLP]TNT010.RELEASE_NOTES ; file [SYSHLP]TNT015.RELEASE_NOTES ; file [SYSEXE]TNT$POPULATE.EXE ; file [SYSEXE]TNT$INITJOURNAL.EXE ; file [SYSEXE]TNT$DUMPACS.EXE ; file [SYSEXE]TNT$DUMPJOURNAL.EXE ; end remove ; information RELEASE_NOTES phase after ; information POST_INSTALL phase after ; file [SYS$STARTUP]TNT$STARTUP.COM ; file [SYS$STARTUP]TNT$SHUTDOWN.COM release execute "@PCSI$DESTINATION:[SYS$STARTUP]TNT$SHUTDOWN.COM" ; file [SYSUPD]TNT$VERSION61.COM ; file [SYSMGR]TNT$UTILITY.COM ; file [SYSTEST]TNT$IVP.COM ; file [SYSEXE]TNT$SERVER.EXE ; file [SYSEXE]TNT$UTILITY.EXE ; file [SYSEXE]TNT$EXCLUDED_SYMBIONTS.DAT generation 1 ; file [SYSTEST.TNT]TNT$SERVER_IVP.EXE ;
When the POLYCENTER Software Installation utility removes a software product, it uses the data in the product database to delete managed objects from the system.
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 already exists in the directory, a conflict occurs. It's possible that this file is a remnant of an earlier instance of your software product and you can freely overwrite it. However, it is also possible that the existing file is owned by some other software product and you do not want to randomly replace it.
When the utility detects conflict, it displays an informational message. The following statements detect managed object conflict and display informational messages:
In some cases, the POLYCENTER Software Installation utility allows you to anticipate and resolve conflict before it occurs. For example, the generation option to the file statement lets you resolve managed object conflict. During installation, if the utility attempts to create a file that already exists, it compares the generation numbers of the files (if present), preserving the file with the highest generation number.
The following statements provide some level of conflict resolution:
The description of these statements in Chapter 7 indicates how each one resolves managed object conflict.
As described in Section 2.7.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:
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 it with the desired characteristics.
For more information about kit types, see Table 2-2.
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 correct scope.
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, see Chapter 6.
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.6.
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.
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:
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:
To define the environment for your product, use the following checklist. (Chapter 7 of this guide describes each PDL statement.)
You supply the PDF as input to the PRODUCT PACKAGE command. The PDF can have any valid OpenVMS file name and file type. For example:
TEST.PDF BLACKJACK-V2.TEXT ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.DESCRIPTION
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$DESCRIPTIONSee Section 2.3 for a description of the product naming syntax.
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 ;
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.
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:
A PDL statement consists of:
Additional Syntax Rules
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:
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:
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 ;
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.
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,
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. |
5952P001.HTM OSSG Documentation 3-DEC-1996 08:58:40.91
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.