Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $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.

## $UNWIND

> Unwinds the procedure call stack.

### Format

> SYS$UNWIND [depadr] ,[newpc]

### C Prototype

> int sys$unwind (unsigned int *depadr, void *newpc);

### Arguments

> #### depadr

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Depth to which the procedure call stack is to be unwound. The depadr argument is the address of a longword value. The value 0 specifies the call frame of the procedure that was executing when the condition occurred (that is, no call frames are unwound); the value 1 specifies the caller of that frame; the value 2 specifies the caller of the caller of that frame, and so on.

> If depadr specifies the value 0, no unwind occurs and $UNWIND returns a successful condition value in R0.

> If you do not specify depadr, $UNWIND unwinds the stack to the call frame of the procedure that called the procedure that established the condition handler that is calling the $UNWIND service. This is the default and the normal method of unwinding the procedure call stack.

> #### newpc

> OpenVMS usage: | address
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> New value for the program counter (PC); this value replaces the current value of the PC in the call frame of the procedure that receives control when the unwinding operation is complete. The newpc argument is a longword value containing the address at which execution is to resume.

> Execution resumes at this address when the unwinding operation is complete.

> If you do not specify newpc, execution resumes at the location specified by the PC in the call frame of the procedure that receives control when the unwinding operation is complete.

### Description

> The Unwind Call Stack service unwinds the procedure call stack; that is, it removes a specified number of call frames from the stack. Optionally, it can return control to a new program counter (PC) unwinding the stack. The $UNWIND service is intended to be called from within a condition-handling routine.

> The actual unwind is not performed immediately. Rather, the return addresses in the call stack are modified so that, when the condition handler returns, the unwind procedure is called from each frame being unwound.

> During the actual unwinding of the call stack, $UNWIND examines each frame in the call stack to see if a condition handler has been declared. If a handler has been declared, $UNWIND calls the handler with the condition value SS$_UNWIND (indicating that the call stack is being unwound) in the condition name argument of the signal array. When you call a condition handler with this condition value, that handler can perform any procedure-specific cleanup operations that might be required. After the condition handler returns, the call frame is removed from the stack.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

> $DCLCMH, $SETEXV, $SETSFM

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The call stack is not accessible to the caller. This condition is detected when the call stack is scanned to modify the return address.
> SS$_INSFRAME | There are insufficient call frames to unwind to the specified depth.
> SS$_NOSIGNAL | No signal is currently active for an exception condition.
> SS$_UNWINDING | An unwind operation is already in progress.

## $UPDSEC

> Writes all modified pages in an active private or global section back into the section file on disk. One or more I/O requests are queued, based on the number of pages that have been modified.

### Format

> SYS$UPDSEC inadr ,[retadr] ,[acmode] ,[updflg] ,[efn] ,[iosb] ,[astadr] ,[astprm]

### C Prototype

> int sys$updsec (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode, char updflg, unsigned int efn, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);

### 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 that are to be written to the section file if they have been modified. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. Addresses are adjusted up or down to CPU-specific pages.

> Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.

> $UPDSEC scans pages starting at the address contained in the first longword specified by inadr and ending at the address contained in the second longword. Within this range, $UPDSEC locates read/write pages that have been modified and writes them (contiguously, if possible) to the section file on disk. Unmodified pages are also written to disk if they share the same cluster with modified pages.

> If the starting and ending virtual addresses are the same, a single page is written to the section file if the page has been modified.

> The address specified by the second longword might be smaller than the address specified by the first longword.

> #### retadr

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

> Addresses of the first and last pages that were actually queued for writing, in the first $QIO request, back to the section file on disk. The retadr argument is the address of a 2-longword array containing, in order, the addresses of the first and last pages. Addresses always are adjusted up or down to fall on CPU-specific boundaries.

> If $UPDSEC returns an error condition value in R0, each longword specified by retadr contains the value --1. In this case, an event flag is not set, no asynchonous system trap (AST) is delivered, and the I/O status block is not written to.

> #### acmode

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

> Access mode on behalf of which the service is performed. 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. A page cannot be written to disk unless the access mode used by $UPDSEC is equal to or more privileged than the access mode of the owner of the page to be written.

> #### updflg

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Update specifier for read/write global sections. The updflg argument is a longword value. The value 0 (the default) specifies that all read/write pages in the global section are to be written to the section file on disk, whether or not they have been modified. The value 1 specifies that the caller is the only or the last process having the global section mapped for write access and that only modified pages should be written to the section file on disk.

> #### efn

> OpenVMS usage: | ef_number
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Event flag to be set when the section file on disk is actually updated. The efn argument is a longword specifying the number of the event flag; however, $UPDSEC uses only the low-order byte.

> If you do not specify efn, event flag 0 is used.

> When you invoke $UPDSEC, the specified event flag or event flag 0 is cleared; when the update operation is complete, the event flag is set.

> #### iosb

> OpenVMS usage: | io_status_block
> type: | quadword (unsigned)
> access: | write only
> mechanism: | by reference

> I/O status block to receive the final completion status of the updating operation. The iosb argument is the address of the quadword I/O status block.

> When you invoke $UPDSEC, the I/O status block is cleared. After the update operation is complete, that is, when all I/O to the disk is complete, the I/O status block is written as follows:

> - The first word contains the condition value returned by $QIO, indicating the final completion status.
> - The first bit in the second word is set only if an error occurred during the I/O operation and the error was a hardware write error. The remaining bits of the second word are zeros.
> - The second longword contains the virtual address of the first page that was not written.

> Though this argument is optional, Compaq strongly recommends that you specify it for the following reasons:

> - If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
> - If you are using $SYNCH to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
> - The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to $UPDSEC. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $UPDSEC, you must check the condition values returned in both R0 and the I/O status block.

> #### astadr

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference---procedure reference or descriptor

> AST routine to be executed when the section file has been updated. The astadr argument is the address of this routine.

> If you specify astadr, the AST routine executes at the access mode from which the section file update was requested.

> #### astprm

> OpenVMS usage: | user_arg
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> AST parameter to be passed to the AST routine. The astprm argument is this longword parameter.

### Description

> The Update Section File on Disk service writes all modified pages in an active private or global section back into the section file on disk. One or more I/O requests are queued, based on the number of pages that have been modified.

> Proper use of this service requires the caller to synchronize completion of the update request. You do this by first checking the condition value returned in R0 by $UPDSEC. If SS$_NOTMODIFIED is returned, the caller can continue. If SS$_NORMAL is returned, the caller should wait for the I/O to complete and then check the first word of the I/O status block for the final completion status. You can use the Synchronize ($SYNCH) service to determine whether the I/O operation has actually completed.

> On VAX systems, for a global section located in memory shared by multiple processors, only processes running on the processor that created the section can specify that global section in a call to $UPDSEC. Processes on another processor that attempt to update the section file receive an error condition.

> Required Access or Privileges

> None

> Required Quota

> $UPDSEC uses the calling process's direct I/O limit (DIRIO) quota in queuing the I/O request and uses the calling process's AST limit (ASTLM) quota if the astadr argument is specified.

> Related Services

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

### Condition Values Returned

> SS$_NORMAL | The service completed successfully. One or more I/O requests were queued.
> SS$_NOTMODIFIED | The service completed successfully. No pages in the input address range were section pages that had been modified. No I/O requests were queued.
> SS$_ACCVIO | The input address array cannot be read by the caller, or the output address array cannot be written by the caller.
> SS$_EXQUOTA | The process has exceeded its AST limit quota.
> SS$_ILLEFC | You specified an illegal event flag number.
> SS$_IVSECFLG | You specified an invalid flag.
> +SS$_NOTCREATOR | The section is in memory shared by multiple processors and was created by a process on another processor.
> 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$_UNASCEFC | The process is not associated with the cluster containing the specified event flag.

+VAX specific

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_102.HTML