[Digital logo]
[HR]

POLYCENTER Software Installation Utility Developer's Guide


Previous | Contents

Table 3-2 describes additional constraints on the string data type.

Table 3-2 String Data Type Constraints
String Type Values Examples
Unconstrained None; any character may appear in any position.
Access control entry (ACE) Specifies an ACE for a directory or file. "(IDENTIFIER=[KM],ACCESS=READ)"
Command Specifies an operating system command that you want to execute during a specific operation. @SYS$TEST:PROD$IVP.COM
Device name Specifies the name of a hardware device. DUB6:
File name Specifies a file name (without a device or directory specification). STARTUP.DAT
Identifier name Specifies a rights identifier. DOC
Module name Specifies the name of a module in a library. FMSHELP
Processor model name Specifies the model identification of a particular computer system. 7
Relative directory specification Specifies the directory name and, if necessary, the directory path, relative to the root directory specification. [MY_PRODUCT]
Relative file specification Specifies the directory path and file name, relative to the root directory path. [MY_PRODUCT]DRIVER.DAT
Root directory specification Specifies the directory name and a trailing period (.). If you specify a directory name and omit the period, it is inserted. If necessary, you can add the device name. [TEST.]
SYS$SYSDEVICE:[VMS$COMMON.]

3.5 Writing a PDF for a Full Kit

Example 3-1 shows a PDF for Checktran. You can see how the requirements of the execution environment were translated into statements in the PDF.

Example 3-1 Checktran Product Description File


$ TYPE CHECKTRAN-TEST.PDF
product DEC VAXVMS CHECKTRAN V4.3 full ; (1)     
    software DEC VAXVMS VMS version minimum V6.1 ; (2)
    file [SYSEXE]CHECKTRAN.EXE ; (3)
    module [SYSUPD]CHECKTRAN.CLD type command module CHECK ; (4)
    module [SYSUPD]CHECKTRAN.HLP type help module CHECKTRAN ; (5)
    file [SYSTEST]CHECKTRAN$IVP.COM ; (6)
    file [SYSEXE]CHECKTRAN.DAT ; 
    execute test @SYS$TEST:CHECKTRAN$IVP ; (7)
end product ; (8)                                            

The following list describes the function of the PDL statements in Example 3-1:

  1. The product statement identifies the product as DEC VAXVMS CHECKTRAN Version 4.3. The full option specifies that the kit is a complete software distribution and not an update or patch.
  2. The software statement specifies that to run Checktran, the execution environment must be running at least OpenVMS Version 6.1.
  3. The first file statement in the PDF supplies the file [SYSEXE]CHECKTRAN.EXE.
  4. The first module statement in the PDF installs the command module for Checktran in the default command library [SYSLIB]DCLTABLES.EXE.
  5. The second module statement in the PDF installs the help module for Checktran in the default help library [SYSHLP]HELPLIB.HLB.
  6. The next statement installs the DCL command procedure that will be used for the functional test.
  7. The execute test statement executes the functional test for the product.
  8. The end product statement closes the group of product statements.

In this example, the PDF for Checktran is relatively brief. Example 3-2 shows a PDF for DEC TCP/IP Services for OpenVMS, which is more complex.

Example 3-2 UCX Product Description File


$ TYPE UCX.DES
-- "DEC TCP/IP Services for VMS" (1)
                       
product DEC VAXVMS UCX V2.0 full ; (2)
 
software DEC VAXVMS VMS version minimum V6.1 ; (3)
 
process parameter ASTLM minimum 24 ; (4)
process parameter BIOLM minimum 18 ; 
process parameter BYTLM minimum 32768 ; 
process parameter DIOLM minimum 18 ; 
process parameter ENQLM minimum 200 ; 
process parameter FILLM minimum 100 ; 
 
rights identifier UCX$NFS_REMOTE ; (5)
 
execute start "@SYS$STARTUP:UCX$STARTUP.COM" (6)
        stop "@SYS$STARTUP:UCX$SHUTDOWN.COM" ; 
 
execute test "@SYS$TEST:UCX$IVP.COM" ; (7)
 
information PRE_INSTALL confirm ; (8)
 
information POST_INSTALL phase after ; (9)
 
directory [SYSTEST.UCX] ; (10)
directory [SYSHLP.EXAMPLES.UCX] ; 
 
module [000000]UCX$TOP_LEVEL_HELP.HLP type help module UCX ; (11)
module [000000]UCX.CLD type command module UCX ; (12)
 
file [SYSEXE]UCX$SERVICE.DAT ; (13)
file [SYSEXE]UCX$FTPSERVER.COM ; 
file [SYSEXE]UCX$SNMP_AGENT.EXE ; 
file [SYSEXE]UCX$UCP.EXE ; 
   .
   .
   .
file [SYSTEST]UCX$IVP.COM ; 
file [SYSTEST.UCX]UCX$INET_IVP.EXE ; 
file [SYSUPD]UCX$CLEANUP.COM ; 
 
option EXAMPLES ; (14)
 
  file [SYSHLP.EXAMPLES.UCX]UCX$IOCTL_ROUTINE.C ; 
  file [SYSHLP.EXAMPLES.UCX]UCX$TCP_CLIENT_IPC.C ; 
   .
   .
   .
  file [SYSHLP.EXAMPLES.UCX]UCX_TRACE.EXE ; 
  file [SYSHLP.EXAMPLES.UCX]TRACEROUTE.EXE ; 
 
end option ; 
 
option NFS ; (15)
 
  file [SYSEXE]UCX$CONVERT.FDL ; 
  file [SYSEXE]UCX$CONVERT.COM ; 
  file [SYSEXE]UCX$SERVER_NFS.EXE ; 
 
  file [SYSHLP]UCX$VMS_FILES.DOC ; 
 
  file [SYSLIB]UCX$CFS_SHR.EXE ; 
 
end option ; 
 
option APPLICATIONS ; (16)
 
  module [000000]FTP.CLD type command module FTP ; 
  module [000000]RLOGIN.CLD type command module RLOGIN ; 
  module [000000]RSH.CLD type command module (RSH,RSHELL) ; 
  module [000000]TELNET.CLD type command module TELNET ; 
  module [000000]UCX$LPQ_CLD.CLD type command module LPQ ; 
  module [000000]UCX$LPRM_CLD.CLD type command module LPRM ; 
 
  file [SYSEXE]UCX$ENCODE.COM ; 
  file [SYSEXE]UCX$DECODE.COM ; 
   .
   .
   .
  file [SYSEXE]UCX$LPD_RCV.EXE ; 
  file [SYSEXE]UCX$LPRSETUP.EXE ; 
 
  file [SYSHLP]UCX$FTP_HELP.HLB ; 
  file [SYSHLP]UCX$TELNET_HELP.HLB ; 
 
  file [SYSLIB]UCX$SMTP_MAILSHR.EXE ; 
  file [SYSLIB]UCX$LPD_SHR.EXE ; 
 
end option ; 
 
end product ; (17)

The following list describes the function of the PDL statements in the UCX example:

  1. The first line of the PDF is a comment line (identified by two hyphens).
  2. The product statement identifies the product as DEC VAXVMS UCX V2.0. The full option specifies that the kit is a complete software distribution and not an update or patch.
  3. The software statement specifies that to run UCX, the execution environment must be running at least OpenVMS Version 6.1.
  4. The process parameter statements specify the process parameters that the product requires. The utility will display a message about these requirements to users when they install UCX.
  5. The rights identifier statement causes the utility to create the specified rights identifier.
  6. The first execute statement specifies command procedures for product startup and shutdown.
  7. The second execute statement specifies the functional test for the product.
  8. The first information statement displays a message about preinstallation tasks. The utility prompts the user for confirmation of these tasks. The actual PRE_INSTALL message text is found in the related PFT file:
    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." 
    
  9. The second information statement displays a message about postinstallation tasks.
  10. The directory statements create the directories [SYSTEST.UCX] and [SYSHLP.EXAMPLES.UCX].
  11. The first module statement installs the help module for UCX in the default help library [SYSHLP]HELPLIB.HLB.
  12. The second module statement installs the command module for UCX in the default command library [SYSLIB]DCLTABLES.EXE.
  13. The next file statements install several required files for UCX.
  14. The EXAMPLES option group contains programming example files that the user can select. The actual EXAMPLES message text is found in the related PFT file:
    1 EXAMPLES 
    =prompt Example files 
    The example files include client/server programming examples. 
    
  15. The NFS option group contains NFS protocol support files that the user can select.
  16. The APPLICATIONS option group contains optional application support files and modules that the user can select.
  17. The end product statement closes the group of product statements.

3.6 Writing a PDF for a Platform Kit

As mentioned in Section 2.8, the POLYCENTER Software Installation utility gives you the means to create a software kit that is a combination of products (an integrated platform). To do this, you must create a platform PDF.

A platform PDF is distinguished from other types of PDFs by using the platform keyword in the product statement. In a platform PDF, you can use any statements to express the execution environment for the platform. For example, you can use the component option of the software statement to specify the software products that make up the platform.

When you package a platform, the PDFs and PTFs of the referenced products do not need to be present. However, when you copy a platform, products that are referenced with the component option of the software statement must be present.

Example 3-3 shows a product description file for the OFFICE_PLAT product.

Example 3-3 Product Description File for a Platform Kit


product DEC VAXVMS OFFICE_PLAT V1.0 platform ; 
    file [SYSEXE]SOFTWARE.TST ; 
    software DEC VAXVMS VMS 
             version minimum V6.1 ; 
    software DEC VAXVMS PROD_B 
             version required 4.3 component ; 
    software DEC VAXVMS PROD_C component ; 
end product ;

The PDF in this example is for a platform named OFFICE_PLAT. The software products PROD_C and PROD_B are components of the platform. OpenVMS Version 6.1 or greater must be present along with Version 4.3 of PROD_B.

3.7 Writing a PDF for a Transition Kit

If you install a product using a mechanism other than the POLYCENTER Software Installation utility, the product database does not store information about the product. A transition product description file allows you to register a product in the product database even if it was installed using a mechanism other than the POLYCENTER Software Installation utility.

Once users register a product using the POLYCENTER Software Installation utility, they can perform utility operations on that product (for example, reconfigure or remove operations). Registering a product also allows you to use software statements or functions to reference that product.

A transition PDF must use the transition keyword in the product statement. A transition PDF can reference managed objects such as files, directories, modules, and so forth. However, none of these objects is created or modified when the product is registered using the DCL command PRODUCT REGISTER PRODUCT. In addition, files specified in file statements do not need to be present when a transition kit is packaged because product material is not included in this type of kit.

In a transition PDF, the infer statement is useful for testing the target system to determine if a product or product version is available.

An alternative to providing a transition kit and having the user register it with a PRODUCT REGISTER PRODUCT command is to instruct the user to register the product by using the SYS$UPDATE:PCSI$REGISTER_PRODUCT.COM procedure. This procedure prompts the user to enter product name, version, and producer information. Registering a product with minimal information is sufficient to reference the product with a software statement from another kit.

Example 3-4 shows a transition PDF for the FMS product.

Example 3-4 FMS Product Description File


 
product DEC AXPVMS FMS V2.4 transition ; (1)
    infer version from [SYSLIB]FDVSHR.EXE ; (2)
    file [SYSLIB]FDVSHARE.OPT ; (3)
    module [SYSUPD]FDV.OBJ type object module FDV ; (4)
    module [SYSUPD]FDVMSG.OBJ type object module FDVMSG ; 
    module [SYSUPD]FDVDAT.OBJ type object module FDVDAT ; 
    module [SYSUPD]FDVERR.OBJ type object module FDVERR ; 
    module [SYSUPD]FDVTIO.OBJ type object module FDVTIO ; 
    module [SYSUPD]FDVXFR.OBJ type object module FDVXFR ; 
    module [SYSUPD]HLL.OBJ type object module HLL ; 
    module [SYSUPD]HLLDFN.OBJ type object module HLLDFN ; 
end product ; 

The following list describes the statements in this example:

  1. The transition keyword to the product statement indicates that this is a transition PDF.
  2. The infer version statement tests the execution environment to determine whether the file FDVSHR.EXE is present. If it is, the utility infers the version that is installed.
  3. The file statement indicates that the [SYSLIB]FDVSHARE.OPT file is part of the FMS kit.
  4. The module statements describe object modules in the default object library [SYSLIB]STARLET.OLB that are part of the FMS kit.


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 both brief and detailed descriptions. By default, the brief version of the text module is displayed. The user requests detailed explanations by including the /HELP qualifier on the PRODUCT INSTALL command line. If you choose to provide only brief text for a given text module and the user asks for detailed text, the brief version is displayed. By providing detailed descriptions and other informational 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 statements, 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:

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

TEST.PDF 
TEST.PCSI$TEXT 
 
ABC_CO-AXPVMS-BLACKJACK-V0201-17-1.DESCRIPTION 
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 library file. Its name consists of the product's stylized file name and a file type of .PCSI$TLB:

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

For example:

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

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:

The user chooses whether to receive brief or detailed explanations by use of 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 kit_type 

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 ; 

When a user chooses the SAMPLE option, the utility displays the help text for the choice. Note that the format of the help text in the PTF (for example, spacing and blank lines) is preserved when the utility displays it to the user.

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:

For example, a product might contain the following modules:

=product DEC VAXVMS C V1.0 full 
1 'PRODUCT 
=prompt DEC C++ for OpenVMS 
DEC 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. DEC C++ generates optimized object code 
   without employing an intermediate translation to C. 
 
o  The DEC 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 © 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: <xxx> and <xxx-RT>. 
This software is furnished under the licensing provisions of Digital 
  Equipment Corporation's Standard Terms and Conditions. For more in- 
  formation about Digital's licensing terms and policies, contact your 
  local Digital office. 
1 'PRODUCER 
=prompt Digital Equipment Corporation 
This software product is sold by Digital Equipment Corporation. 

4.2.4 Including Prompt and Help Text

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" 


Chapter 5
Packaging the Kit

You use the 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.


Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]

[HR]

  5952P002.HTM
  OSSG Documentation
   3-DEC-1996 08:58:42.80

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal