HP OpenVMS System Services Reference Manual


Previous Contents Index


$DLCEFC

Marks a permanent common event flag cluster for deletion.

Format

SYS$DLCEFC name


C Prototype

int sys$dlcefc (void *name);


Argument

name


OpenVMS usage: ef_cluster_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

Name of the common event flag cluster to be deleted. The name argument is the address of a character string descriptor pointing to the name of the cluster.

The names of event flag clusters are unique to UIC groups, and the UIC group number of the calling process is part of the name.


Description

The Delete Common Event Flag Cluster service marks a permanent common event flag cluster for deletion. The cluster is actually deleted when no more processes are associated with it. The $DLCEFC service does not disassociate a process from a common event flag cluster; the Disassociate Common Event Flag Cluster ($DACEFC) service does this. However, the system disassociates a process from an event flag cluster at image exit.

If the cluster has already been deleted or does not exist, the $DLCEFC service returns the status code SS$_NORMAL.

Required Access or Privileges

Delete access is required.

Required Quota

None

Related Services

$ASCEFC, $CLREF, $DACEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_IVLOGNAM The cluster name string has a length of 0 or has more than 15 characters.
SS$_NOPRIV The process does not have the privilege to delete a permanent common event flag cluster, or the process does not have the privilege to delete a common event flag cluster in memory shared by multiple processors.

$END_BRANCH

Removes a branch from a transaction and returns the outcome of the transaction.

Format

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


C Prototype

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


Arguments

efn


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

Number of the event flag 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, described in Table SYS-26. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-26 $END_BRANCH Option Flags
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.
DDTM$M_NOWAIT Indicates that the service should return to the caller without waiting for final cleanup. Note that $END_BRANCHW with the DDTM$M_NOWAIT flag set is not equivalent to $END_BRANCH. The latter returns when the operation has been queued. The former does not return until the operation has been initiated. 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

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

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 $END_BRANCH 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.

tid


OpenVMS usage: trans_id
type: octaword (unsigned)
access: read only
mechanism: by reference

The identifier (TID) of the transaction from which the branch is to be removed.

bid


OpenVMS usage: branch_id
type: octaword (unsigned)
access: read only
mechanism: by reference

The identifier (BID) of the branch to be removed from the transaction.

Description

The $END_BRANCH system service:

If $END_BRANCH completes successfully, the outcome of the transaction is commit. If it returns SS$_ABORT, the outcome is abort.

Preconditions for the successful completion of $END_BRANCH are:

$END_BRANCH may fail for the following reasons:

Postconditions on successful completion of $END_BRANCH are described in Table SYS-27:

Table SYS-27 Postconditions When$END_BRANCH Completes Successfully
Postcondition Meaning
The branch that started the transaction has initiated a call to $END_TRANS. The completion of $END_BRANCH is delayed until this occurs. If the transaction was not started on the local node, the successful completion of $END_BRANCH may be indefinitely postponed by network failure.
Every other authorized and synchronized branch of the transaction has initiated a call to $END_BRANCH. The completion of $END_BRANCH is delayed until this occurs.
The transaction is ended. The result is that:
  • 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 that 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 that completed successfully before $END_TRANS was called will take effect; that is, the effects of these operations will be made permanent.

Operations by any 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 the SS$_ABORT error are listed in Table SYS-28. $END_BRANCH does not complete with this error until all branches on the local node have been removed from the transaction. Thus this call to $END_BRANCH cannot complete with the SS$_ABORT error until after every authorized and synchronized branch on the local node has initiated a call to $END_TRANS, $END_BRANCH, or $ABORT_TRANS.

Table SYS-28 Postconditions When$END_BRANCH Completes with the 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 that TID will fail, and calls to resource managers that pass that 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. 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 and the transaction was the default transaction of the calling process, then it is no longer the default.

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

Required Privileges

None

Required Quotas

ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCHW, $END_TRANS, $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 Either the options flags were invalid or the tid argument was omitted but the bid argument was not zero.
SS$_BRANCHENDED Either the calling process had already called $END_BRANCH or $ABORT_TRANS specifying that BID, or the branch was unsynchronized.
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$_NOSUCHBID The calling process did not contain the branch identified by the BID passed in the bid argument.
SS$_NOSUCHTID The calling process did not contain any branches in the transaction.
SS$_WRONGACMODE The access mode of the caller was less privileged than that of a branch of the specified transaction in this process.

$END_BRANCHW

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]);


$END_TRANS

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-29.

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

Table SYS-29 $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 $DDTMMSGDEF macro defines symbolic names for these abort reason codes, which are described in Table SYS-30:

Table SYS-30 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


OpenVMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference

AST routine that is executed when the service completes if SS$_NORMAL is returned in R0. The astadr argument is the address of this routine. The routine is executed in the access mode of the caller.

astprm


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

AST parameter that is passed to the AST routine specified by the astadr argument.

tid


OpenVMS usage: trans_id
type: octaword (unsigned)
access: read only
mechanism: by reference

Identifier (TID) of the transaction to be ended.

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:

Preconditions for the successful completion of $END_TRANS are:

$END_TRANS may fail for various reasons, including:

Postconditions on successful completion of $END_TRANS are listed in Table SYS-31. $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:

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-31 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.


Previous Next Contents Index