| Previous | Contents | Index |
The Set Distributed Transaction Information service removes resource managers from transactions. It can also be used to modify transaction states.
SYS$SETDTI [efn], [flags], iosb, [astadr], [astprm], [contxt], func, itmlst
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);
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:
| OpenVMS usage: | ast_procedure |
| type: | procedure entry mask |
| access: | call without stack unwinding |
| mechanism: | by reference |
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
| OpenVMS usage: | contxt |
| type: | longword (unsigned) |
| access: | modify |
| mechanism: | by reference |
| OpenVMS usage: | function_code |
| type: | word (unsigned) |
| access: | read only |
| mechanism: | by value |
Table SYS-52 lists the available 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. |
| OpenVMS usage: | item_list_3 |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by reference |
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. |
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.
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.
SYSPRV is required to modify transactions with which the process is not currently associated.
BYTLM, ASTLM
$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
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.
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.
SYS$SETDTIW [efn], [flags], iosb, [astadr], [astprm], [contxt], func, itmlst
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);
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.
SYS$SETEF efn
int sys$setef (unsigned int efn);
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.
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.
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.
SYS$SETEXV [vector] ,[addres] ,[acmode] ,[prvhnd]
int sys$setexv (unsigned int vector, int (*addres)(__unknown_params), unsigned int acmode, void *(*(prvhnd)));
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.
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.
None
None
$DCLCMH, $UNWIND
SS$_NORMAL The service completed successfully. SS$_ACCVIO The longword to receive the previous contents of the vector cannot be written by the caller.
| Previous | Next | Contents | Index |