 |
HP OpenVMS System Services Reference Manual
$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 (or with some languages
you specify an address of 0), $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
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.
|
|
SS$_EXPGFLQUOTA or other condition values that can be returned by
SS$EXPREG_64 (Integrity servers only)
|
The process exceeded its paging file quota while allocating memory to
perform the unwind operation. As a result, no unwind is performed. The
condition handler return proceeds as though $UNWIND was not called.
|
$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, HP 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.
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$_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
$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 additional
information about the $UPDSECW service, see the description of $UPDSEC.
For additional information about system service completion, see 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 and Integrity servers)
On Alpha and Integrity server 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 HP. The value in this field is unpredictable.
- iosa$q_count_q (offset 8)
This field is reserved for future
use by HP. 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 HP. 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.
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.
Proper use of this service requires the caller to synchronize
completion of the update request. To do this, first check the condition
value returned. 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 I/O status for final completion status.
If any error is returned by this service, a value cannot be
returned in the memory locations pointed to by the
iosb_64, return_va_64, and
return_length_64 arguments.
Required Privileges
|
