 |
HP OpenVMS System Services Reference Manual
$SETDTI
The Set Distributed Transaction Information service removes resource
managers from transactions. It can also be used to modify transaction
states.
Format
SYS$SETDTI [efn], [flags], iosb, [astadr], [astprm], [contxt], func,
itmlst
C Prototype
int sys$setdti (unsigned int efn, unsigned int flags, struct _iosb
*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int
*contxt, unsigned short int *func, void *itmlst);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag that is set when the service completes. If
this argument is omitted, event flag 0 is used.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flags specifying options for the service. The flags
argument is a longword bit mask in which each bit corresponds to an
option flag. The $DDTMDEF macro defines symbolic names for the option
flag described in Table SYS-51. All undefined bits must be 0. If this
argument is omitted, no flags are used.
Table SYS-51 $SETDTI Operation Flag
| Flag Name |
Description |
|
DDTM$M_SYNC
|
Specifies successful synchronous completion by returning SS$_SYNCH.
When SS$_SYNCH is returned, the AST routine is not called, the event
flag is not set, and the I/O status block is not filled in.
|
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The I/O status block in which the completion status of the service is
returned as a condition value. See the Condition Values Returned
section.
The following diagram shows the structure of the I/O status block:
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure entry mask |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
The AST routine executed when the service completes, if SS$_NORMAL is
returned in R0. The astadr argument is the address of
the entry mask of this routine. The routine is executed in the same
access mode as that of the caller of the $SETDTI service.
astprm
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The AST parameter passed to the AST routine specified by the
astadr argument.
contxt
| OpenVMS usage: |
contxt |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Context value obtained from a call to $GETDTI. It implicitly specifies
a node and transaction manager log identifier.
func
| OpenVMS usage: |
function_code |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Function modifier that specifies the set operation to be performed. The
func argument is a longword value containing the
function code.
Table SYS-52 lists the available function codes:
Table SYS-52 $SETDTI Function Codes
| Function |
Description |
|
DTI$K_DELETE_RM_NAME
|
Deletes the resource manager specified in
itmlst item DTI$_TRANSACTION_INFORMATION,
DTI$T_PART_NAME from the transaction specified by
DTI$_TRANSACTION_INFORMATION, DTI$T_TID.
|
|
DTI$K_DELETE_TRANSACTION
|
Deletes the transaction specified by
itmlst item DTI$_TRANSACTION_INFORMATION, DTI$T_TID.
|
|
DTI$K_MODIFY STATE
|
Modifies the transaction specified by
itmlst item DTI$_TRANSACTION_INFORMATION, DTI$T_TID,
using the transaction state specified in DTI$_B_STATE.
|
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying the transaction information that $SETDTI is to
use. The itmlst argument is the address of a list of
item descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0. Each item
descriptor in the item list acts as an input argument to $SETDTI and as
such is only required to be read only.
The following diagram depicts the format of a single item descriptor:
The following table describes the itmlst item
descriptor fields:
| Field |
Description |
|
Buffer length
|
A word containing a user-supplied integer specifying the length (in
bytes) of a buffer from which $SETDTI is to read the information. The
length of the buffer needed depends on the item code specified in the
item code field of the item descriptor. If the value of buffer length
is too small, $SETDTI will return an error status.
|
|
Item code
|
A word containing a user-supplied symbolic code specifying the search
item that $SETDTI is to use. The $DTIDEF macro defines these codes.
Each item code is described in the Item Codes section.
|
|
Buffer address
|
A longword containing the user-supplied address of the buffer from
which $SETDTI reads the item information.
|
|
Return length address
|
This longword that is not used in the item list as all items are
read-only.
|
Item Codes
DTI$_TRANSACTION_INFORMATION
When you specify DTI$_TRANSACTION_INFORMATION, $SETDTI uses the fields
in the following table to perform the $SETDTI call. Each function
requires a specific set of fields from the transaction record to
perform its operation. If one or more of these fields is not present or
valid, then the $SETDTI call will fail. The fields required by each
function are listed in the func argument description.
| Item |
Description |
|
DTI$B_PART_NAME_LEN
|
A byte containing the length of the participant name field
DTI$T_PART_NAME.
|
|
DTI$B_STATE
|
A byte containing the state of the transaction. Two states are valid:
DTI$K_COMMITTED and DTI$K_ABORTED.
|
|
DTI$T_PART_NAME
|
A character field containing DTI$B_PART_NAME_LEN characters that
specifies a resource manager name.
To ensure smooth operation in a mixed-network environment, refer to
the chapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, for
information on defining node names.
|
|
DTI$T_PART_LOG_ID
|
Reserved by HP.
|
|
DTI$T_TID
|
A 16-byte field containing the transaction identifier.
|
Description
The $SETDTI service can be used either to remove resource managers from
transactions, or to modify transaction states.
The $SETDTI service removes resource managers from a single transaction
or from all transactions when they no longer have any further interest
in a transaction. A call to $SETDTI typically follows a call to $GETDTI
that established a search context and returned the state of an
unresolved transaction.
When a resource manager is recovering from a system failure it will use
$GETDTI to return the state of all unresolved transactions. If the
resource manager can recover the transaction, then it needs to be
removed from the transaction in the same way it would have been removed
had it been able to call $ACK_EVENT with the forget status before the
system failure.
To remove a resource manager, $SETDTI uses the following fields from
the DTI$_TRANSACTION_INFORMATION item descriptor in the
itmlst argument:
- Transaction Identifier (TID)
- Resource Manager name
- Resource Manager log identifier
This information, along with the search context, is used to remove the
resource manager from the transaction. If the TID field is zero in the
DTI$_TRANSACTION_INFORMATION item descriptor, then the resource manager
will be removed from all committed transactions in which it was
involved.
When searching for a resource manager, a comparison is made of the
leftmost bytes in the transaction manager's log records. This feature
enables multiple instances of resource manager classes to be removed
from the transaction manager's log after performing a recovery.
The $SETDTI service can also be used to modify transaction states. It
can perform two state transitions: from prepared to committed, or from
prepared to aborted. To modify transaction states, $SETDTI uses the
following fields from the DTI$_TRANSACTION_INFORMATION item descriptor
in the itmlst argument:
- Transaction Identifier (TID)
- Transaction state
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.
- 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.
|
|
