Stat (15)

The Stat operation (B_STAT) retrieves the defined characteristics of a file and statistics about the file's contents, such as the number of records in the file, the number of unique key values stored for each index in the file, and the number of unused pages in the file.

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

Pass the Position Block for the file.

Indicate a Data Buffer to hold the statistics defined for the file.

Specify the Data Buffer Length, which must be long enough to hold the file statistics. (For more information, see Table 2-20 and Table 2-21.)

Specify a Key Buffer that is at least 255 characters long.

Set the Key Number as follows:

Specify 0 to exclude file version and unused duplicate pointers information. Parse the returned Data Buffer as shown in Table 2-20.

Specify -1 (0xFF) to include file version and unused duplicate pointers information. Parse the returned Data Buffer as shown in Table 2-21.

Details

The MicroKernel returns information about all keys in the file, including those added since file creation. The key information includes any applicable ACS definitions. You must account for this extra information in the Data Buffer. Specifically, do not use the same Data Buffer here that you used for the Create (0) operation.

Because the MicroKernel allows up to 119 keys and multiple ACSs in a file, the longest possible Data Buffer is 33,455 bytes (that is, 16 + (11 * 16) + (119 * 265)). However, you probably do not need such a large data buffer. In fact, you may prefer to specify a smaller Data Buffer if you want only certain information. For example, you could set the Data Buffer Length to 1920 bytes (that is, 16 + (16 * 119)). In effect, such a setting returns all key information but not necessarily all the ACSs. If your application does not need information about the ACSs, you might prefer this method.

If you specify a value of 0 in the Key Number parameter, the MicroKernel returns Stat information as shown in the following table.

Table 2-20 Data Buffer Excluding File Version Information
Element	Description	Length (in Bytes)
File Specification	Record Length	2
	Page Size	2
	Number of Indexes	2
	Number of Records	4
	File Flags	2
	Reserved Word	2
	Unused Pages	2
Key Specification (repeated for each segment)	Key Position	2
	Key Length	2
	Key Flags	2
	Number of Unique Key Values	4
	Extended Data Type	1
Key Specification (repeated for each segment) continued	Null Value	1
	Reserved	2
	Key Number	1
	ACS Number	1
ACS Number 0	ACS	265
. . .	. . .	. . .


ACS Number x	ACS	265

If you specify a value of -1 in the Key Number parameter, the MicroKernel returns Stat information as shown in the following table.

Table 2-21 Data Buffer Including File Version Information
Element	Description	Length (in Bytes)
File Specification	Record Length	2
	Page Size	2
	Number of Indexes	1
	File Version Number	1
	Number of Records	4
	File Flags	2
	Number of Unused Duplicate Pointers	1
	Reserved Byte	1
	Unused Pages	2
Key Specifications (repeated for each key segment)	Key Position	2
	Key Length	2
	Key Flags	2
	Number of Unique Key Values	4
	Extended Data Type	1
	Null Value	1
	Reserved	2
	Key Number	1
(last member of Key Specification, end of repeated elements)	ACS Number	1
ACS Number 0	ACS	265
. . .	. . .	. . .
ACS Number x	ACS	265

File Specifications

The File Specification fields in the returned Data Buffer are the same as those described for Create (14), with the following exceptions:

In the File Specification area:

If the Data Buffer includes file version information, the Number of Indexes is 1 byte long and is followed by a 1-byte File Version Number. Do not translate the File Version Number value to decimal. A value of 0x70 indicates that the file is a 7.0 file; a value of 0x60 indicates that the file is 6.x, and so on. When creating a file, the MicroKernel assigns a version number according to the attributes defined for the file.

The Number of Records is a 4-byte value representing the number of records in the file.

In the File Flags word, Bits 9 and 12 have the following meaning:


Bit 9 = 1 and Bit 12 = 0	File was created with system data. (This does not necessarily mean that the system-defined log key is currently in use; it may have been dropped.)
Bit 9 = 1 and Bit 12 = 1	File was created without system data.

Stat does not indicate whether system data was included by default or explicitly.

If the Data Buffer includes file version information, a 1-byte Number of Unused Duplicate Pointers follows the File Flags field and indicates how many unused duplicate pointers remain in the file.

The reserved areas are allocated even though the MicroKernel ignores them on a Stat operation.

Key Specifications

The Key Specification fields in the returned Data Buffer are the same as those described in Table 2-3, except that a 4-byte Number of Unique Key Values follows the Key Flags field and indicates the number of records that have a unique, non-duplicated value for the specified key.

ACSs

The ACS definitions in the returned Data Buffer are the same as those described for Create (14).

Result

If the Stat operation is successful, the MicroKernel returns the file and key characteristics to the Data Buffer and the length of the Data Buffer in the Data Buffer Length. If the file is an extended file, the MicroKernel returns the filename of the first extension file in the Key Buffer. If the filename of the first extension file is longer than 63 bytes, the MicroKernel truncates the filename. If the file is not an extended file, the MicroKernel initializes the first byte of the Key Buffer to 0. (You can use the Stat Extended operation to retrieve statistics regarding extended files.)

If the Stat operation is unsuccessful, the MicroKernel returns one of the following status codes:


3	The file is not open.
22	The data buffer parameter is too short.

Positioning

The Stat operation has no effect on positioning.