Establishes a correspondence between pages (maps) in the virtual
address space of the process and physical pages occupied by a
global section.
Format
SYS$MGBLSC inadr ,[retadr] ,[acmode] ,[flags] ,gsdnam ,[ident]
,[relpag]
C Prototype
int sys$mgblsc (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode, unsigned int
flags, void *gsdnam, struct _secid *ident,
unsigned int relpag);
1 – Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses into which the section is
to be mapped. The inadr argument is the address of a 2-longword
array containing, in order, the starting and ending process
virtual addresses. Only the virtual page number portion of each
virtual address is used to specify which pages are to be mapped;
the low-order byte-within-page bits are ignored for this purpose.
The interpretation of the inadr argument depends on the setting
of SEC$M_EXPREG in the inadr argument and whether you are
using an Alpha or an Integrity servers system. For a complete
description of these differences, see the VSI OpenVMS System
Services Reference Manual.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses into which the
section was actually mapped by $MGBLSC. The retadr argument
is the address of a 2-longword array containing, in order, the
starting and ending process virtual addresses.
On Alpha and Integrity server systems, the retadr argument
returns the starting and ending addresses of the usable range
of addresses. This might differ from the total amount mapped.
The retadr argument is required when the relpag argument is
specified. If the section being mapped does not completely
fill the last page used to map the section, the retadr argument
indicates the highest address that actually maps the section.
If the relpag argument is used to specify an offset into the
section, the retadr argument reflects the offset.
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.
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 wherein a bit when set
specifies the corresponding option.
The $SECDEF macro defines symbolic names for the flag bits. You
construct the flags argument by specifying the symbolic names of
each desired option in a logical OR operation.
The following table describes each flag option:
Flag Option Description
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 and the section is not copy-
on-reference, write access is required.
SEC$M_SYSGBL Map a system global section. By default, the
section is a group global section.
SEC$M_EXPREG Map the section into the first available virtual
address range. By default, the section is mapped
into the range specified by the inadr argument.
See the inadr argument description for a complete
explanation of how to set the SEC$M_EXPREG flag.
SEC$M_ Flag that must be set when a PFN-mapped section
UNCACHED is created if this section must be treated as
uncached memory. Flag is ignored on Alpha systems;
it applies only to Integrity server systems.
gsdnam
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the global section. The gsdnam argument is the address of
a character string descriptor pointing to this name string.
For group global sections, the operating system interprets the
group UIC as part of the global section name; thus, the names
of global sections are unique to UIC groups. Further, all global
section names are implicitly qualified by their identification
fields.
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 VSI OpenVMS
Programming Concepts Manual.
ident
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification value specifying the version number of a global
section and, for processes mapping to an existing global section,
the criteria for matching the identification. The ident argument
is the address of a quadword structure containing three fields.
The first longword specifies, in the low-order two bits, the
matching criteria. Their valid values, the symbolic names by
which they can be specified, and their meanings are as follows:
Value/Name Match Criteria
0 SEC$K_ Match all versions of the section.
MATALL
1 SEC$K_ Match only if major and minor identifications
MATEQU match.
2 SEC$K_ Match if the major identifications are equal and
MATLEQ the minor identification of the mapper is less
than or equal to the minor identification of the
global section.
The version number is in the second longword and contains two
fields: a minor identification in the low-order 24 bits and a
major identification in the high-order 8 bits.
If you do not specify ident or specify it as the value 0 (the
default), the version number and match control fields default to
the value 0.
relpag
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Relative page number within the section of the first page to be
mapped. The relpag argument is a longword containing this number.
On Alpha and Integrity server systems, the relpag argument is
interpreted as an index into the section file, measured in
pagelets for a file-backed section or CPU-specific pages for a
PFN-mapped section.
On Alpha, Integrity servers systems, if you do not specify relpag
or specify it as the value 0 (the default), the global section
is mapped beginning with the first virtual block in a file-backed
section or the first CPU-specific page in a PFN-mapped section.