Document revision date: 30 March 2001

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 preallocated, contiguous, aligned 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.

16.6.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 also preallocated as contiguous, aligned physical pages.

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

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

16.6.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, contiguous, aligned 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 pre-allocated 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 contiguous, aligned 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.

16.6.2.1 Allocating Reserved Memory

During system initialization, the VMS$RESERVED_MEMORY.DATA data file is read.

For each entry in the data file, the number of megabytes is deducted from the system's fluid page count for this memory-resident global section as specified by the /SIZE qualifier on the RESERVED_MEMORY ADD command. If /PAGE_TABLES was specified, the amount of memory required for the shared page tables mapping the memory-resident global section is deducted from the system's fluid page count as well.

If /ALLOCATE was specified on the RESERVED_MEMORY ADD command, a contiguous chunk of physical pages is also allocated and set aside for the memory-resident global section. If /PAGE_TABLES was specified, an additional contiguous chunk of physical pages is allocated and set aside for the shared page tables. The pages have a physical alignment appropriate for the largest granularity hint factor for the given sized chunk. If /ZERO was specified, the pages are zeroed during system initialization or when the system is idle. If /ZERO was not specified or if /NOZERO was specified, the pages are zeroed at the time the memory-resident global section is created.

If the system parameter STARTUP_P1 is set to MIN, entries in the Reserved Memory Registry entries are ignored and memory is not reserved.

If errors are encountered during system initialization while processing the Reserved Memory Registry data file, with reserving system fluid pages, or with allocating contiguous, aligned physical pages, an error message is issued to the console and the system continues to boot.

16.6.2.2 Freeing Reserved Memory

In the running system, you can free reserved memory by issuing the following SYSMAN command:

SYSMAN RESERVED_MEMORY FREE gs_name /GROUP = n

The specified gs_name is the name of the memory-resident section associated with the entry being freed 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 freed. If the memory-resident global section is a group global 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 contiguous, aligned physical pages were not pre-allocated during system initialization for this global section, the reserved memory is simply added to the system's fluid page count. Otherwise the physical pages are deallocated onto the system's free or zeroed page list. The system's fluid page count is adjusted to include the deallocated pages.

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

If the reserved memory is in use by the named memory-resident global section, the amount of reserved memory not currently in use is freed.

The RESERVED_MEMORY FREE command does not affect the Reserved Memory Registry data file contents, it only affects the memory within the running system.

16.6.2.3 Displaying Reserved Memory

Two different places hold reserved memory information, the Reserved Memory Registry data file and the Reserved Memory Registry in the running system created during system initialization based on the entries in the data file.

Different display mechanisms may be used depending on where the information about the reserved memory originates.

There are three mechanisms for displaying the Reserved Memory Registry within the running system: SYSMAN, the DCL SHOW MEMORY command and SDA.

• SYSMAN
  You can display the Reserved Memory Registry within the running system by issuing the following SYSMAN command:

  SYSMAN RESERVED_MEMORY SHOW gs_name /GROUP = n

  
  The specified gs_name is the name of the memory-resident global section associated with the entry being displayed from within the running system. If gs_name is not specified, the reserved memory for all registered global sections is displayed.
  The value specified by the /GROUP qualifier is the UIC n group number (in octal) associated with the memory-resident section being displayed. If the memory-resident global section is a group global 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. The /GROUP qualifier is allowed only if gs_name is specified.

• DCL SHOW MEMORY command
  You can display the Reserved Memory Registry within in the running system by issuing the DCL SHOW MEMORY command. This command shows all memory-related information about the running system including information about the Reserved Memory Registry.
  SHOW MEMORY /RESERVED displays just information about the Reserved Memory Registry within the running system.
  The information displayed by SHOW MEMORY includes how much memory is currently in use by the named global section. It also includes how much memory is reserved and in use (if any) for page tables.
• SDA
  SDA also includes various enhancements to display the Reserved Memory Registry within the running system as well as in crash dump files. The command interface is TBD.

The system services SYS$CREATE_GDZRO and SYS$CRMPSC_GDZRO_64 call internal kernel mode OpenVMS Alpha routines to use the reserved memory registered in the Reserved Memory Registry.

The global section need not be registered in the Reserved Memory Registry. If the global section name is registered in the Reserved Memory Registry, the size of the global section need not exactly match the size of the reserved memory. If the global section is not registered, or if /NOALLOCATE was specified when the global section was registered in the Reserved Memory Registry, the fault option is used for the memory-resident global DZRO section. If the size is greater than the size of the reserved memory, the system service call to create the memory-resident global DZRO section fails if there are not enough additional fluid pages within the system.

If /ALLOCATE was specified when the global section was registered in the Reserved Memory Registry, the allocate option is used for the memory-resident global DZRO section. The size of the global section must be less than or equal to the size of the reserved, pre-allocated memory or the error SS$_MRES_PFNSMALL is returned by the system service call.

16.6.2.5 Returning Reserved Memory

When a memory-resident global section is deleted, the physical pages used for that global section are deallocated to the free page list if contiguous, aligned physical pages were not pre-allocated for this global section. The system's fluid page count is adjusted only for those pages not reserved in the Reserved Memory Registry for this global section.

When a memory-resident global section is deleted, the physical pages used for that global section are returned to the Reserved Memory Registry if contiguous, aligned physical pages were pre-allocated for this global section. The physical pages are not deallocated to the free page list and are still reserved. No adjustment is made to the system's fluid page count.

Reserved memory may only be freed to the running system by using the RESERVED_MEMORY FREE command to the SYSMAN utility.

The configuration of an OpenVMS Alpha application that uses memory-resident global sections performs the following steps:

1. Execute the SYSMAN RESERVED_MEMORY ADD commands that specify the required use of reserved memory.
2. Run AUTOGEN with feedback to set the system's fluid page count appropriately and size the system's pagefile, number of processes and working set maximum size appropriately.
3. Reboot the system to allow for the reserved memory to be deducted from the system's fluid page count and for contiguous, aligned pages to be allocated and zeroed as necessary.

This chapter describes the format used to document system routine calls and explains where to find and how to interpret information about routine calls. Subsequent chapters provide more specific information about calling run-time library (RTL) routines and system services.

This chapter provides additional explanations for the following documentation categories for routines:

• Format
• Returns
• Arguments
• Condition values returned

However, some main categories in the routine format contain information requiring no explanation beyond that given in Table 17-1.

Table 17-1 Main Headings in the Documentation Format for System Routines

Main Heading	Description
Routine Name	Always present. The routine entry point name appears at the top of the first page. It is usually followed by the English text name of the routine.
Routine Overview	Always present. Appears directly below the routine name and briefly explains what the routine does.
Format	Always present. Follows the routine overview and gives the routine entry point name and the routine argument list.
Returns	Always present. Follows the routine format and explains what information is returned by the routine.
Arguments	Always present. Follows the Returns heading and gives detailed information about each argument. If a routine takes no arguments, the word None appears.
Description	Optional. Follows the Arguments heading and contains information about specific actions taken by the routine: interaction between routine arguments, if any; operation of the routine within the context of OpenVMS; user privileges needed to call the routine, if any; system resources used by the routine; and user quotas that might affect the operation of the routine. Note that any restrictions on the use of the routine are always discussed first in the Description section. For example, any required user privileges or necessary system resources are explained first. For some simple routines, a Description section is not necessary because the routine overview provides the needed information.
Condition Values Returned	Always present. Follows the Description section and lists the condition values (typically status or completion codes) that are returned by the routine.
Example	Optional. Follows the Condition Values Returned heading and contains one or more programming examples that illustrate how to use the routine, followed by an explanation. All examples under this heading are complete. They have been tested and should run when compiled (or assembled) and linked. Throughout the manuals that document system routines, examples are provided in as many different programming languages as possible.

17.2 Format Heading

The following three types of information can be present in the format heading:

• Procedure call format
• Explanatory text
• Jump to Subroutine (JSB) format (VAX only)

On VAX processors, all system routines have a procedure call format, but few system routines have JSB formats. If a routine has a JSB format, the format always appears after the routine's procedure call format.

17.2.1 Procedure Call Format

Procedure call formats can appear in many forms. The following four formats illustrate the meaning of syntactical elements, such as brackets and commas. General rules of syntax governing how to use procedure call formats are shown in Table 17-2.

Table 17-2 General Rules of Syntax for Procedure Call Formats

Element	Syntax Rule
Entry point names	Entry point names are always shown in uppercase characters.
Argument names	Argument names are always shown in lowercase characters.
Spaces	One or more spaces are used between the entry point name and the first argument, and between each argument.
Braces ({})	Braces surround two or more arguments. You must choose one of the arguments.
Brackets ([])	Brackets surround optional arguments. Note that commas can also be optional (see the comma element). Note that programming language syntax for optional arguments differs between languages. Refer to your language user's guide for more information.
Commas (,)	Between arguments, the comma always follows the space. If the argument is optional, the comma might appear either inside or outside the brackets, depending on the position of the argument in the list and on whether surrounding arguments are optional or required.
Null arguments	A null argument is a placeholding argument. It is used for one of the following reasons: (1) to hold a place in the argument list for an argument that has not yet been implemented by Compaq but might be in the future; or (2) to mark the position of an argument that was used in earlier versions of the routine but is not used in the latest version (upward compatibility is thereby ensured because arguments that follow the null argument in the argument list keep their original positions). A null argument is always given the name nullarg. In the argument list constructed when a procedure is called, both null arguments and omitted optional arguments are represented by argument list entries containing the value 0. The programming language syntax required to produce argument list entries containing 0 differs from language to language. See your language user's guide for language-specific syntax.

Format 1

This format illustrates the standard representation of optional arguments and best describes the use of commas as delimiters. Arguments enclosed within square brackets are optional. In most languages, if an optional argument other than a trailing optional argument is omitted, you must include a comma as a delimiter for the omitted argument.

ROUTINE_NAME arg1[, [arg2][, arg3]]

Typically, OpenVMS RMS system routines use this format when a maximum of three arguments appear in the argument list.

Format 2

When the argument list contains three or more optional arguments, the syntax does not provide enough information. If you omit the optional arguments arg3 and arg4 and specify the trailing argument arg5, you must use commas to delimit the positions of the omitted arguments.

ROUTINE_NAME arg1, [arg2], nullarg, [arg3], [arg4], arg5

Typically, system services, utility routines, and run-time library routines contain call formats with more than three arguments.

Format 3

In the following call format, the trailing four arguments are optional as a group; that is, you specify either arg2, arg3, arg4, and arg5, or none of them. Therefore, if you do not specify the optional arguments, you need not use commas to delimit unoccupied positions.

However, if you specify a required argument or a separate optional argument after arg5, you must use commas when arg2, arg3, arg4, and arg5 are omitted.

ROUTINE_NAME arg1[, arg2, arg3, arg4, arg5]

Format 4

In the following example, you can specify arg2 and omit arg3. However, whenever you specify arg3, you must specify arg2.

ROUTINE_NAME arg1[, arg2[, arg3]]

	privacy and legal statement
5841PRO_049.HTML