Stat Extended (65)

Additional bytes needed for returned information. See Output Data Buffer Structure. For the file information subfunction, the transactional interface returns a file information structure in the Data Buffer.

Output Data Buffer Structure

For the file information subfunction, the transactional interface returns a file information structure in the Data Buffer, as follows.

Table 37

File Information Structure - Open File

A unique number which the transactional interface uses to identify the file.

NumberOfHandles

The current number of handles that the transactional interface has open on this file.

OpenTimeStamp

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

FileUsageCount

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 transactional interface cache. When a checkpoint starts, this number increments.

Flags

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 38

File Information Flags

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 Read Only. 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 39

Gateway Information Descriptor

Unique identifier for an extended stat call. Specify ExSt. See Table 30.

Subfunction

Type of extended stat call. Specify 0x00000005.

Buffer space

at least 80

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

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 40

File Information Structure - Gateway Information

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

Minor Version

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

Patch Level

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

Platform

The operating system platform the engine is running on.

Server Name

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 41

Lock Owner Information Descriptor

Unique identifier for an extended stat call. Specify ExSt. See Table 30.

Subfunction

Type of extended stat call. Specify 0x00000006.

Buffer space

at least 96

Additional bytes needed for returned information. See Subfunction 7: Security Information 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 42

Lock Owner Information Return Buffer

The 16-byte client ID of the blocking client.

Flags

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

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

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 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

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

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 43

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.

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 44

Security Information Descriptor

Type of extended stat call. Specify 0x45785374. (This is equivalent to ASCII ExSt.)

Signature

Type of extended stat call. Specify 0x00000007.

Buffer Space

at least 142

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 45

Security Information Return Buffer

A four-byte bitmap containing flags indicating the methods used for security on this handle. See the table below 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 table below for a description of each flag value.

Permissions

These are the permissions granted to the client using this handle. See the permission table below 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 Pervasive 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

Variable

The database name used to establish security for this handle.

Handle Table Name

Variable

The table name associated with this handle

Handle User Name

Variable

The user name used to establish security for this handle.

Current Database Name

Variable

The current default database name for this client.

Current User Name

Variable

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

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

Table 46

This handle is trusted, no database is assigned.

0x00000002

Implicit

Database Login is Implicit - during the Open.

0x00000004

Explicit

Database Login is Explicit - a Btrieve Login was made.

0x00000008

Authentication by Database

Authentication was done by Database Security. If not set, Authentication was done using Operating System Security.

0x00000010

Authorization by Database

Authorization was done by Database Security. If not set, Authorization was done using Operating System Security.

0x00000020

Windows Named Pipe

If Authentication is by the Operating System, this indicates that an NT Named Pipe connection was used for security.

0x00000040

Workgroup

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.

0x00000080

Btpasswd

If Authentication is by the Linux Operating System, this indicates that etc/btpasswd file was used.

0x00000100

PAM

If Authentication is by the Linux Operating System, this indicates that PAM authentication was used.

0x00000200

RTSS Complete

If Authentication is by the Operating System, this indicates that authentication was done using RTSS with the Complete setting.

0x00000400

RTSS Preauthorized

If Authentication is by the Operating System, this indicates that authentication was done using RTSS with the Preauthorized setting.

0x00000800

RTSS Disabled

If Authentication is by the Operating System, this indicates that authentication was done using RTSS with the Disabled setting.

Table 47

No rights to the database object. No permission granted.

0x00000001

Open

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

0x00000002

Insert

Permission granted to Insert records.

0x00000004

Update

Permission granted to Update records.

0x00000008

Create

Permission granted to Create this file.

0x00000010

Delete

Permission granted to Delete records.

0x00000020

Execute

Permission granted to Execute Stored Procedures in SQL.

0x00000040

Alter

Permission granted to Alter this file in SQL.

0x00000080

Refer

Permission granted to Refer to this file in SQL.

0x00000100

Create View

Permission granted to Create Views to this file in SQL.

0x00000200

Create Stored Procedure

Permission granted to Create Stored Procedures for this file in SQL.

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.