 |
HP OpenVMS System Services Reference Manual
$JOIN_RMW
Adds a new Resource Manager (RM) participant to a transaction.
$JOIN_RMW always waits for the request to complete before returning to
the caller. Other than this, it is identical to $JOIN_RM.
Format
SYS$JOIN_RMW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id [,[tid]
,[part_name] ,[rm_context] ,[timout] ,[bid] ]
C Prototype
int sys$join_rmw (unsigned int efn, unsigned int flags, struct _iosb
*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int
rm_id,...);
$LCKPAG
Locks a page or range of pages in memory. The specified virtual pages
are forced into the working set and then locked in memory. A locked
page is not swapped out of memory if the working set of the process is
swapped out. These pages are not candidates for page replacement and in
this sense are locked in the working set as well.
Format
SYS$LCKPAG inadr ,[retadr] ,[acmode]
C Prototype
int sys$lckpag (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode);
Arguments
inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Starting and ending virtual addresses of the range of pages to be
locked. 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; the low-order byte-within-page bits are ignored.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Starting and ending process virtual addresses of the pages that $LCKPAG
actually locked. The retadr argument is the address of
a 2-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be associated with the pages to be locked. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines the four access modes.
The most privileged access mode used is the access mode of the caller.
For the $LCKPAG service to complete successfully, the resultant access
mode must be equal to or more privileged than the access mode already
associated with the pages to be locked.
Description
The Lock Pages in Memory service locks a page or range of pages in
memory. The specified virtual pages are forced into the working set and
then locked in memory. A locked page is not swapped out of memory if
the working set of the process is swapped out. These pages are not
candidates for page replacement and in this sense are locked in the
working set as well.
If more than one page is being locked and you need to determine
specifically which pages were previously locked, the pages should be
locked one at a time.
If an error occurs while the $LCKPAG service is locking pages, the
return array, if requested, indicates the pages that were successfully
locked before the error occurred. If no pages are locked, both
longwords in the return address array contain the value --1.
On Alpha and Integrity server systems, if you are attempting to lock
executable code, you should issue multiple $LCKPAG calls: one to lock
the code pages and others to lock the linkage section references into
these pages.
Required Access or Privileges
The calling process must have PSWAPM privilege to lock pages into
memory.
Required Quota
None
Related Services
You can unlock pages locked in memory with the Unlock Pages from Memory
($ULKPAG) service. Locked pages are automatically unlocked at image
exit.
For more information, see the chapter on memory management in the
HP OpenVMS Programming Concepts Manual.
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. All of the specified pages were
previously unlocked.
|
|
SS$_WASSET
|
The service completed successfully. At least one of the specified pages
was previously locked.
|
|
SS$_ACCVIO
|
The input array cannot be read; the output array cannot be written; the
page in the specified range is inaccessible or nonexistent; or an
attempt to lock pages was made by a caller whose access mode is less
privileged than the access mode associated with the pages.
|
|
SS$_LCKPAGFUL
|
The system-defined maximum limit on the number of pages that can be
locked in memory has been reached.
|
|
SS$_LDWSETFUL
|
The locked working set is full. If any more pages are locked, not
enough dynamic pages will be available to continue execution.
|
|
SS$_NOPRIV
|
The process does not have the privilege to lock pages in memory.
|
|
SS$_PAGOWNVIO
|
The pages could not be locked because the access mode associated with
the call to $LCKPAG was less privileged than the access mode associated
with the pages that were to be locked.
|
$LCKPAG_64 (Alpha and Integrity servers)
On Alpha and Integrity server systems, locks a range of pages in
memory. The specified virtual pages are forced into the working set and
then locked in memory. A locked page is not swapped out of memory if
the working set of the process is swapped out. These pages are not
candidates for page replacement and, in this sense, are locked in the
working set as well.
This service accepts 64-bit addresses.
Format
SYS$LCKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$lckpag_64 (void *start_va_64, unsigned __int64 length_64,
unsigned int acmode, void *(*(return_va_64)), unsigned __int64
*return_length_64);
Arguments
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address of the pages to be locked. The specified
virtual address will be rounded down to a CPU-specific page boundary.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space to be locked. The specified length
will be rounded up to a CPU-specific page boundary so that it includes
all CPU-specific pages in the requested range.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the pages to be locked. The
acmode argument is a longword containing the access
mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values for the
four access modes:
| Value |
Symbolic Name |
Access Mode |
|
0
|
PSL$C_KERNEL
|
Kernel
|
|
1
|
PSL$C_EXEC
|
Executive
|
|
2
|
PSL$C_SUPER
|
Supervisor
|
|
3
|
PSL$C_USER
|
User
|
The most privileged access mode used is the access mode of the caller.
For the $LCKPAG_64 service to complete successfully, the resultant
access mode must be equal to or more privileged than the access mode
already associated with the pages to be locked.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The lowest process virtual address of the pages locked in memory. 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.
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 service returns the length of the virtual address range
locked in bytes.
Description
The Lock Pages in Memory service locks a range of pages in memory. The
specified virtual pages are forced into the working set and then locked
in memory. A locked page is not swapped out of memory if the working
set of the process is swapped out. These pages are not candidates for
page replacement and, in this sense, are locked in the working set as
well.
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 locked before the error occurred. If no pages were locked,
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
A process must have PSWAPM privilege to call the $LCKPAG_64 service.
Required Quota
None
Related Services
$LCKPAG, $ULKPAG, $ULKPAG_64
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. All of the specified pages were
previously unlocked.
|
|
SS$_WASSET
|
The service completed successfully. At least one of the specified pages
was previously locked in the working set.
|
|
SS$_ACCVIO
|
The
return_va_64 argument or the
return_length_64 argument cannot be written by the
caller, or an attempt was made to lock pages by a caller whose access
mode is less privileged than the access mode associated with the pages.
|
|
SS$_LCKPAGFUL
|
The system-defined maximum limit on the number of pages that can be
locked in memory has been reached.
|
|
SS$_LKWSETFUL
|
The locked working set is full. If any more pages are locked, not
enough dynamic pages will be available to continue execution.
|
|
SS$_NOPSWAPM
|
The process does not have the privilege to lock pages in memory.
|
|
SS$_PAGOWNVIO
|
The pages could not be locked because the access mode associated with
the call to $LCKPAG_64 was less privileged than the access mode
associated with the pages that were to be locked.
|
$LKWSET
Locks a range of pages in the working set; if the pages are not already
in the working set, it brings them in and locks them. A page locked in
the working set does not become a candidate for replacement.
Format
SYS$LKWSET inadr ,[retadr] ,[acmode]
C Prototype
int sys$lkwset (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode);
Arguments
inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Starting and ending virtual addresses of the range of pages to be
locked in the working set. 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; the low-order byte-within-page bits
are ignored.
On Alpha and Integrity server systems, if the first address in the
2-longword array is within an image mapped to your process, the entire
image specified by the address is locked in the working set.
Be sure to check calls to the SYS$LKWSET and SYS$LKWSET_64 system
services for correct arguments. This affects only process-based code
running above IPL2. Compiler and linker differences might cause your
program layout to change from Alpha, resulting in incorrectly
calculated starting and ending addresses for calls to SYS$LKWSET and
SYS$LKWSET_64. Calling these services with incorrect arguments and then
executing this code above IPL2 could cause PGFIPLHI bugchecks. Note
that SYS$LKWSET and SYS$LKWSET_64 automatically lock linker-generated
short data sections associated with code sections locked in the working
set.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Starting and ending process virtual addresses of the range of pages
actually locked by $LKWSET. 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, if the inadr
argument specifies an address within an image mapped to your process,
retadr specifies only one range of pages locked in the
working set. Many ranges of pages might be locked.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be associated with the pages to be locked. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines the four access modes.
The most privileged access mode used is the access mode of the caller.
For the $LKWSET service to complete successfully, the resultant access
mode must be equal to or more privileged than the access mode already
associated with the pages to be locked.
Description
The Lock Pages in Working Set service locks a range of pages in the
working set; if the pages are not already in the working set, it brings
them in and locks them. A page locked in the working set does not
become a candidate for replacement.
If more than one page is being locked and you need to determine
specifically which pages were previously locked, the pages should be
locked one at a time.
If an error occurs while the $LKWSET service is locking pages, the
return array, if requested, indicates the pages that were successfully
locked before the error occurred. If no pages are locked, both
longwords in the return address array contain the value --1.
Global pages with write access cannot be locked into the working set.
On Alpha and Integrity server systems, if the first address specified
to SYS$LKWSET is within an image mapped to your process, a success
status indicates that the entire image containing the specified address
is locked in the working set. This behavior helps to ensure that
privileged processes entering kernel mode and raising IPL higher than
IPL 2 do not access an invalid page and cause a PGFIPLHI bugcheck. The
system keeps a count of the number of times each image within your
process is locked in the working set. This count is maintained so that
calls to SYS$ULWSET unlock the image only when it has been called the
same number of times as SYS$LKWSET.
If an attempt to lock an image in the working set returns
SS$_LKWSETFUL, you might consider moving all kernel mode code within
the image to a separate, smaller sharable image. Otherwise, you might
consider increasing the working set quota of the process.
The LIBRTL routine LIB$LOCK_IMAGE and LIB$UNLOCK_IMAGE are preferable
to SYS$LKWSET and SYS$ULKWSET for locking code and related data in the
working set. For more information about locking images in the working
set, see the LIBRTL manual and the descriptions of LIB$LOCK_IMAGE and
LIB$UNLOCK_IMAGE.
Required Access or Privileges
None
Required Quota
None
Related Services
You can unlock pages locked in the working set with the Unlock Page
from Working Set ($ULWSET) service.
For more information, see the chapter on memory management in the
HP OpenVMS Programming Concepts Manual.
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. All of the specified pages were
previously unlocked. The entire image might have been locked in the
working set.
|
|
SS$_WASSET
|
The service completed successfully. At least one of the specified pages
was previously locked in the working set. If the image has been locked
in the working set, the count of times the image has been locked in the
working set has been incremented.
|
|
SS$_ACCVIO
|
The input address array cannot be read; the output address array cannot
be written; a page in the specified range is inaccessible or
nonexistent; or an attempt was made to lock pages by a caller whose
access mode is less privileged than the access mode associated with the
pages.
|
|
SS$_LKWSETFUL
|
The locked working set is full. If any more pages are locked, not
enough dynamic pages will be available to continue execution. If the
image is being locked in the working set, the image is too large to be
entirely locked in the working set.
|
|
SS$_NOPRIV
|
A page in the specified range is in the system address space, or a
global page with write access was specified.
|
|
SS$_PAGOWNVIO
|
The pages could not be locked because the access mode associated with
the call to $LKWSET was less privileged than the access mode associated
with the pages that were to be locked.
|
$LKWSET_64 (Alpha and Integrity servers)
On Alpha and Integrity server systems, locks a range of virtual
addresses in the working set. If the pages are not already in the
working set, the service brings them in and locks them. A page locked
in the working set does not become a candidate for replacement.
This service accepts 64-bit addresses.
Format
SYS$LKWSET_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$lkwset_64 (void *start_va_64, unsigned __int64 length_64,
unsigned int acmode, void *(*(return_va_64)), unsigned __int64
*return_length_64);
Arguments
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address of the pages to be locked in the working
set. The specified virtual address will be rounded down to a
CPU-specific page boundary.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space to be locked in the working set.
The specified length will be rounded up to a CPU-specific page boundary
so that it includes all CPU-specific pages in the requested range.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the pages to be locked. The
acmode argument is a longword containing the access
mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values for the
four access modes:
| Value |
Symbolic Name |
Access Mode |
|
0
|
PSL$C_KERNEL
|
Kernel
|
|
1
|
PSL$C_EXEC
|
Executive
|
|
2
|
PSL$C_SUPER
|
Supervisor
|
|
3
|
PSL$C_USER
|
User
|
The most privileged access mode used is the access mode of the caller.
For the $LKWSET_64 service to complete successfully, the resultant
access mode must be equal to or more privileged than the access mode
already associated with the pages to be locked.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The lowest process virtual address of the pages locked in the working
set. 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.
return_length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The length of the virtual address range locked in the working set. 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 in bytes.
Description
The Lock Pages in Working Set service locks a range of pages in the
working set; if the pages are not already in the working set, it brings
them in and locks them. A page locked in the working set does not
become a candidate for replacement.
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 locked before the error occurred. If no pages were locked,
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.
Global pages with write access cannot be locked into the working set.
Be sure to check calls to the SYS$LKWSET and SYS$LKWSET_64 system
services for correct arguments. This affects only process-based code
running above IPL2. Compiler and linker differences might cause your
program layout to change from Alpha, resulting in incorrectly
calculated starting and ending addresses for calls to SYS$LKWSET and
SYS$LKWSET_64. Calling these services with incorrect arguments and then
executing this code above IPL2 could cause PGFIPLHI bugchecks. Note
that SYS$LKWSET and SYS$LKWSET_64 automatically lock linker-generated
short data sections associated with code sections locked in the working
set.
On Alpha and Integrity server systems, if the first address specified
to SYS$LKWSET_64 is within an image mapped to your process, a success
status indicates that the entire image containing the specified address
is locked in the working set. This behavior helps to ensure that
privileged processes entering kernel mode and raising IPL higher than
IPL 2 do not access an invalid page and cause a PGFIPLHI bugcheck. The
system keeps a count of the number of times each image within your
process is locked in the working set. This count is maintained so that
calls to SYS$ULWSET_64 unlock the image only when it has been called
the same number of times as SYS$LKWSET_64.
|
