Stat Extended (65)
Chapter contents
The Stat Extended operation (B_EXTENDED_STAT) has several subfunctions that allow an application to gather information about an open file.
Table 2-22 Stat Extended (65) Sub-functions
|
Sub-function ID
|
Description
|
|
1
|
Listing of extension file names
|
|
2
|
System Data information for the file
|
|
3
|
Duplicate conflict record and key identification
|
|
4
|
File information
|
|
5
|
Gateway identification
|
|
6
|
Lock owner identification
|
Parameters
| |
Op Code
|
Pos Block
|
Data Buf
|
Data Buf Len
|
Key Buffer
|
Key Number
|
|
Sent
|
|
|
|
|
|
|
|
Returned
|
|
|
|
|
|
|
Prerequisites
The file must be open.
Procedure
- Set the Operation Code to 65.
- Pass the Position Block for the given file.
- Store the extended stat structure in the Data Buffer. See the subsections below for more information about the extended stat structure required for each subfunction.
- Specify the Data Buffer Length.
- Set the Key Number to 0.
Subfunction 1: Extended File Information
For the file specified by the input Position Block, this subfunction returns information about the extension files associated with the specified data file. Returned information includes number of extension files that exist, number returned by the function, and file names for the returned files.
Input Data Buffer Structure
To receive information about extension files, you must create an extended files descriptor in the Data Buffer, as follows.
Table 2-23 Extended Files Descriptor
|
Element
|
Length (in Bytes)
|
Description
|
|
Signature
|
4
|
Type of extended stat call. Specify the following 4 bytes to indicate an Extended Stat Call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.
|
|
Subfunction
|
4
|
Type of extended stat call. Specify 0x00000001.
|
|
Namespace
|
4
|
File naming convention. Specify 0x00000000.
|
|
Max Files
|
4
|
Maximum number of filenames to return. You can set this value higher than the number of extension files composing the extended file. (An extended file can contain up to 32 extension files.)
|
|
First File Sequence
|
4
|
Sequence number of the first filename to return. Specify 0 to begin with the base file, 1 to begin with the first extension file, and so on. If you specify a number higher than the number of extension files, the transactional interface returns Status Code 0 and no filenames.
|
|
Buffer space
|
n
|
Allow enough additional room for the return data. If you receive Status Code 22, re-try the operation with a larger data buffer size.
|
Output Data Buffer Structure
For the extended files subfunction, the transactional interface updates the value of the Data Buffer Length parameter and returns an extended files structure in the Data Buffer, as illustrated in Table 2-24.
Table 2-24 Extended Files Return Buffer
|
Element
|
Length (in Bytes)
|
Description
|
|
Number of Files
|
4
|
Number of operating system files that comprise the extended file.
|
|
Number of Extensions
|
4
|
Number of extension files returned.
|
|
Filename Portion (Repeated for each filename returned)
|
|
Length of Filename
|
4
|
Length of the extension filename.
|
|
Filename
|
n
|
Extension filename.
|
Subfunction 2: System Data Information
For the file specified by the input Position Block, this subfunction returns information about whether there is a system key defined on a file, and whether the file can be logged (transaction durable).
Input Data Buffer Structure
To receive information about a file's use of system data, you must create a system data descriptor in the Data Buffer, as follows.
Table 2-25 System Data Descriptor
|
Element
|
Length (in Bytes)
|
Description
|
|
Signature
|
4
|
Unique identifier for an extended stat call. Specify ExSt. See Table 2-23.
|
|
Subfunction
|
4
|
Type of extended stat call. Specify 0x00000002.
|
Output Data Buffer Structure
For the system data subfunction, the transactional interface returns a system data structure in the Data Buffer, as follows.
Table 2-26 System Data Return Buffer
|
Element
|
Length (in Bytes)
|
Description
|
|
Has System Data
|
1
|
Indicates whether the file's records contain a system-defined log key (also called system data). 1 = Yes and 0 = No.
|
|
Has Log Key
|
1
|
Indicates whether the system-defined log key is currently being used, as opposed to being dropped.
1 = Yes and 0 = No (dropped).
|
|
Is Loggable
|
1
|
Indicates whether the file has a unique key that can be used to implement transaction durability. This key can be either a user-defined unique key or a system-defined log key. 1 = Yes and 0 = No.
|
|
Log Key Number
|
1
|
Key number that the transactional interface is currently using as the transaction log key. If the system-defined log key is being used as the transaction log key, this value is 125.
|
|
Size of System Data
|
2
|
Size of the system-defined log key, which is 8.
|
|
System Data Version
|
2
|
Major version in byte 7, minor version in byte 8 - (0x0007).
|
Subfunction 3: Duplicate Record Conflict Information
For the file specified by the input Position Block, this subfunction returns information about the extension files associated with the specified data file. Returned information includes the record address and key number that caused a Status Code 5 (Duplicate Key) on a previous failed insert or update operation.
Input Data Buffer Structure
To receive information about the record address and key number that caused the most recent Status Code 5 (Duplicate Key), you must create a duplicate record information descriptor in the Data Buffer, as follows.
Table 2-27 Duplicate Record Conflict Descriptor
|
Element
|
Length (in Bytes)
|
Description
|
|
Signature
|
4
|
Unique identifier for an extended stat call. Specify ExSt. See Table 2-23.
|
|
Subfunction
|
4
|
Type of extended stat call. Specify 0x00000003.
|
Output Data Buffer Structure
For the system data subfunction, the transactional interface returns a system data structure in the Data Buffer, as follows.
Table 2-28 Duplicate Record Conflict Return Buffer
|
Element
|
Length (in Bytes)
|
Description
|
|
Duplicate Record Address
|
4
|
Physical address of record containing the duplicate key value.
|
|
Key Number
|
4
|
Key number of the key containing the duplicate value.
|
Subfunction 4: File Information
For the file specified by the input Position Block, this subfunction returns information about the extension files associated with the specified data file. Returned information includes: the internal file ID used by the transactional interface to identify the file, the number of file handles currently open, the timestamp of the last time the file was opened, and a variety of flags indicating file properties.
Input Data Buffer Structure
To receive information about an open file, you must create a file information descriptor in the Data Buffer, as follows.
Table 2-29 File Information Descriptor - Open File
|
Element
|
Length (in Bytes)
|
Description
|
|
Signature
|
4
|
Unique identifier for an extended stat call. Specify ExSt. See Table 2-23.
|
|
Subfunction
|
4
|
Type of extended stat call. Specify 0x00000004.
|
|
Buffer space
|
12
|
|
Output Data Buffer Structure
For the file information subfunction, the transactional interface returns a file information structure in the Data Buffer, as follows.
Table 2-30 File Information Structure - Open File
|
Element
|
Length (in Bytes)
|
Description
|
|
FileID
|
4
|
A unique number which the transactional interface uses to identify the file.
|
|
NumberOfHandles
|
4
|
The current number of handles that the transactional interface has open on this file.
|
|
OpenTimeStamp
|
4
|
The system time when the file was last opened by the transactional interface.
|
|
FileUsageCount
|
4
|
This number gets incremented at each checkpoint or System Transaction. It is also the usage count placed in the FCR. The number returned here is the usage count of the file as it is represented in the transactional interface cache. When a checkpoint starts, this number gets incremented.
|
|
Flags
|
4
|
A four-byte bitmap in which various values may be set. See the table below for descriptions of the possible values. More flags may be added in the future.
|
The permitted values for the Flags field are described in the tables below.
Table 2-31 File Information Flags
|
Value
|
Name
|
Description
|
|
0x00000001
|
Explicit Locks
|
There are explicit locks currently on the file.
|
|
0x00000002
|
Client Transactions
|
There is at least one client transaction currently open on the file.
|
|
0x00000004
|
Read Only
|
The file was opened by the transactional interface as ReadOnly. This may be a CD-ROM drive or a read-only directory.
|
|
0x00000008
|
Continuous Operations
|
The file is currently in continuous operations.
|
|
0x00000010
|
Referential Integrity
|
The file has referential integrity constraints on it.
|
|
0x00000020
|
Owner Read/Write
|
The file has a Read/Write Owner name assigned to it. The owner name is required to read from or write to the file.
|
|
0x00000040
|
Owner Reads OK
|
The file has an owner name that is required only to write to the file. Reads can be done without an owner name.
|
|
0x00000080
|
Opened with Wrong Owner
|
The file has a Reads-OK Owner name assigned to it and the handle was opened with the wrong owner name.
|
|
0x00000100
|
Owner Encryption
|
The file has the encryption flag on the owner name. This flag means that every page in the file is encrypted and cannot be read using a text editor.
|
Subfunction 5: Gateway Information
For the file specified by the input Position Block, this subfunction returns information about the Gateway engine that has control of the file.
Input Data Buffer Structure
To receive information about the Gateway engine that is responsible for the specified file, you must create a gateway information descriptor in the Data Buffer, as follows.
Table 2-32 Gateway Information Descriptor
|
Element
|
Length (in Bytes)
|
Description
|
|
Signature
|
4
|
Unique identifier for an extended stat call. Specify ExSt. See Table 2-23.
|
|
Subfunction
|
4
|
Type of extended stat call. Specify 0x00000005.
|
|
Buffer space
|
at least 80
|
|
Output Data Buffer Structure
For the gateway information subfunction, the transactional interface modifies the Data Buffer Length parameter and returns a file information structure in the Data Buffer, as follows.
Table 2-33 File Information Structure - Gateway Information
|
Element
|
Length (in Bytes)
|
Description
|
|
Major Version
|
4
|
The major version of the engine, such as version 7 or 8.
|
|
Minor Version
|
4
|
The minor version of the engine, such as 05 or 82.
|
|
Patch Level
|
4
|
The patch level of the engine, such as 1, 2, or 3.
|
|
Platform
|
4
|
The operating system platform the engine is running on.
|
|
Server Name
|
64
|
A null-terminated string indicating the name of the machine where the database engine is running. The Data Buffer Length returned by the Btrieve API call contains the actual length of the data returned, including the server name and the null terminator.
|
Subfunction 6: Lock Owner Identification
For the file specified by the input Position Block, this subfunction returns information about the cause of the most recent Status Code 84 or 85 that occurred when accessing the file.
Input Data Buffer Structure
To receive information about the cause of a Status Code 84 or 85, you must create a lock owner information descriptor in the Data Buffer, as follows.
Table 2-34 Lock Owner Information Descriptor
|
Element
|
Length (in Bytes)
|
Description
|
|
Signature
|
4
|
Unique identifier for an extended stat call. Specify ExSt. See Table 2-23.
|
|
Subfunction
|
4
|
Type of extended stat call. Specify 0x00000006.
|
|
Buffer space
|
at least 96
|
Additional bytes needed for returned information. See Result for details.
|
Output Data Buffer Structure
For the lock owner information subfunction, the transactional interface modifies the Data Buffer Length parameter and returns a file information structure in the Data Buffer, as follows.
Table 2-35 Lock Owner Information Return Buffer
|
Element
|
Length (in Bytes)
|
Description
|
|
Client ID
|
16
|
The 16-byte client ID of the blocking client.
|
|
Flags
|
4
|
A four-byte bitmap containing flags indicating the type of conflict that occurred. See the table below for a description of each flag value.
|
|
Time In Transaction
|
4
|
Number of milliseconds in which the blocking client has been in a transaction. This can be helpful in determining whether to retry the operation.
|
|
Key Number
|
4
|
If the conflict occurred on a key page, this element indicates which key is involved. Tracking this information can be useful in designing a database with fewer potential conflicts.
|
|
Transaction Level
|
4
|
If this number is non-zero, then the blocking client is currently in a transaction. Since some page and record locks are held until the transaction completes, this information might be useful in determining if the operation should be retried.
|
|
Reserved
|
8
|
Reserved for future use. If there is some information about the blocking client which you think may be useful, please contact Pervasive Software.
|
|
Display Name
|
64
|
This is a null-terminated string which is the same identifying name that is displayed in Monitor for each client. Use at least 64 bytes since that is the current maximum display name length. The Data Buffer Length returned by the Btrieve API call contains the actual length of the data returned, including the display name and the null terminator.
|
If there is no record in the transactional interface of a previous blocking client, then the output data buffer length is set to zero.
The permitted values for the Flags field are described in the table below.
Table 2-36 Lock Owner Flags
|
Value
|
Name
|
Description
|
|
0x00000001
|
Implicit Lock
|
The blocking client is using an implicit lock.
|
|
0x00000002
|
Explicit Lock
|
The blocking client is using an explicit lock.
|
|
0x00000010
|
File Lock
|
The blocking client is using a file lock.
|
|
0x00000020
|
Page Lock
|
The blocking client is using a page lock.
|
|
0x00000040
|
Record Lock
|
The blocking client is using a record lock.
|
|
0x00000100
|
Data Page
|
If the conflict was a Page Lock, this flag indicates the conflict occurred on a data page.
|
|
0x00000200
|
Key Page
|
If the conflict was a Page Lock, this flag indicates the conflict occurred on a key page.
|
|
0x00000400
|
Variable Page
|
If the conflict was a Page Lock, this flag indicates the conflict occurred on a variable page.
|
|
0x00000800
|
Same Process
|
If this flag is set, then the first 12 bytes of the blocking client ID are the same as the first 12 bytes of the client that got blocked, that is, the client that is issuing the Stat Extended call. In this case, it means that the two blocking clients came from the same process on the same computer. If you have a single threaded application making Btrieve API calls, then retrying this operation will not help. You need to complete or abort the work that is blocking.
|
|
0x00001000
|
Write No Wait
|
Indicates that the blocking client is using the 500 bias.
|
|
0x00002000
|
Write Hold
|
Indicates that the blocking client made a change to a page that caused that client to keep the full page lock until its transaction completes. This situation can occur on implicit key page locks when a change causes key entries to move to another page.
|
|
0x00004000
|
Read No Wait
|
For explicit record locks, this flag indicates that the blocking client is using either lock bias 200 or 400.
|
|
0x00008000
|
Read Multiple
|
For explicit record locks, this flag indicates that the blocking client is using either lock bias 300 or 400.
|
Result
If the Stat Extended operation is unsuccessful, the transactional interface returns one of the following status codes:
|
3
|
The file is not open.
|
|
06
|
The key number parameter is invalid.
|
|
22
|
The data buffer parameter is too short.
|
|
62
|
The descriptor is incorrect.
|
