 |
HP OpenVMS System Services Reference Manual
The following diagram shows the format of a single item descriptor:
The following table describes the itmlst item
descriptor fields:
| Field |
Description |
|
Buffer length
|
A word containing a user-supplied integer 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 address
|
A longword containing the user-supplied address of the buffer where
$GETDTI is to write the information.
|
|
return length address
|
A longword containing the user-supplied address of a word where $GETDTI
writes return length information.
|
Search Item Codes
DTI$_SEARCH_AS_NODE
When you specify DTI$_SEARCH_AS_NODE, $GETDTI limits the get request to
the specified node name. This can be used during cluster failover
recovery processing to allow another node in the cluster to act on
behalf of the failed node. The DTI$_SEARCH_AS_NODE item descriptor
should point to an ASCII string containing a valid node name string.
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.
DTI$_SEARCH_RESOLVED_STATE
When you specify DTI$_SEARCH_RESOLVED_STATE, the buffer address points
to a transaction record that describes the search conditions for this
$GETDTI call. The following fields are used from this transaction
record and must be specified before $GETDTI can proceed. The $DTIDEF
macro defines these fields.
| Item |
Description |
|
DTI$B_PART_NAME_LEN
|
A byte containing the length of the participant name field
DTI$T_PART_NAME.
|
|
DTI$T_PART_NAME
|
A character field containing DTI$B_PART_NAME_LEN characters that
specifies a resource manager name. When the resource manager name
string is supplied, a wildcard search can be specified. The left-most
characters supplied in this string will be matched against all resource
managers with the same leftmost characters. If the string entered has a
length of 0, all resource managers will be selected.
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.
|
|
DTI$T_PART_LOG_ID
|
Reserved by HP.
|
|
DTI$T_TID
|
A 16-byte field containing the transaction identifier.
|
DTI$_SEARCH_RESOLVED_STATE uses the DTI$_TRANSACTION_INFORMATION item
in the itmlst argument to write the following
information:
| Item |
Description |
|
DTI$B_STATE
|
A byte containing the state of the transaction identified by DTI$T_TID.
Table SYS-42 lists the possible values returned in the state field.
|
|
DTI$B_PART_NAME_LEN
|
A byte containing the length of the participant name field
DTI$T_PART_NAME.
|
|
DTI$T_PART_NAME
|
A character field containing DTI$B_PART_NAME_LEN characters that
specifies a resource manager name. When the resource manager name
string is supplied, a wildcard search can be specified. The left-most
characters supplied in this string will be matched against all resource
managers with the same leftmost characters. If the string entered has a
length of 0, all resource managers will be selected.
|
|
DTI$T_PART_LOG_ID
|
Reserved by HP.
|
|
DTI$T_TID
|
A 16-byte field containing the transaction identifier.
|
Table SYS-42 $GETDTI Transaction States
| Item |
Description |
|
DTI$K_STARTING
|
The transaction is in the starting state.
|
|
DTI$K_ACTIVE
|
The transaction is in the active state.
|
|
DTI$K_ONE_P_COMMITTING
|
The transaction is committing to phase one.
|
|
DTI$K_PREPARING
|
The transaction is in the preparing state.
|
|
DTI$K_PREPARED
|
The transaction has prepared.
|
|
DTI$K_COMMITTING
|
The transaction is in the committing state.
|
|
DTI$K_COMMITTED
1
|
The transaction has committed.
|
|
DTI$K_ONE_P_COMMITTED
|
The transaction has committed to phase one.
|
|
DTI$K_ABORTING
|
The transaction is in the aborting state.
|
|
DTI$K_ABORTED
1
|
The transaction has been aborted or forgotten. Note that, if the
transaction was aborted before the call to $GETDTI, then the alternate
status SS$_NOSUCHTID is returned; if the transaction was aborted during
the call to $GETDTI, then the DTI$K_ABORTED state is returned in the
transaction record.
|
1The DTI$K_COMMITTED and DTI$K_ABORTED transaction states
are the only values that can be returned when the DDTM$M_FULL_STATE
flag is specified.
Itmlst Item Codes
DTI$_TRANSACTION_INFORMATION
When you specify DTI$_TRANSACTION_INFORMATION, $GETDTI returns the
following fields dependent on the search criteria established by the
search argument.
Each record may be composed of some of the following items:
| Item |
Description |
|
DTI$B_STATE
|
A byte containing the state of the transaction identified by DTI$T_TID.
Table SYS-42 lists the possible values returned in the state field.
|
|
DTI$B_PART_NAME_LEN
|
A byte containing the length of the participant name field
DTI$T_PART_NAME.
|
|
DTI$T_PART_NAME
|
A character field containing DTI$B_PART_NAME_LEN characters that
specifies a resource manager name.
|
|
DTI$T_PART_LOG_ID
|
Reserved by HP.
|
|
DTI$T_TID
|
A 16-byte field containing the transaction identifier.
|
The DTI$_TRANSACTION_INFORMATION item buffer size should be at least
equal to the symbolic value DTI$S_TRANSACTION_INFORMATION defined by
$DTIDEF.
Description
During recovery from a failure, a resource manager calls $GETDTI to
request the state of certain transactions with which it had been
involved. As part of the recovery, the resource manager identifies any
unresolved transactions, so that they can be processed to completion.
The $GETDTI service returns the resolved state of in-doubt transactions
to recovering resource managers. The DDTM$M_FULL_STATE flag instructs
$GETDTI to return only the transactions in the DTI$K_COMMITTED or
DTI$K_ABORTED states (or an error status of SS$_NOSUCHTID). The action
taken depends on whether a transaction identifier is specified:
- If a transaction identifier is specified in DTI$T_TID, $GETDTI does
not return until the resolved state of the transaction is available.
- If DTI$T_TID is 0, $GETDTI ignores transactions that are not in the
DTI$K_COMMITTED or DTI$K_ABORTED states.
This can mean that the $GETDTI call may have to wait for other DECdtm
nodes or a coordinating CRM to become available. This is the
recommended method of obtaining an in-doubt transaction outcome for
recovering resource managers.
Alternatively, $GETDTI can be used to return the current known state of
transactions. Intermediate states may be returned. In particular,
DTI$K_PREPARED indicates that a DECdtm node is unavailable and
DTI$K_PREPARING indicates that a coordinating CRM is unavailable.
If $GETDTI is called during normal system operation to resolve the
state of transactions that have not failed, then the returned
transaction state can be any of the states listed in Table SYS-42.
A $GETDTI call may also be used in an OpenVMS Cluster environment to
perform recovery on behalf of a resource manager on a failed node. To
perform this action, the DTI$_SEARCH_AS_NODE search item descriptor is
used to inform $GETDTI of the node for which recovery is being
performed. This action is equivalent to performing the $GETDTI request
on the failed node. The use of DTI$_SEARCH_AS_NODE will perform
correctly when the target node is either available or unavailable. If
the target node is available when the $GETDTI call is executed, the
request is re-routed to the target node for execution.
To obtain information about transactions, $GETDTI must be given a set
of search criteria. The criteria are specified as parameters and as
part of an itemlist for the search argument using the
DTI$_SEARCH_RESOLVED_STATE item descriptor. The transaction information
required by $GETDTI to resolve a transaction includes:
- Transaction Identifier (TID).
- Resource Manager name.
- Transaction Manager log identifier.
- Resource Manager log identifier.
- Optionally, a remote node name.
If you specify a TID as 0, $GETDTI assumes a wildcard operation and
returns the requested information for each TID in the log that it has
privilege to access, one TID per call. To perform a wildcard operation,
you must call $GETDTI in a loop, testing for the condition value
SS$_NOSUCHTID after each call and exiting the loop when SS$_NOSUCHTID
is returned.
A resource manager is identified by its name in DTI$T_PART_NAME. A
wildcard search can be specified for the resource manager with this
item. The leftmost characters supplied in this string are matched
against all resource managers with the same leftmost characters in
their names.
If a resource manager name entered as the item has a length of 0, all
resource managers are selected.
Transaction managers and resource managers maintain log files to keep a
record of transactions and their related states. During recovery, it is
important that the transaction manager and resource manager use
matching log files. The transaction manger log identifier is returned
by the $DECLARE_RM service call. It should be recorded in the resource
manager's log records and supplied to $GETDTI as the value of the
log-id argument. If the wrong resource manager log, or
the wrong transaction manager log, is used, the discrepancy will result
in an error from $GETDTI or $SETDTI.
The contxt argument is used by $GETDTI to establish a
search context when it is returning the resolved state of a
transaction. The search context indicates the node and transaction
manager log identifier for use in a subsequent $SETDTI operation to
delete the resource manager from the transaction. The search context is
created when the contxt argument is invalid, or
re-used if the contxt argument is valid. The search
context is deleted when a call is made to $GETDTI that returns
SS$_NOSUCHTID. The search context is maintained exclusively by $GETDTI
and $SETDTI and should not be modified by the caller, with an exception
of initially zeroing the context. SYSPRV privilege is required to
retrieve or modify information about transactions with which the
process is not currently associated.
Required Privileges
SYSPRV is required to retrieve information about transactions with
which the process is not currently associated.
Required Quotas
BYTLM, ASTLM
Related Services
$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,
$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW,
$END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $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$_ACCVIO
|
An argument was not accessible to the caller.
|
|
SS$_BADLOGVER
|
There is an invalid or unsupported log version.
|
|
SS$_BADPARAM
|
The option flags, SEARCH or ITMLST are invalid.
|
|
SS$_BUGCHECK
|
A failure has occurred during the processing of the request.
|
|
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$_INVLOG
|
The log format is invalid.
|
|
SS$_NOSUCHFILE
|
The transaction manager log cannot be found.
|
|
SS$_NOSUCHNODE
|
The subordinate DECnet node is unknown.
|
|
SS$_NOSUCHPART
|
The participant is not part of the transaction.
|
|
SS$_NOSUCHTID
|
The designated TID is unknown.
|
|
SS$_NOSYSPRV
|
The caller is not authorized to examine the specified transaction.
|
|
SS$_PROTOCOL
|
There is a message protocol error.
|
|
SS$_REMOTE_PROC
|
There was an attempt to use a node when it is not part of the OpenVMS
Cluster.
|
|
SS$_REMRSRC
|
There are insufficient resources at the remote node.
|
|
SS$_UNREACHABLE
|
A superior node is unreachable.
|
$GETDTIW
Returns information about the resolved state of transactions and the
process default transaction identifier.
$GETDTIW always waits for the request to complete before returning to
the caller. Other than this, it is identical to $GETDTI.
Format
SYS$GETDTIW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,[contxt]
,[log_id] ,search ,itmlst
C Prototype
int sys$getdtiw (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);
$GETDVI
Returns information related to the primary and secondary device
characteristics of an I/O device.
For synchronous completion, use the Get Device/Volume Information and
Wait ($GETDVIW) service. The $GETDVIW service is identical to the
$GETDVI service in every way except that $GETDVIW returns to the caller
with the requested information.
For additional information about system service completion, refer to
the Synchronize ($SYNCH) service.
Note
All pathname-related information pertains only to
Alpha and I64 systems.
|
Format
SYS$GETDVI [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr] [,astprm]
[,nullarg] [,pathname]
C Prototype
int sys$getdvi (unsigned int efn, unsigned short int chan, void
*devnam, void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm, struct _generic_64
*nullarg,...);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag to be set when $GETDVI returns the requested
information. The efn argument is a longword containing
this number; however, $GETDVI uses only the low-order byte.
Upon request initiation, $GETDVI clears the specified event flag (or
event flag 0 if efn was not specified). Then, when
$GETDVI returns the requested information, it sets the specified event
flag (or event flag 0).
chan
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word
containing this number.
To identify a device to $GETDVI, you can specify either the
chan or devnam argument, but you
should not specify both. If you specify both arguments, the
chan argument is used.
If you specify neither chan nor
devnam, $GETDVI uses a default value of 0 for
chan.
devnam
| OpenVMS usage: |
device_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
The name of the device about which $GETDVI is to return information.
The devnam argument is the address of a character
string descriptor pointing to this name string.
The device name string can be either a physical device name or a
logical name. If the first character in the string is an underscore
(_), the string is considered a physical device name; otherwise, the
string is considered a logical name and logical name translation is
performed until either a physical device name is found or the system
default number of translations has been performed.
If the device name string contains a colon (:), the colon and the
characters that follow it are ignored.
To identify a device to $GETDVI, you can specify either the
chan or devnam argument, but you
should not specify both. If both arguments are specified, the
chan argument is used.
If you specify neither chan nor
devnam, $GETDVI uses a default value of 0 for
chan.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list
of item descriptors, each of which describes an item of information.
The list of item descriptors is terminated by a longword of 0. The
following diagram depicts the format of a single item descriptor:
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Buffer length
|
A word containing a user-supplied integer specifying the length (in
bytes) of the buffer in which $GETDVI is to write the information. The
length of the buffer needed depends on the item code specified in the
item code field of the item descriptor. If the value of buffer length
is too long, $GETDVI truncates the data.
|
|
Item code
|
A word containing a user-supplied symbolic code specifying the item of
information that $GETDVI is to return. The $DVIDEF macro defines these
codes. Each item code is described in the Item Codes section.
|
|
Buffer address
|
A longword containing the user-supplied address of the buffer in which
$GETDVI is to write the information.
|
|
Return length address
|
A longword containing the user-supplied address of a word in which
$GETDVI is to write the information.
|
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
I/O status block that is to receive the final completion status. The
iosb argument is the address of the quadword I/O
status block.
When you specify the iosb argument, $GETDVI sets the
quadword to 0 upon request initiation. Upon request completion, a
condition value is returned to the first longword; the second longword
is reserved to HP.
Though this argument is optional, HP strongly recommends that you
specify it, for the following reasons:
- If you are using an event flag to signal the completion of the
service, you can test the I/O status block for a condition value to be
sure that the event flag was not set by an event other than service
completion.
- If you are using the $SYNCH service to synchronize completion of
the service, the I/O status block is a required argument for $SYNCH.
- The condition value returned in R0 and the condition value returned
in the I/O status block provide information about different aspects of
the call to the $GETDVI service. The condition value returned in R0
gives you information about the success or failure of the service call
itself; the condition value returned in the I/O status block gives you
information about the success or failure of the service operation.
Therefore, to accurately assess the success or failure of the call to
$GETDVI, you must check the condition values returned in both R0 and
the I/O status block.
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
AST service routine to be executed when $GETDVI completes. The
astadr argument is the address of this routine.
If you specify astadr, the AST routine executes at the
same access mode as the caller of the $GETDVI service.
astprm
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
AST parameter to be passed to the AST service routine specified by the
astadr argument. The astprm argument
is the longword parameter.
nullarg
| OpenVMS usage: |
null_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Placeholding argument reserved to HP.
pathname
| OpenVMS usage: |
path_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
On Alpha and I64 systems, the name of the path about which $GETDVI is
to return information. The pathname argument is the
address of a character string descriptor pointing to this name string.
The pathname can be used with either the
chan or the devnam argument.
Check the definitions of the item codes to see if the
pathname argument is used. In general, item codes that
return information that can vary by path make use of the
pathname argument. Use the SHOW DEVICE /FULL command,
the SYS$DEVICE_PATH_SCAN system service, or the F$MULTIPATH DCL lexical
function to see the paths for a multipath device.
If the pathname argument is used, it is validated
against the existing paths for the device specified. If the path does
not exist, the error SS$_NOSUCHPATH is returned, even if the item code
or codes used do not make use of the pathname argument.
Item Codes
DVI$_ACCESSTIMES_RECORDED
On Alpha and I64, returns an unsigned longword, which is interpreted as
Boolean. A value of 1 indicates the volume supports the recording of
access times.
DVI$_ACPPID
Returns the ACP process ID as an unsigned integer longword.
DVI$_ACPTYPE
Returns the ACP type code as an unsigned integer longword. The
following symbols define each of the ACP type codes that $GETDVI can
return:
| Symbol |
Description |
|
DVI$C_ACP_F11V1
|
Files-11 Level 1
|
|
DVI$C_ACP_F11V2
|
Files-11 Level 2
|
|
DVI$C_ACP_F11V3
|
Files-11 presentation of ISO 9660
|
|
DVI$C_ACP_F11V4
|
Files-11 presentation of High Sierra
|
|
DVI$C_ACP_F11V5
|
Files-11 Level 5
|
|
DVI$C_ACP_F11V6
|
Files-11 Level 6
|
|
DVI$C_ACP_F64
|
Files 64 support for Spiralog
|
|
DVI$C_ACP_HBS
|
Not used
|
|
DVI$C_ACP_HBVS
|
Host Based Volume Shadowing
|
|
DVI$C_ACP_MTA
|
Magnetic tape
|
|
DVI$C_ACP_NET
|
Networks
|
|
DVI$C_ACP_REM
|
Remote I/O
|
|
DVI$C_ACP_UCX
|
ACP for TCP/IP Services for OpenVMS
|
DVI$_ALL
Returns an unsigned longword, interpreted as Boolean. A value of 1
indicates that the device is allocated.
DVI$_ALLDEVNAM
Returns the allocatable device name as a 64-byte, zero-filled string.
|
