[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS System Services Reference Manual


Previous Contents Index


$TSTCLUEVT

Simulates the occurrence of a cluster configuration event to test the functionality of the notification AST.

Format

SYS$TSTCLUEVT [handle] ,[acmode] ,[event]


C Prototype

int sys$tstcluevt (unsigned int *handle, unsigned int acmode, unsigned int event);


Arguments

handle


OpenVMS usage: identifier
type: quadword (unsigned)
access: read only
mechanism: by reference

Identification of the asynchronous system trap (AST) to be tested. The handle argument uniquely identifies the request and is returned when the $SETCLUEVT service is called.

acmode


OpenVMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value

Access mode for which a configuration event AST is to be triggered. The acmode argument is a longword containing the access mode.

Each access mode has a symbolic name. The $PSLDEF macro defines the following symbols for the four access modes.
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User

event


OpenVMS usage: event_code
type: longword (unsigned)
access: read only
mechanism: by value

Event code indicating the type of configuration for which an AST is to be triggered.

Each event type has a symbolic name. The $CLUEVTDEF macro defines the following symbolic names.
Symbolic Name Description
CLUEVT$C_ADD One or more OpenVMS nodes have been added to the OpenVMS Cluster system.
CLUEVT$C_REMOVE One or more OpenVMS nodes have been removed from the OpenVMS Cluster system.


Description

The Test Cluster Event service simulates the occurrence of a cluster configuration event to test the functionality of the notification ASTs. The service allows an application to test itself and must be issued from within the same process as the application being tested. $TSTCLUEVT does not affect other processes in the cluster.

The service will allow one specific AST to be fired via the handle argument, or all ASTs for a specific configuration event via the event argument. Specifying both the event and the handle arguments will return an error.

If the handle argument is specified, the value of the acmode argument must not be greater than the access mode of the caller and must match the mode specified when the $SETCLUEVT service was called.

If the event argument is specified, those ASTs that match the value specified in the acmode argument, or that match the caller's mode, will be triggered.

Required Access or Privileges

None

Required Quota

None

Related Services

$CLRCLUEVT, $SETCLUEVT


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_BADPARAM There is an unsatisfactory combination of event and handle parameters, or the event was specified incorrectly.
SS$_NOSUCHOBJ No request was found that matches the description supplied.

$ULKPAG

Unlocks pages that were previously locked in memory by the Lock Pages in Memory ($LCKPAG) service. Locked pages are automatically unlocked and deleted at image exit.

Format

SYS$ULKPAG inadr ,[retadr] ,[acmode]


C Prototype

int sys$ulkpag (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 pages to be unlocked. 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. If the starting and ending virtual addresses are the same, a single page is unlocked.

If more than one page is being unlocked and you need to determine specifically which pages had been previously unlocked, you should unlock the pages one at a time, that is, one page per call to $ULKPAG. The condition value returned by $ULKPAG indicates whether the page was previously unlocked.

retadr


OpenVMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference---array reference or descriptor

Starting and ending process virtual addresses of the pages actually unlocked by $ULKPAG. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.

If an error occurs while multiple pages are being unlocked, retadr specifies those pages that were successfully unlocked before the error occurred. If no pages were successfully unlocked, both longwords in the retadr array contain the value --1.

acmode


OpenVMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value

Access mode on behalf of which the request is being made. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the symbols for the four access modes.

The most privileged access mode used is the access mode of the caller. To unlock any specified page, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.


Description

The Unlock Pages from Memory service unlocks pages that were previously locked in memory by the Lock Pages in Memory ($LCKPAG) service. Locked pages are automatically unlocked and deleted at image exit.

On Alpha systems, if you are attempting to unlock executable code, you should issue multiple $ULKPAG calls: one to unlock the code pages and others to unlock the linkage section references to these pages.

Required Access or Privileges

To call the $ULKPAG service, a process must have PSWAPM privilege.

Required Quota

None

Related Services

For more information, see the chapter on memory management in the OpenVMS Programming Concepts Manual.


Condition Values Returned

SS$_WASCLR The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET The service completed successfully. All of the specified pages were previously locked.
SS$_ACCVIO The input array cannot be read by the caller; the output array cannot be written by the caller; or a page in the specified range is inaccessible or does not exist.

$ULKPAG_64 (Alpha Only)

On Alpha systems, unlocks pages that were previously locked in memory by the Lock Pages in Memory ($LCKPAG_64) service.

This service accepts 64-bit addresses.


Format

SYS$ULKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64


C Prototype

int sys$ulkpag_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 unlocked. 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 unlocked. 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 on behalf of which the request is being made. 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. To unlock any specified page, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.

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 unlocked virtual address range. 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 unlocked. 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 Unlock Pages from Memory service unlocks pages that were previously locked in memory by the Lock Pages in Memory ($LCKPAG_64) service.

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 unlocked before the error occurred. If no pages were unlocked, 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

To call the $ULKPAG_64 service, a process must have PSWAPM privilege.

Required Quota

None

Related Services

$LCKPAG_64, $ULKPAG


Condition Values Returned

SS$_WASCLR The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET The service completed successfully. All of the specified pages were previously locked in the working set.
SS$_ACCVIO The return_va_64 or return_length_64 argument cannot be written by the caller, or an attempt was made to unlock pages by a caller whose access mode is less privileged than the access mode associated with the pages.

$ULWSET

Unlocks pages that were previously locked in the working set by the Lock Pages in Working Set ($LKWSET) service.

Format

SYS$ULWSET inadr ,[retadr] ,[acmode]


C Prototype

int sys$ulwset (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---array reference or descriptor

Starting and ending virtual addresses of the pages to be unlocked. 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. If the starting and ending virtual address are the same, a single page is unlocked.

If more than one page is being unlocked and you need to determine specifically which pages had been previously unlocked, you should unlock the pages one at a time, that is, one page per call to $ULWSET. The condition value returned by $ULWSET indicates whether the page was previously unlocked.

retadr


OpenVMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference---array reference or descriptor

Starting and ending process virtual addresses of the pages that were actually unlocked by $CRMPSC. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.

If an error occurs while multiple pages are being unlocked, retadr specifies those pages that were successfully unlocked before the error occurred. If no pages were successfully unlocked, both longwords in the retadr array contain the value --1.

acmode


OpenVMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value

Access mode on behalf of which the request is being made. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the symbols for the four access modes.

The most privileged access mode used is the access mode of the caller. To unlock any specified page, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.


Description

The Unlock Pages from Working Set service unlocks pages that were previously locked in the working set by the Lock Pages in Working Set ($LKWSET) service. Unlocked pages become candidates for replacement within the working set of the process.

On Alpha systems, if you are attempting to unlock executable code, you should issue multiple $ULKWSET calls: one to unlock the code pages and others to unlock the linkage section references to these pages.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $UPDSEC, $UPDSECW


Condition Values Returned

SS$_WASCLR The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET The service completed successfully. All of the specified pages were previously locked in the working set.
SS$_ACCVIO The inadr argument cannot be read by the caller; the retadr argument cannot be written by the caller; or a page in the specified range is inaccessible or does not exist.
SS$_NOPRIV A page in the specified range is in the system address space.

$ULWSET_64 (Alpha Only)

On Alpha systems, unlocks a virtual address range that was previously locked in the working set by the Lock Pages in Working Set ($LKWSET_64) service.

This service accepts 64-bit addresses.


Format

SYS$ULWSET_64 start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64


C Prototype

int sys$ulwset_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 unlocked from 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 unlocked from 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 on behalf of which the request is being made. 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. To unlock any specified page, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.

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 unlocked virtual address range. 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 unlocked. 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 Unlock Pages from Working Set service unlocks pages that were previously locked in the working set by the Lock Pages in Working Set ($LKWSET_64) service. Unlocked pages become candidates for replacement within the working set of the process.

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 unlocked before the error occurred. If no pages were unlocked, 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

None

Required Quota

None

Related Services

$LKWSET_64, $PURGE_WS, $ULWSET


Condition Values Returned

SS$_WASCLR The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET The service completed successfully. All of the specified pages were previously locked in the working set.
SS$_ACCVIO The return_va_64 or return_length_64 argument cannot be written by the caller, or an attempt was made to unlock pages by a caller whose access mode is less privileged than the access mode associated with the pages.
SS$_PAGNOTINREG A page in the specified range is not within process private address space.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4527PRO_095.HTML