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.


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

2

Pass the position block for the file.

3

Indicate a data buffer to hold the statistics defined for the file.

4

Specify the data buffer length, which must be long enough to hold the file statistics. (For more information, see Table 28 and Table 29.)

5

Specify a key buffer that is at least 255 characters long.

6

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

•

Specify -1 (0xFF) to include file version and unused duplicate pointers information. Parse the returned data buffer as shown in Table 29.

The MicroKernel Engine 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 Engine 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 Engine returns Stat information as shown in the following table.

Table 28

Data Buffer Excluding File Version Information

File Specification

Number of indexes

Number of records

Key Specification (repeated for each segment)

Number of unique key values

Extended data type

Key Specification (repeated for each segment) continued

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

Table 29

Data Buffer Including File Version Information

File Specification

Number of indexes

File version number

Number of records

Number of unused duplicate pointers

Key Specifications (repeated for each key segment)

Number of unique key values

Extended data type

(last member of Key Specification, end of repeated elements)

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 Engine 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 Engine 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 10, 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, nonduplicated value for the specified key.

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

If the Stat operation is successful, the MicroKernel Engine 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 Engine returns the file name of the first extension file in the key buffer. If the file name of the first extension file is longer than 63 bytes, the MicroKernel Engine truncates the file name. If the file is not an extended file, the MicroKernel Engine 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 Engine returns one of the following status codes:


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

The Stat operation has no effect on positioning.