HP OpenVMS Systems Documentation

HP OpenVMS System Services Reference Manual

Removes a branch from a transaction and returns the outcome of the transaction. $END_BRANCHW always waits for the request to complete before returning to the caller. Other than this, it is identical to $END_BRANCH.

Format

SYS$END_BRANCHW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,bid

C Prototype

int sys$end_branchw (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid [4], unsigned int bid [4]);

Ends a transaction by attempting to commit it, and returns the outcome of the transaction.

Format

SYS$END_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]]

C Prototype

int sys$end_trans (unsigned int efn, unsigned int flags, struct _iosb *iosb,...);

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 these option flags, which are defined in Table SYS-30.

All undefined bits must be 0. If this argument is omitted, no flag is set.

Table SYS-30 $END_TRANS Option Flags

Flag	Description
DDTM$M_SYNC	Set this flag to specify that successful synchronous completion is to be indicated by returning SS$_SYNCH. When SS$_SYNCH is returned, the asynchronous system trap (AST) routine is not called, the event flag is not set, and the I/O status block is not filled in.
DDTM$M_NOWAIT	Indicates that the service should return to the caller without waiting for final cleanup. Note that $END_TRANSW with the DDTM$M_NOWAIT flag set is not equivalent to $END_TRANS. The former does not return until the operation has been initiated, while $END_TRANS returns when the operation has been queued. The full range of status values may be returned from a nowait call.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

I/O status block in which the following information is returned contains:

• The completion status of the service. This is returned as a condition value. See the Condition Values Returned section.
• The outcome of the transaction. If the service returns SS$_NORMAL, the outcome of the transaction is commit. If the service returns SS$_ABORT, the outcome of the transaction is abort.
• An abort reason code that gives one reason why the transaction aborted, if the completion status of the service is SS$_ABORT.

The $DDTMMSGDEF macro defines symbolic names for these abort reason codes, which are described in Table SYS-31:

Table SYS-31 Abort Reason Codes

Symbolic Name	Description
DDTM$_ABORTED	The application aborted the transaction.
DDTM$_COMM_FAIL	A communications link failed.
DDTM$_INTEGRITY	A resource manager integrity constraint check failed.
DDTM$_LOG_FAIL	A write operation to the transaction log failed.
DDTM$_ORPHAN_BRANCH	Unauthorized branch caused failure.
DDTM$_PART_SERIAL	A resource manager serialization check failed.
DDTM$_PART_TIMEOUT	The timeout specified by a resource manager expired.
DDTM$_SEG_FAIL	A process or image terminated.
DDTM$_SERIALIZATION	A DECdtm transaction manager serialization check failed.
DDTM$_SYNC_FAIL	The transaction was not globally synchronized (an authorized branch had not been added).
DDTM$_TIMEOUT	The timeout specified on $START_TRANS expired.
DDTM$_UNKNOWN	The reason is unknown.
DDTM$_VETOED	A resource manager was unable to commit the transaction.

The following diagram shows the structure of the I/O status block:

astadr

astprm

tid

If this argument is omitted, $END_TRANS ends the default transaction of the calling process.

Description

The End Transaction service ends a transaction by attempting to commit it, and returns the outcome of the transaction.

The $END_TRANS service:

• Initiates the commit protocol to determine whether the outcome of the transaction is commit or abort.

  Caution Do not call $END_TRANS while any transaction operation is in progress. If any of these operations is in progress when $END_TRANS is called, an unintended set of operations can be committed. This can invalidate application data managed by the resource managers participating in the transaction.

  
  Provided that no abort event has occurred, the DECdtm transaction manager delivers a prepare event to each Resource Manager (RM) participant in the transaction that:
  • Is associated with a Resource Manager instance (RMI) that requests prepare events.
  • Did not set the DDTM$M_COORDINATOR flag when it was added to the transaction.
  
  If there is only one such RM participant, the DECdtm transaction manager delivers a one-phase commit event, not prepare event, to that RM participant.
• $END_TRANS returns the outcome of the transaction. If it completes successfully, the outcome of the transaction is commit. If it returns the SS$_ABORT error, the outcome is abort.
• $END_TRANS removes from the specified transaction the branch that started the transaction.

Preconditions for the successful completion of $END_TRANS are:

• The calling process must contain the branch that started the transaction.
• The access mode of the caller must be the same as or more privileged than that of any branch of the specified transaction within this process. (See $START_TRANS and $START_BRANCH.)
• $START_BRANCH must have been performed for each authorized branch of the specified transaction.

$END_TRANS may fail for various reasons, including:

• The preconditions were not met.
• An abort event has occurred for the transaction.

Postconditions on successful completion of $END_TRANS are listed in Table SYS-32. $END_TRANS will not complete successfully (that is, the event flag will not be set, the AST routine will not be called, and the I/O status block will not be filled in) until after each authorized and synchronized branch of the transaction has initiated a call to $END_BRANCH.

$END_TRANS will not complete successfully (that is, the event flag will not be set, the AST routine will not be called, and the I/O status block will not be filled in) while the calling process is either:

• In an access mode that is more privileged than the DECdtm calls made by any resource manager participant in the transaction. RMS Journaling calls DECdtm in executive mode. Oracle Rdb and Oracle CODASYL DBMS call DECdtm in user mode.
• At AST level (in any access mode).

For example, if Oracle Rdb is a participant in the transaction, $END_TRANS will not complete successfully while the calling process is in supervisor, executive, or kernel mode, or while the calling process is at AST level. Successful completion of $END_TRANS is not indefinitely postponed by network failure.

Table SYS-32 Postconditions When$END_TRANS Completes Successfully

Postcondition	Meaning
The transaction is ended.	The meanings are: The TID of the transaction is invalid. Calls to any DECdtm system services except $GETDTI and $SETDTI that pass that TID will fail, and calls to resource managers that pass the TID will fail. The transaction no longer has any application or RM participants on the local node. All communications about the transaction between the local DECdtm transaction manager and other DECdtm transaction managers are finished (including the final cleanup acknowledgments).
The outcome of the transaction is commit.	All the transaction operations by authorized branches that completed successfully before $END_TRANS was called will take effect. That is, the effects of these operations will be made permanent. Operations by unauthorized branches will be aborted. (An unauthorized branch is one without a matching $ADD_BRANCH.)
DECdtm quotas are returned.	All quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.
The transaction is not the default transaction of the calling process.	If the transaction was the default transaction of the calling process, then it is now no longer the default.

Postconditions on completion with SS$_ABORT error are listed in Table SYS-33. $END_TRANS does not complete with the SS$_ABORT error until all branches on the local node have been removed from the transaction. Thus it does not complete with this error until after each authorized and synchronized branch on the local node has initiated a call to either $END_BRANCH or $ABORT_TRANS.

Note that the completion of $END_TRANS with the SS$_ABORT error is not indefinitely postponed by network failure.

Table SYS-33 Postconditions When$END_TRANS Completes with SS$_ABORT Error

Postcondition	Meaning
The transaction is ended.	If DDTM$M_NOWAIT is clear: The TID of the transaction is invalid. Calls to any DECdtm system services except $GETDTI and $SETDTI that pass the TID will fail, and calls to resource managers that pass the TID will fail. The transaction no longer has any application or RM participants on the local node. All communications about the transaction between the local DECdtm transaction manager and other DECdtm transaction managers are finished (including the final "cleanup" acknowledgments).
The outcome of the transaction is abort.	None of the operations of the transaction will ever take effect. The I/O status block contains one reason why the transaction was aborted. Note that if there are multiple reasons for the transaction aborting, the DECdtm transaction manager returns one of the reasons in the I/O status block. It may return different reasons to different branches in the transaction. For example, if the transaction timeout expires and a communications link fails, then either the DDTM$_TIMEOUT or DDTM$_COMM_FAIL abort reason code may be returned.
DECdtm quotas are returned.	If DDTM$M_NOWAIT is clear, all quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.
The transaction is not the default transaction of the calling process.	If DDTM$M_NOWAIT is clear then, if the transaction was the default transaction of the calling process, then the transaction is now no longer the default.

There is also a wait form of the service, $END_TRANSW.

Required Access or Privileges

None

Required Quotas

ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $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$_ABORT	The transaction aborted. See the abort reason code returned in the I/O status block for one reason why the transaction aborted.
SS$_ACCVIO	An argument was not accessible to the caller.
SS$_BADPARAM	The options flags were invalid.
SS$_CURTIDCHANGE	The tid argument was omitted and a call to change the default transaction of the calling process was in progress.
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$_NOCURTID	An attempt was made to end the default transaction (the tid argument was omitted), but the calling process did not have a default transaction.
SS$_NOSUCHTID	The calling process did not contain any branches in the transaction.
SS$_NOTORIGIN	The calling process did not start the transaction.
SS$_WRONGACMODE	The access mode of the caller was less privileged than that of a branch of the transaction in this process.
SS$_WRONGSTATE	The calling process had already called either $ABORT_TRANS with a zero BID or $END_TRANS to end the transaction, and processing had not completed.

Ends a transaction by attempting to commit it, and returns the outcome of the transaction.

$END_TRANSW always waits for the request to complete before returning to the caller. Other than this, it is identical to $END_TRANS.

Do not call $END_TRANSW from asynchronous system trap (AST) level, or from an access mode that is more privileged than the DECdtm calls made by any resource manager participant in the transaction. If you do, the $END_TRANSW service will wait indefinitely.

Format

SYS$END_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]]

C Prototype

int sys$end_transw (unsigned int efn, unsigned int flags, struct _iosb *iosb,...);

Queues a new lock or lock conversion on a resource.

The $ENQ, $ENQW, $DEQ (Dequeue Lock Request), and $GETLKI (Get Lock Information) services together provide the user interface to the Lock Management facility. Refer to the descriptions of these other services for additional information about lock management.

On Alpha and I64 systems, this service accepts 64-bit addresses.

For additional information about system service completion, see the Synchronize ($SYNCH) service.

Format

SYS$ENQ [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid] ,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id] ,[nullarg]

C Prototype

int sys$enq (unsigned int efn, unsigned int lkmode, struct _lksb *lksb, unsigned int flags, void *resnam, unsigned int parid, void (*astadr)(__unknown_params), unsigned int acmode, unsigned int rsdm_id,...);

Arguments

efn

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

Number of the event flag to be set when the request has been granted or canceled. Cancellation occurs if you use $DEQ with the cancel modifier or if the waiting request is chosen to break a deadlock. The efn argument is a longword containing this number; however, $ENQ uses only the low-order byte.

Upon request initiation, $ENQ clears the specified event flag (or event flag 0 if efn was not specified). Then, when the lock request is granted, the specified event flag (or event flag 0) is set unless you specified the LCK$M_SYNCSTS flag in the flags argument.

lkmode

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by value

Lock mode requested. The lkmode argument is a longword specifying this lock mode.

Each lock mode has a symbolic name. The $LCKDEF macro defines these symbolic names. The following table gives the symbolic name and description for each lock mode:

Lock Mode	Description
LCK$K_NLMODE	Null mode. This mode grants no access to the resource but serves as a placeholder and indicator of future interest in the resource. The null mode does not inhibit locking at other lock modes; further, it prevents the deletion of the resource and lock value block, which would otherwise occur if the locks held at the other lock modes were dequeued.
LCK$K_CRMODE	Concurrent read. This mode grants the caller read access to the resource while permitting write access to the resource by other users. This mode is used to read data from a resource in an unprotected manner, because other users can modify that data as it is being read. This mode is typically used when additional locking is being performed at a finer granularity with sublocks.
LCK$K_CWMODE	Concurrent write. This mode grants the caller write access to the resource while permitting write access to the resource by other users. This mode is used to write data to a resource in an unprotected fashion, because other users can simultaneously write data to the resource. This mode is typically used when additional locking is being performed at a finer granularity with sublocks.
LCK$K_PRMODE	Protected read. This mode grants the caller read access to the resource while permitting only read access to the resource by other users. Write access is not allowed. This is the traditional share lock.
LCK$K_PWMODE	Protected write. This mode grants the caller write access to the resource while permitting only read access to the resource by other users; the other users must have specified concurrent read mode access. No other writers are allowed access to the resource. This is the traditional update lock.
LCK$K_EXMODE	Exclusive. The exclusive mode grants the caller write access to the resource and allows no access to the resource by other users. This is the traditional exclusive lock.

The following table shows the compatibility of lock modes:

Table SYS-34 Compatibility of Lock Modes

Mode of	Mode of Currently Granted Locks
Requested Lock	NL	CR	CW	PR	PW	EX
NL	Yes	Yes	Yes	Yes	Yes	Yes
CR	Yes	Yes	Yes	Yes	Yes	No
CW	Yes	Yes	Yes	No	No	No
PR	Yes	Yes	No	Yes	No	No
PW	Yes	Yes	No	No	No	No
EX	Yes	No	No	No	No	No

NL---Null
CR---Concurrent read
CW---Concurrent write
PR---Protected read
PW---Protected write
EX---Exclusive

lksb

The lock status block can optionally contain a 16-byte or a 64-byte lock value block. The initial value of the lock value block is zero (0).

• When you specify the LCK$M_VALBLK flag in the flags argument, the lock status block contains a lock value block. In this case, the 16-byte lock value block appears at the beginning of the first byte following the eighth byte of the lock status block, bringing the total length of the lock status block to 24 bytes.
• When you specify the LCK$M_XVALBLK flag together with the LCK$M_VALBLK flag in the flags argument, the lock status block contains an extended lock value block. In this case, the 64-byte lock value block appears at the beginning of the first byte following the eighth byte of the lock status block, bringing the total length of the lock status block to 72 bytes.
  The LCK$M_XVALBLK flag is valid only on Alpha and I64 systems.