OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

$DELTVA

Deletes a range of addresses from a process's virtual address space. Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations.

Format

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

C Prototype

int sys$deltva (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 deleted. The inadr argument is the address of a 2-longword array containing, in order, the starting and the ending process virtual addresses. If the starting and ending virtual addresses are the same, a single page is deleted. The addresses are adjusted up or down to fall on CPU-specific page boundaries. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.
The $DELTVA service deletes pages starting at the address contained in the second longword of the inadr argument and ending at the address in the first longword. Thus, if you use the same address array for both the Create Virtual Address Space ($CRETVA) and the $DELTVA services, the pages are deleted in the reverse order from which they were created.
retadr

OpenVMS usage: address_range

type: longword (unsigned)

access: write only

mechanism: by reference

Starting and ending process virtual addresses of the pages that $DELTVA has deleted. 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 on behalf of which the service is to be performed. The acmode argument is a longword containing the access mode.
The most privileged access mode used is the access mode of the caller. The calling process can delete pages only if those pages are owned by an access mode equal to or less privileged than the access mode of the calling process.

Description

The Delete Virtual Address Space service deletes a range of addresses from a process's virtual address space. Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations. If any of the pages in the specified range have already been deleted or do not exist, the service continues as if the pages were successfully deleted.
If an error occurs while pages are being deleted, the retadr argument specifies the pages that were successfully deleted before the error occurred. If no pages are deleted, both longwords in the return address array contain the value --1.
Required Access or Privileges

None
Required Quota

None
Related Services

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

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The input address array cannot be read by the caller, or the return address array cannot be written by the caller.

SS$_NOPRIV A page in the specified range is in the system address space.

SS$_PAGOWNVIO A page in the specified range is owned by an access mode more privileged than the access mode of the caller.

SS$_NOSHPTS The region ID of a shared page table region was specified.

SS$_VA_IN_USE The existing underlying page cannot be deleted because it is associated with a buffer object.

$DELTVA_64 (Alpha Only)

On Alpha systems, deletes a range of virtual addresses from a process's virtual address space. Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations.
This service accepts 64-bit addresses.

Format

SYS$DELTVA_64 region_id_64 ,start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64

C Prototype

int sys$deltva_64 (struct _generic_64 *region_id_64, void *start_va_64, unsigned __int64 length_64, unsigned int acmode, void *(*(return_va_64)), unsigned __int64 *return_length_64);

Arguments

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 from which to address the VA space.
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. Also, the region ID that a virtual address is in can be obtained by calling the $GET_REGION_INFO service, specifying the VA$_REGSUM_BY_VA function.
start_va_64

OpenVMS usage: address

type: quadword address

access: read only

mechanism: by value

The starting virtual address of the pages to be deleted. The specified address must be a CPU-specific page aligned address. If the region_id_64 argument specifies a shared page table region or if the start_va_64 argument lies within a shared page table region, the specified address must be a CPU-specific page table page aligned address.
length_64

OpenVMS usage: byte count

type: quadword (unsigned)

access: read only

mechanism: by value

Length of the virtual address space to be deleted. The length specified must be a multiple of CPU-specific pages. If the virtual address space is being deleted from a shared page table region, the specified length must be page table page aligned or include the last page in a memory-resident section.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode associated with the call to $DELTVA_64. 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. The calling process can delete pages only if those pages are owned by an access mode equal to or less privileged than the access mode of the calling process.
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 deleted virtual address range. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the $DELTVA_64 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 $DELTVA_64 service returns the length in bytes of the virtual address range deleted.

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region

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

Description

The Delete Virtual Address Space service is a kernel mode service that can be called from any mode. This service deletes a range of addresses from a process's virtual address space. Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations. If any of the pages in the specified range have already been deleted or do not exist, the service continues as if the pages were successfully deleted.
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 deleted before the error occurred. If no pages were deleted, 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

$CREATE_REGION_64, $CRETVA_64, $CRMPSC_FILE_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64, $CRMPSC_GPFN_64, $CRMPSC_PFN_64, $DELETE_REGION_64, $EXPREG_64, $MGBLSC_64, $MGBLSC_GPFN_64

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The return_va_64 argument or the return_length_64 argument cannot be written by the caller.

SS$_IVREGID Invalid region ID specified. This condition value is returned if P0, P1, or P2 space is specified because these regions cannot be deleted, or if no region exists for the specified ID.

SS$_LEN_NOTPAGMULT The length_64 argument is not a multiple of CPU-specific pages; or, for shared page table regions, is not a multiple of CPU-specific page table pages or does not include the last page in a memory-resident global section.

SS$_PAGNOTINREG A page in the specified range is not within the specified region.

SS$_PAGOWNVIO A page in the specified range is owned by an access mode more privileged than the access mode of the caller.

SS$_VA_NOTPAGALGN The start_va_64 argument is not a CPU-specific page table page aligned address; or, for shared page table regions, is not page table page aligned.

SS$_VA_IN_USE The existing underlying page cannot be deleted because it is associated with a buffer object.

$DEQ

Dequeues (unlocks) granted locks; dequeues the sublocks of a lock; or cancels an ungranted lock request. The calling process must have previously acquired the lock or queued the lock request by calling the Enqueue Lock Request ($ENQ) service.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$DEQ [lkid] ,[valblk] ,[acmode] ,[flags]

C Prototype

int sys$deq (unsigned int lkid, void *valblk, unsigned int acmode, unsigned int flags);

Arguments

lkid

OpenVMS usage: lock_id

type: longword (unsigned)

access: read only

mechanism: by value

Lock identification of the lock to be dequeued. The lkid argument specifies this lock identification.
Note that if you do not specify the lkid argument, you must specify the LCK$M_DEQALL flag in the flags argument.
When you specify the LCK$M_DEQALL flag in the flags argument, different values (or no value) for the lkid argument produce varying behavior:

When you do not specify the lkid argument (or specify it as 0) and you do specify the LCK$M_DEQALL flag, $DEQ dequeues all locks held by the process, at access modes equal to or less privileged than the effective access mode, on all resources. The effective access mode is the least privileged of the caller's access mode and the access mode specified in the acmode argument.
When you specify the lkid argument as a nonzero value together with the LCK$M_DEQALL flag, $DEQ dequeues all sublocks of the lock identified by lkid; it does not dequeue the lock identified by lkid. For this operation, $DEQ ignores the LCK$M_CANCEL flag if it is set. A sublock of a lock is a lock that was created when the parid argument in the call to $ENQ was specified, where parid is the lock ID of the parent lock.

If you omit the lkid argument (or specify it as 0) and the LCK$M_DEQALL flag is not set, the $DEQ service returns the invalid lock ID condition value (SS$_IVLOCKID).
valblk

OpenVMS usage: lock_value_block

type: longword (unsigned)

access: modify

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Lock value block for the resource associated with the lock to be dequeued. The valblk argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit (on VAX systems) of the 16-byte lock value block. When you specify the LCK$M_DEQALL flag, you cannot use this argument.
When a protected write (PW) or exclusive (EX) mode lock is being dequeued and you specify a lock value block in the valblk argument, the contents of that lock value block are written to the lock value block in the lock database. Further, if the lock value block in the lock database was marked as invalid, that condition is cleared; the block becomes valid.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode of the lock to be dequeued. The acmode argument is a longword containing the access mode.
The acmode argument is valid only if the LCK$M_DEQALL flag of the flags argument is set. 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

When dequeuing locks, $DEQ maximizes the access mode of the caller and the specified acmode argument. The maximized access mode is the less privileged of the caller's access mode and the acmode argument. If you do not specify the acmode argument, $DEQ uses the caller's access mode. Only those locks with an access mode that is equal to or less than the maximized access mode are dequeued.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Flags specifying options for the $DEQ operation. The flags argument is a longword bit mask that is the logical OR of each bit set, where each bit corresponds to an option.
Note that if you do not specify the lkid argument, you must specify the LCK$M_DEQALL flag in the flags argument.
A symbolic name for each flag bit is defined by the $LCKDEF macro. The following table describes each flag.

Flag Description

LCK$M_DEQALL When you specify this flag, $DEQ dequeues multiple locks, depending on the value of the lkid argument. Refer to the description of the lkid argument for details. The acmode argument is ignored if the LCK$M_DQALL flag is not set. If you specify LCK$M_DEQALL, the LCK$M_CANCEL flag, if set, is ignored.

LCK$M_CANCEL When you specify this flag, $DEQ attempts to cancel a lock request that was queued by $ENQ. You can cancel only a waiting request. When the request is canceled, $DEQ returns the condition value SS$_NORMAL.
If you attempt to cancel a granted lock, the request fails and $DEQ returns the condition value SS$_CANCELGRANT. There are two types of waiting requests that can be canceled:

A request for a new lock
A request to convert an existing lock

When canceling a new lock request, the following action is taken:

If a completion asynchronous system trap (AST) was requested, the AST is queued for delivery and SS$_ABORT is stored in the lock status block.

When canceling a request to convert an existing lock, the conversion request is canceled. The existing granted lock remains unchanged. The following specific actions are taken:

The blocking AST address specified for the existing granted lock is queued for delivery if the granted mode of the existing lock is blocking other waiting requests.
If a completion AST was specified by the conversion request, the completion AST is queued for delivery with SS$_CANCEL status stored in the lock status block that was specified by the conversion request.

If you specify the LCK$M_DEQALL flag, the LCK$M_CANCEL flag is ignored.

LCK$M_INVVALBLK When you specify this flag, $DEQ marks the lock value block, which is maintained for the resource in the lock database, as invalid. The lock value block remains marked as invalid until it is again written to. The Description section of the $ENQ service provides additional information about lock value block invalidation.
This flag is ignored if (1) the lock mode of the lock being dequeued is not protected write or exclusive, or (2) you specify the LCK$M_CANCEL flag.

Symbol	Access Mode
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

Flag	Description
LCK$M_DEQALL	When you specify this flag, $DEQ dequeues multiple locks, depending on the value of the lkid argument. Refer to the description of the lkid argument for details. The acmode argument is ignored if the LCK$M_DQALL flag is not set. If you specify LCK$M_DEQALL, the LCK$M_CANCEL flag, if set, is ignored.
LCK$M_CANCEL	When you specify this flag, $DEQ attempts to cancel a lock request that was queued by $ENQ. You can cancel only a waiting request. When the request is canceled, $DEQ returns the condition value SS$_NORMAL. If you attempt to cancel a granted lock, the request fails and $DEQ returns the condition value SS$_CANCELGRANT. There are two types of waiting requests that can be canceled: A request for a new lock A request to convert an existing lock When canceling a new lock request, the following action is taken: If a completion asynchronous system trap (AST) was requested, the AST is queued for delivery and SS$_ABORT is stored in the lock status block. When canceling a request to convert an existing lock, the conversion request is canceled. The existing granted lock remains unchanged. The following specific actions are taken: The blocking AST address specified for the existing granted lock is queued for delivery if the granted mode of the existing lock is blocking other waiting requests. If a completion AST was specified by the conversion request, the completion AST is queued for delivery with SS$_CANCEL status stored in the lock status block that was specified by the conversion request. If you specify the LCK$M_DEQALL flag, the LCK$M_CANCEL flag is ignored.
LCK$M_INVVALBLK	When you specify this flag, $DEQ marks the lock value block, which is maintained for the resource in the lock database, as invalid. The lock value block remains marked as invalid until it is again written to. The Description section of the $ENQ service provides additional information about lock value block invalidation. This flag is ignored if (1) the lock mode of the lock being dequeued is not protected write or exclusive, or (2) you specify the LCK$M_CANCEL flag.

Description

The Dequeue Lock Request service dequeues (unlocks) granted locks and waiting lock requests. The calling process must have previously acquired the lock or queued the lock request by calling the Enqueue Lock Request ($ENQ) service.
Action taken by the $DEQ service depends on the current state (granted or waiting) and the type of lock request (new lock or conversion request) to be dequeued.
When dequeuing a granted lock, the $DEQ service returns the condition value SS$_NORMAL and the following specific action is taken:

Any queued blocking ASTs that have not been delivered are removed from the process's AST queues.

There are two types of waiting requests that can be dequeued:

A request for a new lock
A request to convert an existing lock

When dequeuing a new lock request, the $DEQ service returns the condition value SS$_NORMAL and the following specific action is taken:

If a completion AST was requested, the completion AST is queued for delivery with SS$_ABORT stored in the lock status block.

When dequeuing a lock for which there is a conversion request waiting, the existing lock and its conversion request are dequeued. The $DEQ service returns the condition value SS$_NORMAL and the following specific actions are taken:

If a blocking AST was queued to the process, it is removed from the process's AST queue.
If a completion AST was specified by the conversion request, the completion AST is queued for delivery with SS$_ABORT status stored in the lock status block that was specified by the conversion request.

When a protected write (PW) or exclusive (EX) mode lock is being dequeued and you specify a lock value block in the valblk argument, the contents of that lock value block are written to the lock value block in the lock database.
If you specify the LCK$M_INVVALBLK flag in the flags argument and the lock mode of the lock being dequeued is PW or EX, the lock value block in the lock database is marked as invalid whether or not a lock value block was specified in the valblk argument.
The $DEQ, $ENQ, $ENQW, and $GETLKI services together provide the user interface to the lock management facility. For additional information about lock management, refer to the descriptions of these other services and to the OpenVMS Programming Concepts Manual.
Required Access or Privileges

None
Required Quota

None
Related Services

$ENQ, $ENQW, $GETLKI, $GETLKIW

Condition Values Returned

SS$_NORMAL The lock was dequeued successfully.

SS$_ACCVIO The value block specified by the valblk argument cannot be accessed by the caller.

SS$_CANCELGRANT The LCK$M_CANCEL flag in the flags argument was specified, but the lock request that $DEQ was to cancel had already been granted.

SS$_ILLRSDM An illegal attempt to modify a value block was made.

SS$_IVLOCKID An invalid or nonexistent lock identification was specified or the process does not have the privilege to dequeue a lock at the specified access mode.

SS$_SUBLOCKS The lock has sublocks and cannot be dequeued.

Contents

Index

privacy and legal statement

4527PRO_028.HTML

OpenVMS System Services Reference Manual

$DELTVA

Format

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

C Prototype

int sys$deltva (struct _va_range inadr, struct _va_range retadr, unsigned int acmode);

Arguments

inadr

retadr

acmode

Description

Condition Values Returned

$DELTVA_64 (Alpha Only)

Format

SYS$DELTVA_64 region_id_64 ,start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64

C Prototype

int sys$deltva_64 (struct _generic_64 region_id_64, void start_va_64, unsigned __int64 length_64, unsigned int acmode, void ((return_va_64)), unsigned __int64 *return_length_64);

Arguments

region_id_64

start_va_64

length_64

acmode

return_va_64

return_length_64

Description

Condition Values Returned

$DEQ

Format

SYS$DEQ [lkid] ,[valblk] ,[acmode] ,[flags]

C Prototype

int sys$deq (unsigned int lkid, void *valblk, unsigned int acmode, unsigned int flags);

Arguments

lkid

valblk

acmode

flags

Description

Condition Values Returned

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	read only
mechanism:	by reference

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

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The input address array cannot be read by the caller, or the return address array cannot be written by the caller.
SS$_NOPRIV	A page in the specified range is in the system address space.
SS$_PAGOWNVIO	A page in the specified range is owned by an access mode more privileged than the access mode of the caller.
SS$_NOSHPTS	The region ID of a shared page table region was specified.
SS$_VA_IN_USE	The existing underlying page cannot be deleted because it is associated with a buffer object.

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

OpenVMS usage:	address
type:	quadword address
access:	read only
mechanism:	by value

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by value

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

OpenVMS usage:	lock_value_block
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

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

SS$_NORMAL	The lock was dequeued successfully.
SS$_ACCVIO	The value block specified by the valblk argument cannot be accessed by the caller.
SS$_CANCELGRANT	The LCK$M_CANCEL flag in the flags argument was specified, but the lock request that $DEQ was to cancel had already been granted.
SS$_ILLRSDM	An illegal attempt to modify a value block was made.
SS$_IVLOCKID	An invalid or nonexistent lock identification was specified or the process does not have the privilege to dequeue a lock at the specified access mode.
SS$_SUBLOCKS	The lock has sublocks and cannot be dequeued.