HP OpenVMS Systems Documentation

Managed objects are the files, directories, accounts, network objects, and so forth that support the proper functioning of your product. The POLYCENTER Software Installation utility must directly create them.

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 manually delete the error log.

In addition, if your PDF includes command procedures in execute statements 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.

2.6.1 Creating Managed Objects

To 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 directory, file, and module statements to specify directory, file, and library module managed objects, as shown in the following example:

directory [SYSTEST.FORTRAN] ;
file [SYSTEST]FORT$IVP.COM ;
file [SYSHLP]TNT030.RELEASE_NOTES release notes ;
file [SYSHLP]HELPLIB.HLB generation 40069227 release merge ;
module [000000]CPQC.CLD type command module CC ;

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.

Use the PRODUCT SHOW OBJECT command to display the names of objects installed on a system. For example:

$ PRODUCT SHOW OBJECT *COPY*
----------------------------------------------- ----------------- -----
OBJECT NAME                                     OBJECT TYPE       STATUS
----------------------------------------------- ----------------- -----
[SYSEXE]COPY.EXE                                 file              OK
[SYSHLP.EXAMPLES.DECW.UTILS]COPYRIGHT.H          file              OK
COPY                                             module            OK

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 interproduct 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 intraproduct 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:

• account
• directory
• file
• link
• loadable image
• module
• network object
• register module
• rights identifier

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:

• file
• module
• register module

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;
end product;

product CPQ AXPVMS TEST2 V1.0 full;
    file [SYSEXE]TEST.EXE generation 200;
end product;

If you first install product TEST1 and then install TEST2, the TEST.EXE file 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; therefore, product TEST1 will continue to work properly. To restore product TEST1 to its original state, you will need to reinstall it. This will remove all the installed files 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 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 the description of the scope statement in Chapter 7.

2.7 Creating an Integrated 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.

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 installation time.
• Specifies any dependencies the product may have on other software products.
• Defines various actions that must be performed during installation.

This chapter discusses the following PDF topics:

• General PDF guidelines ( Section 3.1)
• Define the environment ( Section 3.2)
• PDF file-naming conventions ( Section 3.3)
• PDF structure ( Section 3.4)
• Kit types and usage ( Section 3.5)

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.

To define the environment for your product, use the following checklist.

• 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 Note 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 an integrated 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 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 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. 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?
  Use the rights identifier statement.
  
• Does your product 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 user options, 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?
  Use the patch image statement (VAX only).
  
• Do you need 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?
  Use the process parameter statement to display these requirements to users.
  
• Does your product require certain values for process privileges?
  Use the process privilege statement to display these requirements to users.
  
• Do you want to include a functional test with 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?
  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?
  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.

You supply the PDF as input to the PRODUCT PACKAGE command. The PDF can have any valid OpenVMS file name and file type. We recommend that you give the input PDF file the extension .PCSI$DESC. For example:

TEST.PCSI$DESC

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 as follows:

producer-base-product-version-kittype.PCSI$DESCRIPTION.

For example, the output PDF for product BLACKJACK V2.1-17 might be named:

ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.PCSI$DESCRIPTION

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 ;

The product description language consists of statements that are defined in Chapter 7 of this manual. As an overview, these statements are listed here 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 the Boolean value of a statement 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
  • directory
  • file
  • link (create an alias directory entry)
  • loadable image
  • module
  • network object
  • 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 post_undo
  • execute preconfigure
  • execute pre_undo
  • execute start...stop
  • execute test
  • execute upgrade
• 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>
  • <option>
  • <software>
  • <upgrade>

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
• module
• software
• option and end option
• if and end if
• execute install...remove
• execute test