POLYCENTER Software Installation Utility Developer's Guide

Document revision date: 19 July 1999

POLYCENTER Software Installation Utility Developer's Guide

Contents

Index

logical name

The logical name function tests whether a specified logical name is defined in the default logical name table LNM$SYSTEM_TABLE or in the table specified by the user.

Function Syntax

< logical name name [ equals value ] [ table table _name ] >

Parameter

name
Indicates the logical name string.

Option

equals value
Indicates the equivalence name string of the logical name. If you do not specify the equivalence name, the presence of the logical name in the default or specified logical name table is sufficient to make the function evaluate to TRUE.
table table_name
Indicates the name of the logical name table in which the logical name is to be searched. If the name of the table is not specified, LNM$SYSTEM_TABLE becomes the default table name.

Description

Function

The logical name function tests whether the specified logical name is defined. The value of the function is true if the following conditions are met:

No options are specified, and the logical name has been found in the LNM$SYSTEM_TABLE logical name table. The equivalence name is not probed in such an instance.
An equivalence name is specified, no logical table name is listed, the logical name has been found in the LNM$SYSTEM_TABLE logical name table, and the equivalence string from the table matches the equivalence string specified in the function.
Both options are specified, the logical name has been found in the user specified table, and the equivalence string from the table matches the equivalence string specified in the function.

The function evaluates to false in any other case.
The logical name function is evaluated by the utility immediately after processing the execute preconfigure statement. This gives you the opportunity to define the logical name while performing the install, configure, or reconfigure operation and alter the result of the operation.

Example


execute preconfigure "@PCSI$SOURCE:[SYSUPD]EXEC_PREC.COM" uses [SYSUPD]EXEC_PREC.COM interactive ; if ( < logical name YOUR_ANSWER equals MENU_ITEM_1 > ) ; file [SYSEXE]FILE1.EXE ; else if ( < logical name YOUR_ANSWER equals MENU_ITEM_2 > ) ; file [SYSEXE]FILE2.EXE ; else if ( < logical name YOUR_ANSWER equals MENU_ITEM_3 > ) ; file [SYSEXE]FILE3.EXE ; end if ;

execute preconfigure "@PCSI$SOURCE:[SYSUPD]EXEC_PREC.COM" 
             uses [SYSUPD]EXEC_PREC.COM interactive ; 
if ( < logical name YOUR_ANSWER equals MENU_ITEM_1 > ) ; 
             file [SYSEXE]FILE1.EXE ; 
else if ( < logical name YOUR_ANSWER equals MENU_ITEM_2 > ) ; 
             file [SYSEXE]FILE2.EXE ; 
else if ( < logical name YOUR_ANSWER equals MENU_ITEM_3 > ) ; 
             file [SYSEXE]FILE3.EXE ; 
end if ;

The utility limits your configuration options to accept only true or false values. This example shows you how to handle multiple choice answers from the user.
The first statement executes commands from the EXEC_PREC.COM file in an interactive mode. The user is prompted to select one of three menu items. The answer is stored by the command procedure as an equivalence name to a logical name YOUR_ANSWER. The logical name is evaluated immediately after the execute preconfigure statement and the result is stored internally. During the execution phase, the logical name function is probed and, based on the result, an appropriate file is provided for the product being installed.

module

The module statement adds or replaces one or more modules in a command, help, macro, object, or text library file.

Syntax

module file type type module (module _name[,...])
[ [no] generation generation ]
[ [no] globals ]
[ library library ]
[ [no] selective search ] ;

Parameters

file
Indicates the relative file specification of the file that contains the modules.
type type
The library type. Table 7-4 lists the keywords you can specify with this parameter.

Table 7-4 Library Types for Module Statement
Keyword Library Type Default Library File

Command Command definition library [SYSLIB]DCLTABLES.EXE

Help Help library [SYSHLP]HELPLIB.HLB

Macro Macro library [SYSLIB]STARLET.MLB

Object Object library [SYSLIB]STARLET.OLB

Text Text library [SYSLIB]STARLETSD.TLB

module module_name
The list of module names you are specifying.

**Table 7-4 Library Types for Module Statement**
Keyword	Library Type	Default Library File
Command	Command definition library	[SYSLIB]DCLTABLES.EXE
Help	Help library	[SYSHLP]HELPLIB.HLB
Macro	Macro library	[SYSLIB]STARLET.MLB
Object	Object library	[SYSLIB]STARLET.OLB
Text	Text library	[SYSLIB]STARLETSD.TLB

Options

[no] generation generation
Indicates that the file has an explicit generation number. Specify the number as an unsigned integer in the range of 0 through 4294967295. Refer to the Description section for the meaning of this value. By default, the file does not have an explicit generation number (no generation), which is equivalent to zero.
[no] globals
Indicates whether the global symbol names of the modules you are inserting into an object library are included in the global symbol table. You can use this option with object libraries only. By default, the global symbols of the module are inserted into the global symbol table.
library library
Indicates the relative file specification of the library. The file you specify must be a library of the type you specified with the type parameter.
[no] selective search
Indicates whether the input modules being inserted into the library are available for selective searches by the linker (by default they are not). You cannot use this option with the command and help libraries. For more information about selective searches, see the OpenVMS Linker Utility Manual.

Description

The module statement adds or replaces one or more modules in a command library file, or a single module in a help, macro, object, or text library file. The module statement adds the module name to the product database. You do not need to use a register module statement to register a module.
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.

Examples

#1
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.

#2
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.

#3
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.

#4
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.

#5
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.

network object

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 name parameter).
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 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

#1
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].

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

In this example, the first file 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.

option

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.

Required Terminator end option ;

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 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

#1
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 ;

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.

#2
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.

part

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.

Required Terminator end part ;

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;

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.

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.

Contents

Index

privacy and legal statement

5952PRO_010.HTML

POLYCENTER Software Installation Utility Developer's Guide

logical name

Function Syntax

< logical name name [ equals value ] [ table table _name ] >

Parameter

name

Option

equals value

table table_name

Description

Example

module

Syntax

module file type type module (module _name[,...]) [ [no] generation generation ] [ [no] globals ] [ library library ] [ [no] selective search ] ;

Parameters

file

type type

module module_name

Options

[no] generation generation

[no] globals

library library

[no] selective search

Description

Examples

network object

Syntax

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

Parameters

name

with (parameters,...)

Description

Examples

option

Statement Syntax

option name [ default value ] [ with helptext ]

[ PDL-statements ]

end option

Function Syntax

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

Parameter

name

Options

default value

with helptext

PDL-statements

Description

Examples

part

Syntax

part name ;

[ PDL-statements ]

end part ;

Parameter

name

Option

PDL-statements

Description

Example

module file type type module (module _name[,...])
[ [no] generation generation ]
[ [no] globals ]
[ library library ]
[ [no] selective search ] ;