Document revision date: 30 March 2001

## OpenVMS System Management Utilities Reference Manual

Previous | Contents | Index

## Chapter 11
Install Utility

## 11.1 INSTALL Description

The Install utility (INSTALL) creates known file entries to improve the performance of executable and shareable images, especially those that run frequently, run concurrently with several processes, or allow images to run in a privileged context.

Known file entries 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, you are encouraged to include additional INSTALL commands for selected images in the site-specific command procedure SYS$MANAGER:SYSTARTUP_VMS.COM.

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

> INSTALL [command]

### Parameter

> #### command

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

### Description

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

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

> 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

## 11.3 INSTALL Commands

This section describes and provides examples of the INSTALL commands. The following table summarizes the INSTALL command functions.

Command | Function
--- | ---
ADD | Synonym for the CREATE command
CREATE | Installs the specified image as a known image
DELETE | Synonym for the REMOVE command
EXIT | Exits from INSTALL
HELP | Describes how to use INSTALL
LIST | Displays a description of each specified known image, global sections, and the addresses of known image data structures
PURGE | Deletes all known images installed without the /NOPURGE qualifier
REMOVE | Deletes a known image
REPLACE | Associates a known image with the latest version of the image file or modifies the attributes of an installed image

## ADD

> Installs the specified image file as a known image. The ADD command is a synonym for the CREATE command.

> Requires the CMKRNL privilege. Also requires the SYSGBL privilege to create system global sections and the PRMGBL privilege to create permanent global sections.

## CREATE

> Installs the specified image file as a known image. The CREATE command is a synonym for the ADD command.

> Requires the CMKRNL privilege. Also requires the SYSGBL privilege to create system global sections and the PRMGBL privilege to create permanent global sections.

### Format

> CREATE file-spec

### Parameter

> #### 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, which must have been linked with the /NOTRACEBACK qualifier. If you omit the device and directory specification, the default SYS$SYSTEM is used. The default file type is .EXE.

> The highest existing version of the file is used by default. However, you can specify another version of the file as the known version of the image. Even if other versions of the file exist, the version that you specify will be the version that satisfies all known file lookups for the image.

### Qualifiers

> #### /ACCOUNTING

> #### /NOACCOUNTING (default)

> Enables image-level accounting for the specified image even if image accounting is disabled (by using the DCL command SET ACCOUNTING/DISABLE=IMAGE). When image accounting is enabled on the local node, it logs all images, and the /NOACCOUNTING qualifier has no effect.

> #### /ARB_SUPPORT=keyword

> On Alpha systems, overrides the system parameter ARB_SUPPORT for this installed image.

> The following table shows the keywords you can use with the /ARB_SUPPORT qualifier:

> Keyword | Behavior
> --- | ---
> None | The obsolete kernel data cells are not maintained by the system. Fields are initialized to zero or set to invalid pointers at process creation.
> Clear | The obsolete kernel data cells are cleared or set to invalid pointers when the code would have set up values for backward compatibility.
> Read-only | The obsolete cells are updated with corresponding security information stored in the current Persona Security Block (PSB) when a $PERSONA_ASSUME is issued.
> Full (default) | Data is moved from the obsolete cells to the currently active PSB on any security-based operation.

> For more information about obsolete kernel cells, refer to the ARB_SUPPORT system parameter in an appendix to this manual or in online help.

> #### /AUTHPRIVILEGES[=(priv-name[,...])]

> #### /NOAUTHPRIVILEGES

> Installs the file as a known image installed with the authorized privileges specified.

> Usage Notes

> - If a privileged image is not located on the system volume, the image is implicitly installed /OPEN.
> - The set of privileges for a privileged image can be empty. You must, however, list each privilege every time you define or redefine privileges.
> - The /AUTHPRIVILEGES qualifier applies only to executable images.
> - You cannot specify this qualifier for an executable image linked with the /TRACEBACK qualifier.
> - You cannot assign privilege names with the /NOAUTHPRIVILEGES qualifier.

> You can specify one or more of the privilege names described in detail in an appendix to the OpenVMS Guide to System Security. (ALL is the default.)

> #### /EXECUTE_ONLY

> #### /NOEXECUTE_ONLY (default)

> 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 no read access. All shareable images referenced by the program must be installed, and OpenVMS RMS uses trusted logical names (those created for use in executive or kernel mode).

> You cannot specify this qualifier for an executable image linked with the /TRACEBACK qualifier.

> #### /HEADER_RESIDENT

> #### /NOHEADER_RESIDENT

> Installs the file as a known image with a permanently resident header (native mode images only). An image installed header resident is implicitly installed open.

> #### /LOG

> #### /NOLOG (default)

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

> #### /OPEN

> #### /NOOPEN

> Installs the file as a permanently open known image.

> #### /PRIVILEGED[=(priv-name[,...])]

> #### /NOPRIVILEGED

> Installs the file as a known image with active privileges specified. If a privileged image is not located on the system volume, the image is implicitly installed /OPEN.

> Usage Notes

> - The set of privileges for a privileged image can be empty.
> - You must list each privilege every time you define or redefine privileges.
> - The /PRIVILEGED qualifier applies only to executable images.
> - You cannot specify this qualifier for an executable image linked with the /TRACEBACK qualifier.
> - You cannot assign privilege names with the /NOPRIVILEGED qualifier.

> Installing Shareable Images

> Installing an image with privileges declares that the image is trusted to maintain system integrity and security properly. To maintain that trust, any routine called by the privileged image must also be trusted. For this reason, any shareable images activated for use by a privileged image must be installed. Only trusted logical names (names defined in executive and kernel mode) can be used in locating shareable images to be used by a privileged image.

> Interaction of /PRIVILEGED and /AUTHPRIVILEGES

> When you create a new entry, the privileges you assign are also assigned for Authorized Privileges if you do not assign specific authorized privileges with the /AUTHPRIVILEGED qualifier.

> When you replace an image, any privileges assigned with the /PRIVILEGED qualifier are not repeated as Authorized Privileges. Also, if you use the REPLACE command with the /NOAUTHPRIVILEGES qualifier, the Authorized Privileges become the same as the Default Privileges (set using the /PRIVILEGED qualifier).

> You can specify one or more of the privilege names described in detail in an appendix to the OpenVMS Guide to System Security. (ALL is the default.)

> For examples of how to use CREATE commands with /PRIVILEGES qualifiers, see the Examples section at the end of this command.

> #### /PROTECTED

> #### /NOPROTECTED (default)

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

> #### /PURGE (default)

> #### /NOPURGE

> Specifies that the image can be removed by a purge operation; if you specify /NOPURGE, you can remove the image only by a remove operation.

> #### /RESIDENT[=([NO]CODE,[NO]DATA)]

> On Alpha systems, causes image code sections or read-only data sections to be placed in the granularity hint regions and compresses other image sections, which remain located in process space. If you do not specify the /RESIDENT qualifier, neither code nor data is installed resident. If you specify the /RESIDENT qualifier without keyword arguments, code is installed resident, and data is not installed resident.

> The image must be linked using the /SECTION_BINDING=(CODE,DATA) qualifier. An image installed with resident code or data is implicitly installed header resident and shared.

> #### /SHARED[=[NO]ADDRESS_DATA]

> #### /NOSHARED

> Installs the file as a shared known image and creates global sections for the image sections that can be shared. An image installed shared is implicitly installed open.

> When you use the ADDRESS_DATA keyword with the /SHARED qualifier, P1 space addresses are assigned for shareable images. With the assigned addresses, the Install utility can determine the content of an address data section when the image is installed rather than when it is activated, reducing CPU and I/O time. A global section is created to allow shared access to address data image sections.

> #### /WRITABLE

> #### /NOWRITABLE

> Installs the file as a writable known image as long as you also specify the /SHARED qualifier. The /WRITABLE qualifier only applies to images with image sections that are shareable and writable. The /WRITABLE qualifier is automatically negated if you do not specify the /SHARED qualifier.

###

#### Examples

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

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

#2
    INSTALL> CREATE/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.

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

#4
    INSTALL> CREATE/SHARED=ADDRESS_DATA WRKD$:[MAIN]INFOSHR

> The command in this example installs the INFOSHR file as a shared known image and creates shared global sections for code sections and read-only data sections. Because the command includes the ADDRESS_DATA keyword, address data is also created as a shared global section.

#5
    INSTALL> CREATE STATSHR/PRIV

> The command in this example creates the STATSHR image with all privileges.

#6
    INSTALL> CREATE STATSHR/PRIV=(OPER,SYSPRV)

> The command in this example creates the STATSHR image with the OPER and SYSPRV privileges.

#7
    INSTALL> CREATE STATSHR/PRIV=NOALL

> The command in this example creates the STATSHR image with an empty set of privileges.

#8
    INSTALL> CREATE STATSHR/NOPRIV

> The command in this example creates the STATSHR image explicitly with no privileges.

## DELETE

> Deletes a known image. The DELETE command is a synonym for the REMOVE command.

## EXIT

> Terminates INSTALL and returns control to the DCL command level. You can also exit from INSTALL by pressing Ctrl/Z.

### Format

> EXIT

## HELP

> Displays information about how to use INSTALL.

### Format

> HELP [command]

### Parameter

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

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

#2

    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 the known image for file-spec
         LIST                    List all entries

      Additional information available:

      Qualifiers
      /FULL      /GLOBAL    /STRUCTURE    /SUMMARY

> The command in this example displays help information about the LIST command.

## LIST

> Displays a description of each specified known image or, if no file is specified, all known images.

### Format

> LIST [file-spec]

### Parameter

> #### file-spec

> Names the file specification of an image installed as a known image. If you omit the file specification, INSTALL displays all known images.

### Description

> You can use the LIST command with the /FULL qualifier to display information that is useful in tuning the known image 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 about how to estimate the size of installed images, refer to the OpenVMS System Services Reference Manual.

### 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 about global sections, plus the current owner and protection codes and access control entries.

> #### /GLOBAL

> Lists global sections for any specified shared image, or if you omit the file specification, lists all global sections. If a global section is created by INSTALL to support a particular image, that image is also identified.

> #### /RESIDENT

> Displays a description of each resident image.

> #### /STRUCTURE

> Lists addresses of known image data structures.

> #### /SUMMARY

> Used with the /GLOBAL qualifier, displays the global section and global page usage on the system for local and shared memory global sections.

###

#### Examples

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

>     SYS$DISK:<SYS0.SYSCOMMON.SYSEXE>.EXE
>        ANALIMDMP;1 (1)               Prv (2)
>        AUTHORIZE;1                    Prv
>        CDU;1            Open Hdr      Prv
>        DCL;1            Open Hdr Shar          Lnkbl
>        FAL;1            Open Hdr Shar
>        INSTALL;1                      Prv
>        LOGINOUT;1       Open Hdr Shar Prv
>        MAIL;1           Open Hdr Shar
>        MAIL_SERVER;1    Open Hdr Shar Prv
>        REQUEST;1                      Prv
>        SET;1            Open Hdr Shar Prv
>        SETAUDIT;1                     Prv
>        SETP0;1          Open Hdr Shar Prv
>        SETRIGHTS;1                    Prv
>        SHOW;1           Open Hdr Shar Prv
>        SHWCLSTR;1       Open Hdr Shar Prv
>        SUBMIT;1         Open Hdr Shar Prv
>        SYSMAN;1                       Prv

>     SYS$DISK:<SYS0.SYSCOMMON.SYSLIB>.EXE
>        ANALIMDMPSHR;1                 Prv
>        CONVSHR;1
>        DCLTABLES;1      Open Hdr Shar          Lnkbl
>     .
>     .
>     .
>        LIBOTS;1         Open Hdr Shar          Lnkbl        Resid
>        LIBRTL;1         Open Hdr Shar          Lnkbl        Resid
>        MAILSHR;1        Open Hdr Shar          Lnkbl
>     .
>     .
>     .

> 1. File specification of the known image
> 2. Attribute of known image, as follows:

>    Attribute | Meaning
>    --- | ---
>    ACNT | Image accounting is enabled for the image (/ACCOUNTING).
>    +CMODE | Image is in compatibility mode, set by the VAX--11 RSX Linker.
>    HDR | Image header is permanently resident (/HEADER_RESIDENT).
>    LNKBL | Image is not executable; it is a shareable (linkable) image set by the OpenVMS 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 (/PRIVILEGED).
>    ++RESID | Image is resident (/RESIDENT).
>    SAFE | Image is a privileged image registered as being compatible with the running version of OpenVMS. For more information about registered images, refer to the OpenVMS System Manager's Manual, Volume 1: Essentials.
>    SHAR | Image is shared (/SHARED).
>    WRT | Image is writable (/WRITABLE).
>    XONLY | Only execute access to image is allowed (/EXECUTE_ONLY).

+VAX specific
++Alpha specific

#2
    INSTALL> LIST/RESIDENT

> The command in this Alpha example displays a single-line description of all resident images. The description includes the location in memory, the size of the code sections, and the type of section.

>      System Resident Sections

>     SYS$DISK:<SYS0.SYSCOMMON.SYSLIB>.EXE
>        CMA$TIS_SHR;1

>      Base VA     End VA     Length       Type

>      80490000    80490A00   00000A00     Resident Code

>      7FC04000    7FC04A00   00000A00     Linkage
>      7FC14000    7FC14200   00000200     Writeable data
>      7FC34000    7FC34200   00000200     Writeable data

>        DECC$SHR;1

>      Base VA     End VA     Length       Type

>      80548000    805D1C00   00089C00     Resident Code
>      805D2000    805D2400   00000400     Resident Code

>      7FE34000    7FE4B800   00017800     Linkage
>      7FE54000    7FE59A00   00005A00     Writeable data
>      7FE64000    7FE64800   00000800     Read-only data
>      7FE84000    7FE84200   00000200     Writeable data
>      7FE94000    7FE94200   00000200     Demand-zero
>      7FEA4000    7FEA7000   00003000     Demand-zero
>      7FEB4000    7FEB5800   00001800     Writeable data

>        DPML$SHR;1

>      Base VA     End VA     Length       Type

>      80492000    80547600   000B5600     Resident Code

>      7FC44000    7FC6FA00   0002BA00     Read-only data
>      7FC74000    7FC88200   00014200     Linkage
>      7FC94000    7FC94400   00000400     Writeable data
>      7FCA4000    7FCCE600   0002A600     Read-only data
>      7FD94000    7FD95000   00001000     Writeable data

>        LIBOTS;1

>      Base VA     End VA     Length       Type

>      80482000    8048F600   0000D600     Resident Code

>      7FBC4000    7FBC6600   00002600     Read-only data
>      7FBD4000    7FBD5A00   00001A00     Linkage
>      7FBF4000    7FBF4200   00000200     Writeable data

>        LIBRTL;1

>      Base VA     End VA     Length       Type

>      80400000    80481A00   00081A00     Resident Code

>      7FB54000    7FB64800   00010800     Linkage
>      7FB74000    7FB75000   00001000     Writeable data
>      7FB84000    7FB8D600   00009600     Read-only data
>      7FB94000    7FB94200   00000200     Writeable data
>      7FBA4000    7FBA5000   00001000     Demand-zero
>      7FBB4000    7FBB5400   00001400     Writeable data

#3
    INSTALL> LIST/FULL LOGINOUT

> The command in this example displays a multiline description of the known image LOGINOUT.

>     SYS$DISK:<SYS0.SYSCOMMON.SYSEXE>.EXE

>         LOGINOUT;3       Open Hdr    Shar Priv
>             Entry access count         = 44 (1)
>             Current / Maximum shared   = 3 / 5 (2)
>             Global section count       = 2 (3)
>             Privileges = CMKRNL SYSNAM TMPMBX EXQUOTA SYSPRV (4)

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 6048PRO_028.HTML