Updated: 11 December 1998

POLYCENTER Software Installation Utility Developer's Guide

You can include prompt and help text in your PTF using the =prompt directive. Prompt text cannot exceed one line of text. (The suggested line length is 60 characters.) Help text is similar to prompt text, except that it can span multiple lines. The help text follows the =prompt line. You can also include blank lines in help text.

The following example shows prompt text:

=prompt This option provides files for programming support.

The following example shows a sample product text file. Note the prompt and help text:

=product DEC VAXVMS UCX V2.0 full 1 'PRODUCT =prompt DEC TCP/IP Services for OpenVMS DEC TCP/IP Services for OpenVMS is an OpenVMS layered software product that promotes interoperability and resource sharing between OpenVMS systems, UNIX systems, and other systems that support the TCP/IP and NFS protocol suites. The product provides capabilities for file access, remote terminal access, remote command execution, remote printing, mail, and application development, including three major functional components: o The Run-Time component, which is based on the Berkeley Standard Distribution, brings TCP/IP communications to OpenVMS computer systems. It also includes a suite of application development tools (DECrpc, C socket programming interface, and QIO programming interface). o The Applications component includes the popular user-oriented protocols for file transfer, remote processing, remote printing, and mail: File Transfer Protocol (FTP), Telnet Protocol (Telnet), Berkeley R commands (rsh, rlogin, rexec), remote printing, and Simple Mail Transfer Protocol (SMTP). o The DEC NFS component supports Network File System (NFS) V2.0 proto- col specifications. NFS is an Application layer protocol that provides clients with transparent access to remote file services. 1 'NOTICE =prompt © Digital Equipment Corporation 1992. All rights reserved. Unpublished rights reserved under the copyright laws of the United States. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, or in FAR 52.227-19 or in FAR 52.227-14 Alt. III, as applicable. 1 'LICENSE =prompt This product uses the PAKs: UCX and UCX-IP-RT. This product currently has two Product Authorization Keys (PAKs): Producer PAK Name Version Release Date DEC UCX 2.0 6-JUL-1992 DEC UCX-IP-RT 2.0 6-JUL-1992 1 'PRODUCER =prompt Digital Equipment Corporation This software product is sold by Digital Equipment Corporation. 1 EXAMPLES =prompt Example files The example files include client/server programming examples. 1 NFS =prompt NFS files The DEC NFS component supports Network File System (NFS) protocol specifications. NFS is an Application layer protocol that provides clients with transparent access to remote file services. The DEC NFS server promotes data sharing among clients by providing a central data storage facility for OpenVMS and UNIX files. The DEC NFS server provides two types of file access for UNIX clients: 1) client access to OpenVMS files, and 2) client access to files compatible with UNIX systems. 1 APPLICATIONS =prompt Applications The Applications component includes the popular user-oriented protocols for file transfer, remote processing, remote printing, and mail: File Transfer Protocol (FTP), Telnet Protocol (Telnet), Berkeley R commands (rsh, rlogin, rexec), remote printing, and Simple Mail Transfer Protocol (SMTP). 1 PRE_INSTALL =prompt Complete preinstallation tasks for DEC TCP/IP Services first. Before you install DEC VMS UCX, you must complete certain preinstallation tasks. For more information, refer to the "DEC TCP/IP Services for VMS Installation and Configuration Guide." 1 POST_INSTALL =prompt Postinstallation tasks required for DEC TCP/IP Services. For more information, refer to these associated documents: - "DEC TCP/IP Services for VMS Installation and Configuration Guide" - "DEC TCP/IP Services for VMS System Management"

You use the PRODUCT PACKAGE command to create a software product kit. This operation uses a product description file (PDF), an optional product text file (PTF), and product material files as input to produce a software product kit in either sequential or reference format.

The syntax of the PRODUCT PACKAGE command is documented in the OpenVMS System Management Utilities Reference Manual.

This chapter provides an example of how to package a product given a set of product materials spread across sub-directories. It also demonstrates the following techniques:

• How to use an execute preconfigure statement
• How to name your input PDF and PTF files
• How to use the PRODUCT EXTRACT PDF command

Assume that you want to package an installation kit for a product named CHESS and that the product material is located in the directory tree [TEST...]. The product consists of the following files:

• An executable image named CHESS.EXE. CHESS.EXE is located in [TEST.OBJ], and will be placed in [SYSEXE] on the destination disk when installed.
• Two data files, CHESS.OPENINGS and CHESS.GAMES, located in [TEST.SRC]. The first file always will be provided in [SYSEXE] on the destination disk, but the user will be given the option of installing the second file.
• Two command procedures, CHESS_IVP.COM and CHECK_SPACE.COM, located in [TEST.COM]. CHESS_IVP.COM will be placed in [SYSTEST] on the destination disk and executed to verify the installation of the product.
  CHECK_SPACE.COM will be executed but not left on the system disk. Its purpose is to check for adequate space on the destination device for installation of the product, as well as large work files that may be created when the product is used.

A display of the directory structure for the product material might be similar to the following:

$ DIRECTORY /COLUMN=1 /NOTRAILING DKA300:[TEST.*] Directory DKA300:[TEST.COM] CHECK_SPACE.COM;1 CHESS_IVP.COM;1 Directory DKA300:[TEST.KIT] CHESS.PCSI$DESC;1 CHESS.PCSI$TEXT;1 PACKAGE.COM;1 Directory DKA300:[TEST.LIS] CHESS.LIS;1 Directory DKA300:[TEST.OBJ] CHESS.EXE;1 CHESS.OBJ;1 Directory DKA300:[TEST.SRC] CHESS.C;1 CHESS.GAMES;1 CHESS.OPENINGS;1 HEADER.H;1

5.2 Description of the Files Needed to Package the Kit

In this CHESS kit example, the [TEST.KIT] directory contains the following files to package the kit:

• CHESS.PCSI$DESC, which is the product description file
• CHESS.PCSI$TEXT, which is the product text file

As a convenience, PRODUCT.COM has been created to simplify the task of entering the PRODUCT PACKAGE command with the appropriate qualifiers.

The content of the packaging files for the CHESS product might be similar to the following:

$ TYPE [TEST.KIT]*.* DKA300:[TEST.KIT]CHESS.PCSI$DESC;1 product ABC_CO VAXVMS CHESS V1.0 full ; execute preconfigure "@pcsi$source:[000000]check_space.com" uses [000000]check_space.com interactive ; file [sysexe]chess.exe ; file [sysexe]chess.openings ; option master_games ; file [sysexe]chess.games ; end option ; file [systest]chess_ivp.com ; execute test "@pcsi$destination:[systest]chess_ivp.com" ; end product ; DKA300:[TEST.KIT]CHESS.PCSI$TEXT;1 =product abc_co vaxvms chess v1.0 full 1 'PRODUCT =prompt ABC Company's Chess for OpenVMS VAX Chess V1.0 provides a chess playing engine with 50 selectable user levels (rated playing strength from 1200 to 2450), a graphical interface with 2D and 3D boards, an extensive database of openings plus thousands of complete master games, and three modes of operation: play, analyze, and tutorial. 1 MASTER_GAMES =prompt Do you want the database of master games? Answer YES to install a database containing 16000 complete games played by GMs and IMs (25000 blocks). Your choice not affect the quality or size of the opening database which is always installed in its entirety. DKA300:[TEST.KIT]PACKAGE.COM;1 $! This command file packages product CHESS into a sequential format kit. $! $! Note that by default the package command searches for the input PDF and $! input PTF in the source directory using file name and type of: $! <producer-base-product-version-edit-type>.pcsi$desc (for PDF) [1] $! <producer-base-product-version-edit-type>.pcsi$text (for PTF) $! For example: $! abc_co-vaxvms-chess-v0100--1.pcsi$desc $! abc_co-vaxvms-chess-v0100--1.pcsi$text $! $! You can override this default by specifying the file name of the PDF and $! PTF (and optionally the file type of the PDF) in the /source qualifier $! (e.g., /source=dev:[dir]chess.pdf). The file type of the PTF, however, $! must be .pcsi$text. The approach used in this command procedure is to $! to specify the file name of the PDF and PTF in the /source qualifier and $! let the file types be defaulted. For example, /source=dev:[dir]chess $! causes the package command to search for input PDF and input PTF named: $! chess.pcsi$desc $! chess.pcsi$text $! $! [1] For OpenVMS V6.1-V7.1, the default input PDF file type was $! .pcsi$description (the same as the output PDF), but beginning with $! OpenVMS V7.1-2, the utility looks for .pcsi$desc; if not found it $! then searches for .pcsi$description. $! $ product package chess - /base=vaxvms - /producer=abc_co - /source=dka300:[test.kit]chess - ! where to find PDF and PTF /destination=dka300:[test.kit] - ! where to put .PCSI file /material=dka300:[test.*] - ! where to find product material /format=sequential $ exit $ TYPE [TEST.COM]*.* DKA300:[TEST.COM]CHECK_SPACE.COM;1 $! This command procedure is executed from an EXECUTE PRECONFIGURE statement $! with the INTERACTIVE keyword specified. Therefore, all output lines $! generated will be displayed. $! $ write sys$output "*** Output from execute preconfigure ***" $ exit 1 DKA300:[TEST.COM]CHESS_IVP.COM;1 $! This command procedure is executed from an EXECUTE TEST statement without $! the INTERACTIVE keyword specified. Therefore, only output lines that $! look like an OpenVMS message (i.e., those starting with %) will be $! displayed. By default, all other output from this $! procedure will be suppressed unless the /TRACE qualifier is used on the $! PRODUCT INSTALL command. For testing purposes you can force a line $! of text to be displayed by putting a percent sign in column 1. $! $ write sys$output "%%% Output from execute test %%%" $ exit 1

5.3 Executing the PRODUCT PACKAGE Command

The following output shows the execution of the PRODUCT PACKAGE command and the creation of the installable kit in sequential copy format. The kit is named ABC_CO-VAXVMS-CHESS-V0100--1.PCSI.

$ SET DEFAULT [TEST.KIT] $ @PACKAGE.COM The following product has been selected: ABC_CO VAXVMS CHESS V1.0 Layered Product Do you want to continue? [YES] The following product will be packaged: ABC_CO VAXVMS CHESS V1.0 Portion done: 0%...100% The following product has been packaged: ABC_CO VAXVMS CHESS V1.0 Layered Product $ DIRECTORY /COLUMN=1 /NOTRAILING Directory DKA300:[TEST.KIT] ABC_CO-VAXVMS-CHESS-V0100--1.PCSI;1 CHESS.PCSI$DESC;1 CHESS.PCSI$TEXT;1 PACKAGE.COM;1

5.4 Listing the Contents of the Product Kit

You can list the contents of the product kit with the PRODUCT LIST command. Note that any file specified in a USES clause in the PDF is not listed in this output. Notice that the input PTF has been converted to a text library file with a file type of .PCSI$TLB during the packaging operation.

$ PRODUCT LIST CHESS The following product has been selected: ABC_CO VAXVMS CHESS V1.0 Layered Product Do you want to continue? [YES] ------------------------------------------------------------------- Files in _KRYSYS$DKA300:[TEST.KIT]ABC_CO-VAXVMS-CHESS-V0100--1.PCSI ------------------------------------------------------------------- [000000]ABC_CO-VAXVMS-CHESS-V0100--1.PCSI$TLB [SYSEXE]CHESS.EXE [SYSEXE]CHESS.GAMES [SYSEXE]CHESS.OPENINGS [SYSTEST]CHESS_IVP.COM [000000]ABC_CO-VAXVMS-CHESS-V0100--1.PCSI$DESCRIPTION End of list

5.5 Extracting the PDF From the Kit

You can extract the PDF from the kit with the PRODUCT EXTRACT PDF command. Notice that the names of the input and output PDFs are different.

$ PRODUCT EXTRACT PDF CHESS The following product has been selected: ABC_CO VAXVMS CHESS V1.0 Layered Product Do you want to continue? [YES] Portion done: 0%...100% Product Description File has been extracted from the following product: ABC_CO VAXVMS CHESS V1.0 Layered Product $ DIRECTORY /COLUMN=1 /NOTRAILING Directory DKA300:[TEST.KIT] ABC_CO-VAXVMS-CHESS-V0100--1.PCSI;1 ABC_CO-VAXVMS-CHESS-V0100--1.PCSI$DESCRIPTION;1 CHESS.PCSI$DESC;1 CHESS.PCSI$TEXT;1 PACKAGE.COM;1

5.6 Listing the Installed Products

After the product kit is installed, you can use the PRODUCT SHOW PRODUCT command to list the products installed on the system. Use the /FULL qualifier for additional information about software references and patches that may have been applied to the products. Additional commands (not shown here) that are useful for obtaining more information about installed products are the PRODUCT SHOW HISTORY /FULL and PRODUCT SHOW OBJECT /FULL commands.

$ PRODUCT INSTALL CHESS ! /LOG and /TRACE are useful for debugging . . . $ PRODUCT SHOW PRODUCT ----------------------------------- ----------- ------------ PRODUCT KIT TYPE STATE ----------------------------------- ----------- ------------ ABC_CO VAXVMS CHESS V1.0 Full LP Installed DEC VAXVMS DECNET_PHASE_IV V7.1 Full LP Installed DEC VAXVMS DWMOTIF V1.2-4 Full LP Installed DEC VAXVMS VMS V7.1 Transition Installed ----------------------------------- ----------- ------------ 4 items found

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

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:

• Global scope is the largest scope in which a single POLYCENTER Software Installation utility operation can have an effect. A single file that must be shared by every process in the computing facility must exist in global scope. Modules in system object libraries are examples of managed objects that must be in global scope. Writable databases might be in global scope.
  Global scope managed objects have the following characteristics:
  • They exist in every process in the computing facility (as established by an initial system load).
  • They are always stored together.
  • They are usually used by operating system products.
• Bootstrap scope managed objects function during system bootstrap when operating system facilities are unable to locate and use larger scopes. Drivers and loadable images that must be present before startup executes are examples of files that should be in the bootstrap scope.
  Bootstrap scope should be used for products that use device drivers, especially those drivers that must be read by the primitive file system. Because files in bootstrap scope are read by the primitive file system, they are read when not synchronized with the file system on other cluster members that might access the same disk.
  Therefore, those files must retain stable positions as long as the disk is in use from any system and must not be manipulated by online disk defragmentation operations, including those that use the MOVEFILE primitive.
  Bootstrap scope managed objects have the following characteristics:
  • They support specific computers and usually exist on the same disk volume as processor scope managed objects.
  • A computing facility can have several bootstrap scopes, and multiple computers can share the same bootstrap scope.
  • They are usually used by operating system products.
• Product scope managed objects are product specific. Most managed objects for a product reside in product scope. Product scope is the default scope for most objects; therefore, it is generally unnecessary to specify product scope. Product scope managed objects for different products can be stored together or separately.
• Processor scope managed objects exist in all processes executing on a single computer. For example, a logical name might exist in processor scope.

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:

• You can use the scope statement to ensure that the utility looks in a specific scope for the file managed object you want to update.
• If you do not use the scope statement, the utility searches the execution environment for a file managed object with the same name. If the utility finds the object, it replaces the object; if the utility does not find the file managed object, it provides a new file in product scope.

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5952PRO_005.HTML