HP OpenVMS Systems Documentation

Content starts here

POLYCENTER Software Installation Utility Developer's Guide


Previous Contents Index

3.5.7.1 The PCSI$REGISTER_PRODUCT.COM Command Procedure

An alternative way to register a product (without providing a transition kit for the user to register with a PRODUCT REGISTER PRODUCT command) is to execute the SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM command procedure. This procedure prompts the user to enter product name, version, producer, and base system information, as shown in the following example:


$ @SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM
Product name: FMS
Version: V2.4
Producer [DEC] :
Base System [AXPVMS] :
   .
   .
   .
The following product has been registered:
DEC AXPVMS FMS V2.4          Transition (registration)

Registering a product using the command procedure allows another software product to reference this product with a software statement. However, use of this command procedure does not allow objects (such as files) to be registered along with the product name in the product database.


Chapter 4
Creating the Product Text File

The product text file (PTF) is an optional component of a software product kit. However, most kits created using the POLYCENTER Software Installation utility include a PTF. You must supply a PTF to the kitting process if you want to use PDF statements that display text to users during product installation. The following PDF statements have corresponding text modules in the PTF:

For each text module in the PTF you can provide a brief, one-line prompt and a detailed (more than one line) help description. The brief, one-line prompt from the text module is displayed by default (with the exception of the error statement). (See Chapter 7 to see how help text is displayed for each statement.) To display the detailed help text, the user includes the /HELP qualifier on the PRODUCT INSTALL command line. If you choose to provide only a brief, one-line prompt for a given text module and the user asks for detailed help text, the brief prompt is displayed. By providing detailed help text, you should be able to reduce or eliminate hardcopy installation documentation.

Note

You might want to force the detailed text to be displayed without the user having to request it. To do this, use the information or option PDF statement, as in the following example:


option EXAMPLE default YES with helptext;

4.1 PTF File Naming Conventions

The PTF you provide as input to the PRODUCT PACKAGE command must:

  • Reside in the same directory as the PDF
  • Have the same file name as the PDF and a file type of .PCSI$TEXT

The following are examples of valid input PDF and PTF names:


TEST.PDF
TEST.PCSI$TEXT

ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.PCSI$DESC
ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.PCSI$TEXT

The execution of the PRODUCT PACKAGE command transforms the input PTF into an output PTF. The input PTF is a text file containing header lines and text module lines. The output PTF is an OpenVMS text library file. Its name consists of the product's stylized file name and a file type of .PCSI$TLB:


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

For example:


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

Note that you can convert the output PTF from an OpenVMS library file back to a text file by executing the command procedure PCSI$EXTRACT_TLB.COM, which is located in SYS$COMMON:[SYSUPD]. You must supply the PTF library file as a parameter to the procedure.

4.2 Structure of a PTF

A PTF is a text file that contains packaging directives, module header lines, and module text. The PTF must begin with the =product directive line that uniquely identifies the product and specifies the type of kit. The rest of the file contains one or more text modules. Each text module entry consists of:

  • A module header line that identifies the name of the text module
  • An =prompt directive line that includes text for a brief display
  • Zero or more lines of text that are combined with the brief text to form the detailed display associated with the text module

The user chooses whether to receive brief or detailed explanations using the /HELP qualifier on the PRODUCT INSTALL command.

Brief text format (the default) is restricted to one line of text, that is, the text in the =prompt directive line. To avoid carrying the single-line text over to the next line, try to keep your brief message to no more than 60 characters.

Detailed or help text can include any number of lines of text. The formatting of the information is preserved on output, except that the POLYCENTER Software Installation utility may indent the entire block of text displaying information about configuration options or software requirements.

Comment lines are not permitted in a PTF.

4.2.1 Specifying the Product Name

You must use the =product directive to specify product information in the PTF. The information that you specify with the =product directive must match the information you specify with the product statement in the PDF.

The =product directive has the following format:


=product producer base product version kittype

See Section 2.3 for the naming conventions.

4.2.2 PTF Modules and the Relationship with the PDF

PTF text modules are text blocks that you want to present to the user. The POLYCENTER Software Installation utility does not process text blocks sequentially, so the order of the text modules in the PTF does not matter.

Text modules are identified by a module header line in the following format:


1 module-name

The module header line consists of the number 1, followed by a space or tab and the name of the module. The module-name must be from 1 to 31 ISO Latin-1 characters, excluding the horizontal tab, space, exclamation point (!), and comma (,) characters. For example:


1 SAMPLE

The POLYCENTER Software Installation utility uses the name of the module to associate the text module with a line from the PDF. For example, the SAMPLE module could correspond to an option in the PDF:


option SAMPLE ;

4.2.3 PTF Modules Not Related with the PDF

The utility also allows you to specify text modules that are not associated with statements in the PDF. These text modules are preceded by an apostrophe ('). Use the following module names to specify information about your product:

  • The 'LICENSE module specifies licensing information.
  • The 'NOTICE module specifies copyright, ownership, and similar legal information.
  • The 'PRODUCER module specifies a brief description of the producer of the product.
  • The 'PRODUCT module specifies a brief functional description of the product.

For example, a product might contain the following modules:


=product DEC VAXVMS C V1.0 full
1 'PRODUCT
=prompt DEC C++ for OpenVMS
Compaq C++ for OpenVMS VAX is a native compiler that implements the C++
programming language and includes:

o  A C++ compiler that implements C++ as defined by The Annotated C++
   Reference Manual, Ellis & Stroustrup, reprinted with corrections,
   May 1991. The compiler implementation includes templates but ex-
   cludes exception handling. Compaq C++ generates optimized object code
   without employing an intermediate translation to C.

o  The Compaq C++ Class Library, which consists of the following class li-
   brary packages: iostream, complex, generic, Objection, Stopwatch,
   String, task, messages, and vector.
1 'NOTICE
=prompt Copyright 2001 Compaq Computer Corporation. 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
Compaq Computer Corporation. Possession, use, or copying of this software
and media is authorized only pursuant to a valid written license from Compaq
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: <xxx> and <xxx-RT>.
This software is furnished under the licensing provisions of Compaq
  Computer Corporation's Standard Terms and Conditions. For more in-
  formation about Compaq's licensing terms and policies, contact your
  local Compaq office.
1 'PRODUCER
=prompt Compaq Computer Corporation
This software product is sold by Compaq Computer Corporation.

4.2.4 Including Prompt and Help Text

You can include prompt 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 Compaq TCP/IP Services for OpenVMS
 Compaq 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 Compaq 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 Copyright 2001 Compaq Computer Corporation. 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
Compaq Computer Corporation. Possession, use, or copying of this software
and media is authorized only pursuant to a valid written license from Compaq
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 Compaq Computer Corporation
This software product is sold by Compaq Computer Corporation.
1 EXAMPLES
=prompt Example files
The example files include client/server programming examples.
1 NFS
=prompt NFS files

The Compaq 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 Compaq NFS server promotes data sharing among clients by providing
a central data storage facility for OpenVMS and UNIX files. The Compaq 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 Compaq TCP/IP Services first.
Before you install Compaq OpenVMS UCX, you must complete certain preinstallation
tasks. For more information, refer to the "Compaq TCP/IP Services for OpenVMS
Installation and Configuration Guide."
1 POST_INSTALL
=prompt Postinstallation tasks required for Compaq TCP/IP Services.
For more information, refer to these associated documents:

- "Compaq TCP/IP Services for OpenVMS Installation and Configuration Guide"
- "Compaq TCP/IP Services for OpenVMS System Management"


Chapter 5
Packaging the Kit

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 shows you how to create a product kit in sequential format from product materials that are spread across several directories. A game application named CHESS is used throughout this chapter to illustrate the steps required to package the kit. You will also be introduced to the PRODUCT LIST, PRODUCT EXTRACT, and PRODUCT COPY commands which are useful for manipulating the product kit.

Assume that the files needed to package the CHESS product have been organized into a directory tree. The following is a listing of this directory tree containing the product material, required kitting files, and other files produced by the engineering team (such as listing and object files).


$ 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.1 Description of the Product Material

The product material for the CHESS application consists of the files that will be installed on the user's system along with any command procedures included in the kit to perform product specific tasks during installation.

Assume that the product material is located in the directory tree [TEST...] as follows:

  • An executable image named CHESS.EXE is located in [TEST.OBJ]. It will be placed in [SYSEXE] on the target disk when the product is installed.
  • Two data files, CHESS.OPENINGS and CHESS.GAMES, reside in [TEST.SRC]. The first file, an opening book, will always be copied to [SYSEXE] on the user's system. However, the second file, a large games collection, is an optional component of the product. Users determine at install time whether or not to install this file. If they choose not to install it, they can later reconfigure the product to obtain this optional file.
  • Two command procedures, CHESS_IVP.COM and CHECK_SPACE.COM, are placed in [TEST.COM]. CHESS_IVP.COM will be copied to [SYSTEST] on the destination device and executed to verify the correct installation of the product. CHECK_SPACE.COM will be executed early during the installation but it will not be left on the user's system. It checks for adequate space on the destination device for large work files that will be used when the product is used.

The contents of the two command procedures from [TEST.COM] are shown below as they might appear early in the packaging process. Later in the development cycle they will be replaced by command procedures that perform their intended functions.


$ 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.2 Files Required to Package the Kit

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

  • CHESS.PCSI$DESC, the product description file
  • CHESS.PCSI$TEXT, the product text file
  • PACKAGE.COM, as a convenience

PACKAGE.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 AXPVMS 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 axpvms chess v1.0 full
1 'PRODUCT
=prompt ABC Company's Chess for OpenVMS Alpha
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 does
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-axpvms-chess-v0100--1.pcsi$desc
$!      abc_co-axpvms-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 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=axpvms -
    /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

5.3 Creating the Product Kit

The sample output below shows the execution of the PRODUCT PACKAGE command (via a command procedure listed in Section 5.2) to create the product kit in sequential format. The full kit name for CHESS V1.0 produced by ABC_CO to run on OpenVMS Alpha is ABC_CO-AXPVMS-CHESS-V0100--1.PCSI.


$ SET DEFAULT [TEST.KIT]
$ @PACKAGE.COM

The following product has been selected:
    ABC_CO AXPVMS CHESS V1.0               Layered Product

Do you want to continue? [YES]

The following product will be packaged:
    ABC_CO AXPVMS CHESS V1.0

Portion done: 0%...100%

The following product has been packaged:
    ABC_CO AXPVMS CHESS V1.0               Layered Product


$ DIRECTORY /COLUMN=1 /NOTRAILING

Directory DKA300:[TEST.KIT]

ABC_CO-AXPVMS-CHESS-V0100--1.PCSI;1
CHESS.PCSI$DESC;1
CHESS.PCSI$TEXT;1
PACKAGE.COM;1


Previous Next Contents Index