 |
HP OpenVMS System Services Reference Manual
Postconditions on completion with SS$_ABORT error are listed in
Table SYS-32. $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-32 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.
|
$END_TRANSW
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,...);
$ENQ
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. For additional information about lock management,
see the descriptions of these other services.
On Alpha and Integrity server 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-33 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
|
Key to Lock Modes:
NL---Null
CR---Concurrent read
CW---Concurrent write
PR---Protected read
PW---Protected write
EX---Exclusive
lksb
| OpenVMS usage: |
lock_status_block |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
Lock status block in which $ENQ writes the final completion status of
the operation. The lksb argument is the 32- or 64-bit
address of the 8-byte lock status block.
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 Integrity server systems.
The following diagram shows the format of the lock status block and the
optional lock value block:
The following table defines the status block fields:
| Status Block Field |
Definition |
|
Condition value
|
A word in which $ENQ writes a condition value describing the final
disposition of the lock request; for example, whether the lock was
granted, converted, and so on. The condition values returned in this
field are described in the Condition Values Returned in the Lock Status
Block section, which appears following the list of condition values
returned in R0.
|
|
Reserved
|
A word reserved by HP.
|
|
Lock identification
|
A longword containing the identification of the lock.
For a new lock, $ENQ writes the lock identification of the
requested lock into this longword when the lock request is queued.
For a lock conversion on an existing lock, you must supply the lock
identification of the existing lock in this field.
|
|
Lock value block
|
A user-defined structure containing information about the resource.
This information is interpreted only by the user program.
The length of the user data structure is 16 bytes if only the
LCK$M_VALBLK flag is specified. The user data structure is 64 bytes if
both the LCK$M_VALBLK and LCK$M_XVALBLK flags are specified. The length
of the system copy of the lock value block structure is always 64 bytes
on OpenVMS and Integrity server systems beginning with OpenVMS Version
8.2. Refer to the HP OpenVMS Programming Concepts Manual for information about using the
LCK$M_XVALBLK flag in a mixed-version cluster.
When a process acquires a lock on a resource, the lock management
facility provides that process with a process-private copy of the lock
value block associated with the resource, provided that process has
specified the LCK$M_VALBLK flag in the
flags argument. The copy provided to the process is a
copy of the lock value block stored in the lock manager's database.
The copy of the lock value block maintained in the lock database is
either read into or updated from the caller's lock value block. The
method used depends on the lock mode of the lock that was granted, and
on the mode of the original lock held, if the operation was a
conversion.
In general, a grant or a conversion to an equal-level or
higher-level lock mode reads the lock value from the lock database into
the caller's lock value block.
When a lock conversion from EX-mode or PW-mode to an equal-level or
lower-level lock mode occurs, the contents of the caller's lock value
block are written into the lock database. The specific behavior of the
lock conversion is documented in the HP OpenVMS Programming Concepts Manual in the table
entitled, "Effect of Lock Conversion on Lock Value Block".
|
Callers of $ENQ are provided with copies of the updated lock value
block from the lock database in the following way: when $ENQ grants a
new lock to the caller or converts the caller's existing lock to the
same lock mode or a higher lock mode, $ENQ copies the lock value block
from the lock database to the caller's lock value block, provided the
caller has specified the LCK$M_VALBLK flag.
The Description section describes events that can cause the lock value
block to become invalid.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flags specifying options for the $ENQ operation. The
flags argument is a longword bit mask that is the
logical OR of each bit set, where each bit corresponds to an option.
The $LCKDEF macro defines a symbolic name for each flag bit. The
following table describes each flag:
| Flag |
Description |
|
LCK$M_NOQUEUE
|
When this flag is specified, $ENQ does not queue the lock request
unless the lock can be granted immediately. By default, $ENQ always
queues the request.
If you specify LCK$M_NOQUEUE in a lock conversion operation and the
conversion cannot be granted immediately, the lock remains in the
original lock mode.
|
|
LCK$M_SYNCSTS
|
When you specify this flag, $ENQ returns the successful condition value
SS$_SYNCH in R0 if the lock request is granted immediately; in this
case, no completion asynchronous system trap (AST) is delivered and no
event flag is set. If the lock request is queued successfully but
cannot be granted immediately, $ENQ returns the condition value
SS$_NORMAL in R0; then when the request is granted, $ENQ sets the event
flag and queues an AST if the
astadr argument was specified.
|
|
LCK$M_SYSTEM
|
When you specify this flag, the resource name is interpreted as
systemwide. By default, resource names are qualified by the user
identification code (UIC) group number of the creating process. This
flag is ignored in lock conversions.
|
|
LCK$M_VALBLK
|
When you specify this flag, the lock status block contains a lock value
block. The initial value of the lock value block is zero (0). See the
description of the
lksb argument and the LCK$M_XVALBLK flag for more
information.
|
|
LCK$M_CONVERT
|
When you specify this flag, $ENQ performs a lock conversion. In this
case, the caller must supply (in the second longword of the lock status
block) the lock identification of the lock to be converted.
|
|
LCK$M_NODLCKWT
|
By specifying this flag, a process indicates to the lock management
services that it is not blocked from execution while waiting for the
lock request to complete. For example, a lock request might be left
outstanding on the waiting queue as a signaling device between
processes.
This flag helps to prevent false deadlocks by providing the lock
management services with additional information about the process
issuing the lock request. When you set this flag, the lock management
services do not consider this lock when trying to detect deadlock
conditions.
|
|
|
A process should specify the LCK$M_NODLCKWT flag only in a call to the
$ENQ system service. The $ENQW system service waits for the lock
request to be granted before returning to the caller; therefore,
specifying the LCK$M_NODLCKWT flag in a call to the $ENQW system
service defeats the purpose of the flag and can result in a genuine
deadlock being ignored.
The lock management services make use of the LCK$M_NODLCKWT flag
only when the lock specified by the call to $ENQ is in either the
waiting or the conversion queue.
Improper use of the LCK$M_NODLCKWT flag can result in the lock
management services ignoring genuine deadlocks.
|
|
LCK$M_NODLCKBLK
|
By specifying this flag, a process indicates to the lock management
services that, if this lock is blocking another lock request, the
process intends to give up this lock on demand. When you specify this
flag, the lock management services do not consider this lock as
blocking other locks when trying to detect deadlock conditions.
A process typically specifies the LCK$M_NODLCKBLK flag only when it
also specifies a blocking AST. Blocking ASTs notify processes with
granted locks that another process with an incompatible lock mode has
been queued to access the same resource. Use of blocking ASTs can cause
false deadlocks, because the lock management services detect a blocking
condition, even though a blocking AST has been specified; however, the
blocking condition will disappear as soon as the process holding the
lock executes, receives the blocking AST, and dequeues the lock.
Specifying the LCK$M_NODLCKBLK flag prevents this type of false
deadlock.
To enable blocking ASTs, the
blkast argument of the $ENQ system service must
contain the address of a blocking AST service routine. If the process
specifies the LCK$M_NODLCKBLK flag, the blocking AST service routine
should either dequeue the lock or convert it to a lower lock mode
without issuing any new lock requests. If the blocking AST routine does
otherwise, a genuine deadlock could be ignored.
The lock management services make use of the LCK$M_NODLCKBLK flag
only when the lock specified by the call to $ENQ has been granted.
Improper use of the LCK$M_NODLCKBLK flag can result in the lock
management services ignoring genuine deadlocks.
|
|
LCK$M_NOQUOTA
|
This flag is reserved by HP. When you set this flag, the calling
process is not charged Enqueue Limit (ENQLM) quota for this new lock.
The calling process must be running in executive or kernel mode to set
this flag. This flag is ignored for lock conversions.
|
|
LCK$M_CVTSYS
|
This flag is reserved by HP. When you set this flag, the lock is
converted from a process-owned lock to a system-owned lock. The calling
process must be running in executive or kernel mode to set this flag.
|
|
LCK$M_EXPEDITE
|
This flag is valid only for new lock requests. Specifying this flag
allows a request to be granted immediately, provided the requested mode
when granted would not block any currently queued requests in the
resource conversion and wait queues. Currently, this flag is valid only
for NLMODE requests. If this flag is specified for any other lock mode,
the request will fail and an error of SS$_UNSUPPORTED will be returned.
|
|
LCK$M_QUECVT
|
This flag is valid only for conversion operations. A conversion request
with the LCK$M_QUECVT flag set will be forced to wait behind any
already queued conversions.
The conversion request is granted immediately, if there are no
already queued conversions.
The QUECVT behavior is valid only for a subset of all possible
conversions. Table SYS-34 defines the legal set of conversion requests
for LCK$M_QUECVT. Illegal conversion requests are failed with
SS$_BADPARAM returned.
|
|
LCK$M_XVALBLK
|
This flag is valid only if it is used in conjunction with the
LCK$M_VALBLK flag. When you specify the LCK$M_XVALBLK flag, you must
provide a 64-byte lock value block at the end of the lock states block
specified in the
lksb argument. If you do not specify this flag, only
the first 16 bytes of the lock value block buffer specified as part of
the lock status block in the
lksb argument will be read or written.
If the value block is written without this flag, the value block
will be flagged so that a future reader who specifies the LCK$M_XVALBLK
flag in the $ENQ system service call will receive the warning status
SS$_XVALNOTVALID until a future writer writes to the value block
specifying this flag.
|
Table SYS-34 Legal QUECVT Conversions
| Lock Mode |
Lock Mode to Which Lock Is Converted |
at Which
Lock Is Held |
NL |
CR |
CW |
PR |
PW |
EX |
|
NL
|
No
|
Yes
|
Yes
|
Yes
|
Yes
|
Yes
|
|
CR
|
No
|
No
|
Yes
|
Yes
|
Yes
|
Yes
|
|
CW
|
No
|
No
|
No
|
Yes
|
Yes
|
Yes
|
|
PR
|
No
|
No
|
Yes
|
No
|
Yes
|
Yes
|
|
PW
|
No
|
No
|
No
|
No
|
No
|
Yes
|
|
EX
|
No
|
No
|
No
|
No
|
No
|
No
|
Key to Lock Modes
NL---Null lock
CR---Concurrent read
CW---Concurrent write
PR---Protected read
PW---Protected write
EX---Exclusive lock
resnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string
descriptor |
Name of the resource to be locked by this lock. The
resnam argument is the 32- or 64-bit address of a
character string descriptor pointing to this name. The name string can
be from 1 to 31 bytes in length.
|
