Digital PDFs

AA-LA29A-TE

December 1988

43 pages

Original

1.4MB

Document:	VMS 5.0 Install Utility Manual 198804
Order Number:	AA-LA29A-TE
Revision:
Pages:	43
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.0/AA-LA29A-TE_VMS_5.0_Install_Utility_Manual_198804.pdf

OCR Text

VMS Install Utility Manual
Order Number: AA-LA29A-TE

April 1988
This document describes the Install Utility for the VMS operating system.

Revision/Update Information:

This manual supersedes the VAX/VMS
Install Utility Reference Manual, Version

4.0.
Software Version:

digital equipment corporation
maynard, massachusetts

VMS Version 5.0

April 1988
The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright © 1988 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

~urnuo~u TM
ZK4545

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA 8r. PUERTO Rico*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digitals local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
* Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.

Production Note
This book was produced with the VAX DOCUMENT electronic publishing
system, a software tool developed and sold by DIGITAL. In this system,
writers use an ASCII text editor to create source files containing text and
English-like code; this code labels the structural elements of the document,
such as chapters, paragraphs, and tables. The VAX DOCUMENT software,
which runs on the VMS operating system, interprets the code to format the
text, generate a table of contents and index, and paginate the entire document.
Writers can print the document on the terminal or line printer, or they can use
DIGITAL-supported devices, such as the LN03 laser printer and PostScript®
printers (PrintServer 40 or LN03R ScriptPrinter), to produce a typeset-quality
copy containing integrated graphics.

®l

PostScript is a trademark of Adobe Systems, Inc.

Contents
PREFACE

vii

NEW AND CHANGED FEATURES

INSTALL Description

INS-1

REASONS TO INSTALL IMAGES

INS-1

ASSIGNING ATTRIBUTES TO KNOWN IMAGES

INS-2

INSTALLING IMAGES WITH THE SHARED ATTRIBUTE

INS-3

INSTALLING IMAGES WITH PRIVILEGES
Privileged Executable Images
Privileged Shareable Images

INS-3
INS-4
INS-4

INSTALLING EXECUTE-ONLY IMAGES
Execute-Only Main Programs
Execute-Only Shareable Images

INS-4
INS-4
INS-5

FILE SPECIFICATIONS FOR INSTALLED IMAGES
Defining Logical Names for Shareable Image Files
Effect of Installing Images on the DCL Command RUN

INS-5
INS-5
INS-6

INSTALLING SHARED IMAGES IN MA780 MULTIPORT
MEMORY

INS-6

DELETING KNOWN IMAGES AND DISMOUNTING
VOLUMES

INS-6

SUMMARY OF INSTALL COMMANDS

INS-7

4.1
4.2

5
5.1
5.2

6
6.1
6.2

INSTALL Usage Summary

INS-8

Contents

INSTALL Commands

INS-9
ADD
CREATE
DELETE
EXIT
HELP
LIST
PURGE
REMOVE
REPLACE

INS-10
INS-13
INS-15
INS-16
INS-17
INS-18
INS-22
INS-23
INS-24

INDEX

TABLE
INS-1

INSTALL Command Summary

INS-7

Preface
Intended Audience
This manual is intended for VMS system managers, operators, and system
programmers.

Document Structure
This document consists of the following three sections:
•

Description-Provides a full description of the Install Utility (INSTALL).

•

Usage Summary-Outlines the following INSTALL information:
-Invoking the utility
-Exiting from the utility
-Restrictions or privileges required

•

Commands-Describes INSTALL commands, including format,
parameters, and examples.

Associated Documents
For additional information on topics covered in this document, see the
following manuals:

•

VMS DCL Dictionary

•

Guide to Setting Up a VMS System

•

VMS System Messages and Recovery Procedures Reference Manual

•

VMS Linker Utility Manual

•

VMS System Generation Utility Manual

•

VMS System Services Reference Manual

vii

Preface

Conventions
Convention

Meaning
In examples, a key name (usually abbreviated)
shown within a box indicates that you press
a key on the keyboard; in text, a key name is
not enclosed in a box. In this example, the key
is the RETURN key. (Note that the RETURN
key is not usually shown in syntax statements
or in all examples; however, assume that you
must press the RETURN key after entering a
command or responding to a prompt.)

viii

CTRL/C

A key combination, shown in uppercase with a
slash separating two key names, indicates that
you hold down the first key while you press the
second key. For example, the key combination
CTRL/C indicates that you hold down the key
labeled CTRL while you press the key labeled C.
In examples, a key combination is enclosed in a
box.

$SHOW TIME
05-JUN-1988 11 :55:22

In examples, system output (what the system
displays) is shown in black. User input (what
you enter) is shown in red.

$ TYPE MYFILE.DAT

In examples, a vertical series of periods, or
ellipsis, means either that not all the data that
the system would display in response to a
command is shown or that not all the data a
user would enter is shown.

input-file, ...

In examples, a horizontal ellipsis indicates
that additional parameters, values, or other
information can be entered, that preceding
items can be repeated one or more times, or
that optional arguments in a statement have
been omitted.

[logical-name]

Brackets indicate that the enclosed item is
optional. (Brackets are not, however, optional
in the syntax of a directory name in a file
specification or in the syntax of a substring
specification in an assignment statement.)

quotation marks
apostrophes

The term quotation marks is used to refer
to double quotation marks ( " ). The term
apostrophe ( ' ) is used to refer to a single
quotation mark.

New and Changed Features
The Install Utility (INSTALL) has a new DCL command line interface. To
invoke the utility, enter the command INSTALL at the DCL prompt.
Note that Version 4.0 command procedures defining INSTALL as a foreign
command (INSTALL :== $SYS$SYSTEM:INSTALL/COMMAND_MODE)
will execute successfully with the DCL command interface.
If you wish to continue using the Version 3.0 INSTALL command syntax,
which is incompatible with commands described in this manual, enter the
command:
$RUN SYS$SYSTEM:lNSTALL

Alternatively, you can enter the command:
$ MCR _j_NSlAL,_,

Please be aware, however, that DIGITAL does not guarantee that
Version 3.0 INSTALL command syntax will receive future development.
DIGITAL recommends that you convert to the command syntax presented in
this manual.

INSTALL Description
The Install Utility (INSTALL) improves the performance of executable
and shareable images, especially those that run frequently, usually run
concurrently with several processes, or require special privileges.
The system defines installed images on internal data structures called known
file lists. Each entry in the known file list identifies the file name of the
installed file and the attributes with which it was installed. A separate
known file list exists for all installed images whose device, directory, and
file type are identical. For example, all installed images with the file name
DISK$VOLUME:[MAIN]filename.EXE would be on one known file list, and
all installed images with the file name DISK$VOLUME:[TEST]filename.EXE
would be on another known file list.
Known file lists last only while the system is operating. If the system is
shut down or fails for any reason, you must reinstall all known images
after the system is rebooted. For this reason, the site-independent startup
command procedure, SYS$SYSTEM:STARTUP.COM, includes a series of
INSTALL commands that install certain system programs as known images.
You are encouraged to include in the site-specific command procedure,
SYS$MANAGER:SYSTARTUP.COM, additional INSTALL commands that
install selected images.

Reasons to Install Images
The Install Utility allows you to do the following:
•

Make programs that require enhanced privileges available for general use.

•

Conserve memory by creating shared images.

•

Improve system performance.

A nonprivileged process can perform the privileged functions of an executable
image when it is installed as a privileged image. A user-written system
service also assumes the privileges it requires when you install it as a
privileged, shareable image.
Shared images conserve memory because only one copy of code needs to
be in memory at any time, and many users can access the code concurrently.
The Install Utility is the only way to create shared images. Use the /SHARED
qualifier to install shared images.
System performance improves when programs are installed because the
VMS operating system opens any installed file by file ID rather than by
file name, thus eliminating costly directory operations. Installing images as
header-resident further enhances performance because the system avoids the
overhead of a directory operation to read the image header into memory.
Frequently accessed images, critical to a site's operations, can be installed as
open images. This makes the image resident in memory and entirely avoids
the overhead of opening a file.

INS-1

INSTALL Description

Because an installed file requires system resources, such as nonpaged dynamic
memory, install those files that most improve system performance and siterequirements. The Install Utility's LIST command provides information about
installed images that helps you evaluate the merits of installing images. For
example, the LIST command calculates the number of times each image is
accessed, and shows the number of concurrent accesses, so you can determine
if the installation of the images is justified given the expense of installation.

Assigning Attributes to Known Images
By specifying appropriate qualifiers to INSTALL commands, you can assign
known images the following attributes:

INS-2

•

Permanently open-Directory information on the image file remains
permanently resident, eliminating the usual directory search required
to locate a file. The cost of keeping an image file permanently open is
approximately one page of paged dynamic memory per file.

•

Header resident-The header of the image file (native images only)
remains permanently resident, saving one disk 1/0 operation per file
access. For images with single-block file headers, the cost is less than
one page of paged dynamic memory per file; for images with multiblock
headers, the cost varies according to the header block count. The images
must also be declared permanently open.

•

Privileged-Amplified privileges are temporarily assigned to any process
running the image (executable images only), permitting the process
to exceed its user authorization file (UAF) privilege restrictions during
execution of the image. In this way, users with normal privileges can run
programs that require higher-than-normal privileges.

•

Protected-A shareable image contains protected code, that is, code that
runs in Kernel or Executive mode but that can be called by a user-level
image. Protected images must be declared shared.

•

Shared-More than one user can access the read-only and non-copyon-reference read/write sections of the image concurrently, so that only
one copy of those sections ever need be in physical memory. (Copy-onreference sections always require a separate copy for each process.) The
image is implicitly declared permanently open.

•

Writable-When a shared non-copy-on-reference writable section is
removed from physical memory (for paging reasons or because no
processes are referencing it), it is written back to the image file. Any
updates made by processes mapped to the section, therefore, are
preserved (while the initial values are lost). The image must also be
declared shared.

INSTALL Description

Installing Images with the Shared Attribute
Before installing an image with the shared attribute (using the /SHARE
qualifier), you must understand the distinction between executable and
shareable images:
•

An executable image is one linked with the /EXECUTABLE qualifier (or
without the /SHAREABLE qualifier) of the VMS Linker. For information
on the VMS Linker, refer to the VMS Linker Utility Manual.

•

A shareable image is one linked with the /SHAREABLE qualifier of the
VMS Linker; it must subsequently be linked into an executable image to
be used. (Shareable images are sometimes referred to as linkable images,
because they can be specified-implicitly or explicitly-as input files
to the link of another file.) A shareable image is not copied into the
executable images that link with it. Thus, only one copy of the shareable
image need be on disk, no matter how many executable images have
linked with it.

When you install an image with the shared attribute, permanent system
global sections are created. Execution of non-copy-on-reference global
sections requires only one copy per section to be in physical memory, no
matter how many processes are running the image to which the sections
belong.
The number of images you can install with the /SHARED qualifier is
restricted by the GBLP AGES and GBLSECTIONS system parameters. See
the description of the System Generation Utility in the VMS System Generation
Utility Manual.
When an image is not installed, or is installed without the shared attribute,
each process running the image requires private sections in memory. (A
shareable image linked to an executable image need not be installed to be
executed. At image execution time, the system creates private sections from
the shareable image. The only exception is that a shareable image containing
a writable non-copy-on-reference section must be installed as a known image
with the shared and writable attributes.)

Installing Images with Privileges
The VMS operating system allows images to execute in an enhanced privilege
environment through the following mechanisms:
•

You can install existing executable images with extra privileges to allow a
nonprivileged process to perform the privileged functions of the image.

•

You can install privileged shareable images. Privileged shareable images
are used to implement user-written system services, thereby allowing
nonprivileged images to execute select portions of privileged code without
enhancing the privileges of each image that uses the privileged portion of
code.

INS-3

INSTALL Description

4.1

Privileged Executable Images
Install executable images with enhanced privileges by using the
/PRIVILEGED qualifier. Only images linked with the VMS Linker qualifiers
/NODEBUG and /NOTRACE should be installed with enhanced privilege.
Installing other images with enhanced privilege can compromise system
security.

4.2

Privileged Shareable Images
The VMS operating system supports user-written system services through a
mechanism called privileged shareable images. See the VMS System Services
Reference Manual for a description of how to create privileged shareable
images. You must link a privileged shareable image with the /PROTECT
command qualifier or the /OPTIONS positional qualifier of the VMS Linker,
so that the image acquires its particular form of enhanced privileges.
•

Use the /PROTECT command qualifier when all parts of an image require
protection.

•

Use the /OPTIONS positional qualifier when only part of a privileged
shareable image requires protection.

Then install the privileged shareable image with the Install Utility, specifying
both the /PROTECTED and /SHAREABLE qualifiers. If you do not follow
all these steps, you will prevent successful activation of a privileged shareable
image.

Installing Execute-Only Images
The image activator allows execution of images to which the caller has
EXECUTE but not READ access. The support differs slightly for main
programs and shareable images.
The /EXECUTE_ONLY qualifier has meaning only for main programs. A
main program installed with this qualifier is capable of activating shareable
images to which the process has EXECUTE but not READ access. The image
activator ignores this qualifier when it is used on images other than main
programs.

5.1

Execute-Only Main Programs
When a process runs a main program to which it has EXECUTE but not READ
access, the image activator enters a restricted mode of operation similar to
that entered when a privileged program is run. That is, all shareable images
activated during the life of the execute-only program must be installed. In
addition, the image activator directs VMS Record Management Services
(RMS) to use only "trusted" logical names when opening image files. Logical
names associated with EXEC or KERNEL mode are trusted. User-mode and
supervisor-mode names are not.

INS-4

INSTALL Description

5.2

Execute-Only Shareable Images
Execute-only shareable images can be executed only in the restricted
environment established when a main program that references them is run.
The main program must be installed with the /EXECUTE_QNLY qualifier,
and all shareable images the program references must be installed.
When an installed execute-only shareable image is run, the image activator
enters the same restricted mode of operation that it enters when it detects an
execute-only main program. That is, only "trusted" logical names are used by
VMS RMS.

File Specifications for Installed Images
When using the INSTALL commands, file specifications must name existing
executable or shareable images. VMS RMS resolves each file specification
using the following defaults:
•

A device and directory type of SYS$SYSTEM

•

A file type of EXE

Unless a file shares these defaults, specify a device and directory name as well
as a file type with each file name. Do not include a version number in the
file specification. The highest existing version is always used. Specification
of a version number produces unpredictable results because file lookups for
known images ignore version numbers.
All images installed with the /SHARE qualifier must be in directory
SYS$SHARE, unless you define a logical name for the image. (SYS$SHARE
is equivalent to SYS$LIBRARY.)

6.1

Defining Logical Names for Shareable Image Files
After installing a shareable image, define a logical name for it if it is not
located in directory SYS$SHARE. For example, if the file specification for
STATSHR is SYS$SHARE:STATSHR.EXE, no DEFINE command is necessary.
But if you put STATSHR in SYS$DEVICE:[TEST], you must define STATSHR
as a logical name before running an executable image that calls it. The logical
name must be the same one that was used as the input file specification
for the shareable image when it was linked (this is the same name used in
installation). For example:
$DEFINE STATSHR SYS$SYSDEVICE: [TEST]STATSHR

With logical names, one shareable image can be substituted for another
without requiring the calling executable image to relink. You redefine the
logical name of the shareable image. For example, the following statement
redefines the file name STATSHR. It becomes the logical name of the
shareable image SYS$SYSDEVICE:[MAIN]STATSHR.EXE for executable
images calling STATSHR.
$DEFINE STATSHR SYS$SYSDEVICE: [MAIN]STATSHR

(Logical name redirection in the process or group logical name table is ignored
when you run a privileged executable image. Only logical names that can be
redirected by privileged users are allowed.)

INS-5

INSTALL Description

If the new image is installed with the /SHARED qualifier, executable images
linked against the old image are mapped to global sections for the new image.
Otherwise, they are mapped to private sections for the new image.

The old and new images can have the same name, but they must reside
in different directories. You should not substitute one version of a file for
another in the same directory. (Use the REPLACE command to update file
versions.)

6.2

Effect of Installing Images on the DCL Command RUN
The DCL command RUN parses search lists in a manner that favors installed
images. On its first pass through the search list the RUN command looks up
images on known file lists and executes each installed image that it finds. On
its second pass through the search list, the RUN command looks up images
on disk and executes those images. In essence, then, installing an image alters
the ordering of a search list.

Installing Shared Images in MA780 Multiport Memory
To install a shared image so that the global sections reside in a MA780
multiport memory unit, you enter the DCL command DEFINE to create a
logical name of the following form:
GBL$filename shrmem-name:filename

The following example ensures that any global sections created for an image
whose file name is STATSHR reside in the MA780 multiport memory unit
whose logical name is SHRMEMl:
$DEFINE GBL$STATSHR SHRMEM1:STATSHR
$ INSTALL
INSTALL> ADD /OPEN/SHARED STATSHR

To create global sections in memory shared by multiple processors requires
the SHMEM privilege.

Deleting Known Images and Dismounting Volumes
System operations are affected by the following characteristics of known
images:
•

Deletion-A known image is not deleted as soon as the INSTALL
DELETE command is entered. The deletion occurs only after all processes
using the image have released it.

•

Dismounting-A volume cannot be dismounted while any known file
lists associated with it contain entries.

To dismount a volume, you must not only delete all known images associated
with it. You must wait for all processes using those images to release them
and for the system to write writable images back to their files. You can use
the DCL command SHOW DEVICES/FILES to determine the status of the
files.

INS-6

INSTALL Description

Summary of INSTALL Commands
Table INS-1 summarizes INSTALL command functions.
Table INS-1

INSTALL Command Summary

Command

Function

ADD

Installs the specified image as a known file entry

CREATE

Installs the specified image as a known file entry (identical to
ADD command)

DELETE

Deletes a known file entry

EXIT

Exits from INST ALL

HELP

Describes (interactively) how to use INST ALL

LIST

Displays a description of each specified known file entry, global
sections, and the addresses of known file entry data structures

PURGE

Deletes all known file entries installed without the /NOPURGE
qualifier

REMOVE

Deletes a known file entry (identical to DELETE command)

REPLACE

Associates a known file entry with the latest version of the
image file or modifies the attributes of an installed image

INS-7

INSTALL Usage Summary
Use the Install Utility (INSTALL) to enhance the performance of selected
executable and shareable images, to assign enhanced privileges to images,
and to support user-written system services. The system stores the name
and attributes of installed images on known file lists.

FORMAT
PARAMETER

INSTALL [command}
command
Specifies an INSTALL command. This parameter is optional. If no command
is specified, the utility displays its prompt and waits for command input.

usage summary
To invoke INSTALL, enter the DCL command INSTALL at the DCL prompt
as follows:
$ INSTALL

The utility responds with the following prompt:
INSTALL>

You can then perform INSTALL operations by entering the appropriate
INSTALL commands. Alternatively, you can enter a single INSTALL
command on the same line as the command that invokes the utility, for
example:
$ INSTALL LIST/FULL SYS$SYSTEM:LOGINOUT

To exit from the Install Utility, enter the EXIT command at the INSTALL>
prompt or press CTRL/Z. Either method returns control to the DCL command
level.
The Install Utility requires that you have the CMKRNL privilege to
invoke it. It requires the SYSGBL privilege to create system global
sections and the PRMGBL privilege to create permanent global sections.

INS-8

INSTALL
INSTALL Commands

INSTALL
COMMANDS

This section describes the INSTALL commands and provides examples of
their use.
ADD
CREATE
DELETE
EXIT
HELP
LIST
PURGE
REMOVE
REPLACE

INS-9

INSTALL
ADD

ADD
Installs the specified image file as a known image.

FORMAT
PARAMETER

ADD

file-spec

file-spec
Names the file specification of an image to be installed as a known image.
The file specification must name an existing executable or shareable image. If
you omit the device and directory specification, the default SYS$SYSTEM is
used. The default file type is EXE. A version number must not be specified.

QUALIFIERS

/[NO]ACCOUNTING
Allows you to enable image-level accounting for selected images when
image accounting is disabled on the system (with the DCL command SET
ACC /DISABLE=IMAGE). When image accounting is enabled on the system,
it logs all images. The /NOACCOUNTING qualifier has no effect.

/[NO]EXECUTE_ONL Y
The /EXECUTE_ONLY qualifier is only meaningful to main programs.
It allows the image to activate shareable images to which the user has
EXECUTE access but has no READ access. All shareable images referenced
by the program must be installed, and VMS RMS uses "trusted" logical
names, those created for use in EXEC or KERNEL mode.
You may not specify this qualifier for an executable image linked with the
/TRACEBACK qualifier.

/[NO]HEADER_RESIDENT
Installs the file as a known image with a permanently resident header (native
mode images only). The image is made permanently open even if /OPEN is
not specified.

/[NO]LOG
Lists the newly added known file entry along with any associated global
sections created by the installation.

/[NO]OPEN
Installs the file as a permanently open known image.

INS-10

INSTALL
ADD
/PRIVILEGED[=(priv-name[, ... ])]
Installs the file as a known image with the privileges specified (executable
images only). Then, if the image is not located on the system volume, the
image is made permanently open even if /OPEN is not specified.
You can specify one or more of the following privilege names:
ACNT

ALLS POOL

ALTPRI

BUGCHK

BYPASS

CM EXEC

CMKRNL

DETACH

DIAGNOSE

EXOUOTA

GROUP

GRPNAM

GRPPRV

LQG_IO

MOUNT

NETMBX

OPER

PFNMAP

PHY_IO

PRMCEB

PRMGBL

PRMMBX

PSWAPM

READALL

SECURITY

SETPRV

SHMEM

SYSGBL

SYSLCK

SYSNAM

SYSPRV

TM PM BX

VO LP RO

WORLD

You may not specify this qualifier for an executable image linked with the
/TRACEBACK qualifier.

/[NO]PROTECTED
Installs the file as a known image that is protected from user-mode and
supervisor-mode write access. You can only write into the image from
EXEC or KERNEL mode. The /PROTECTED qualifier together with the
/SHARE qualifier are used to implement user-written services, which become
privileged shareable images.

/[NO]PURGE
Specifies that the image can be removed by a PURGE operation; if you do
not specify /PURGE, it can be removed only by a DELETE or REMOVE
operation. /NOPURGE is the default form of the qualifier.

/[NO]SHARED
Installs the file as a shared known image and causes creation of global
sections for the image. The image is made permanently open even if /OPEN
is not specified.

/[NO]WRITABLE
Installs the file as a writable known image as long as you also specify the
/SHARED qualifier. The /WRITABLE qualifier is automatically negated if the
/NOSHARED qualifier is specified.

INS-11

INSTALL
ADD

EXAMPLES
i]

INSTALL> ADD /OPEN/SHARED WRKD$: [MAIN]STATSHR

The command in this example installs the image file STATSHR as a
permanently open, shared known image.
~

INSTALL> ADD /OPEN/PRIVILEGED=(GROUP,GRPNAM) GRPCOMM

The command in this example installs the image file GRPCOMM as a
permanently open known image with the privileges GROUP and GRPNAM.
Any process running GRPCOMM receives the GROUP and GRPNAM
privileges for the duration of the execution of GRPCOMM. The full name
of GRPCOMM is assumed to be SYS$SYSTEM:GRPCOMM.EXE.
~

INSTALL> ADD /LOG GRPCOMM

The command in this example installs the image file GRPCOMM as a known
image and then displays the newly added known file entry.

INS-12

INSTALL
CREATE

CREATE
Installs the specified image file as a known image. The CREA TE command
is synonymous with the ADD command.

FORMAT
PARAMETER

CREATE

file-spec

QUALIFIERS

/[NO]ACCOUNTING
Allows you to enable image-level accounting for selected images when
image accounting is disabled on the system (with the DCL command SET
ACC/DISABLE=IMAGE). When image accounting is enabled on the system,
it logs all images. The /NOACCOUNTING qualifier has no effect.

/[NO]EXECUTE_ONL Y
The /EXECUTE_ONLY qualifier is meaningful only to main programs.
It allows the image to activate shareable images to which the user has

EXECUTE access but has no READ access. All shareable images referenced
by the program must be installed, and VMS RMS uses "trusted" logical
names, those created for use in EXEC or KERNEL mode.
You may not specify this qualifier for an executable image linked with the
/TRACEBACK qualifier.

/[NO]HEADER_RESIDENT
Installs the file as a known image with a permanently resident header (native
mode images only). The image is made permanently open even if /OPEN is
not specified.

/[NO]LOG
Lists the newly created known file entry along with any associated global
sections created by the installation.

/[NO]OPEN
Installs the file as a permanently open known image.

/[NO]PRIVILEGED[=(priv-name[, .. .])]
Installs the file as a known image with the privileges specified (executable
images only). Then, if the image is not located on the system volume, the
image is made permanently open even if /OPEN is not specified. You
may not specify this qualifier for an executable image linked with the
/TRACEBACK qualifier.

INS-13

INSTALL
CREATE

/[NO]PURGE
Specifies that the image can be removed by a PURGE operation; if you do
not specify /PURGE, it can be removed only by a DELETE or REMOVE
operation. (/NOPURGE is the default form of the qualifier.)

/[NO]SHARED
Installs the file as a shared known image and causes creation of global
sections for the image. The image is made permanently open even if /OPEN
is not specified.

/[NO]WRITABLE
Installs the file as a writable known image as long as you also specify the
/SHARED qualifier. The /WRITABLE qualifier is automatically negated if the
/NOSHARED qualifier is specified.

EXAMPLES

INSTALL> CREATE /OPEN/SHARED WRKD$: [MAIN]STATSHR

The command in this example installs the image file STATSHR as a
permanently open shared known image.
~

INSTALL> CREATE /OPEN/PRIVILEGED=(GROUP,GRPNAM) GRPCOMM

INSTALL> CREATE /LOG GRPCOMM

The command in this example installs the image file GRPCOMM as a known
image and then displays the newly created known file entry.

INS-14

INSTALL
DELETE

DELETE
Deletes a known image.

FORMAT
PARAMETER

DELETE

file-spec

file-spec
Names the file specification of an image installed as a known image.

QUALIFIERS

None.

DESCRIPTION

The DELETE command deletes an entry from the known image file list.
The image's entry on the known file list and any global sections created
for the image are deleted. The image itself (that is, the image file) remains
unaffected. Writable global sections are written back to disk upon their
removal as known images.
If a process is accessing global sections when the DELETE command is
entered, the global sections are deleted only after the operation initiated
by the process completes. However, once the command is entered, no
additional processes can access the global sections because they are "marked
for deletion."

The DELETE command is identical to the REMOVE command.

EXAMPLE
INSTALL> DELETE WRKD$: [MAIN]STATSHR

The command in this example deletes the entry for the image STATSHR from
the known file list.

INS-15

INSTALL
EXIT

EXIT
Terminates INST ALL and returns control to the DCL command level. You
can also exit from INST ALL by pressing CTRL/Z.

FORMAT

EXIT

PARAMETERS

None.

QUALIFIERS

None.

INS-16

INSTALL
HELP

HELP
Interactively displays information about how to use INST ALL.

FORMAT

HELP

PARAMETER

[command]

command
Specifies the name of a command for which help infomation is to be
displayed. If you omit a command name, a list of commands is displayed,
and you are prompted for a command name.

EXAMPLES

INSTALL> HELP

The command in this example displays a list of INSTALL topics and a Topic?
prompt. Any topic from the list can be entered at the prompt.
INSTALL> HELP LIST
LIST
For display of a one-line description of the specified known image, or if
no file is specified, then for all known images. Use with /FULL to obtain
a multiline description.
Format:

LIST [file-spec] /qualifier
QUALIFIER COMBINATION

BEHAVIOR

LIST [file-spec]
LIST

List the known file entry for file-spec
List all entries

Additional information available:
Qualifiers
/FULL
/GLOBAL

/STRUCTURE

/SUMMARY

The command in this example displays information on the LIST command.

INS-17

INSTALL
LIST

LIST
Displays a description of each specified known image or (if no file is
specified) all known images.

FORMAT
PARAMETER

LI ST [file-spec]
file-spec
Names the file specification of an image installed as a known image. If you
omit the file specification, INSTALL displays all known file entries.

QUALIFIERS

/FULL
Displays a multiline description of the specified known image, including the
number of accesses, the number of concurrent accesses, and the number of
global sections created. The /FULL qualifier with the /GLOBAL qualifier
shows information on global sections, plus owner and protection codes and
access control entries, if set.

/GLOBAL
Lists global sections for any specified shared image, or if you omit the file
specification, lists all global sections.

/STRUCTURE
Lists addresses of known file entry data structures.

/SUMMARY
Used with the /GLOBAL qualifier; displays a summary of global section
and global page usage on the system, for local and shared memory global
sections.

DESCRIPTION

INS-18

You can use the LIST command with the /FULL qualifier to display
information that is useful in "tuning" the known file database. For example,
a high entry access count for an image may indicate that system performance
could benefit if the image were installed /OPEN. Similarly, high entry access
counts for an image may indicate that installing the image /SHARED-that
is, with global sections-could improve performance. For a description of
global sections and global pages, including information on how to estimate
the size of installed images, see the VMS System Services Reference Manual.

INSTALL
LIST

EXAMPLES

D INSTALL> LIST
The command in this example displays a single-line description of all known
images. The description includes the file specification of the known image
and its attributes.
DISK$VAXVMSRL4:<SYSO.SYSEXE>.EXE
BLISS32;2tt
Open8
Shar
CDU;4
Open
COPY;4
Open
Shar
DCL;2
Open
Shar
MOUNTSHR;6
Open
Shar
SYSMGTMSG;1

Priv
Lnkbl
Prot

«t File specification of the known image.
8

Attribute of known image, as follows:
Attribute

Meaning

ACNT

Image accounting is enabled for the image (/ACCOUNTING)

CMODE

Image is compatibility mode, set by the V AX-11 RSX Linker

HOR

Image header is permanently resident (/HEADER_RESIDENT)

LNKBL

Image is not executable; it is a shareable (linkable) image, set
by the VMS Linker

NOPURG

Image cannot be removed by a PURGE operation; it can only
be removed by a DELETE or REMOVE operation (/NOPURGE)

OPEN

Image is permanently open (/OPEN)

PROT

Image contains protected code (/PROTECTED)

PRV

Image has privileges (/PRIVILEGE=)

SHAR

Image is shared (/SHARED)

SHM

Image has global sections installed in shared memory
(/SHARED)

WRT

Image is writable (/WRIT ABLE)

XONLY

Only execute access to image is allowed (/EXECUTE_QNLY)

INSTALL> LIST /FULL LOGINOUT

The command in this example displays a multiline description of the known
image LOGINOUT.
DISK$VAXVMSRL5:<SYSO.SYSEXE>.EXE
LOGINOUT;3
Open Hdr
Shar Priv
Entry access count
= 44 «t
Current I Maximum shared = 3 I 5 8
Global section count
= 2 _,
Privileges = CMKRNL SYSNAM TMPMBX EXQUOTA SYSPRV ~

INS-19

INSTALL
LIST

Number of times known file entry has been accessed by this node since it
became known.

The first number indicates the current count of concurrent accesses of the
known file. The second number indicates the highest count of concurrent
accesses of the file since it was installed. This number appears only if the
image is installed with the /OPEN qualifier.

Number of global sections created for the known file; appears only if the
image is installed with the /SHARED qualifier.

Translation of the privilege mask; appears only if the image is installed
with privileges.

INSTALL>LIST /GLOBAL

The command in this example displays all global sections for shared images.
System Global Sections 0
LBRSHR_004 8 (01000001) 0 WRT 0 PRM 0 SYS 0 Pagcnt/Ref cnt=1/08
CRFSHR_003
(010003E8) WRT PRM SYS Pagcnt/Ref cnt=1/1

27 Global Sections Used, 828/3268 Global Pages Used/Unused 0

Display of global sections in local memory.

Name of global section.

Version number (in hexadecimal) of global section; for shareable
images only, the high-order byte (01 in CRFSHR_003) contains major
identification, and low-order bytes (0003E8 in CRFSHR_003) contain
minor identification determined by the programmer at link time. For
executable images, the number is a known unique value determined by
the system.

G The global section is writable.

INS-20

The global section is permanent; TMP indicates a temporary global
section, which would be created by a program other than the Install
Utility.

The global section is systemwide; GRP and a group number indicate a
groupwide section, which would be created by a program other than
Install.

Number of pages in the section and number of page table entries
currently mapped to this global section. See the VMS System Services
Reference Manual for a detailed discussion.

Number of global sections created, number of global pages used, and
number of global pages unused in local memory. Note that, because of
arithmetic rounding, the number of global sections created will sometimes
be greater than the SYSGEN parameter GBLSECTIONS. When the size of
the system header is being computed, the values of the GBLSECTIONS
and SYSMWCNT parameters are combined with the size of the fixed
part of the process header. The result is rounded up to the next page
boundary. This rounding process sometimes adds space to the global
section table, depending on the values of the two SYSGEN parameters

INSTALL
LIST

and the amount of system paging that preceded the running of INSTALL
to create all of the global sections.
~

INSTALL> LIST/GLOBAL/FULL

The command in this example displays a complete listing of global sections
for shared images. The /FULL qualifier adds owner and protection codes to
the display.
System Global Sections
NM_MAILSHR_003 (741A6919)
NM_MAILSHR_002 (741A6919)
NM_MAILSHR_001 (741A6919)
Owner:
Protection:

PRM SYS
PRM SYS
PRM SYS

Pagcnt/Ref cnt=10/0
Pagcnt/Ref cnt=1/0
Pagcnt/Ref cnt=11/0

[1,4] 0
S:RWED,O:RWED,G:RWED,W:RE fJ

UIC of the owner of the global section

fJ The type of access allowed for the image
~

INSTALL>LIST /GLOBAL

When you issue the command in this example, the display shows global
sections in multiport memory in addition to the global sections for shared
images.
System Global Sections 0

Global Sections in Multiport Memory "SHM" fJ
VMSRTL_001
(010003FC)
Basepfn/Pagcnt=00000000/7 0
Port 0 PTE Ref cnt=35 0

PRM SYS

Creator Port=O 8

659 Global Pages Used, 1329 Global Pages Unused
15 Global Sections Used, 17 Global Sections Unused Ci)

Display of global sections in local memory.

fJ Display of global sections in shared multiport memory unit named SHM
by the system manager; one such display appears for each attached
multiport memory unit.

Number of the port from which the global section was created.

Base page frame number (in hexadecimal) and number of pages in the
section.

Page table entry (PTE) reference count; one appears for each port where
the reference count is not 0.

Number of global pages used, number of global pages unused, number
of global sections used, and number of global sections unused in shared
memory.

INS-21

INSTALL
PURGE

PURGE
Deletes all known file entries for images installed without the /NOPURGE
qualifier.

FORMAT

PURGE

PARAMETERS

None.

QUALIFIERS

None.

DESCRJPTION

The PURGE command deletes all known file entries for images installed
without the /NOPURGE qualifier.
If a process is accessing global sections when the PURGE command is
entered, the global sections are deleted only after the operation initiated
by the process completes. However, once the command is entered, no
additional processes can access the global sections because they are "marked
for deletion."

EXAMPLE
INSTALL> PURGE

The command in this example deletes all images except those installed with
the /NOPURGE qualifier. The images themselves (that is, the image files)
remain unaffected. Writable global sections are written back to disk upon
their removal as known images.

INS-22

INSTALL
REMOVE

REMOVE
Removes an entry from the known image file list. The REMOVE command
is synonymous with the DELETE command.

FORMAT
PARAMETER

REMOVE

file-spec

file-spec
Names the file specification of the known image file entry.

QUALIFIERS

None.

DESCRIPTION

The REMOVE command deletes an entry that appears 'in the known image
file list. The image's entry on the known file list and any global sections
for the image are deleted. The image itself (that is, the image file) remains
unaffected. Writable global sections are written back to disk upon their
removal as known images.
If a process is accessing global sections when the REMOVE command is
entered, the global sections are deleted only after the operation initiated
by the process completes. However, once the command is entered, no
additional processes can access the global sections because they are "marked
for deletion."

EXAMPLE
INSTALL> REMOVE GRPCOMM

The command in this example deletes the entry for the known image
GRPCOMM from the known image file list.

INS-23

INSTALL
REPLACE

REPLACE
Associates a known image with the latest version of the image file, or
modifies the attributes of an installed image.

FORMAT
PARAMETER

REPLACE

file-spec

file-spec
Names the file specification of an image installed as a known image.

QUALIFIERS

/[NO]ACCOUNTING
Allows you to enable image-level accounting for selected images when
image accounting is disabled on the system (with the DCL command SET
ACC/DISABLE=IMAGE). When image accounting is enabled on the system,
it logs all images. The /NOACCOUNTING qualifier has no effect.

/[NO]EXECUTE_ONL Y
The /EXECUTE_ONLY qualifier is meaningful only to main programs.
It allows the image to activate shareable images to which the user has
EXECUTE access but has no READ access. All shareable images referenced
by the program must be installed, and VMS RMS uses "trusted" logical
names, those created for use in EXEC or KERNEL mode.
You may not specify this qualifier for an executable image linked with the
/TRACEBACK qualifier.

/[NO]HEADER_RESIDENT
Installs the file as a known image with a permanently resident header (native
mode images only). The image is made permanently open even if /OPEN is
not specified.

/[NOJLOG
Lists the newly created known file entry along with any associated global
sections created by the installation.

/[NOJOPEN
Installs the file as a permanently open known image.

/[NO]PRIVILEGED[=(priv-name[, ... ])]
Installs the file as a known image with the privileges specified (executable
images only). Then, if the image is not located .on the system volume, the
image is made permanently open even if /OPEN is not specified. For a
complete listing of privileges, see the ADD command.
You may not specify this qualifier for an executable image linked with the
/TRACEBACK qualifier.

INS-24

INSTALL
REPLACE

/[NOJSHARED
Installs the file as a shared known image and causes creation of global
sections for the image. The image is made permanently open even if /OPEN
is not specified.

/[NO]WRITABLE
Installs the file as a writable known image as long as you also specify the
/SHARED qualifier. The /WRITABLE qualifier is automatically negated if the
/NOS HARED qualifier is specified.

DESCRIPTION

The REPLACE command updates a known file to the latest version found in
the specified directory.
You can use the REPLACE command to modify the attributes of currently
installed images. Either specify new qualifiers, or change the value of
qualifiers used when installing the image with the ADD (or CREATE)
command. If you specify no qualifiers, the new image retains the same
attributes as the old one. If the old image was installed with the /SHARED
qualifier, the global sections are recreated, probably with new identifiers.
If a process is accessing global sections when the REPLACE command is

entered, the global sections are deleted only after the operation initiated
by the process completes. However, once the command is entered, no
additional processes can access the global sections because they are "marked
for deletion."

EXAMPLE
INSTALL> REPLACE GRPCOMM /ACCOUNTING/NOOPEN

The command in this example replaces the known image GRPCOMM
with the latest version of the image, while enabling image accounting and
removing the OPEN attribute for this version.
The full name of the file specification is assumed to be
SYS$SYSTEM:GRPCOMM.EXE.

INS-25

Index

ADD command• INS-10

Image
See also known image
executable• INS-3, INS-4
execute-only• INS-4
installation at startup• INS-1
linkable• INS-3
privileged• INS-3, INS-4
protecting installed• INS-4
reasons to install • INS-1
shareable• INS-3, INS-4
Image accounting• INS-10
Installed file
See known image
INST ALL Utility
exiting• INS-8
invoking• INS-8

c
CREA TE command• INS-13

D
DELETE command • INS-1 5

E
Executable image• INS-3
/EXECUTE_ONL Y qualifier• INS-10
EXIT command • INS-16

F
File specification
for installing images• INS-5
/FULL qualifier• INS-18

G
/GLOBAL qualifier• INS-18

H
/HEADER_RESIDENT qualifier• INS-10
HELP command• INS-17

K
Known file list• INS-1
Known image• INS-1
attributes of• INS-19
dismounting volume• INS-6
evaluating merits of installing• INS-2, INS-18
file specification for• INS-5
privilege enhancement• INS-3
removing• INS-6, INS-11
updating• INS-25

L
Linkable image• INS-3
LIST command• INS-18
Logical name
installing images• INS-5
/LOG qualifier• INS-10

lndex-1

Index

Multiport memory
installing shared images• INS-6, INS-21

Writable image• INS-2
/WRIT ABLE qualifier• INS-11

0
Open image• INS-2
OPEN qualifier• INS-10

p
Privilege
assigned to installed images• INS-11
enhancement for installed files• INS-3
Privileged image• INS-2, INS-3
/PRIVILEGED qualifier• INS-11
Protected image• INS-2, INS-4
/PROTECTED qualifier• INS-11
PURGE command• INS-2 2
/PURGE qualifier• INS-11

R
REMOVE command• INS-23
REPLACE command• INS-24

s
Search lists
priority of installed images• INS-6
Shareable image• INS-2
Shared image• INS-2, INS-3
installing in MA 780 multi port memory• INS-6
/SHARED qualifier• INS-11
SHOW DEVICES command
/FILES qualifier• INS-6
/STRUCTURE qualifier• INS-18
/SUMMARY qualifier• INS-18

lndex-2

Reader's Comments

VMS Install Utility Manual
AA-LA29A-TE

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

D
D
D

D
D

D
D
D
D
D

D
D
D

D
D

I would like to see more /less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Name/Title

Poor

Dept.
Date

Company
Mailing Address
Phone

-- ~o;~~;~:d nd Tape ------------------~n~-------~;~i~F---uen

in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION

Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1•• 1.1 ... 1.11 .. 1
- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I
I
I
I

Reader's Comments

VMS Install Utility Manual
AA-LA29A-TE

Excellent

Good

Fair

Poor

0
0
0
0
0
0
0
0

I would like to see more /less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

I am using Version ___ of the software this manual describes.

Name/Title

Dept.
Date

Company
Mailing Address
Phone

-- Do Not Tear - Fold Here and Tape

r---------------

-------------------~lll-

No Postage

mnmnoma™

~;~=i~:J
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1.. 1.1 ... 1.11 .. 1
·- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I
I
I
I