HP OpenVMS Systems Documentation

POLYCENTER Software Installation Utility Developer's Guide

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 [HP] :
Base System [AXPVMS] :
   .
   .
   .
The following product has been registered:
HP 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.

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:

• ERROR
• INFORMATION
• OPTION
• PART
• PRODUCT

For each text module in the PTF, you may provide a brief, one-line prompt and a detailed (longer 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 can reduce or eliminate hardcopy installation documentation.

option EXAMPLE default YES with helptext;

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

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

For example:

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

You can convert the output PTF from an OpenVMS library file back to a text file by executing the PCSI$EXTRACT_TLB.COM command procedure, 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:

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:

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 ;

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 HP VAXVMS C V1.0 full
1 'PRODUCT
=prompt HP C++ for OpenVMS
HP 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. HP C++ generates optimized object code
   without employing an intermediate translation to C.

o  The HP 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 2003 Hewlett-Packard Company. 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
Hewlett-Packard Company. Possession, use, or copying of this software
and media is authorized only pursuant to a valid written license from HP
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 Hewlett-Packard
  Company's Standard Terms and Conditions. For more in-
  formation about HP's licensing terms and policies, contact your
  local HP office.
1 'PRODUCER
=prompt Hewlett-Packard Company
This software product is sold by Hewlett-Packard Company.