OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

The most privileged access mode used is the access mode of the caller. Address space cannot be created within a region that has a create mode associated with it that is more privileged than the caller's mode. The condition value SS$_IVACMODE is returned if the caller is less privileged than the create mode for the region.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Flag mask specifying options for the operation. The flags argument is a longword bit vector in which each bit corresponds to a flag. The $SECDEF macro and the SECDEF.H file define a symbolic name for each flag. You construct the flags argument by performing a logical OR operation on the symbol names for all desired flags.

The following table describes each flag that is valid for the $MGBLSC_64 service.

Flag Description

SEC$M_EXPREG Pages are mapped into the first available space at the current end of the specified region.
If /ALLOCATE was specified when the memory-resident global section was registered in the Reserved Memory Registry, virtually aligned addresses after the first available space are chosen for the mapping.
It the region_id_64 argument specifies a shared page-table region, the first available space is round up to the beginning of the next CPU-specific page-table page.

SEC$M_GBL Pages form a global section. By default, this flag is always present in this service and cannot be disabled.

SEC$M_NO_OVERMAP Pages cannot overmap existing address space.

SEC$M_SYSGBL The global section map is a system global section. By default, the section is a group global section.

SEC$M_WRT Map the section with read/write access.

Flag	Description
SEC$M_EXPREG	Pages are mapped into the first available space at the current end of the specified region. If /ALLOCATE was specified when the memory-resident global section was registered in the Reserved Memory Registry, virtually aligned addresses after the first available space are chosen for the mapping. It the region_id_64 argument specifies a shared page-table region, the first available space is round up to the beginning of the next CPU-specific page-table page.
SEC$M_GBL	Pages form a global section. By default, this flag is always present in this service and cannot be disabled.
SEC$M_NO_OVERMAP	Pages cannot overmap existing address space.
SEC$M_SYSGBL	The global section map is a system global section. By default, the section is a group global section.
SEC$M_WRT	Map the section with read/write access.

All other bits in the flags argument are reserved for future use by Compaq and should be specified as 0. The condition value SS$_IVSECFLG is returned if any undefined bits are set or if an attempt is made to use the SEC$M_PAGFIL flag, which applies only to the creation of a page-file backed section.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The process virtual address into which the global disk or page file section was mapped. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the virtual address.

Upon successful completion of this service, if the section_offset_64 argument was specified, the virtual address returned in the return_va_64 argument reflects the offset into the global section mapped such that the virtual address returned cannot be aligned on a CPU-specific page boundary. The virtual address returned will always be on an even virtual disk block boundary.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The length of the usable virtual address range mapped. The return_length_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length of the virtual address range mapped in bytes.

Upon successful completion of this service, the value in the return_length_64 argument might differ from the total amount of virtual address space mapped. The value in the return_va_64 argument plus the value in the return_length_64 argument indicates the address of the first byte beyond the end of the mapping of the global disk file section.

If the value in the section_offset_64 argument plus the value in the length_64 argument did not specify to map the entire global section, this byte can be located at an even virtual disk block boundary within the last page of the mapping.

If the section being mapped does not completely fill the last page used to represent the global disk file section, this byte can be mapped into your address space; however, it is not backed up by the disk file.

start_va_64

OpenVMS usage:	address
type:	quadword address
access:	read only
mechanism:	by value

The starting virtual address to which to map the global section. The specified virtual address must be a CPU-specific page-aligned address. If the flag SEC$M_EXPREG is specified, the start_va_64 argument must not be specified or must be specified as 0. If SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the condition value SS$_IVSECFLG is returned.

If the region_id_64 argument specifies a shared page-table region, start_va_64 must be aligned to a CPU-specific page-table page boundary.

Description

The Map to Global Section service establishes a correspondence between pages in the virtual address space of the process and pages occupied by a global disk file, page file, or memory-resident demand-zero section. This service adds pages to the virtual address space of the process.
If a global disk file or page file backed section is being mapped, invalid page table entries are placed in the process page table.
If a memory-resident global section is being mapped, global pages are not charged against the process's working set quota when the virtual memory is referenced and the global pages are not charged against the process's pagefile quota.
If the memory-resident global section was not registered in the Reserved Memory Registry or /NOALLOCATE was specified when the global section was registered, invalid page table entries are placed in the process page table.
If the memory-resident global section was registered in the Reserved Memory Registry and /ALLOCATE was specified when the memory-resident global section was registered, valid page table entries are placed in the process page tables.
If a global disk file or page file backed section is being mapped and the flag SEC$M_EXPREG is set, the first free virtual address within the specified region is used to start mapping to the global section.
To use the shared page tables associated with a memory-resident global section, you must first create a shared page table region (with SYS$CREATE_REGION_64). To map to the memory-resident global section using the shared page tables you must do the following:

Specify a shared page table region in the region_id_64 argument.
Specify SEC$M_WRT in the flags argument.
Set the flag SEC$M_EXPREG or provide a CPU-specific page-table page-aligned virtual address in the start_va_64 argument.
Specify a CPU-specific page-table page-aligned value for the section_offset_64 argument or zero.
Specify a value for the map_length_64 argument that is an even multiple of bytes mapped by a CPU-specific page-table page, or include the last page of the section or zero.

See the description of $CREATE_REGION_64 for information about calculating virtual addresses that are aligned to a CPU-specific page table page boundary.
A memory-resident global section can be mapped with shared page tables or private page tables. The following table lists the factors associated with determining whether the mapping occurs with shared page tables or private page tables.

Global Section Created with Shared Page Tables Shared Page-Table Region Specified by region_id_64 Type of Page Tables Used in Mapping

No No Private

No Yes Private

Yes No Private

Yes Yes Shared

In general, if the flag SEC$M_EXPREG is set, the first free virtual address within the specified region is used to map to the global section.
If the flag SEC$M_EXPREG is set, a memory-resident global section is being mapped and the region_id_64 argument indicates a shared page-table region, the first free virtual address within the specified region is rounded up to a CPU-specific page-table page boundary and used to map to the global section.
If the flag SEC$M_EXPREG is set and the /ALLOCATE qualifier was specified with the SYSMAN command RESERVED_MEMORY ADD for the memory-resident global section, the first free virtual address within the specified region is rounded up to the same virtual alignment as the physical alignment of the preallocated pages and used to map to the global section. Granularity hints are set appropriately for each process private page-table entry (PTE).
In general, if the flag SEC$M_EXPREG is clear, the virtual address in the start_va_64 argument is used to map to the global section.
If the flag SEC$M_EXPREG is clear and a memory-resident global section is being mapped, the value specified in the start_va_64 argument can determine if the mapping is possible and if granularity hints are used in the private page tables. If a shared page-table region is specified by the region_id_64 argument, the virtual address specified by the start_va_64 argument must be on an even CPU-specific page-table page boundary or an error is returned by this service. If the region_id_64 argument does not specify a shared page-table region and the /ALLOCATE qualifier was specified with the SYSMAN command RESERVED_MEMORY ADD for this global section, granularity hints are used only if the virtual alignment of start_va_64 is appropriate for the use of granularity hints (either 8-page, 64-page or 512-page alignment).
Whenever granularity hints are being used within the mapping of a memory-resident global section, if the length_64 argument is not an exact multiple of the alignment factor, lower granularity hints factors are used as appropriate at the higher addressed portion of the global section. If the section_offset_64 argument is specified, a lower granularity hint factor can be used throughout the mapping of the global section to match the physical alignment of the first page mapped.
If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64 and return_length_64 arguments.
If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully mapped before the error occurred. If no pages were mapped, the return_va_64 argument contains the value --1.
Required Privileges

None
Required Quota

If private page tables are used to map to the global section, the working set limit quota (WSQUOTA) of the process must be sufficient to accommodate the increased size of the process page tables required by the increase in virtual address space when the section is mapped.
If private page tables are used to map to a memory-resident global section, the pagefile quota (PGFLQUOTA) of the process must be sufficient to accommodate the increased size of the process page tables required by the increase in virtual address space.
If the process is mapping to a global copy-on-reference section, the pagefile quota (PGFLQUOTA) of the process must be sufficient to accommodate the increased size of the virtual address space.
Related Services

$CREATE_GDZRO, $CREATE_GFILE, $CREATE_GPFILE, $CREATE_REGION_64, $CRMPSC_GDZRO_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64, $DELETE_REGION_64, $DELTVA_64, $LCKPAG_64, $LKWSET_64, $MGBLSC, $MGBLSC_GPFN_64, $PURGE_WS, $ULKPAG_64, $ULWSET_64, $UPDSEC_64, $UPDSEC_64W

Global Section Created with Shared Page Tables	Shared Page-Table Region Specified by region_id_64	Type of Page Tables Used in Mapping
No	No	Private
No	Yes	Private
Yes	No	Private
Yes	Yes	Shared

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The gs_name_64 argument cannot be read by the caller, or the return_va_64 argument or the return_length_64 argument cannot be written by the caller.

SS$_EXPGFLQUOTA The process's page file quota is not large enough to accommodate the increased virtual address space.

SS$_GBLSEC_MISMATCH Global section type mismatch. The specified global section was found; however, it is not a global disk-file, page-file, or demand-zero section.

SS$_INSFWSL The process's working set limit is not large enough to accommodate the increased virtual address space.

SS$_IVACMODE The specified access mode is greater than PSL$_USER or the caller's mode is less privileged than the create mode associated with the region. Or, if a shared page table region is specified by the region_id_64 argument, the acmode argument does not match the access mode of the shared PTEs.

SS$_IVLOGNAM The specified global section name has a length of 0 or has more than 43 characters.

SS$_IVREGID An invalid region ID was specified.

SS$_IVSECFLG An invalid flag, a reserved flag, or an invalid combination of flags was specified.

SS$_IVSECIDCTL The match control field of the global section identification is invalid.

SS$_LEN_NOTBLKMULT The length_64 argument is not a multiple of virtual disk blocks if a map to a global section was requested (SEC$M_PAGFIL is clear in the flags argument).

SS$_LEN_NOTPAGMULT The length_64 argument is not a multiple of CPU-specific pages and a map to a global page file section was requested.

SS$_NOSHPTS The region ID of a shared page-table region was specified, and a gobal section was specified that is not a memory-resident demand-zero section.

SS$_NOSHPTS The region ID of a shared page table region was specified.

SS$_NOSUCHSEC The specified global section does not exist.

SS$_OFF_NOTPAGALGN The section_offset_64 argument is not CPU-specific page aligned if a map to a global page-file or demand-zero section is requested. Or, if a shared page table region is specified by the region_id_64 argument, the section_offset_64 argument is not CPU-specific page-table page aligned.

SS$_OFFSET_TOO_BIG The section_offset_64 argument specified is beyond the logical end-of-file.

SS$_PAGNOTINREG A page in the specified input address range is not within the specified region.

SS$_PAGOWNVIO A page in the specified input address range already exists and cannot be deleted because it is owned by a more privileged access mode.

SS$_PROTVIO The file protection mask specified when the global section was created prohibits the type of access requested by the caller.

SS$_REGISFULL The specified virtual region is full; no space is available in the region for the pages created to contain the mapped section.

SS$_SECREFOVF The maximum number of references for a global section has been reached (2,147,483,647).

SS$_SECTBLFUL There are no entries available in the system global section table.

SS$_TOOMANYLNAM The logical name translation of the gs_name_64 argument exceeded the allowed depth of 10.

SS$_VA_IN_USE A page in the specified input address range is already mapped and the flag SEC$M_NO_OVERMAP is set, or a page in the specified input address range is in another region, in system space, or inaccessible; or, the existing underlying page cannot be deleted because it is associated with a buffer object.

SS$_VA_NOTPAGALGN The start_va_64 argument is not CPU-specific page aligned. Or, if a shared page table region is specified by the region_id_64 argument, the start_va_64 argument is not CPU-specific page-table page aligned.

SS$_NOWRTACC The specified global section is not copy-on-reference and does not allow write access.

$MGBLSC_GPFN_64 (Alpha Only)

On Alpha systems, establishes a correspondence between pages in the virtual address space of the process and the pages occupied by a global page frame section.
This service accepts 64-bit addresses.

Format

SYS$MGBLSC_GPFN_64 gs_name_64 ,ident_64 ,region_id_64 ,relative_page ,page_count ,acmode ,flags ,return_va_64 ,return_length_64 [,start_va_64]

C Prototype

int sys$mgblsc_gpfn_64 (void *gsdnam_64, struct _secid *ident_64, struct _generic_64 *region_id_64, unsigned int relative_page, unsigned int page_count, unsigned int acmode, unsigned int flags, void *(*(return_va_64)), unsigned __int64 *return_length_64,...);

Arguments

gs_name_64

OpenVMS usage: section_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor

Name of the global section. The gs_name argument is the 32- or 64-bit virtual address of a naturally aligned 32-bit or 64-bit descriptor pointing to this name string.
ident_64

OpenVMS usage: section_id

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Identification value specifying the version number of a global section. The ident_64 argument is a quadword containing three fields. The ident_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword that contains the identification value.
The first longword specifies the matching criteria in its low-order two bits. The valid values, symbolic names by which they can be specified, and their meanings are as follows:

Value Symbolic Name Match Criteria

0 SEC$K_MATALL Match all versions of the section.

1 SEC$K_MATEQU Match only if major and minor identifications match.

2 SEC$K_MATLEQ Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section.

If you specify the ident_64 argument as 0, the version number and match control fields default to 0.
The version number is in the second longword. The version number contains two fields: a minor identification in the low-order 24 bits and a major identification in the high-order 8 bits. You can assign values for these fields by installation convention to differentiate versions of global sections. If no version number is specified when a section is created, processes that specify a version number when mapping cannot access the global section.
region_id_64

OpenVMS usage: region identifier

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

The region ID associated with the region to map the private page frame section. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a symbolic name for each of the three default regions in P0, P1, and P2 space. The following region IDs are defined:

Symbol Region

VA$C_P0 Program region

VA$C_P1 Control region

VA$C_P2 64-bit program region

Other region IDs, as returned by the $CREATE_REGION_64 service, can be specified.
relative_page

OpenVMS usage: CPU-specific page count

type: longword (unsigned)

access: read only

mechanism: by value

Relative CPU-specific page number within the global section to start mapping.
page_count

OpenVMS usage: CPU-specific page count

type: longword (unsigned)

access: read only

mechanism: by value

Length of mapping in CPU-specific pages. If zero is specified, the global page frame section is mapped to the end of the section.
acmode

OpenVMS usage: access-mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode to be associated with the pages mapped into the process virtual address space. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the four access modes.
The most privileged access mode used is the access mode of the caller. Address space cannot be created within a region that has a create mode associated with it that is more privileged than the caller's mode. The condition value SS$_IVACMODE is returned if the caller is less privileged than the create mode for the region.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Flag mask specifying options for the operation. The flags argument is a longword bit vector in which each bit corresponds to a flag. The $SECDEF macro and the SECDEF.H file define a symbolic name for each flag. You construct the flags argument by performing a logical OR operation on the symbol names for all desired flags.
The following table describes each flag that is valid for the $MGBLSC_GPFN_64 service:

Flag Description

SEC$M_GBL Pages form a global section. By default, this flag is always present in this service and cannot be disabled.

SEC$M_EXPREG Map the section into the first available space at the current end of the specified region. If this flag is specified, the start_va_64 argument is not used.

SEC$M_PERM Pages are permanent. By default, this flag is always present in this service and cannot be disabled.

SEC$M_PFNMAP Pages form a page frame section. By default, this flag is always present in this service and cannot be disabled.

SEC$M_PAGFIL Pages form a global page-file section. SEC$M_PAGFIL also implies SEC$M_WRT and SEC$M_DZRO.

SEC$M_SYSGBL Map a system global section. By default, the section is a group global section.

SEC$M_WRT Map the section with read/write access. By default, the section is mapped with read-only access. If SEC$M_WRT is specified, write access is required.

All other bits in the flags argument are reserved for future use by Compaq and should be specified as 0. The condition value SS$_IVSECFLG is returned if any undefined bits are set or if an illegal combination of flags is set.
return_va_64

OpenVMS usage: address

type: quadword address

access: write only

mechanism: by 32- or 64-bit reference

The lowest process virtual address into which the global page frame section was mapped. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword that contains the virtual address.
return_length_64

OpenVMS usage: byte count

type: quadword (unsigned)

access: write only

mechanism: by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword into which the $MGBLSC_GPFN_64 service returns the length of the virtual address range in bytes.
start_va_64

OpenVMS usage: address

type: quadword address

access: read only

mechanism: by value

The starting virtual address to map the global section. The specified virtual address must be a CPU-specified page-aligned address. If the flag SEC$M_EXPREG is specified, the start_va_64 argument must not be specified or must be specified as 0. If SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the condition value SS$_IVSECFLG is returned.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

4527PRO_065.HTML

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The gs_name_64 argument cannot be read by the caller, or the return_va_64 argument or the return_length_64 argument cannot be written by the caller.
SS$_EXPGFLQUOTA	The process's page file quota is not large enough to accommodate the increased virtual address space.
SS$_GBLSEC_MISMATCH	Global section type mismatch. The specified global section was found; however, it is not a global disk-file, page-file, or demand-zero section.
SS$_INSFWSL	The process's working set limit is not large enough to accommodate the increased virtual address space.
SS$_IVACMODE	The specified access mode is greater than PSL$_USER or the caller's mode is less privileged than the create mode associated with the region. Or, if a shared page table region is specified by the region_id_64 argument, the acmode argument does not match the access mode of the shared PTEs.
SS$_IVLOGNAM	The specified global section name has a length of 0 or has more than 43 characters.
SS$_IVREGID	An invalid region ID was specified.
SS$_IVSECFLG	An invalid flag, a reserved flag, or an invalid combination of flags was specified.
SS$_IVSECIDCTL	The match control field of the global section identification is invalid.
SS$_LEN_NOTBLKMULT	The length_64 argument is not a multiple of virtual disk blocks if a map to a global section was requested (SEC$M_PAGFIL is clear in the flags argument).
SS$_LEN_NOTPAGMULT	The length_64 argument is not a multiple of CPU-specific pages and a map to a global page file section was requested.
SS$_NOSHPTS	The region ID of a shared page-table region was specified, and a gobal section was specified that is not a memory-resident demand-zero section.
SS$_NOSHPTS	The region ID of a shared page table region was specified.
SS$_NOSUCHSEC	The specified global section does not exist.
SS$_OFF_NOTPAGALGN	The section_offset_64 argument is not CPU-specific page aligned if a map to a global page-file or demand-zero section is requested. Or, if a shared page table region is specified by the region_id_64 argument, the section_offset_64 argument is not CPU-specific page-table page aligned.
SS$_OFFSET_TOO_BIG	The section_offset_64 argument specified is beyond the logical end-of-file.
SS$_PAGNOTINREG	A page in the specified input address range is not within the specified region.
SS$_PAGOWNVIO	A page in the specified input address range already exists and cannot be deleted because it is owned by a more privileged access mode.
SS$_PROTVIO	The file protection mask specified when the global section was created prohibits the type of access requested by the caller.
SS$_REGISFULL	The specified virtual region is full; no space is available in the region for the pages created to contain the mapped section.
SS$_SECREFOVF	The maximum number of references for a global section has been reached (2,147,483,647).
SS$_SECTBLFUL	There are no entries available in the system global section table.
SS$_TOOMANYLNAM	The logical name translation of the gs_name_64 argument exceeded the allowed depth of 10.
SS$_VA_IN_USE	A page in the specified input address range is already mapped and the flag SEC$M_NO_OVERMAP is set, or a page in the specified input address range is in another region, in system space, or inaccessible; or, the existing underlying page cannot be deleted because it is associated with a buffer object.
SS$_VA_NOTPAGALGN	The start_va_64 argument is not CPU-specific page aligned. Or, if a shared page table region is specified by the region_id_64 argument, the start_va_64 argument is not CPU-specific page-table page aligned.
SS$_NOWRTACC	The specified global section is not copy-on-reference and does not allow write access.

OpenVMS usage:	section_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

OpenVMS usage:	section_id
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Value	Symbolic Name	Match Criteria
0	SEC$K_MATALL	Match all versions of the section.
1	SEC$K_MATEQU	Match only if major and minor identifications match.
2	SEC$K_MATLEQ	Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section.

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region

OpenVMS usage:	CPU-specific page count
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	access-mode
type:	longword (unsigned)
access:	read only
mechanism:	by value