OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

$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 value indicating that the request was not performed.
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$_SHMNOTCNCT The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.

SS$_UNASCEFC The process is not associated with the cluster containing the specified event flag.

+VAX specific

$UPDSECW

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.
The $UPDSECW service completes synchronously; that is, it returns to the caller after writing all updated pages.
For asynchronous completion, use the Update Section File on Disk ($UPDSEC) service; $UPDSEC returns to the caller after queuing the update request, without waiting for the pages to be updated.
In all other respects, $UPDSECW is identical to $UPDSEC. For all other information about the $UPDSECW service, refer to the description of $UPDSEC.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.

Format

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

C Prototype

int sys$updsecw (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);

$UPDSEC_64 (Alpha Only)

On Alpha systems, writes all pages (or only those pages modified by the current process) in an active private or global disk file section back into the section file on disk. One or more I/O requests are queued to perform the write operation.
The $UPDSEC_64 service completes asynchronously. For synchronous completion, use the Update Global Section File on Disk and Wait ($UPDSEC_64W) service.
This service accepts 64-bit addresses.

Format

SYS$UPDSEC_64 start_va_64 ,length_64 ,acmode ,updflg ,efn ,iosa_64 ,return_va_64 ,return_length_64 [,astadr_64 [,astprm_64]]

C Prototype

int sys$updsec_64 (void *start_va_64, unsigned __int64 length_64, unsigned int acmode, unsigned int updflg, unsigned int efn, struct _iosa *iosa_64, 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 written to the section file. The specified virtual address is 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 range to be written to the section file. The length specified is 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 service is performed. 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. A page cannot be written to disk unless the access mode used by $UPDSEC_64 is equal to or more privileged than the access mode of the owner of the page to be written.
updflg

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

The 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 UPDFLG$M_WRT_MODIFIED specifies that the caller is the only process actually writing the global section and that only those pages that were actually modified by the caller are to be written to the section file on disk.
Definitions for this flag can be found in the file SECDEF.H in SYS$STARLET_C.TLB for C and in $SECDEF in STARLET.MLB for macro.
efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read_only

mechanism: by value

The 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, this service only uses the low-order byte. If you do not specify the efn, event flag 0 is used.
When you invoke $UPDSEC_64, the specified event flag or event flag 0 is cleared. When the update operation is complete, the event flag is set.
iosa_64

OpenVMS usage: io_status_area

type: IOSA structure

access: write only

mechanism: by 32- or 64-bit reference

The I/O status area to receive the final completion status of the updating operation. The iosa_64 argument is the 32- or 64-bit virtual address of the I/O status area. The I/O status area structure is 32 bytes in length.
The I/O status area structure definition can be found in $IOSADEF in STARLET.MLB for macro and in the file IOSADEF.H in SYS$STARLET_C.TLB for C.
When you call SYS$UPDSEC_64, the I/O status area 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:

isoa$l_status (offset 0)
The first word contains the condition value return by SYS$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.
iosa$l_resd (offset 4)
This field is reserved for future use by Compaq. The value in this field is unpredictable.
iosa$q_count_q (offset 8)
This field is reserved for future use by Compaq. The value in this field is unpredictable.
iosa$ph_upsec_nowrt_va (offset 16)
This field contains the virtual address of the first byte in the first disk block that was not written. In the case of an I/O error, this virtual address indicates the disk block for which the error occurred.
iosa$q_resq (offset 24)
This field is reserved for future use by Compaq. The value in this field is unpredictable.

return_va_64

OpenVMS usage: address

type: quadword address

access: write only

mechanism: by 32- or 64-bit reference

The process virtual address of the first page that was actually queued for writing (in the first I/O request) back to the section file on the disk. 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 first I/O request to write modified pages back to the section file on disk. 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, written by the first I/O request.
astadr_64

OpenVMS usage: ast_procedure

type: procedure value

access: call without stack unwinding

mechanism: by 32- or 64-bit reference

The asynchronous system trap (AST) routine to be executed when the section file has been updated. The astadr_64 argument is the 32- or 64-bit address of this routine. If you specify the astadr_64 argument, the AST routine executes at the access mode from which the section file update was requested.
astprm_64

OpenVMS usage: user_arg

type: quadword

access: read only

mechanism: by value

The AST parameter to be passed to the AST routine. The astprm_64 argument is a quadword argument that is passed to the AST routine.

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 Update Global Section File on Disk service writes all pages in an active private or global section back into the section file on disk. If the updflg argument indicates that only modified pages are to be written back to the disk file, only those global pages modified by the current process are queued to be written back into the section file on disk.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

4527PRO_096.HTML

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

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

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.

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

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

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

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

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

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

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$_SHMNOTCNCT	The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.
SS$_UNASCEFC	The process is not associated with the cluster containing the specified event flag.

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

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

OpenVMS usage:	io_status_area
type:	IOSA structure
access:	write only
mechanism:	by 32- or 64-bit reference