[Digital logo]
[HR]

POLYCENTER Software Installation Utility Developer's Guide


Previous | Contents

The product statement in this example identifies the product as FMS version 2.4 provided by Digital that is intended to be installed on an OpenVMS VAX system. #2

product DEC AXPVMS INTERNET_PRODUCTS V1.1 platform ; 

The product statement in this example identifies INTERNET_PRODUCTS version 1.1 as a suite of products (that is, a platform) provided by Digital for installation on an OpenVMS Alpha system.


register module

The register module statement registers in the product database one or more existing modules in a command, help, macro, object, or text library file.

Syntax

register module type type module (module _name,...)
[ [no] generation generation ]
[ library library ] ;


PARAMETERS

type type

Indicates the library type. Table 7-5 lists the keywords you can use with this parameter.

Table 7-5 Library Types for Register 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

Indicates the names of the modules contained within the library.

OPTIONS

[no] generation generation

Indicates that the module has an explicit generation number. Enter the number as an unsigned integer in the range of 0 through 4294967295. Refer to the Description section of the module statement for the meaning of this value. By default, the module does not have an explicit generation number (no generation), which is equivalent to zero.

library library

The file specification of the library. The file you use must be a library of the type you specified with the type parameter.

DESCRIPTION

The register module statement registers in the product database one or more existing modules in a command, help, macro, object, or text library file. Typically, register module statements are used when a product provides a library file with a file statement that is already populated with modules. Registering these modules in the product database allows the utility to detect conflicts with other modules. In contrast, module statements automatically register their modules. When you populate a library using module statements, you do not need to use register module statements to register the information.

Examples

#1
register module type HELP 
          module (":=","=","@",ACCOUNTING,ALLOCATE,ANALYZE,APPEND,...) ; 

In this example, the register module statement registers several help modules in [SYSLIB]DCLTABLES.EXE.

#2
register module type OBJECT generation  1 
        module (BAS$$CB,BAS$$COPY_FD,BAS$$DISPATCH_T,...) ; 

In this example, the register module statement registers several object modules. The generation option allows the utility to perform conflict resolution with these object modules.


remove

The remove statement removes managed objects from the product database and the system. The remove and end remove statements form a remove group.

Note

You cannot use the remove statement in a transition PDF.


Syntax

remove ;

[PDL-statements ]

end remove

;

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

DESCRIPTION

The remove statement allows you to remove managed objects from the product database and from the system. Statements that normally provide managed objects (for example, the file statement) remove managed objects when contained within remove, end remove.

By using the remove statement in a partial, patch, or mandatory update kit, you can eliminate obsolete files from a previous version of your product. By using the remove statement in a full kit, you can eliminate objects provided by a previous installation mechanism (for example, VMSINSTAL).

Statements that do not provide managed objects function normally within remove, end remove.

You can nest remove, end remove within scope, end scope, if necessary.


Examples

#1
remove ; 
  directory [SYSHLP.EXAMPLES.FOO] ; 
  file [SYSHLP.EXAMPLES.FOO]SMLUS.COM ; 
  file [SYSHLP.EXAMPLES.FOO]SMLUT.COM ; 
  file [SYSHLP.EXAMPLES.FOO]SMLUU.COM ; 
end remove ; 
 

The statements in this example remove some files and a directory (if they exist) from the product database and the running system.

#2
scope bootstrap ; 
  remove ; 
      file [SYSEXE]PROD_PROC.EXE ; 
  end remove ; 
  file [SYSEXE]PROD_PROC_V2.EXE ; 
end scope ; 

The statements in this example remove a file in the bootstrap scope and then provide a new file.


rights identifier

The rights identifier statement uses a command procedure to create a rights identifier.

Syntax

rights identifier name with (parameters,...) ;


PARAMETERS

name

Indicates the name of the rights identifier. The rights identifier 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 rights identifier. Each parameter must be a single quoted string that specifies P2 and P3, in order. Refer to the Description section for the meaning of the parameters.

DESCRIPTION

The rights identifier statement invokes a command procedure (SYS$UPDATE:PCSI$CREATE_RIGHTS_IDENTIFIER.COM) to create rights identifiers. This command procedure runs the AUTHORIZE utility to perform the function. The utility passes the following parameters to the command procedure:

When you remove a product that created rights identifiers, the POLYCENTER Software Installation utility uses a command procedure (SYS$UPDATE:PCSI$DELETE_RIGHTS_IDENTIFIER.COM) to delete rights identifiers 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 rights identifier statement specifies a rights identifier managed object that has the following characteristics:


Example

rights identifier PCSI_TEST 
       with ("/attributes=DYNAMIC", 
             "/value=IDENTIFIER:14600926") ; 

In this example, the rights identifier statement creates a rights identifier named PCSI_TEST with a value of 14600926.


scope

The scope statement specifies for certain managed objects a scope and lifetime other than its defaults. The scope and end scope statements form a scope group.

Syntax

scope
{ bootstrap |
global |
processor |
product } ;

[ PDL-statements ]

end scope

;

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

DESCRIPTION

The scope statement specifies for a managed object a scope and lifetime other than its defaults. You can nest scope statements. For more information about the scope and lifetime of managed objects, see Chapter 6.
See Also directory
file
infer
link

Example

scope bootstrap ; 
    file [SYSEXE]SYSBOOT.EXE ; 
    file [SYSEXE]VMB.EXE ; 
    bootstrap block [SYSEXE]VMB.EXE image [SYSEXE]BOOTBLOCK.EXE ; 
end scope; 

The statements in this example specify that the files VMB.EXE and SYSBOOT.EXE must be placed on every bootstrap disk.


software

The software statement specifies a software product that must be available. The software function tests for the presence of a product. You can also specify the version of the product that must be present.

Statement Syntax

software producer base name
[ [no] component ]
[ { version below version |
version maximum version |
version minimum version |
version required version |
version minimum version version below version |
version minimum version version maximum version } ] ;


Function Syntax

< software producer base name
[ { version below version |
version maximum version |
version minimum version |
version required version |
version minimum version version below version |
version minimum version version maximum version } ] >


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.

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.

OPTIONS

[no] component

Indicates that if the product is copied (using the PRODUCT COPY command) or packaged (using the PRODUCT PACKAGE command), the component products will be copied or packaged along with the product. The default is no component (the product does not need to be present during a copy or package operation).

version below version

Indicates the smallest invalid product version. Use this option to specify that the product version must be less than (but not equal to) the specified version. You cannot use this option with either the version maximum or version required options. By default, there is no smallest invalid version.

version maximum version

Indicates a maximum product version. The version must be a single quoted or unquoted string that specifies a version identifier. The version of the product that is available must be less than or equal to the specified version. You cannot use this option with the version below option. By default, there is no maximum version.

version minimum version

Indicates a minimum product version. The version must be a single quoted or unquoted string that specifies a version identifier. The version of the product that is available must be greater than or equal to the specified version. You cannot use this option with the version required option. By default, there is no minimum version.

version required version

Indicates a required product version. The version must be a single quoted or unquoted string that specifies a version identifier. The version of the product that is available must be equal to the specified version. You cannot use this option with either the version below, version maximum, or version minimum options. By default, there is no required version.

DESCRIPTION

Statement

The software statement indicates a software product that must be available in the execution environment. You can also specify a particular version of a product.

If you use the component option, the POLYCENTER Software Installation utility creates a copy of the referenced product when you use the PRODUCT COPY command.

If you reference a product that is not available or one that does not fit the constraints you specified, the utility prompts the user to continue or to terminate the operation.

If the operation executes in batch mode and a referenced product is not available, the operation terminates.


Note

If a referenced product is not available, Digital recommends that users accept the default prompt and terminate the operation.

If your product references another product with a software statement, the referenced product will be installed earlier than, and removed later than, your product. If two products reference each other (creating an infinite loop), the utility issues an error message.

Function

The software function tests for the presence of a product. You can also specify a particular version of a product. The software function tests the state the system will be in when the operation finishes, not when the operation begins.

The function value is true if the following conditions exist; otherwise, the value is false:

The software function value, when evaluated as true, does not cause the utility to create a reference to the specified product.

See Also apply to
product
upgrade

Examples

#1
software DEC VAXVMS FORTRAN 
    version minimum V3.0 version maximum V5.0 ; 
 

The software statement in this example specifies that this product requires DEC Fortran software. The version must be between 3.0 and 5.0.

#2
software DEC VAXVMS FORTRAN version below V5.0 ; 

The software statement in this example specifies that this product requires DEC Fortran software. The version must be less than (but not equal to) 5.0.

#3
if ( < software DEC AXPVMS COOL_PRODUCT version minimum V3.0 > ) ; 
    software DEC AXPVMS COOL_PRODUCT version minimum V3.0 ; 
else if ( < option NO_COOL_REFERENCE default YES with helptext > ) ; 
    file [SYSEXE]COOL_SUBSTITUTE.EXE ; 
else ; 
    error MISSING_COOL ; 
end if ; 
 

In this example, thesoftware function is used to probe for the COOL_PRODUCT. If the POLYCENTER Software Installation utility finds the software with Version 3.0 or higher on the system, the reference to it is created with a separate software statement.

If the COOL_PRODUCT V3.0 or higher is not found, an option to install its substitute (file[SYSEXE]COOL_SUBSTITUTE.EXE]) is offered to the user. If the user declines to accept the substitute image, an error is issued and the user is prompted to either terminate or continue the current session.


system parameter

The system parameter statement allows you to display a message to users that expresses system parameter requirements for your product.

Note

The POLYCENTER Software Installation utility does not change system parameters.


Syntax

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


PARAMETER

name

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

OPTIONS

consume value

Indicates that the system parameter must be increased by the specified value. Use this option when the product consumes a resource that is controlled by the system 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 system 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 system 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 system 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 system parameter statement displays a message to users after the installation about system parameter requirements for your product. Note that the POLYCENTER Software Installation utility does not adjust system parameters.

Example

system parameter vaxcluster require 1 ; 
system parameter tty_classname require "TT" ; 
system parameter pagedyn consume 200 ; 

The statements in this example display the following messages:

 
This product requires the following system parameters 
    VAXCLUSTER value 1 
 
This product requires the following system parameters 
    TTY_CLASSNAME value TT 
 
This product requires the following system parameters 
    PAGEDYN add 200 


upgrade

The upgrade statement specifies product versions that must be available for a successful product upgrade. The upgrade function tests whether a version of the product is available.

Syntax

upgrade
{ version below version |
version maximum version |
version minimum version |
version required version |
version minimum version version below version |
version minimum version version maximum version } ;


Function Syntax

< upgrade
{ version below version |
version maximum version |
version minimum version |
version required version |
version minimum version version below version |
version minimum version version maximum version } >


OPTIONS

version below version

Indicates the smallest invalid product version. Use this option to specify that the product version must be less than (but not equal to) the specified version. You cannot use this option with either the version maximum or version required options. By default, there is no smallest invalid version.

version maximum version

Indicates a maximum product version that must be available. Use this option to specify that the product version must be less than or equal to the specified version. You cannot use this option with either the version below or version required options. By default, there is no maximum version.

version minimum version

Indicates a minimum product version that must be available. Use this option to specify that the product version must be greater than or equal to the specified version. You cannot use this option with the version required option. By default, there is no minimum version.

version required version

Indicates a required product version that must be available. Use this option to specify that a specific product version must be present. You cannot use this option with either the version below, version maximum, or version minimum options. By default, there is no required version.


DESCRIPTION

Statement

In a full, operating system, or platform PDF, the upgrade statement specifies which product versions must be available for a successful product upgrade. If there is no available version of the product installed, the POLYCENTER Software Installation utility ignores the upgrade statement and performs a new installation. If the upgrade statement is not present, there is no constraint on the available version of the product.

In a partial PDF, the upgrade statement is required to specify which product versions must be available for the partial kit to be applied successfully.

Function

The upgrade function tests whether a version of the product is available. If a version of the product is available, the function returns true. If a version of the product is not available, the function returns false.

See Also apply to
product
software

Example

product DEC VAXVMS ABC V5.5-2 partial ; 
    upgrade version minimum V5.5 version maximum V5.5-2 ; 
   .
   .
   .
end product; 

The upgrade statement in this example specifies that to install ABC Version 5.5--2, your system must be running at least ABC Version 5.5 and no higher than ABC Version 5.5--2.


Appendix A
Migrating from VMSINSTAL to the POLYCENTER Software Installation Utility

VMSINSTAL is an installation mechanism supplied by Digital. This appendix contains information about VMSINSTAL options and callbacks and their POLYCENTER Software Installation utility equivalents.

A.1 VMSINSTAL Options and Equivalents

Table A-1 lists some tasks that you may need to perform, the corresponding VMSINSTAL option, and the POLYCENTER Software Installation utility equivalent. Note that some VMSINSTAL options do not have an equivalent. In many cases, this is because the design of the POLYCENTER Software Installation utility eliminates the need for an equivalent.

Table A-1 VMSINSTAL Options and Equivalents
Task VMSINSTAL Option POLYCENTER Software Installation Utility Equivalent
Creating a file that specifies answers to installation questions OPTIONS A Create a product configuration file (PCF). This is similar to an auto-answer file in VMSINSTAL.
Specifying a temporary work directory OPTIONS AWD Specify the /WORK qualifier to the PRODUCT command.
Startup OPTIONS B¹ No equivalent.
Tracing callbacks during installation OPTIONS C² Use the /LOG and /TRACE qualifiers to the PRODUCT command. You can also use the /NOCOPY qualifier when debugging a product description file (PDF) to prevent the product material from being copied into the reference copy.
Manipulating product kits OPTIONS G Use the COPY/FORMAT=REFERENCE and COPY/FORMAT=SEQUENTIAL commands to manipulate product kits (see Chapter 5).
Suppressing VMSINSTAL prompts OPTIONS I² No equivalent.
Debugging a kit OPTIONS K² Use the /LOG and /TRACE qualifiers to assist in debugging a PDF.
Providing a log of installation operations OPTIONS L Use the /LOG and /TRACE qualifiers. This provides more information than OPTIONS L with VMSINSTAL.
Displaying or printing release notes OPTIONS N Use the release notes option to the file statement and the PRODUCT EXTRACT RELEASE_NOTES command. The release notes are created in the file DEFAULT.PCSI$RELEASE_NOTES in the current directory.
Performing an installation in test mode OPTIONS Q² No equivalent.
Installing a product in an alternate root OPTIONS R Use the /DESTINATION qualifier.
Pausing the installation at various points OPTIONS RSP² No equivalent.
Compiling information about the installation OPTIONS S² Use the /LOG and /TRACE qualifiers to the PRODUCT command.


¹OpenVMS startup use only
²Developer's use only

A.2 VMSINSTAL Callbacks and Equivalents

To install a product using VMSINSTAL, you create a command procedure named KITINSTAL.COM that makes callbacks to VMSINSTAL. If you are migrating from VMSINSTAL to the POLYCENTER Software Installation utility, refer to Table A-2, which lists the VMSINSTAL callbacks and their equivalents.

Table A-2 VMSINSTAL Callbacks and Equivalents
Task VMSINSTAL Callback Option POLYCENTER Software Installation Utility Equivalent
Adding an identifier to the rights database ADD_IDENTIFIER Use the rights identifier statement.
Prompting the installer for information ASK To confirm the completion of preinstallation tasks, use the confirm option to the information statement. The product text file (PTF) contains the prompt and help text.
Not recording responses to installation questions A No equivalent.
Forcing a Boolean answer B No equivalent.
Preceding prompt with blank line D No equivalent.
Disabling terminal echo E No equivalent.
Displaying help text before the prompt H The information statement.
Answer must be an integer I No equivalent.
Returning input in lowercase L No equivalent.
Returning input in the same case M No equivalent.
Indicating a null response is acceptable N No equivalent.
Ringing the terminal bell before the prompt R No equivalent.
Indicating the response can be a string S No equivalent.
Returning input in uppercase U No equivalent.
Indicating the response can be Ctrl/Z A No equivalent.
Determining whether a license for the product is installed on the system CHECK_LICENSE No equivalent. License management is outside the domain of the utility.
Determining whether the network is running CHECK_NETWORK No equivalent. If you use a statement that references the DECnet network, the utility ensures that the network is available.
Determining whether there is sufficient disk space on the target device CHECK_NET_UTILIZATION No equivalent. The utility ensures that sufficient disk space is available.
Determining whether a minimum version of software is present in the execution environment CHECK_PRODUCT_VERSION Use the version minimum option to the software statement.
Limiting an installation to specified versions of the OpenVMS operating system CHECK_VMS_VERSION Use the version minimum and version maximum options to the software statement, specifying DEC as the producer name, VAXVMS or AXPVMS as the base, and VMS as the product name.
Determining which is the most recent version of an image COMPARE_IMAGE You can manage file versions using the generation option to the file statement.
Determining whether the user has loaded the license for the product being installed on the system CONFIRM_LICENSE No equivalent. License management is outside the domain of the utility.
Providing for orderly exit from an installation CONTROL_Y No equivalent necessary; the utility provides this automatically.
Creating an account on the system CREATE_ACCOUNT Use the account statement.
Deleting obsolete files from a previous installation DELETE_FILE In full and operating system kits, the utility deletes files that are replaced during an upgrade. However, in a partial kit, you can remove obsolete files using the remove statement.
Locating files FIND_FILE If you want to determine whether an optional software product is available, use the software function. You do not need to determine whether a file is present before performing an operation that references it; the utility does this automatically.
Generating structure definition language (SDL) definition files GENERATE_SDL No equivalent.
Extracting the image file identification string for a file GET_IMAGE_ID If you want to determine the available version of a software product, use the software statement or function.
Obtaining a password for an account GET_PASSWORD No equivalent necessary; the utility provides this function.
Placing requirements on system parameters GET_SYSTEM_PARAMETER Use the system parameter statement.
Displaying messages to the user MESSAGE Use the information statement to display information about pre- and postinstallation tasks. You do not need to provide error messages and progress information; the utility does this automatically.
Patching an image as part of the installation PATCH_IMAGE Use the patch image statement.
Moving a shareable image's symbol table to the system shareable image library when the patch is complete I No equivalent necessary. The image library option to the file statement controls its replacement in the image library.
Creating a journal file of patches J No equivalent.
Saving old versions of the image file K No equivalent necessary. The utility deletes existing versions.
Moving the file to the SYS$SPECIFIC directory O No equivalent necessary. The placement of the file statement that originally described the image within a scope group determines its placement.
Reinstalling the image when the patch is complete R No equivalent necessary; the utility does this automatically.
Queuing a print job to SYS$PRINT PRINT_FILE No equivalent.
Invoking a command procedure of product-specific callbacks PRODUCT No equivalent.
Adding a command to the system DCL table PROVIDE_DCL_COMMAND Use the module statement with the type command parameter. You do not need to reinstall the system command table as a known image; the utility does this automatically.
Adding help to the DCL help library PROVIDE_DCL_HELP Use the module statement with the type help parameter.
Adding a new file to the system PROVIDE_FILE Use the file statement.
Placing the file in more than one location C No equivalent necessary.
Preserving old versions K No equivalent necessary. The utility deletes existing versions.
Adding the file to the SYS$SPECIFIC directory O Enclose the file statement in a scope processor group.
Specifying an input file that contains a list of logical names for the source files and their respective destinations T No equivalent necessary. Use one file statement for each file.
Adding a new image to the system PROVIDE_IMAGE Use the file statement. The utility can distinguish whether a file is a valid executable image.
Placing the file in more than one location C No equivalent necessary.
Dynamically patching ECOs into the new image file E No equivalent necessary. You should package the file with the correct ECO numbers already set.
Moving a shareable image's symbol table to the system shareable image library I Use the image library option to the file statement.
Preserving old versions K No equivalent necessary. The utility deletes existing versions.
Moving the file to the SYS$SPECIFIC directory O Enclose the file statement in a scope processor group.
Specifying an input file that contains a list of logical names for the source image files and their respective destinations T No equivalent necessary. Use one file statement for each file.
Changing the file name and file type of all versions of a file RENAME_FILE Use the archive option of the file statement to preserve an existing version of a file during an upgrade.
Restoring save sets of a product that is divided among several save sets RESTORE_SAVESET No equivalent necessary.
Running an image during installation RUN_IMAGE Use the execute statement or the assemble execute option to the file statement.
Specifying a UIC or protection code for product files SECURE_FILE Use the owner and protection options to the directory and file statements.
Modifying the access control list (ACL) of a device, directory, or file SET ACL Use the access control option of the file and directory statements.
Determining the default case (upper or lower) in which text from the installer is returned to the installation procedure SET ASK_CASE No equivalent.
Running an installation verification procedure (IVP) SET IVP No equivalent necessary. You can specify the execute test statement and invoke the functional test for a product with the /TEST qualifier to the PRODUCT INSTALL command.
Calling a product's installation procedure after files have been moved to their target directories SET POSTINSTALL Depending on your application, you can use the execute postinstall statement.
Purging files replaced by an installation SET PURGE No equivalent necessary. The utility deletes existing versions.
Rebooting the system after the installation SET REBOOT No equivalent.
Ensuring a high level of installation success SET SAFETY No equivalent necessary. The utility provides the necessary disk management and reliability features.
Rebooting the system after the installation SET SHUTDOWN No equivalent.
Specifying a product-specific startup command procedure SET STARTUP Use the execute start statement.
Editing text files SUMSLP_TEXT Use the patch text statement.
Identifying installation peculiarities TELL_QA No equivalent necessary.
Exiting the installation procedure UNWIND No equivalent necessary. The utility controls the flow of the installation.
Updating an existing user account UPDATE_ACCOUNT Use the account statement to modify existing user accounts.
Making a file available for updating by copying it to a working directory UPDATE_FILE No equivalent necessary.
Modifying an identifier in the rights database UPDATE_IDENTIFIER Use the rights identifier statement to modify an existing rights identifier.
Updating a library UPDATE_LIBRARY Use the module statement with the appropriate parameter for the type of library you are updating. To update the shareable image library, use the image library option to the file statement. No equivalent exists to update RSX libraries.


This glossary lists and defines the terms used in this guide.


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

[HR]

  5952P007.HTM
  OSSG Documentation
   3-DEC-1996 08:58:52.16

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal