[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index

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


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 and I64)

On Alpha and I64 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.

You can specify any name from 1 to 43 characters. All processes mapping to the same global section must specify the same name. Note that the name is case sensitive.

Use of characters valid in logical names is strongly encouraged. Valid values include alphanumeric characters, the dollar sign ($), and the underscore (_). If the name string begins with an underscore (_), the underscore is stripped and the resultant string is considered to be the actual name. Use of the colon (:) is not permitted.

Names are first subject to a logical name translation, after the application of the prefix GBL$ to the name. If the result translates, it is used as the name of the section. If the resulting name does not translate, the name specified by the caller is used as the name of the section.

Additional information on logical name translations and on section name processing is available in the OpenVMS Programming Concepts Manual.

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) on Alpha, quadword (unsigned) on I64
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_ARGS64 Indicates that all parameters, specifically start_pfn and page_count, are passed as 64-bit numbers.
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_UNCACHED Flag accepted but ignored on I64 systems. The cached/uncached characteristic is stored as a section attribute, and the system uses this attribute when the section is mapped. Refer to this flag in the documentation of the SYS$CREATE_GPFN system service.
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 HP 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.

Always refer to the return_va_64 and return_length_64 arguments to determine the range of virtual addresses mapped.


Description

The Map Global Page Frame Section service establishes a correspondence between pages in the virtual address space of the process and pages occupied by a global page frame section. It adds pages to the virtual address space of the process.

Pages mapped to a global page frame section are not included in or charged against the process's working set; they are always valid. Do not lock these pages in the working set by using $LKWSET; this can result in a machine check if they are in I/O space.

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 will contain the value -1, and a value cannot be returned in the memory location pointed to by the return_length_64 argument.

Required Privileges

Read access is required. If the SEC$M_WRT flag is specified, write access is required.

Required Quota

The working set quota (WSQUOTA) of the process must be sufficient to accommodate the increased length of the process page table required by the increase in virtual address space.

The page file quota (PAGFLQUOTA) of the process must be sufficient to accommodate the increased number of process page tables required by the increase in virtual address space. (Note that this service can return the SS$_EXPGFLQUOTA.)

Related Services

$CREATE_GPFN, $CREATE_REGION_64, $CRMPSC_GPFN_64, $DELETE_REGION_64, $DELTVA_64, $MGBLSC, $MGBLSC_64


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 or return_length_64 argument cannot be written by the caller.
SS$_GBLSEC_MISMATCH Global section type mismatch. The specified global section was found; however, it is not a global page frame section.
SS$_ILLRELPAG The specified relative page argument is either larger than the highest page number within the section or is not a valid 32-bit physical page frame number.
SS$_INSFWSL The working set limit of the process is not large enough to accommodate the increased virtual address space.
SS$_IVACMODE The caller's mode is less privileged than the create mode associated with the region.
SS$_IVLOGNAM The specified global section name has a length of 0 or has more than 43 characters.
SS$_IVREGID Invalid region ID 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$_NOSUCHSEC The specified global section does not exist.
SS$_NOWRTACC The specified global section is not copy-on-reference and does not allow write access.
SS$_PROTVIO The file protection mask specified when the global section was created prohibits the type of access requested by the caller.
SS$_PAGNOTINREG A page in the specified range is not within the specified region.
SS$_PAGOWNVIO A page in the specified range already exists and cannot be deleted because it is owned by a more privileged access mode than that of 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 global section.
SS$_TOOMANYLNAM The logical name translation of the gs_name_64 argument exceeded the allowed depth of 10.
SS$_VA_IN_USE 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.


Previous Next Contents Index