Copyright Digital Equipment Corp. All rights reserved.
Arguments
function_code
OpenVMS usage:function code
type: longword (unsigned)
access: read only
mechanism: by value
Function code specifying how the information you are requesting
should be looked up. All function codes return region summary
information in the return buffer in the format of the Region
Summary Buffer. The Region Summary Buffer format is shown in the
table in the buffer_address_64 argument.
If less buffer space is specified than the length of the Region
Summary Buffer, only the amount of information requested is
returned. If more buffer space is specified than the length of
the Region Summary Buffer, the service will fill in the buffer.
The return length will reflect the amount of useful information
written to the buffer, the size of the Region Summary Buffer.
The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
STARLET.MLB define a symbolic name for each function code.
The following function codes are defined:
Symbolic Name Description
VA$_REGSUM_BY_ID Return the region summary information for
the region whose ID is specified in the
region_id_64 argument.
VA$_REGSUM_BY_VA Return the region summary information for
the region that contains the virtual address
specified in the start_va_64 argument.
VA$_NEXT_REGSUM_ Return the region summary information for
BY_VA the region containing the starting address.
If the starting address is not in a region,
return the region summary information for
the next region with a starting address
higher than the specified address.
Note: For the VA$_NEXT_REGSUM_BY_VA
function, OpenVMS checks for a start_va_64
argument in the inaccessible address range
in P2 space. If it finds one, OpenVMS
adjusts the address to account for the
discontinuity. For more information about
the layout of the 64-bit virtual address
space, see the VSI OpenVMS Programming
Concepts Manual.
This function code can be used for wildcard
operations. See the description of the
start_va_64 argument for information on how
to program a wildcard operation on regions.
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 about which information
is requested. This argument is read only if the function code
VA$_REGSUM_BY_ID is specified.
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.
start_va_64
OpenVMS usage:input address
type: quadword address
access: read only
mechanism: by value
Virtual address associated with region about which information
is requested. This argument is read only if the function_code
argument is VA$_REGSUM_BY_VA or VA$_NEXT_REGSUM_BY_VA.
If the function_code argument is VA$_REGSUM_BY_VA, this argument
is a virtual address within the region about which you are
requesting information.
To perform a wildcard search on all regions, specify VA$_
NEXT_REGSUM_BY_VA as the function code and begin with the
start_va_64 argument specified as -1. For subsequent calls,
specify start_va_64 as the sum of the previous region's start
address and length. Call the $GET_REGION_INFO service in a loop
until the condition SS$_NOMOREREG is returned.
NOTE
Before performing the lookup function, OpenVMS sign-extends
the 64-bit starting address so that it represents a properly
formed virtual address for the CPU.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument Reserved to VSI.
buffer_length
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Length of the buffer into which information is returned.
buffer_address_64
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a quadword-aligned buffer
into which to return information if the buffer_length argument is
nonzero.
This argument is ignored if the buffer_length argument is zero.
The following table shows the format of the Region Summary
Buffer:
Table SYS-20 Region Summary Buffer Format
Field
Size Field Offset
Field name Meaning (Bytes) (Decimal)
VA$L_FLAGS Flags used when 4 8
region was created
VA$L_REGION_ Create and owner 4 12
PROTECT mode of region
VA$Q_REGION_ID Region identifier 8 0
VA$PQ_START_VA Starting (lowest) 8 16
virtual address of
region
VA$Q_REGION_SIZE Total length of 8 24
region
VA$PQ_FIRST_FREE_ First free virtual 8 32
VA address in region
VA$C_REGSUM_LENGTH Length of Region constant 40
Summary Buffer
The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF MACRO in
STARLET.MLB define the REGSUM structure.
return_length_64
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
The 32- or 64-bit virtual address of a naturally aligned longword
into which the service returns the length of the information in
bytes.