|
HP OpenVMS Systems Documentation |
|
OpenVMS Programming Concepts Manual
16.6 Reserved Memory RegistryThe 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:
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.
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.
16.6.1.1 Reserved Memory Registry Data FileConsumers 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:
The file is maintained by the SYSMAN utility (as is the executive
loaded image data file).
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.
You add an entry to the data file by using the SYSMAN utility. The SYSMAN command is as follows:
16.6.2 Removing Entries from the Reserved Memory RegistryYou can remove a reserved memory entry by issuing the following SYSMAN command:
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.
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.
In the running system, you can free reserved memory by issuing the following SYSMAN command:
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.
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.
16.6.2.4 Using Reserved MemoryThe 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.
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.
16.6.3 Application ConfigurationThe configuration of an OpenVMS Alpha application that uses memory-resident global sections performs the following steps:
Part 4
This part describes the basic calling format for OpenVMS routines and
system services. It also describes the STARLET structures and
definitions for C programmers.
|
The documentation format described in this chapter is generic; portions of it are used or not used, as appropriate, in the following OpenVMS manuals that document system routines: OpenVMS System Services Reference Manual: A--GETUAI |
This chapter provides additional explanations for the following documentation categories for routines:
However, some main categories in the routine format contain information requiring no explanation beyond that given in Table 17-1.
| 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. |
The following three types of information can be present in the format heading:
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.
| 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. |
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.
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.
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]
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]]
| Previous | Next | Contents | Index |