Stat Extended (65)

Stat Extended (65)

The Stat Extended operation (B_EXTENDED_STAT) has several subfunctions that allow an application to gather information about an open file.

Table 30

Stat Extended (65) Subfunctions

Listing of extension file names

System Data information for the file

Duplicate conflict record and key identification

File information

Gateway identification

Lock owner identification

Security information

Listing of table or file name causing a status code 71 (a violation of the referential integrity definitions)

See the following subfunction topics for more information on each one.


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

The file must be open.

1

Set the operation code to 65.

2

Pass the position block for the given file.

3

Store the stat extended structure in the data buffer. See the subsections below for more information about the stat extended structure required for each subfunction.

4

Specify the data buffer length.

5

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 31

Extended Files Descriptor

Type of stat extended call. Specify the following 4 bytes to indicate a stat extended call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.

Type of stat extended call. Specify 0x00000001.

File naming convention. Specify 0x00000000.

Maximum number of file names 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

Sequence number of the first file name 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 MicroKernel Engine returns Status Code 0 and no file names.

Allow enough additional room for the return data. If you receive Status Code 22, retry the operation with a larger data buffer size.

Output Data Buffer Structure

For the extended files subfunction, the MicroKernel Engine updates the value of the data buffer length parameter and returns an extended files structure in the data buffer, as illustrated in Table 32.

Table 32

Extended Files Return Buffer

Number of Files

Number of operating system files that comprise the extended file.

Number of Extensions

Number of extension files returned.

File Name Portion (Repeated for each file name returned)

Length of File Name

Length of the extension file name.

Extension file name.

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 33

System Data Descriptor

Type of stat extended call. Specify the following 4 bytes to indicate a stat extended call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.

Type of stat extended call. Specify 0x00000002.

Output Data Buffer Structure

For the system data subfunction, the MicroKernel Engine returns a system data structure in the data buffer, as follows.

Table 34

System Data Return Buffer

Has System Data

Indicates whether the file’s records contain a system-defined log key (also called system data). 1 = Yes and 0 = No.

Indicates whether the system-defined log key is currently being used, as opposed to being dropped.
1 = Yes and 0 = No (dropped).

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.

Key number that the MicroKernel Engine 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

Size of the system-defined log key, which is 8.

System Data Version

A two-byte field that contains the major version of the database engine. For example, 0x0009 for version 9.x and 0x000a for version 10.x.

Subfunction 3: Duplicate Record Conflict Information

For the file specified by the input position block, this subfunction returns information about duplicate record conflicts. 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 35

Duplicate Record Conflict Descriptor

Type of stat extended call. Specify the following 4 bytes to indicate a stat extended call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.

Type of stat extended call. Specify 0x00000003.

Output Data Buffer Structure

For the system data subfunction, the MicroKernel Engine returns a system data structure in the data buffer, as follows.

Table 36

Duplicate Record Conflict Return Buffer

Duplicate Record Address

Physical address of record containing the duplicate key value.

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 file information. Returned information includes: the internal file ID used by the MicroKernel Engine 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 37

File Information Descriptor - Open File

Type of stat extended call. Specify the following 4 bytes to indicate a stat extended call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.

Type of stat extended call. Specify 0x00000004.

Additional bytes needed for returned information. See Output Data Buffer Structure. For the file information subfunction, the MicroKernel Engine returns a file information structure in the data buffer.

Output Data Buffer Structure

For the file information subfunction, the MicroKernel Engine returns a file information structure in the data buffer, as follows.

Table 38

File Information Structure - Open File

A unique number which the MicroKernel Engine uses to identify the file.

Number of Handles

The current number of handles that the MicroKernel Engine has open on this file.

Open Time Stamp

The system time when the physical file was last opened by the MicroKernel Engine. This system time is expressed as the number of seconds since midnight on January 1, 1970 in coordinated universal time (UTC) time.

File Usage Count

This number increments 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 MicroKernel Engine cache. When a checkpoint starts, this number increments.

A four-byte bitmap in which various values may be set. See the following table 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 following tables.

Table 39

File Information Flags

There are explicit locks currently on the file.

Client Transactions

There is at least one client transaction currently open on the file.

The file was opened by the MicroKernel Engine as Read Only. This may be a CD-ROM drive or a read-only directory.

Continuous Operations

The file is currently in continuous operations.

Referential Integrity

The file has referential integrity constraints on it.

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.

The file has an owner name that is required only to write to the file. Reads can be done without an owner name.

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.

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 40

Gateway Information Descriptor

Type of stat extended call. Specify the following 4 bytes to indicate a stat extended call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.

Type of stat extended call. Specify 0x00000005.

Additional bytes needed for returned information. See Output Data Buffer Structure for details.

Output Data Buffer Structure

For the gateway information subfunction, the MicroKernel Engine modifies the data buffer length parameter and returns a file information structure in the data buffer, as follows.

Table 41

File Information Structure - Gateway Information

The major version of the engine, such as version 7 or 8.

The minor version of the engine, such as 05 or 82.

The patch level of the engine, such as 1, 2, or 3.

The operating system platform the engine is running on.

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 42

Lock Owner Information Descriptor

Unique identifier for a stat extended call. Specify ExSt. See Table 31.

Type of stat extended call. Specify 0x00000006.

Additional bytes needed for returned information. See Subfunction 7: Security Information for details.

Output Data Buffer Structure

For the lock owner information subfunction, the MicroKernel Engine modifies the data buffer length parameter and returns a file information structure in the data buffer, as follows.

Table 43

Lock Owner Information Return Buffer

The 16-byte client ID of the blocking client.

A four-byte bitmap containing flags indicating the type of conflict that occurred. See the following table for a description of each flag value.

Time In Transaction

Number of milliseconds in which the blocking client has been in a transaction. This can be helpful in determining whether to retry the operation.

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

If this number is nonzero, 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 for future use. If there is some information about the blocking client which you think may be useful, please contact PSQL Support.

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 MicroKernel Engine 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 following table.

Table 44

Lock Owner Flags

The blocking client is using an implicit lock.

The blocking client is using an explicit lock.

The blocking client is using a file lock.

The blocking client is using a page lock.

The blocking client is using a record lock.

If the conflict was a Page Lock, this flag indicates the conflict occurred on a data page.

If the conflict was a Page Lock, this flag indicates the conflict occurred on a key page.

If the conflict was a Page Lock, this flag indicates the conflict occurred on a variable page.

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.

Indicates that the blocking client is using the 500 bias.

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.

For explicit record locks, this flag indicates that the blocking client is using either lock bias 200 or 400.

For explicit record locks, this flag indicates that the blocking client is using either lock bias 300 or 400.

Subfunction 7: Security Information

This subfunction returns information about how the client was Authenticated and Authorized to access the current file. It also shows information about the Current Database being used for Security.

Input Data Buffer Structure

To receive Security information about how this handle is Authenticated what permissions it has, you must create a security information descriptor in the data buffer, as follows.

Table 45

Security Information Descriptor

Type of stat extended call. Specify the following 4 bytes to indicate a stat extended call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.

Type of stat extended call. Specify 0x00000007.

Additional bytes needed for returned information. See Result for details.

Output Data Buffer Structure

For the security information subfunction, the MicroKernel modifies the data buffer length parameter and returns a file information structure in the data buffer, as follows.

Table 46

Security Information Return Buffer

Flags for Handle

A four-byte bitmap containing flags indicating the methods used for security on this handle. See the following table for a description of each flag value.

Flags for Handle

A four-byte bitmap containing flags indicating the methods used for security on the current default database for this client. See the following table for a description of each flag value.

These are the permissions granted to the client using this handle. See the permission following table for a description of each flag value.

Buffer Size for Handle Database Name

Length of the buffer used to store the null terminated Handle Database Name string.

Buffer Size for Handle Table Name

Length of the buffer used to store the null terminated Handle Table Name string. Note: The table name will not be known unless the file is bound to a database (Referential Constraints, for example), or the file was opened using a URI connection string that referred to the file by its Table Name. For details about URI connection strings, see Database URIs in PSQL Programmer's Guide.

Buffer Size for Handle User Name

Length of the buffer used to store the null terminated Handle User Name string.

Buffer Size for Current Database Name

Length of the buffer used to store the null terminated Current Database Name string.

Buffer Size for Current User Name

Length of the buffer used to store the null terminated Current User Name string.

Handle Database Name

The database name used to establish security for this handle.

Handle Table Name

The table name associated with this handle

Handle User Name

The user name used to establish security for this handle.

Current Database Name

The current default database name for this client.

Current User Name

The user name associated with the current default database for this client.

The permitted values for the two Flags fields are described in the following tables.

Table 47

This handle is trusted, no database is assigned.

Database login is implicit - during the open.

Database login is explicit - a Btrieve login was made.

Authentication by Database

Authentication was done by database security. If not set, authentication was done using operating system security.

Authorization by Database

Authorization was done by database security. If not set, authorization was done using operating system security.

Windows Named Pipe

If authentication is by the operating system, this indicates that an NT named pipe connection was used for security.

If authentication is by the operating system, this indicates that Workgroup Engine style security was done, which means that no authentication or authorization was done.

If authentication is by a Linux or OS X operating system, this indicates that etc/btpasswd file was used.

If authentication is by the Linux or OS X operating system, this indicates that PAM authentication was used.

If authentication is by the operating system, this indicates that authentication was done using RTSS with the Complete setting.

RTSS Preauthorized

If authentication is by the operating system, this indicates that authentication was done using RTSS with the Preauthorized setting.

If authentication is by the operating system, this indicates that authentication was done using RTSS with the Disabled setting.

Table 48

Permission Flags

No rights to the database object. No permission granted.

Permission granted to open the file. This also implies that the records can be read.

Permission granted to insert records.

Permission granted to update records.

Permission granted to create this file.

Permission granted to delete records.

Permission granted to execute stored procedures in SQL.

Permission granted to alter this file in SQL.

Permission granted to refer to this file in SQL.

Permission granted to create views to this file in SQL.

Create Stored Procedure

Permission granted to create stored procedures for this file in SQL.

Subfunction 8: Listing of Table or File Name Causing a Status Code 71

This subfunction returns information on the table or data file that caused a status code 71, a violation of the referential integrity definitions. Returned information includes the file name, Btrieve operation code, and position of the record that caused the referential integrity error.

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 49

Listing of Table or File Name Descriptor

Type of stat extended call. Specify the following 4 bytes to indicate a stat extended call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware.

Type of stat extended call. Specify 0x00000008.

Output Data Buffer Structure

For the file information subfunction, the MicroKernel Engine returns a file information structure in the data buffer, as follows. The data buffer supplied must be large enough to hold the data returned.

Table 50

Table or File Information Structure

File name causing the RI error.

Btrieve Op Code

Btrieve operation code that caused the RI error.

Record Position

Physical record position of the record that caused the RI error.

If the Stat Extended operation is unsuccessful, the MicroKernel Engine 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.