 |
HP OpenVMS System Services Reference Manual
$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 completion status of the service. This is returned as a
condition value. See the Condition Values Returned section for more
information.
- The outcome of the transaction. If the service completes
successfully, the outcome of the transaction is commit. If it 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.
See $ACK_EVENT for a list of the codes that are currently defined.
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:
- Removes the specified branch from the specified transaction.
- Returns the outcome of the specified transaction.
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:
- The calling process must contain the specified branch of the
specified transaction.
- The specified branch must be a synchronized branch.
- The access mode of the caller must be the same as or more
privileged than that of any branch of the specified transaction in this
process. (See $START_BRANCH and $START_TRANS.)
$END_BRANCH may fail for the following reasons:
- Preconditions were not met.
- An abort event has occurred for the transaction.
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 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-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:
- 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-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:
- 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-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.
|
|
