HP OpenVMS Systems Documentation

The Install utility (INSTALL) stores information about images in memory. Use INSTALL for the following reasons:

The site-independent startup command procedure, STARTUP.COM, uses INSTALL to install certain system images when the system boots. You use INSTALL to install other selected images, according to the needs of your site.

Installed images must be reinstalled each time the system reboots. To do so, include INSTALL commands in the site-specific startup command procedure SYSTARTUP_VMS.COM, as explained in Section 5.2.7.

The Install utility (INSTALL) only installs images that are linked with the /NOTRACEBACK qualifier.

Note that INSTALL commands perform a different function than System Generation utility (SYSGEN) INSTALL commands.

The following sections explain installed images and how to use the Install utility.

17.9.1 Understanding Images and Known Images

An image is a collection of procedures and data bound together by the Linker utility. Executable images can be executed (or run) in a process, either by a command line interpreter (CLI) or the $CREPRC system service. Usually, executable programs have the file type .EXE.

There are three types of images:

When you install an image with INSTALL, the image is assigned attributes and becomes known to the system. For this reason, an installed image is also called a known image.

The image activator processes search lists in two passes, in order to favor known images. On its first pass through the search list, the image activator looks up images as known files. If needed, on a second pass through the search list, the image activator looks up images on disk.

17.9.2 Understanding Known File Entries

The system defines known images in internal data structures called known file entries. Each entry identifies the file name of the installed image and the attributes with which it was installed (for information about attributes of installed images, see Section 17.9.3).

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.

17.9.3 Understanding Attributes You Can Assign to Known Images

By specifying appropriate qualifiers to INSTALL commands, you can assign attributes to known images. Table 17-1 describes these attributes and the qualifiers that are used to assign them to known images.

You can install images for the following reasons:

• Improve image activation performance
• On Alpha systems, improve execution performance of shared images
• Conserve physical memory
• Enhance privileges of images during excution

Because an installed file requires system resources, such as paged dynamic memory, install those files that most improve system performance and site requirements. The INSTALL command LIST provides information about installed images to help 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 worth the overhead.

17.9.5 Installing Images to Improve Image Activation Performance

You can improve image activation performance by installing images that run frequently. Image activation performance improves when programs are installed because the operating system opens installed files by file ID rather than by file name, thus eliminating costly directory operations.

Installing images as header resident further enhances activation performance because the system avoids the overhead of I/O operations to read the image header into memory.

To install an image as header resident, specify the /HEADER_RESIDENT qualifier when you install the image. This makes the header of the image file remain permanently resident, saving disk I/O. Specifying the /HEADER_RESIDENT qualifier implicitly makes the images permanently open.

Image headers are stored in paged dynamic memory. The size of the image headers varies.

Frequently accessed images, critical to a site's operations, can be installed as open images. To install an image as permanently open, specify the /OPEN qualifier when you install the image. The image file remains open, so access to the image does not require a call to the file system. The cost of keeping an image file permanently open is approximately 512 bytes of nonpaged dynamic memory per file.

17.9.6 Installing Images with Shared Address Data

Using shared address data on OpenVMS Alpha systems improves performance at the following times:

• At run time, shared address data saves physical memory because of increased memory sharing between processes.
• At image activation, shared address data reduces CPU and I/O time because fixup is performed at installation time.

For details, refer to the INSTALL section of the OpenVMS System Management Utilities Reference Manual.

Related Terms

Explanations of terms related to shared address data follow.

• Image section
  An image consists of a number of image sections. An image section can contain:
  • Instructions (code)
  • Read-only data (constants)
  • Read/write data
• Shared known images
  You can make an image a shared known image by using the following command:

  $ INSTALL ADD image-name /SHARED

  
  When you enter this command, the Install utility creates global sections for read-only image sections, allowing the sections to be shared by all the processes that run the image.
• Address data
  One kind of image section contains address data. At execution time, address data sections are read-only. However, the addresses are not known until image activation; therefore, the image section is read/write until the end of image activation. Addresses for a shareable image generally vary with the process because different processes are likely to have different collections of mapped images.
• Shared address data
  The shared address data feature assigns unique P1 space addresses for shareable images from the P1 image region. (The IMGREG_PAGES system parameter determines the size of the P1 space.) With the assigned address, the Install utility determines the content of an address data section when the image is installed. A global section is created to allow shared access to each address data image section.
  Executable (main) images can also use shared address data sections; these images are not assigned P1 addresses, however, because the base address for an executable image is determined when the image is linked.

Many images that are part of the OpenVMS software product are installed as shared known images with shared address data. This provides the performance benefit without requiring the system manager to take any explicit action.

17.9.6.2 Application Images

As system manager, you might choose to install additional images with shared address data. In considering this option, you need to investigate application dependencies on sharable images.

17.9.7 Installing Images to Conserve Physical Memory

You can conserve physical memory by installing images that usually run concurrently from several processes. When an image is not installed, or is installed without the shared attribute, each process running the image requires private sections in memory. Shared images conserve physical memory because only one copy of the code needs to be in memory at any time, and many users can access the code concurrently. Use the /SHARED qualifier to install images as shared images.

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 attribute is restricted by the GBLPAGES and GBLSECTIONS system parameters. For more information about these system parameters, refer to the OpenVMS System Management Utilities Reference Manual.

17.9.8 Installing Images to Enhance Privileges of Images

There are two ways to allow an image to execute in an enhanced privilege environment:

• Installing executable images with privileges to allow a nonprivileged process to perform the privileged functions of the image.
  Use the /PRIVILEGED qualifier with the INSTALL commands CREATE or REPLACE.

  Caution Installing an image with enhanced privilege can compromise system security. Make sure the image does not enable a user to regain control with extra privileges enabled.

• Installing protected shareable images (which are used to implement user-written system services), allowing other, nonprivileged images to execute select portions of privileged code without enhancing the privileges of those individual images.
  Use the /PROTECTED and /SHARED qualifiers with the INSTALL commands CREATE or REPLACE.

A nonprivileged process can perform the privileged functions of an executable image when the image is installed with privileges. Install executable images with enhanced privileges by using the /PRIVILEGED qualifier; 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.

For an image installed with privileges to activate another image, such as a shareable image, either by having it linked to the privileged image or by using LIB$FIND_IMAGE_SYMBOL, the following conditions hold:

• The shareable image must be installed as a known image using INSTALL.
• Logical names and table names used to find the image must be defined in executive or kernel mode. In particular, the standard executive-mode definition of LNM$FILE_DEV translates only to LNM$SYSTEM; definitions in the process, job, or group tables are not recognized.
• Only images linked with the Linker utility qualifiers /NODEBUG and /NOTRACE can be installed with enhanced privilege.

A privileged shareable image is a shareable image with defined entry points that execute in inner (executive or kernel) mode. Inner-mode entry points in shareable images are referred to as user-written system services.

To create a privileged shareable image, you must:

1. Create a program section with the VECTOR attribute containing a PLV (privileged library vector) data structure.
2. Link the shareable image with the /PROTECT command qualifier or the PROTECT= option of the Linker utility, 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 PROTECT= option when only part of a privileged shareable image requires protection.
3. Install the privileged shareable image with the Install utility, specifying both the /PROTECTED and the /SHARED qualifiers. The /PROTECTED qualifier assigns the protected attribute. The /SHARED qualifier assigns the shareable attribute. See Section 17.9.3 for information about these attributes.

For more information about creating privileged shareable images, refer to the OpenVMS Programming Concepts Manual.

17.9.9 Activating Images in a Privileged Context

When a process performs one of the following actions, the image activator enters a restricted mode of operation similar to that entered when a privileged program is run:

• Runs an executable or shareable image to which it has execute but not read access.
• Activates an executable image installed with the /PRIVILEGE or /EXECUTE_ONLY qualifier.
• Activates an image called by a privileged shareable image.

In this mode of operation:

• All shareable images activated during the life of the execute-only image must be installed.
• The image activator directs OpenVMS RMS to use only trusted logical names (logical names associated with executive or kernel mode) when opening image files.

When you use INSTALL commands, your file specifications must name existing executable or shareable images. OpenVMS RMS resolves each file specification using the following defaults:

• A device and directory type of SYS$SYSTEM
• A file type of .EXE

You can specify a specific version of the file as the known version of the image with the CREATE or REPLACE command. 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.

17.9.11 Installing Images with INSTALL

Before performing this task, you should understand the following points:

• Attributes of installed images. For information, see Section 17.9.3.
• File specifications for the Install utility. For information, see Section 17.9.10.

How to Perform This Task

1. Give yourself the CMKRNL privilege by entering the following command:

   $ SET PROCESS/PRIVILEGES=CMKRNL

2. Invoke INSTALL by entering the following command:

   $ INSTALL

3. Enter the CREATE command in the following format:

   CREATE file-spec [/qualifier...]

   
   Specify one or more of the following qualifiers, depending on which attributes you want to assign to the image:

   /EXECUTE_ONLY
   /HEADER_RESIDENT
   /OPEN
   /PRIVILEGED
   /PROTECTED
   /RESIDENT (Alpha systems only)
   /SHARED
   /WRITABLE

   
   For more information about installing images, refer to the INSTALL command CREATE in the OpenVMS System Management Utilities Reference Manual.

$ DEFINE INSTALL SYS$SYSTEM:INSTALL.EXE;0