![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 19 July 1999 | |
|
|
|
|
|
|
| Previous | Contents | Index |
Unwinds the procedure call stack.
SYS$UNWIND [depadr] ,[newpc]
int sys$unwind (unsigned int *depadr, void *newpc);
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.
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.
None
None
$DCLCMH, $SETEXV, $SETSFM
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.
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.
SYS$UPDSEC inadr ,[retadr] ,[acmode] ,[updflg] ,[efn] ,[iosb] ,[astadr] ,[astprm]
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);
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.
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.
None
$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.
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSECW
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.
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.
SYS$UPDSECW inadr [,retadr] [,acmode] [,updflg] [,efn] [,iosb] [,astadr] [,astprm]
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);
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.
SYS$UPDSEC_64 start_va_64 ,length_64 ,acmode ,updflg ,efn ,iosa_64 ,return_va_64 ,return_length_64 [,astadr_64 [,astprm_64]]
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,...);
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.
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
privacy and legal statement 4527PRO_096.HTML