VMS Help
System Services, $GETDTI
*Conan The Librarian
|
Returns information about the state of transactions.
Format
SYS$GETDTI [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,[log_id]
,[contxt] ,search ,itmlst
C Prototype
int sys$getdti (unsigned int efn, unsigned int flags, struct
_iosb *iosb, void (*astadr)(__unknown_params),
int astprm, unsigned int log_id [4], unsigned
int *contxt, void *search, void *itmlst);
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 described in $GETDTI Option Flags. All undefined bits must
be 0. If this argument is omitted, no flags are used.
Table SYS-19 $GETDTI Option Flags
Flag Name Description
DDTM$M_FULL_ Indicates that the $GETDTI call for a specified
STATE TID is not to complete until the ABORTED
or COMMITTED state can be returned. Thus,
if another node or coordinating resource
manager must be contacted and it is currently
unreachable, this service does not return
until the node can be contacted. Indicates on
a wildcard search that only transactions known
to be in the ABORTED or COMMITTED states are to
be returned.
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.
Refer to the HP OpenVMS System Services Reference Manual to view
the I/O status block diagram.
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 $GETDTI 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.
log_id
OpenVMS usage:uid
type: octaword (unsigned)
access: read only
mechanism: by reference
The log id of the transaction manager that is coordinating the
transaction, returned as the log_id argument on a $DECLARE_RM
operation. The log_id argument verifies that the recovery log
returning transaction information is the same one used to record
transaction state information.
If you do not specify the same log id used by the transaction
manager to write transaction information, then $GETDTI will
return an error.
If the log_id argument is specified as a zero UID, then $GETDTI
will use the current active log for this node. If the specified
transaction cannot be found in this log, then the returned state
will be aborted. The log identifier can only be specified as
zero when the DTI$_SEARCH_AS_NODE item is absent or results in
a search that specifies the local node. Note that the log_id
argument cannot be specified as a zero address.
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.
contxt
OpenVMS usage:contxt
type: longword (unsigned)
access: modify
mechanism: by reference
The address of a longword used to maintain a context between
sequential calls to $GETDTI. A call to $GETDTI will start a new
search if the context value is zero or continue the existing
search if the context is valid.
The search context is valid only after a successful call to
$GETDTI and is invalidated by a subsequent call to $GETDTI.
The context is also used as input to $SETDTI after a successful
call to $GETDTI. Calls to $SETDTI do not modify or invalidate the
context.
search
OpenVMS usage:item_list_3
type: descriptor list
access: read only
mechanism: by reference
Item list specifying how the search for transaction information
is to be bounded.
The search argument is the address of a list of item descriptors,
each of which describes a search item. The list of item
descriptors is terminated by a longword of 0. Each item
descriptor in the search item list acts as an input argument
to $GETDTI and as such is only required to be read only.
Refer to the HP OpenVMS System Services Reference Manual to view
the single item descriptor format.
The following table describes the search item descriptor fields:
Field Description
Buffer A word containing a user-supplied integer
length specifying the length (in bytes) of a buffer from
which $GETDTI is to read the information. The
length of the buffer needed depends on the item
code field of the search item descriptor. If the
value of buffer length is too small, $GETDTI will
return an error status.
Item code A word containing a user-supplied symbolic code
specifying the search item that $GETDTI is to use.
The $DTIDEF macro defines these codes. Each item
code is described in the Search Item Codes section
below.
Buffer A longword containing the user-supplied address
address of the buffer from which $GETDTI reads the search
information.
Return This longword is not used in the search item list,
length because all search items are read-only.
address
itmlst
OpenVMS usage:item_list_3
type: descriptor list
access: read only
mechanism: by reference
Item list specifying the transaction information that $GETDTI
is to return. The itmlst argument is the address of a list of
item descriptors, containing a single entry that describes an
item of information. The list of item descriptors is terminated
by a longword of 0. The item descriptor in the item list acts
as an output argument to $GETDTI and as such is required to be
writeable in caller's mode.
Refer to the HP OpenVMS System Services Reference Manual to view
the single item descriptor format.
The following table describes the itmlst item descriptor fields:
Field Description
Buffer A word containing a user-supplied integer
length specifying the length (in bytes) of the buffer
where $GETDTI is to write the information. The
length of the buffer needed depends on the item
code field of the search item descriptor. If
the value of buffer length is too small, $GETDTI
truncates the data and returns the condition code
value SS$_BUFFEROVF.
Item code A word containing a user-supplied symbolic code
specifying the search item that $GETDTI is to
use. The $DTIDEF macro defines these codes. Each
item code is described in the Itmlst Item Codes
section.
Buffer A longword containing the user-supplied address
address of the buffer where $GETDTI is to write the
information.
return A longword containing the user-supplied address
length of a word where $GETDTI writes return length
address information.