 |
HP OpenVMS System Services Reference Manual
To modify a transaction state, first modify the DTI$B_STATE field in
the DTI$_TRANSACTION_INFORMATION item descriptor to either
DTI$K_COMMITTED and DTI$K_ABORTED. Then specify the function code
DTI$K_MODIFY_TRANSACTION to instruct $SETDTI to perform the state
transition.
Note that because DECdtm uses a presumed abort protocol, changing the
transaction state to aborted is the same as deleting the transaction.
SYSPRV privilege is required to retrieve or modify information about
transactions with which the process is not currently associated.
In most cases, the search context remains valid across multiple calls
to $SETDTI. That is, a call to $GETDTI may be followed by one or more
calls to $SETDTI without the context becoming invalid. However, the
search context is invalidated when a resource manager is deleted from
all transactions by specifying a zero TID.
Required Privileges
SYSPRV is required to modify transactions with which the process is not
currently associated.
Required Quotas
BYTLM, ASTLM
Related Services
$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,
$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW,
$END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW,
$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTIW, $SET_DEFAULT_TRANS,
$SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS,
$START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW
Condition Values Returned
|
SS$_NORMAL
|
If returned in R0, the request was successfully queued. If returned in
the I/O status block, the service completed successfully.
|
|
SS$_SYNCH
|
The service completed successfully and synchronously (returned only if
the DDTM$M_SYNC flag is set).
|
|
SS$_ACCVIO
|
An argument was not accessible to the caller.
|
|
SS$_BADLOGVER
|
There was an invalid or unsupported log version.
|
|
SS$_BADPARAM
|
Either the options flags were invalid or the
tid argument was omitted but the
bid argument was not zero.
|
|
SS$_BADSTATE
|
There was an invalid transaction state in the ITMLST. Valid states are
DTI$K_COMMITTED and DTI$K_ABORTED.
|
|
SS$_BUGCHECK
|
A failure has occurred during the processing of the request.
|
|
SS$_EXASTLM
|
The process AST limit (ASTLM) was exceeded.
|
|
SS$_ILLEFC
|
The event flag number was invalid.
|
|
SS$_INSFARGS
|
A required argument was missing.
|
|
SS$_INSFMEM
|
There was insufficient system dynamic memory for the operation.
|
|
SS$_INVLOG
|
The log format is invalid.
|
|
SS$_NOSUCHFILE
|
The transaction manager log cannot be found.
|
|
SS$_NOSUCHNODE
|
The subordinate DECnet node is unknown.
|
|
SS$_NOSUCHPART
|
The participant is not part of the transaction.
|
|
SS$_NOSUCHTID
|
The designated TID is unknown.
|
|
SS$_NOSYSPRV
|
The caller does not have the SYSPRV privilege.
|
|
SS$_PROTOCOL
|
There is a message protocol error.
|
|
SS$_REMRSRC
|
There are insufficient resources at the remote node.
|
|
SS$_UNREACHABLE
|
A superior node is unreachable.
|
$SETDTIW
Sets the process current transaction and removes resource managers from
transactions.
$SETDTIW$ always waits for the request to complete before returning to
the caller. Other than this, it is identical to $SETDTI.
Format
SYS$SETDTIW [efn], [flags], iosb, [astadr], [astprm], [contxt], func,
itmlst
C Prototype
int sys$setdtiw (unsigned int efn, unsigned int flags, struct _iosb
*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int
*contxt, unsigned short int *func, void *itmlst);
$SETEF
Sets an event flag in a local or common event flag cluster. The
condition value returned by $SETEF indicates whether the specified flag
was previously set or clear. After the event flag is set, processes
waiting for the event flag to be set resume execution.
Format
SYS$SETEF efn
C Prototype
int sys$setef (unsigned int efn);
Argument
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag to be set. The efn argument
is a longword containing this number; however, $SETEF uses only the
low-order byte.
Two local event flag clusters are local to the process: cluster 0 and
cluster 1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1
contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster 3.
Cluster 2 contains event flag numbers 64 to 95, and cluster 3 contains
event flag numbers 96 to 127.
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. The specified event flag was
previously 0.
|
|
SS$_WASSET
|
The service completed successfully. The specified event flag was
previously 1.
|
|
SS$_ILLEFC
|
You specified an illegal event flag number.
|
|
SS$_UNASEFC
|
The process is not associated with the cluster containing the specified
event flag.
|
$SETEXV
Assigns a condition handler address to the primary, secondary, or last
chance exception vectors, or removes a previously assigned handler
address from any of these three vectors.
Format
SYS$SETEXV [vector] ,[addres] ,[acmode] ,[prvhnd]
C Prototype
int sys$setexv (unsigned int vector, int (*addres)(__unknown_params),
unsigned int acmode, void *(*(prvhnd)));
Arguments
vector
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Vector for which a condition handler is to be established or removed.
The vector argument is a longword value. The value 0
(the default) specifies the primary exception vector; the value 1, the
secondary vector; and the value 2, the last chance exception vector.
addres
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
Condition handler address to be established for the exception vector
specified by the vector argument. The
addres argument is a longword value containing the
address of the condition handler routine.
If you do not specify addres or specify it as the
value 0, the condition handler address already established for the
specified vector is removed; that is, the contents of the longword
vector is set to 0.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode for which the exception vector is to be modified. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines symbols for the four access modes.
The most privileged access mode used is the access mode of the caller.
Exception vectors for access modes more privileged than the caller's
access mode cannot be modified.
prvhnd
| OpenVMS usage: |
procedure value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Previous condition handler address contained by the specified exception
vector. The prvhnd argument is the address of a
longword into which $SETEXV writes the handler's procedure value.
Description
The Set Exception Vector service (1) assigns a condition handler
address to the primary, secondary, or last chance exception vectors or
(2) removes a previously assigned handler address from any of these
three vectors. A process cannot modify a vector associated with a more
privileged access mode.
The operating system provides two different methods for establishing
condition handlers:
- Using the call stack associated with each access mode. Each call
frame includes a longword to contain the address of a condition handler
associated with that frame.
- On VAX systems, the RTL routine LIB$ESTABLISH establishes a
condition handler; the RTL routine LIB$REVERT removes a handler.
- Using the software exception vectors (by using $SETEXV) associated
with each access mode. These vectors are set aside in the control
region (P1 space) of the process.
The modular properties associated with the first method do not apply to
the second. The software exception vectors are intended primarily for
performance monitors and debuggers. For example, the primary exception
vector and the last chance exception vector are used by the OpenVMS
Debugger for user mode access, and DCL uses the last chance exception
vector for supervisor mode access.
User mode exception vectors are canceled at image exit.
Required Access or Privileges
None
Required Quota
None
Related Services
$DCLCMH, $UNWIND
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The longword to receive the previous contents of the vector cannot be
written by the caller.
|
$SETFLT
On Alpha and I64 systems, allows a process to change the fault
characteristic on a page or range of pages.
Format
SYS$SETFLT inadr ,[retadr] ,[acmode] ,fault_flag
C Prototype
int sys$setflt (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode, unsigned int fault_flag);
Arguments
inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Starting and ending virtual addresses of the range of pages whose fault
characteristic is to be changed. 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 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.
If the starting and ending virtual addresses are the same, the fault
characteristic is changed for a single page.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference---array reference or descriptor |
Starting and ending virtual addresses of the range of pages whose fault
characteristic was actually changed by $SETFLT. 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 the fault characteristic is being changed,
$SETFLT writes into retadr the range of pages that
were successfully changed before the error occurred. If no pages were
affected before the error occurred, $SETFLT writes the value --1 into
each longword of the 2-longword array.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the call to $SETFLT. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines symbols for the access modes.
The $SETFLT service uses whichever of the following two access modes is
less privileged: (1) the access mode specified by
acmode or (2) the access mode of the caller. To change
the fault characteristic of any page in the specified range, the
resultant access mode must be equal to or more privileged than the
access mode of the owner of that page.
fault_flag
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying the request options. The
fault_flag argument is a longword bit vector in which
each bit corresponds to a flag. The $FLTDEF macro and the FLTDEF.H file
define a symbolic name for each flag.
The $FLTDEF macro defines the following symbolic names for the fault
characteristic codes:
| Symbol |
Description |
|
FLT$M_NO_EXECUTE
|
Fault on execute access attempt
|
|
FLT$M_EXECUTABLE
|
Allow execute access
|
If you specify the fault characteristic as the value 0, the
characteristic defaults to no execute access.
Description
The Set Fault Characteristic on Pages service allows a process to
change the fault characteristic on a page or range of pages.
Required Access or Privileges
None
Required Quota
None
Related Services
$CRETVA, $EXPREG, $SETPRT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The input address array cannot be read by the caller; the output
address array or the byte to receive the previous protection cannot be
written by the caller; or an attempt was made to change the fault
characteristic of a nonexistent page.
|
|
SS$_BADPARAM
|
A bad fault_flag argument was specified.
|
|
SS$_LENVIO
|
A page in the specified range is beyond the end of the program or
control region.
|
|
SS$_NOPRIV
|
A page in the specified range is in the system address space.
|
|
SS$_PAGOWNVIO
|
The process attempted to change the fault characteristic on a page
owned by a more privileged access mode.
|
$SETFLT_64
On Alpha and I64 systems, allows a process to change the fault
characteristic (for example, no execute) on a page or range of
pages.
Format
$SETFLT_64 start_va_64 ,length_64 ,acmode ,fault_flag ,return_va_64
,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 range of pages whose fault
characteristic is to be changed. The specified virtual address will be
rounded down to a CPU-specifie page boundary.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space whose fault characteristic is to be
changed. 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 associated with the call to $SETFLT_64. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines symbols for the four access modes.
The most privileged access mode used is the access mode of the caller.
The calling process can modify pages only if those pages are owned by
an access mode equal to or less privileged than the access mode of the
calling process.
fault_flag
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying the request options. The
fault_flag argument is a longword bit vector in which
each bit corresponds to a flag. The $FLTDEF macro and the FLTDEF.H file
define a symbolic name for each flag.
The $FLTDEF macro defines the following symbolic names for the fault
characteristic codes:
| Symbol |
Description |
|
FLT$M_NO_EXECUTE
|
Fault on execute access attempt
|
|
FLT$M_EXECUTABLE
|
Allow execute access
|
If you specify the fault characteristic as the value 0, the
characteristic defaults to no execute access.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference |
The lowest process virtual address of the range of pages whose fault
characteristics were actually changed.
return_length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference |
The length of the virtual address range whose fault characteristics
were actually changed. The return_length_64 argument
is the 32-bit 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 Set Fault Characteristic service sets the fault characteristics
(for example, no execute) for the specified range of pages,
checking that the specified mode is at least as privileged as the owner
of the page.
If the condition value SS$_ACCVIO is returned by this service, a value
might not 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
changed before the error occurred. If no pages were changed, the
return_va_64 argument will contain the value -1, and a
value might not be returned in the memory location
pointed to by the return_length_64 argument.
Required Privileges
None
Required Quota
None
Related Services
$CRETVA_64, $EXPREG_64, $SETPRT_64
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
return_va_64 or
return_length_64 argument cannot be written by the
caller.
|
|
SS$_BADPARAM
|
A bad fault_flag argument was specified.
|
|
SS$_LENVIO
|
A page in the specified range is beyond the length of virtual addresses
within that region.
|
|
SS$_NOSUCHPAG
|
An attempt was made to change the fault characteristic on a nonexistent
page.
|
|
SS$_PAGNOTINREG
|
A page in the specified range is not in process private adress space.
|
|
SS$_PAGOWNVIO
|
The process attempted to change the protection on a page owned by a
more privileged access mode.
|
|
