HP OpenVMS System Services Reference Manual


Previous Contents Index


$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:

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:

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:

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.


Previous Next Contents Index