POLYCENTER Software Installation Utility Developer's Guide

The name of a module managed object is specified using the module option. For a help, macro, object, or text library, the name specified with the module option should be the same as the name of the module itself.

The module managed object has assembly lifetime, and its scope is the same as the library.

If a module of the same name already exists, the utility determines which module to preserve by comparing the generation numbers of the modules. If both modules have generation numbers, the utility preserves the module with the higher generation number. If one module does not have a generation number or has a generation number of zero, the utility preserves the module that has a nonzero generation number. If both modules have the same nonzero generation number, they are considered to be equivalent and either one may be used. Finally, if neither module has a nonzero generation number, a module conflict error is reported to the user. See Also file
register module

Examples

module [SYSUPD]CDD.CLD type COMMAND module CDD ; 

The statement in this example creates the command module CDD in the default command library [SYSLIB]DCLTABLES.EXE using the file [SYSUPD]CDD.CLD.

module [SYSUPD]HELP.HLP type HELP module HELP ; 

The statement in this example creates the help module in the default help library [SYSHLP]HELPLIB.HLB using the file [SYSUPD]HELP.HLP.

module [SYSUPD]SPI$CONNECT.MAR type MACRO    
    library [SYSLIB]LIB.MLB module SPI$CONNECT ; 

The statement in this example creates the macro module SPI$CONNECT in the macro library [SYSLIB]LIB.MLB using the file [SYSUPD]SPI$CONNECT.MAR.

module [SYSUPD]COBRTL.OBJ type OBJECT module COBRTL; 

The statement in this example creates the object module COBRTL in the default object library [SYSLIB]STARLET.OLB using the file [SYSUPD]COBRTL.OBJ.

module [SYSUPD]PROTOTYPE_BOOK.TXT type TEXT    
    library [SYSLIB]LPS$FONT_METRICS.TLB module PROTOTYPE_BOOK; 

The statement in this example creates the text module PROTOTYPE_BOOK in the text library [SYSLIB]LPS$FONT_METRICS.TLB using the file [SYSUPD]PROTOTYPE_BOOK.TXT.

The network object statement uses a command procedure to create a DECnet network object.

Syntax

network object name with (parameters,...) ;

PARAMETERS

name

Indicates the name of the network object. The network object name is passed to the command procedure as P1.

with (parameters,...)

Indicates the list of parameters that are passed to the command procedure that creates the network object. Each parameter must be a single quoted string that specifies P2 through P5, in order. Refer to the Description section for the meaning of the parameters.

DESCRIPTION

The network object statement uses a command procedure (SYS$UPDATE:PCSI$CREATE_NETWORK_OBJECT.COM) to create network objects. The command procedure determines whether DECnet Phase IV or DECnet--Plus (DECnet Phase V) is running on the system. If Phase IV is being used, the command procedure runs the Network Control Program (NCP) utility to create the network object. Otherwise, it runs the Network Control Language (NCL) utility.

In the case of DECnet--Plus, the network object created during the product installation will exist only in memory. It is recommended that DECnet--Plus objects be supplied in the form of an NCL script with a file statement and activated with a product startup procedure.

The utility passes the following parameters to the command procedure:

• P1 specifies the name of the network object (using the nameparameter).
• P2 specifies the object number (for DECnet Phase IV systems only).
• P3 specifies the user name associated with the object. If you specify a user name, it must already exist.

  ---

  Note

  The password of the specified user account is changed when the network object is created by PCSI$CREATE_NETWORK_OBJECT.COM. The new password is system generated, and can be viewed with the NCP> SHOW OBJECT... command.

  ---

• P4 specifies optional parameters to use with the NCP command DEFINE OBJECT for DECnet Phase IV objects.
• P5 specifies optional parameters to use with the NCL command CREATE SESSION CONTROL APPLICATION for DECnet--Plus (DECnet Phase V) objects.

When you remove a product that created network objects, the POLYCENTER Software Installation utility uses a command procedure (SYS$UPDATE:PCSI$DELETE_NETWORK_OBJECT.COM) to delete network objects associated with your product.

---

Note

In a future version, the POLYCENTER Software Installation utility may create and delete these managed objects directly without the use of command procedures. If this is the case, these statements will continue to function, but the command procedures may not be maintained or shipped with future versions of the utility.

---

The network object statement specifies a network object managed object that has the following characteristics:

• Its name is the value of the name parameter. The name must be unique with respect to all network object names in the processor scope.
• It has operating lifetime and processor scope.
• Managed object conflict is not recoverable.

Examples

network object k$test with ("number 107", "user KRYPTON") ; 
 

In this example, the network object statement creates a network DECnet Phase IV object named k$test. Its object number is 107 and it will execute as user [KRYPTON].

file [SYSMGR]NETOBJ_TEST.NCL; 
file [SYS$STARTUP]PRODUCT_STARTUP.COM ; 
 
execute 
    start "@sys$startup:product_startup.com" 
    stop  ""; 
 

In this example, the firstfile statement supplies the DECnet--Plus (Phase V) NCL script file. This script can contain NCL directives that create a DECnet Phase V network object; that is, session control application. For example, the script file might contain the following NCL commands:

   .
   .
   .
delete session control application k_test 
create session control application k_test 
set session control application k_test 
   .
   .
   .

where k_test is the network object name.

The second file statement supplies a command procedure, which is executed as a result of processing the execute start statement during the product installation. The startup command procedure may contain the following DCL command that forces the NCL script file to be executed:

   .
   .
   .
$ MCR NCL DO NETOBJ_TEST.NCL 
   .
   .
   .

The startup command procedure can be placed later into the system startup procedure to execute each time the user's system is rebooted.

The option statement conditionally processes a group of statements based on the user's response to a question. The option and end option statements form an option group.

Statement Syntax

option name [ default value ] [ with helptext ]

[PDL-statements ]

end option

Function Syntax

< option name [ default value ] [ with helptext ] >

PARAMETER

name

Indicates, as a quoted or unquoted string, the name of the associated PTF text module. The name you specify can be from 1 to 31 characters in length and must be unique among all names in the same product description.

OPTIONS

default value

Indicates the default value for the option. The value must be either 1 (true), 0 (false), yes, no, true, or false; the default is 1 (true).

If you specify an option statement with the default value 0, and it contains other option statements, any defaults in the contained option statements apply only when the top-level option statement is selected.

with helptext

Forces the display of the full help text module during the installation or configuration of the product. See Section 7.1 for usage constraints.

PDL-statements

Any product description language statement or a group of statements described in this reference section, except the product and end product statements.

DESCRIPTION

Statement

The option statement conditionally processes a group of statements based on the user's response to a question. You can nest option groups, which are processed in lexical order. An option group containing other option statements must be processed and selected by the user before any inner option statements are processed. That is, if the user declines an option, any option groups contained within it are also treated as being declined.

When an option is processed, the POLYCENTER Software Installation utility displays the prompt text line from the specified module in the PTF and waits for a response. The response can be Yes, No, or Return to accept the default answer.

Default answers come from one of three places:

• A product configuration file (PCF), if one is supplied with the /CONFIGURATION=INPUT=pcf-name qualifier on the command line of a PRODUCT INSTALL, PRODUCT CONFIGURE, or PRODUCT RECONFIGURE command.
• The product database (PDB) for an upgrade of a previously installed product where the PDB contains the answers from the previous installation.
• The product description file (PDF) from the product kit.

If an input PCF is used and it contains an answer for an option, that answer is the default. Depending on the entry in the PCF, the user may or may not be allowed to change the default value.

If no input PCF is supplied, or if the input PCF does not contain an answer for an option, the default answer is obtained from either the PDB or the PDF. If the PDB does not contain information about the product (for example, this is a new installation), or a product specific PDB entry exists but does not contain the option (a new option), then the default comes from the PDF. Default answers that come from either the PDB or PDF may be changed by the user.

In addition to the prompt text line, the utility displays help text (if present in the PTF), when the user specifies the /HELP qualifier on the command line, or the option statement contains the with helptext option.

You must supply prompt text for the option statement in the PTF using the =prompt directive. Help text is optional. If provided, it must immediately follow the prompt text line.

Function

The option function returns 1 (true) if the user selects the option and 0 (false) if the user does not select the option. The user is prompted to choose options during the configuration phase of the operation.

Examples

option NET ; 
    file [SYSEXE]NETSERVER.COM ; 
    file [SYSEXE]NETSERVER.EXE ; 
    file [SYSHLP]NCPHELP.HLB ; 
    option NET_A default 0 ; 
        file [SYSEXE]FAL.COM ; 
        file [SYSEXE]FAL.EXE ; 
    end option ; 
    option NET_B ; 
        file [SYSEXE]REMACP.EXE ; 
        file [SYSMGR]RTTLOAD.COM ; 
        file [SYS$LDR]CTDRIVER.EXE ; 
        file [SYS$LDR]RTTDRIVER.EXE ; 
    end option ; 
end option ; 

If the product description file contains the lines above, the product text file contains the corresponding text:

1 NET 
=prompt network support 
This option allows you to participate in a DECnet network. 
1 NET_A 
=prompt incoming remote file access 
This option allows file access from other nodes in a DECnet network. 
1 NET_B 
=prompt incoming remote terminal access 
This option allows users on other nodes in a DECnet network to log 
in. 

The user must select option NET before NET_A or NET_B are available for selection. Therefore, NET is processed before NET_A or NET_B.

if (<option A>) ; 
    file [SYSEXE]A.EXE ; 
else ;  
    file [SYSEXE]B.EXE ; 
end if ; 
 
 
 

The product text file contains the corresponding text:

1 A 
=prompt the X capability 
This feature provides the A capability, but you will not get the B 
capability. 

In this example, if the user selected the A option, the utility provides the file [SYSEXE]A.EXE. Otherwise, the utility provides the file [SYSEXE]B.EXE.

The part statement displays a message from the specified text module in the PTF about a group of statements during the configuration phase of an installation, configuration, or reconfiguration operation. The part and end part statements form a part group.

Syntax

part name ;

[PDL-statements ]

end part

PARAMETER

name

Indicates, as a quoted or unquoted string, the name of the associated PTF text module. The name you specify can be from 1 to 31 characters in length and must be unique among all names in the same product description.

OPTION

PDL-statements

Any product description language statement or a group of statements described in this reference section, except the product and end product statements.

DESCRIPTION

The part statement displays a message from the specified text module in the PTF about a group of statements during the configuration phase of an installation, configuration, or reconfiguration operation. You can nest part groups, which are processed in lexical order.

By default, the prompt text string is displayed without help text. However, help text is displayed after the prompt text when the user specifies the /HELP qualifier on the command line.

You must supply prompt text for the part statement in the PTF using the =prompt directive. Help text is optional. If provided, it must immediately follow the prompt text line.

Example

Suppose the product description file contains the following lines:

part DESKTOP ; 
    software DEC VAXVMS DECPRINT 
        version required V4.0 component ; 
    software DEC VAXVMS DOCUMENT 
        version required V2.0 component ; 
    software DEC VAXVMS LSE 
        version required V3.0 component ; 
end part; 

The product text file contains the corresponding text:

1 DESKTOP 
=prompt Desktop Publishing Tools 
This product provides the following desktop publishing products: 
DECprint Printing Services software, VAX DOCUMENT software, and the VAX 
Language Sensitive Editor (LSE) software are the required products that 
comprise this platform. 

This example shows how to use the part statement to display a message about the required software products that the desktop platform provides.

The patch image statement updates an executable image.

Syntax

patch image name with source ;

PARAMETERS

name

Indicates the relative file specification of the executable image you want to update.

with source

Indicates the file specification of the file containing the update commands. The file that contains the update commands should contain OpenVMS VAX Image File Patch Utility (PATCH) commands.

DESCRIPTION

The patch image statement updates an executable image. Use this statement when it is inconvenient to provide a new image.

You must supply the file containing the update commands as part of the product material.

The patch image statement specifies a maintenance managed object that has the following characteristics:

• Its name is the same as the nameparameter of the product group in which the statement is lexically contained; it is a multicomponent name qualified by the relative file specification of the file that is being updated. It must be unique with respect to all maintenance managed objects in all scopes.
• It has assembly lifetime, and its scope is the same as that of the file being updated.
• Managed object conflict is unrecoverable.

Example

patch image [SYS$LDR]SYS.EXE with [SYSUPD]VERSION_PATCH.PAT ; 

This statement provides a file, [SYSUPD]VERSION_PATCH.PAT, to patch the image [SYS$LDR]SYS.EXE.

The patch text statement updates a text file.

Syntax

patch text name with source ;

PARAMETERS

name

Indicates the relative file specification of the text file you want to update.

with source

Indicates the file specification of the file containing the update commands (as a single quoted or unquoted string). The file that contains the update commands should contain SUMSLP commands.

DESCRIPTION

The patch text statement updates a text file. Use this statement when it is inconvenient to provide a new file.

You must supply the file containing the update commands as part of the product material. You must also supply the file that you want to update, but this file is not propagated to the reference copy. The POLYCENTER Software Installation utility uses it to calculate the input and output checksum values.

The patch text statement creates a temporary directory, identified by the logical name PCSI$SCRATCH, to compute a checksum value. The PCSI$SCRATCH directory is created as a subdirectory of SYS$SCRATCH.

The patch text statement specifies a maintenance managed object that has the following characteristics:

• Its name is the same as the name parameter of the product group in which the statement is lexically contained; it is a multicomponent name qualified by the relative file specification of the file that is being updated. It must be unique with respect to all maintenance managed objects in all scopes.
• It has assembly lifetime, and its scope is the same as that of the file being updated.
• Managed object conflict is unrecoverable.

Example

patch text [SYSUPD]VMSINSTAL.COM with [SYSUPD]VMSINSTAL.SLP ; 

This statement provides a file, [SYSUPD]VMSINSTAL.SLP, to patch the text file [SYSUPD]VMSINSTAL.COM.

The process parameter statement displays a message to users about process parameter requirements.

---

Note

The POLYCENTER Software Installation utility does not adjust process parameters.

---

Syntax

process parameter name
{ { consume | require } value |
maximum value |
minimum value |
minimum value maximum value } ;

PARAMETER

name

Indicates the process parameter name. The name you specify must be valid on the system where the product executes.

OPTIONS

consume value

Indicates that the process parameter must be increased by the specified value. Use this option when the product consumes a resource that is controlled by the process parameter. The value must be a single unquoted string that specifies an unsigned integer value. You cannot use this option with either the maximum, minimum, or require options.

maximum value

Indicates that the process parameter must have a value less than or equal to the specified value. The value must be a single unquoted string that specifies an integer value.

minimum value

Indicates that the process parameter must have a value greater than or equal to the specified value. The value must be a single unquoted string that specifies an integer value.

require value

Indicates that the process parameter must have the specified value. The value must be a single string that specifies a value of the parameter's type. This option is valid for any parameter data type. You cannot use this option with either the maximum, minimum, or consume options.

DESCRIPTION

The process parameter statement displays a message to users after the installation about process parameter requirements. Note that the utility does not adjust process parameters.

Example

process parameter ASTLM minimum 6; 
process parameter BYTLM require 32768; 
process parameter PRCLM consume 2; 
process parameter FILLM maximum 40; 

These statements display a message to users that a process that executes the product must have the following process parameters:

• ASTLM greater than or equal to 6
• BYTLM set to 32768
• PRCLM increased by 2
• FILLM less than or equal to 40

The process privilege statement displays a message to users about process privilege requirements.

---

Note

The POLYCENTER Software Installation utility does not adjust process privileges.

---

Syntax

process privilege (name [,...]) ;

PARAMETER

name

Indicates the process privilege names as a list. The privileges you specify must be valid on the system where the product executes.

DESCRIPTION

The process privilege statement displays a message to users after the installation about process privilege requirements. Note that the utility does not adjust process privileges.

Example

process privilege (group, oper, tmpmbx, sysnam) ; 

The statement in this example displays a message to the user that processes using the product must have the GROUP, OPER, TMPMBX, and SYSNAM privileges.

The product statement specifies product identification and other descriptive information about the product. The product and end product statements form the product group.

Syntax

product producer base name version type

[PDL-statements ]

end product

PARAMETERS

producer

Indicates the legal onwer of the software product. This paramater must be a single quoted or unquoted string.

base

Indicates the base hardware/software system on which the product is intended to be installed. This paramater must be a single quoted or unquoted string. By convention, the string AXPVMS denotes an OpenVMS Alpha product, VAXVMS denotes an OpenVMS VAX product, and VMS denotes a product applicable for either OpenVMS Alpha or VAX.

Although any base system name can be used when you package a product, Digital recommends that you use the names AXPVMS, VAXVMS, and VMS when developing products for use on OpenVMS.

name

Indicates the name of the product. This paramater must be a single quoted or unquoted string. The combination of producer, base, and name parameters must be unique among products installed on the system.

version

Indicates the version of the product. This paramater must be a single quoted or unquoted string.

type

Indicates the kit type of the product through use of one of the following keywords or keyword phrases:

• full. A complete description of a layered product (application software) that can be used to install or upgrade the product.
• operating system. A complete description of an operating system that can be used to install or upgrade the product. Only one product of operating system type can be installed on the system.
• partial. A partial (incomplete) description of a product that can be used only to upgrade an existing version of the same product. Installation of a partial kit changes the version number of the product and can upgrade a product of type: full, operating system, or platform. A partial kit must contain an upgrade statement and have the same producer-base-name identification string as the product it upgrades.
• patch. A partial (incomplete) description of a product that can be used only to update an existing version of a product. Installation of a patch kit does not change the version number of the product and can update a product of type: full, operating system, or platform. A patch kit must contain an apply to statement and have a different producer-base-name identification string than the product it updates.
• platform. A complete description of a suite of products that can be used to install or upgrade the entire set of products.
• transition. A complete or incomplete description of a product that was installed on the system by another installation method such as VMSINSTAL. A transition kit is used only to register a previously installed product; it does not contain any product material. Registration using a transition kit defines the name of a product and its managed objects in the POLYCENTER Software Installation product database. After a product is registered, the utility can use this information to satisfy software dependency requirements that other products may have on the availability of this product.
  The keyword transition used alone denotes a layered product; the keyword phrase transition operating system denotes an operating system.
• mandatory update. This is functionally identical to a patch kit. Its type implies that the patch must be applied to the product it updates.

OPTION

PDL-statements

Any product description language statement or a group of statements described in this reference section, except the product and end product statements.

DESCRIPTION

The product statement is a utility directive that specifies the product identification and other descriptive information about the product. It does not specify a managed object. There can be only one product...end product statement for a given product description file.

Examples

product DEC VAXVMS FMS V2.4 full ; 
    file [sysmsg]fdvshr.exe image library ; 
    file [sysmsg]fmsmsg.exe ; 
    file [sysexe]fmsfed.exe ; 
    file [sysexe]fmsfaa.exe ; 
    file [sysexe]fmsfte.exe ; 
    directory [systest.fms] ; 
    file [systest.fms]ivp.exe ; 
    file [systest.fms]samp.flb ; 
end product ; 

---

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

---

  5952P006.HTM
  OSSG Documentation
   3-DEC-1996 08:58:50.24

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal