Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $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.

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

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

## $MOD_HOLDER

> Modifies the specified holder record of the target identifier in the rights database.

### Format

> SYS$MOD_HOLDER id ,holder ,[set_attrib] ,[clr_attrib]

### C Prototype

> int sys$mod_holder (unsigned int id, struct _generic_64 *holder, unsigned int set_attrib, unsigned int clr_attrib);

### Arguments

> #### id

> OpenVMS usage: | rights_id
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Binary value of target identifier whose holder record is modified when $MOD_HOLDER completes execution. The id argument is a longword containing the identifier value.

> #### holder

> OpenVMS usage: | rights_holder
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by reference

> Identifier of holder being modified when $MOD_HOLDER completes execution. The holder argument is the address of a quadword containing the UIC identifier of the holder in the first longword and the value of 0 in the second longword.

> #### set_attrib

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

> Bit mask of attributes to be enabled for the identifier when $MOD_HOLDER completes execution. The set_attrib argument is a longword containing the attribute mask.

> The attributes actually enabled are the intersection of those specified and the attributes of the identifier. If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled.

> Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position are defined in the system macro library ($KGBDEF):

> Bit Position | Meaning When Set
> --- | ---
> KGB$V_DYNAMIC | Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET RIGHTS_LIST.
> KGB$V_NOACCESS | Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
> KGB$V_RESOURCE | Allows the holder to charge resources, such as disk blocks, to the identifier.
> KGB$V_SUBSYSTEM | Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

> #### clr_attrib

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

> Bit mask of attributes to be disabled for the identifier when $MOD_HOLDER completes execution. The clr_attrib argument is a longword containing the attribute mask.

> If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled.

> Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position are defined in the system macro library ($KGBDEF):

> Bit Position | Meaning When Set
> --- | ---
> KGB$V_DYNAMIC | Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET RIGHTS_LIST.
> KGB$V_NOACCESS | Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
> KGB$V_RESOURCE | Allows the holder to charge resources, such as disk blocks, to the identifier.
> KGB$V_SUBSYSTEM | Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

### Description

> The Modify Holder Record in Rights Database service modifies the specified holder record in the rights database. Identifier attributes can be added or removed.

> When you specify both the set_attrib and clr_attrib arguments, the attribute is cleared first. Thus, if you specify the same attribute bit with each argument, the result is that the bit is set.

> Required Access or Privileges

> Write access to the rights database is required.

> Required Quota

> None

> Related Services

> $ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GET_SECURITY, $GRANTID, $IDTOASC, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The holder argument cannot be read by the caller.
> SS$_BADPARAM | The specified attributes contain invalid attribute flags.
> SS$_INSFMEM | The process dynamic memory is insufficient for opening the rights database.
> SS$_IVIDENT | The specified identifier or holder identifier is of invalid format.
> SS$_NOSUCHID | The specified identifier does not exist in the rights database, or the specified holder identifier does not exist in the rights database.
> RMS$_PRV | The user does not have write access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_069.HTML