Document revision date: 15 July 2002

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.10.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.10.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.10.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.10.3 for information about these attributes.

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

17.10.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.10.11 Installing Images with INSTALL

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

• Attributes of installed images. For information, see Section 17.10.3.
• File specifications for the Install utility. For information, see Section 17.10.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.

Use the INSTALL command LIST to display information about known images.

The information displayed with the /FULL qualifier of the LIST command can help you determine if installing an image is worth the expense.

How to Perform This Task

1. Invoke INSTALL by entering the following command:

   $ INSTALL

2. To display a list of all known images and their attributes, enter the LIST command. To display attributes for a specific image, specify the name of the image as follows:

   LIST file-spec

   
   For example:

   INSTALL> LIST LOGINOUT

3. To display complete information about a specific image, including the number of accesses, the number of concurrent accesses, and the number of global sections created, specify the /FULL qualifier as follows:

   LIST/FULL file-spec

Example

The following example displays complete information about the installed image LOGINOUT.EXE, including the number of accesses, the number of concurrent accesses, and the number of global sections created:

$ INSTALL INSTALL> LIST/FULL LOGINOUT DISK$VMS551:<SYS2.SYSCOMMON.SYSEXE>.EXE LOGINOUT;2 Open Hdr Shar Prv Entry access count = 36366 Current / Maximum shared = 1 / 10 Global section count = 3 Privileges = CMKRNL SYSNAM LOG_IO ALTPRI TMPMBX SYSPRV INSTALL>

17.10.13 Defining Logical Names for Shareable Image Files

If a shareable image is not located in SYS$SHARE, you must define a logical name for that image in order to run an executable image linked against it. For example, if the file specification for STATSHR is SYS$SHARE:STATSHR.EXE, no logical name 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

By redefining the logical name of a shareable image, you can replace that shareable image with another without requiring the calling executable image to relink. 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

The INSTALL command REMOVE removes a known file entry for an image and deletes any global sections created when the image was installed. Note that a volume cannot be dismounted while any known file entries are associated with it. To dismount a volume, you must delete all known images associated with it. You must also wait for all processes using those images to exit. Use the DCL command SHOW DEVICES/FILES to determine the status of the files.

For more information about the INSTALL command DELETE, refer to the INSTALL section of the OpenVMS System Management Utilities Reference Manual.

17.11 Reserved Memory Registry

The Reserved Memory Registry through its interface within the SYSMAN utility allows an OpenVMS Alpha system to be configured with large amounts of memory set aside for use within memory-resident sections and by other privileged applications. The Reserved Memory Registry also allows an OpenVMS system to be properly tuned through the AUTOGEN utility, taking into account the preallocated reserved memory.

With the Reserved Memory Registry you can:

• Reserve system nonfluid memory for the memory-resident global section fault option.
• Reserve suitable physical pages as well as system non-fluid memory for the memory-resident global section allocate option.

The Reserved Memory Registry includes the ability to specify that the preallocated pages are to be zeroed during the booting of the system. This option reduces the time required to create the memory-resident global demand-zero section.

Another option within the Reserved Memory Registry is to include the size of the page tables required to map to the memory-resident global section in the reserved memory. If this option is specified and the reserved memory is being used for a memory-resident global section, the memory-resident global section is created with shared page tables.

17.11.1 Using the Reserved Memory Registry

OpenVMS provides a mechanism to reserve non-fluid memory for use within a memory-resident global demand-zero section. The reserved memory may either be simply a deduction from the system's nonfluid memory size or pages may be preallocated.

Using the Reserved Memory Registry ensures that AUTOGEN tunes the system properly to not include memory-resident section pages in its calculation of the system's fluid page count. AUTOGEN sizes the system pagefile, number of processes and working set maximum size based on the system's fluid page count. A system can experience severe performance problems if AUTOGEN adjusts parameters based upon a fluid page count that does not account for the physical memory that is permanently reserved for some other purpose.

Using the Reserved Memory Registry also ensures that contiguous, aligned memory is available for memory-resident sections when the allocate option is used.

Consumers of reserved, nonfluid memory enter the characteristics of the memory into a data file that is read during the system initialization (boot-time). The mechanics of manipulating the data file are similar to SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DATA (indicates installation-specific executive loaded images).

This file is called:

SYS$SYSTEM:VMS$RESERVED_MEMORY.DATA

The file is maintained by the SYSMAN utility (as is the executive loaded image data file).

17.11.1.2 AUTOGEN

The Reserved Memory Registry file, VMS$RESERVED_MEMORY.DATA, is read by the AUTOGEN feedback mechanism and factors into the setting of the system's fluid page count. AUTOGEN sizes the system pagefile, number of processes and working set maximum size based on the system's fluid page count.

17.11.1.3 Adding Entries to the Reserved Memory Registry

You add an entry to the data file by using the SYSMAN utility. The SYSMAN command is as follows:

SYSMAN RESERVED_MEMORY ADD gs_name - /GROUP = n - /SIZE = {size of reserved memory, unit: MB} - /[NO]ALLOCATE - /[NO]ZERO - /[NO]PAGE_TABLES

• The gs_name field is the name of the memory-resident global section associated with this reserved memory. A name must be specified.
• If the /GROUP qualifier is not present, the reserved memory is for a system global section (SYSGBL).
• If the /GROUP qualifier is present, the reserved memory is for a group global section. The value n UIC group number (in octal) of the process creates the group global section. Only processes within the creator's UIC group number are allowed access to the global section. For example, if a process with the UIC of [6,100] is the creator of the group global section, the group number specified for the /GROUP qualifier would be 6.
• If the /ALLOCATE qualifier is not specified or if the /NOALLOCATE qualifier is specified, the reserved memory is not allocated during the next reboot of the system. The reserved memory is only deducted from the system's fluid page count and the creation of the memory-resident global section results in the fault option being used.
• If the /ALLOCATE qualifier is specified, pages are allocated during the next reboot of the system. The allocated memory is deducted from the system's fluid page count and the creation of the memory-resident global section results in the allocate option being used. The physical alignment of the pages is based on the maximum granularity hint factor that can be used to map the pages given the size of the reserved memory. Possible granularity hint factors are 512 pages (or 4 MB) and 64 pages (or 512 KB). Therefore, assuming an 8- KB system page size, reserved memory is physically aligned as follows:

  1. size >= 4 MB: physically aligned on a 4 Mbyte boundary 2. size < 4 MB: physically aligned on a 512 KB boundary

• If the /ZERO qualifier is not specified or if /NOZERO is specified, the preallocated pages are not zeroed during system initialization. The pages are zeroed at the time the global section is created.
• The /ZERO qualifier is only allowed if the /ALLOCATE qualifier is specified. If the /ZERO qualifier is specified, the preallocated pages are zeroed during system initialization. Zeroed pages are required for memory-resident global sections; however, the pages need not be zeroed during system initialization.
• If the /PAGE_TABLES qualifier is not specified or if /NOPAGE_TABLES is specified, additional memory is not reserved for shared page tables. When the memory-resident global section is created, shared page tables are not created for the global section.
• If the /PAGE_TABLES qualifier is specified, additional memory is reserved for shared page tables. When the memory-resident global section is created, shared page tables are created for the global section. If the /ALLOCATE qualifier is not specified or if /NOALLOCATE is specified, the additional reserved memory is only deducted from the system's fluid page count. If the /ALLOCATE qualifier is specified, additional pages are allocated during the next reboot of the system for the shared page tables and the additional reserved memory is deducted from the system's fluid page count.

You can remove a reserved memory entry by issuing the following SYSMAN command:

SYSMAN RESERVED_MEMORY REMOVE gs_name /GROUP = n

The specified gs_name is the name of the memory-resident section associated with the entry being removed from the Reserved Memory Registry. A name must be specified.

The value n specified by the /GROUP qualifier is the UIC group number (in octal) associated with the memory-resident section being removed. If the memory-resident global section is a group section, you must specify the /GROUP qualifier. If the memory-resident global section is a system global section, you must not specify the /GROUP qualifier.

If page tables are reserved for the named memory-resident global section, the additional reserved memory is also removed.

The REMOVE command only removes entries from the Reserved Memory Registry data file; it does not affect memory within the running system.

	privacy and legal statement
6017PRO_079.HTML