The following topics are covered here:

Zen provides both an interactive Maintenance GUI and a command line Maintenance tool. Both versions perform the following file and data manipulations:

While both utilities provide the same core functionality, minor differences exist. For example, the interactive Maintenance tool allows you to create description files based on file and key specifications you define. The command line Maintenance tool allows you to start and stop continuous operation on a file or set of files locally on the server.

Before you use either Maintenance tool, you should be familiar with Btrieve fundamentals, such as files, records, keys, and segments. For information about these topics, see Zen Programmer’s Guide.

The interactive Maintenance tool is a Windows application that runs on Windows 32-bit and 64-bit platforms. Use it if you prefer a graphical user interface or if you want to create a description file. This section contains the following major topics:

Each major topic contains tasks specific to that topic.

The size of a MicroKernel data file can be larger than the operating system file size limit. When you export data from an extended MicroKernel file to an unformatted file, the size of the unformatted file can exceed the database engine file size limit because of the differences in the physical format.

When you are exporting large files, the interactive Maintenance tool detects when the unformatted file exceeds a 2 GB file size limit and starts creating extension files. This process is transparent. Extension files and the original unformatted file must reside on the same volume. Note that file size limit varies depending on the operating system and file system. The 2 GB size is the limit supported by the database engine.

The extension file uses a naming scheme in which the file names are similar to the base file name. In contrast to native MicroKernel Engine extension files which use a caret “^” to indicate extension file status, the unformatted extension files use a tilde “~” to avoid overwriting any existing extended engine files with the same base file name. The first export extension file is the same base file name with “.~01” extension. The second extension file is “.~02” and so on. These extensions are appended in hexadecimal format.

The naming convention supports up to 255 extension files, thus supporting files as large as 256 GB.

Additionally, when you import data from an unformatted file, the tool detects whether the file has extensions and loads the data from the extension file.

Long file name support, including support for embedded spaces is available in all supported operating system environments. All references to files can contain embedded spaces and be longer than 8 bytes.

Older versions of Btrieve allowed spaces to be added at the end of a file name in path-based operations such as Open and Create. This is still the default behavior. Existing applications will not break. However, if you want to take advantage of file and directory names with embedded spaces, set the Embedded Spaces configuration setting for the client requester to On. Note that On is the default setting.

Even when you turn off the option, an application that accesses a file having a name with embedded spaces can enclose that name in double quotation marks while making the BTRV/BTRVID/BTRCALL/BTRCALLID call to open or create the file.

Zen provides two types of data compression: record and page. These two types may be used separately or together. The primary purpose for both compression types is to reduce the size of the data files and to provide faster performance depending on the type of data and on the type of data manipulation.

Record compression requires a file format of 6.0 or later. Record compression can result in a significant reduction of the space needed to store records that contain many repeating characters. The database engine compresses five or more of the same contiguous characters into 3 bytes.

When creating a file, the database engine automatically uses a page size larger than what is specified to allow room for the specified record length. If the uncompressed record length is too large to fit on the largest available page, the database engine automatically turns on record compression.

Because the final length of a compressed record cannot be determined until the record is written to the file, the database engine creates a file with record compression as a variable-length record file. Compressed images of the records are stored as variable-length records. Individual records may become fragmented across several file pages if your application performs frequent insertions, updates, and deletions. The fragmentation can result in slower access times because the database engine may need to read multiple file pages to retrieve a single record.

See also Choosing a Page Size, Estimating File Size, and Record Compression, all in Zen Programmer’s Guide.

Page compression requires a file format of 9.5 or later. Internally, a Zen data file is a series of different types of pages. Page compression controls the compression and decompression of data pages within a file.

As a file is read from physical storage, data pages are decompressed and held in a memory cache. Record reads and updates are performed against the uncompressed data in the memory cache. When a write action occurs, the data page is compressed then written to physical storage. Depending on cache management, the compressed page is also retained in memory until accessed again.

If the type of data cannot be significantly compressed, the database engine writes the data to physical storage uncompressed.

The benefits obtained by using record compression, page compression, or both depends entirely on the type of data being compressed. Given that, the following table discusses some general factors to consider when deciding to use data compression or not.

Access Maintenance from the operating system Start menu or Apps screen or from the Tools menu in Zen Control Center. The Maintenance main window looks like the following.

The interactive Maintenance tool provides the following menus:

To access the Maintenance tool help system, click Help in the dialog box for which you want help, or choose a command from the Help menu, as follows:

This section provides general information about the File Information Editor with which you can create new files based on file and key specifications you construct. Because this Editor allows you to load information based on an existing file, it is also useful for viewing file and key specifications on existing data files. You can also create a new file based on the file and key specifications of an existing file (similar to the clone command for butil, the command line Maintenance tool).

Open the File Information Editor by clicking Options > Show Information Editor.

At the top of the Editor, the following buttons appear:

The Data File Info area, also at the top of the File Information Editor, contains the following controls:

The File Specification area is in the middle of the File Information Editor. Table 68 describes the controls in this box.

At the bottom left in the dialog box is the Key group box. Table 69 describes the controls in this area. These controls are specific to the key highlighted in the Key list, not just to the current key segment. When you change the setting for one of these controls, the change affects all segments of the specified key.

At the bottom middle of the dialog box, the Key list shows the key numbers defined in a file. (For 6.x and later files, these key numbers do not have to be consecutive; they can have gaps between them.) The Maintenance tool displays the highlighted key’s specifications in the Key box at the bottom left of the dialog box.

Also at the bottom middle of the dialog box, the Segment list shows the key segment numbers defined for the key highlighted in the Key list. The Maintenance tool displays the highlighted segment’s specifications in the Segment box at the bottom right of the dialog box.

In addition, the following buttons appear under the Key and Segment lists:

Because these buttons control key specifications for a file you want to create, you cannot use them to operate on keys in an existing file. If you want to create or drop an index on an existing file, refer to Index Tasks.

At the bottom right in the dialog box is the Key Segment group box. Table 70 describes the controls in this area. These controls are specific to the segment highlighted in the Segment list),

Multiple records may carry the same duplicated value for index keys. The two methods to keep track of the records with duplicate key values are called linked duplicates and repeating duplicates.

The linked duplicates method uses a chain technique in which each record in the group connects to its neighbors by means of pointers. Each entry on an index page contains a pair of record pointers that indicate the first and last links in the chain of records that duplicate that key's value. This makes each key page entry 4 bytes longer than a repeating duplicates index. In addition, each record on the data page requires an extra 8 bytes of overhead for each linked duplicates index. These 8 bytes consist of two record pointers that point to the next and previous records in the chain.

The first record pointer holds the address of the first, or oldest, record stored. The second pointer holds the address of the most recent, or newest record. After the first record is written but before any others are added, both pointers on the key page entry hold the first record’s address. Subsequent records cause the second pointer to be changed to point to each record as it is added. This permits the record pointer for the last record to be used as the previous-record link of the chain built in the data page when the record is added, and also to be used to locate that previous record.

With the repeating duplicates method, each duplicate key value is stored on both the index page and within the record on the data page. Each key value has only one record pointer instead of two. This method requires no chaining within the data records and saves the 8 bytes of overhead per index within each record. Since the key value is repeated for each duplicate record, the indexes affected increase in size.

The linked duplicates and repeating duplicates methods can be compared based on the following criteria:

A linked duplicates index retrieves duplicates in the order in which they were inserted. A repeating duplicates index retrieves duplicates in the order in which they are located within the file. Since location with a file cannot be controlled, the ordering must be considered as random.

A linked duplicates index requires 12 more bytes for the first occurrence of each duplicate key value. That includes 8 extra bytes on each record and 4 extra bytes for the key page entry. But each duplicate record requires no additional space in the key page, and adds only 8 bytes per record. Therefore, as the number of duplicates per key value increases, and as the size of the key value increases, linked duplicate indexes can save significant storage space used by key pages. However, storage space can increase if your file contains very few records with duplicate keys, the key length is very short, or both.

The following figure exemplifies the amount of storage space saved using linked duplicate indexes. Note that linked duplicate indexes take more space if duplicate records per key value are few. As the number of duplicate records per key value increases, however, linked duplicate indexes require less pages, providing significant space savings.

Faster performance results when fewer pages are involved in an index search because fewer pages must be read from disk. The linked duplicates method generally uses less physical storage space and therefore provides faster performance. The repeating duplicates method provides a performance advantage if only a small number of keys have duplicates.

The database engine provides page-level concurrency when several concurrent transactions are active on the same file at the same time. This applies to most changes to key pages and for all changes to data pages. The concurrency means that the same page can contain pending changes from separate transactions at the same time, and the transactions can be committed in any order. Repeating duplicate indexes take the most advantage of this concurrency.

Linked duplicate indexes add another limitation on concurrency that does not exist with repeating duplicates. When a new duplicate is created, the new record is linked to another record at the end of the list. This record linking causes two records to be locked instead of one. Since all duplicates are added to the end of the chain of linked records, only one duplicate can be inserted at a time.

Such a record lock conflict usually causes other clients to wait until the first transaction is committed. In a concurrent environment, if all new records use the same duplicate value, then concurrency can effectively be reduced to one transaction at a time. And if transactions are large or long lasting, this serialization can affect performance tremendously.

Performance is typically better if you use repeating duplicate indexes for databases that are updated in a concurrent environment. Therefore, unless you have a compelling reason to use the linked duplicates method, you should use repeating duplicate indexes for databases that are updated in a concurrent environment.

You perform the following tasks with the File Information Editor:

When you load information from an existing file, you are not editing the existing file. Instead, you are loading a copy of the information about that file. Generally, you want to load a data file before performing other tasks with the File Information Editor, but this is not mandatory.

You can create a new file based on the current information in the File Information Editor or on new information you provide.

The comments are written to the top of the description file when you create the description file. For example, the comment, “This is my file,” appears at the top of the description files as /* This is my file */. If you add additional comments after creating the description file, you need to create the file again to include the additional comments.

You can compact a Btrieve data file to remove unused space in it, which typically decreases the file size. You can also perform this procedure using the command line Maintenance tool (see To compact a Btrieve data file).

You can use an alternate collating sequence (ACS) to sort string keys (types STRING, LSTRING, and ZSTRING) differently from the standard ASCII collating sequence. By using one or more collating sequences, you can sort keys as follows:

Files can have a different ACS for each key in the file, but only one ACS per key. Therefore, if the key is segmented, each segment must use either the key’s specified ACS or no ACS at all. For a file in which a key has an ACS designated for some segments but not for others, Btrieve sorts only the segments that specify the ACS.

The ISR tables are provided with Zen and are based on ISO-standard locale tables. ISR tables are stored in the collate.cfg file, which is installed with the Zen database engine. Multiple data files can share a single ISR.

The MicroKernel gives you the option of restricting access to an individual data file by setting an owner name in the file. Only users who provide the owner name are able to read from or write to the file. This topic covers use of the Maintenance tool to manage owner names. For more information, see Owner Names.

An ODBC error results if you attempt relational access of a table that is restricted by an owner name without providing that string value, such as trying to delete the table in ZenCC. You can specify owner names for one or more tables in a session with the GRANT or SET OWNER statement. Use the GRANT statement to authorize access for a particular user or group, and then manipulate the table relationally through ODBC. The Master user must supply the GRANT statement with the correct owner name. For more information, see GRANT in SQL Engine Reference.

Use SET OWNER to provide one or more owner names to enable file access during the current database session. For more information, see SET OWNER in SQL Engine Reference.

Setting an owner name restricts access to a data file. Clearing the owner name removes the restriction.

Generating a statistics report is a good way to determine whether a file can be logged by the database engine’s transaction durability feature. The report shows whether the file has system data and if a key is unique. (A unique key lacks the D flag, which indicates that duplicates are allowed.) The statistics report provides metadata about the file. This information can be used when you troubleshoot problems or to help you create similar files.

The following task lists the steps to create a statistics report.

An index is a structure that sorts all the key values for a specific key. Btrieve access permits overlapping indexes (an index that includes a partial column). Relational access through ODBC does not permit overlapping indexes. (You can create an overlapping index with the File Information Editor, which you can display by clicking the Goto Editor button.)

You perform the following tasks pertaining to indexes:

You cannot create an index for a file unless the file has at least one key defined. You can create a key with the File Information Editor (see File Information Editor).

Ensure that you understand the access performed by an application program before dropping an index. Certain functions fail (such as GET NEXT) if a required index is missing. This can result in an application program not functioning correctly.

The commands in the Data menu allow you to import, export, and copy records in data files. You can also recover data after a system failure with the Roll Forward feature. See Roll Forward Command for a discussion of Roll Forward.

When you save data, records in the ASCII file have the following format. You can use an ASCII text editor to create files that you can load, as long as they adhere to these specifications. Note that most text editors do not support editing binary data.

Figure 29 shows the correct format for records in the input ASCII file. For this example, the data file has a defined record length of 40 bytes.

You can perform the following data tasks with the Maintenance tool:

You can use the Maintenance tool to import records from an ASCII file to a standard data file. This operation does not perform any conversions on the data. You can create an import file using a text editor or the Maintenance tool (see Exporting Records to an ASCII File).

You can use the Maintenance tool to export records from a data file to an ASCII file.

You can use the Maintenance tool to copy data from one MicroKernel data file to another. The record lengths for both data files you specify must be the same.

See the Logging, Backup, and Restore.

Use butil if you prefer a command line interface or if you want to start or stop continuous operation. You can manually execute Maintenance commands at a command prompt or as an executable batch script. Before you run butil commands, we recommend you understand the concepts and syntax covered here.

The Btrieve command line Maintenance tool performs the following file and data manipulations:

When butil finishes executing, it returns an exit code or DOS error-level return code to the operating system. The return codes are shown in the following table.

The next table lists the commands used with butil. Links in the table lead to more detailed information.

To view a summary of each command usage, enter the butil command at a prompt on the file server.

The format for butil is as follows:

You can use a command file to do the following:

Command files contain the same information as that required on the command line.

Observe the following rules when creating a Maintenance tool command file:

The following is an example command file, copycrs.cmd. the file calls the butil - clone command to create the newcrs.mkd file by cloning the course.mkd file, and the -create command to create the newfile.dta file by using the description provided in the newfiles.des description file.

-clone newcrs.mkd course.mkd <end>
-create newfile.dta newfiles.des <end>

The following command uses the copypats.cmd file and writes the output to the copypats.out file:

butil @copypats.cmd copypats.out

Description files are ASCII files that contain descriptions of file and key specifications that the Maintenance tool can use to create data files and indexes. Some users employ description files as a vehicle for archiving information about the data files they have created. For more information about the description file format, see Description Files.

The size of the database engine data file can be larger than the operating system file size limit. When you export data from an extended MicroKernel file to an unformatted file, the size of the unformatted file can exceed the database engine file size limit because of the differences in the physical format.

When large files are exported, the Interactive Maintenance tool detects when an unformatted file has exceeded the operating system file size limit (2 GB) and starts creating extension files. This process is transparent. Extension files and the original unformatted file must reside on the same volume. The extension file uses a naming scheme in which the file names are similar to the base file name. In contrast to native MicroKernel Engine extension files which use a caret “^” to indicate extension file status, the unformatted extension files use a tilde “~” to avoid overwriting any existing extended MicroKernel Engine files with the same base file name. The first export extension file is the same base file name with “.~01” extension. The second extension file is “.~02,” and so on. These extensions are appended in hexadecimal format.

While the naming convention supports up to 255 extension files, the current maximum number of extension files is 64, thus supporting files as large as 128 GB.

To Save or Recover huge files to unformatted files, see the respective command. Also, when you import data from an unformatted file, the tool detects if the file has extensions and loads the data from the extension file.

The MicroKernel allows you to restrict access to individual files by specifying an owner name for the file. The owner name string is also used for encryption. For more information, see Owner Names.

Be sure that you specify a fully qualified file name, including a drive letter or UNC path, when redirecting error messages.

See Importing and Exporting ASCII File Format in the Interactive Maintenance tool section.

When you run butil on Windows, Linux, or macOS, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.

This topic provides detailed information on importing and exporting data using the following BUTIL commands: Copy, Load, Recover, and Save.

The copy command copies the contents of one MicroKernel file to another. Copy retrieves each record in the input data file and inserts it into the output data file. The record size must be the same in both files. After copying the records, copy displays the total number of records inserted into the new data file.

Using the copy command, you can create a data file that contains data from an old file, but has new key characteristics.

The following command copies the records in course.mkd to newcrs.mkd. the course.mkd input file does not require an owner name, but the newcrs.mkd output file uses the owner name Pam.

butil -copy course.mkd newcrs.mkd /O /OPam

If you omit the first /O from this example, the tool assumes that the owner name Pam belongs to the input data file, not the output data file.

When copying a file requires an owner name for both the original file and the copied file, the -copy option specifies both owner names, as shown in this example:

butil -copy originalFile copiedFile /Od3ltagamm@ /OV3rs10nXIII

The first owner name d3ltagamm@ is required to open originalFile. The second owner name V3rs10nXIII is used to create copiedFile.

If the owner names are provided interactively, the command resembles the following example:

butil -copy originalFile copiedFile /PROMPT /PROMPT

Upon execution, the user is first prompted to enter the owner name to access originalFile. Once that file is open, the user is prompted for the owner name to assign to copiedFile.

The load command inserts records from an input ASCII file into a file. The input ASCII file can be a single file or an extended file (the base file plus several extension files). Load performs no conversion on the data in the input ASCII file. After the tool transfers the records to the data file, it displays the total number of records loaded.

Before running the load command, you must create the input ASCII file and the data file. You can create the input ASCII file using a standard text editor or an application. The input ASCII file must have the required file format (see Importing and Exporting ASCII File Format). You can create the data file using either the  Create or the  Clone command.

The following example loads sequential records from the course.txt file into the course.mkd file. The owner name of the course.mkd file is Sandy.

The recover command extracts data from a MicroKernel file and places it in an ASCII file that has the same format as the input ASCII file that the Load command uses. This is often useful for extracting some or all of the data from a damaged MicroKernel file. The recover command may be able to retrieve many, if not all, of the file’s records. You can then use the load command to insert the recovered records into a new, undamaged MicroKernel file.

For each record in the source file, if the recover command receives a variable page error (Status Code 54), it places all the data it can obtain from the current record in the unformatted file and continues the recovery process.

The tool produces the following messages:

The following statement extracts records from course.mkd and writes them to course.txt.

The save command retrieves records from a MicroKernel file using a specified index path and places them in an ASCII file that is compatible with the required format for the load command. You can then edit the ASCII file and use the load command to store the edited data in another data file. (See Importing and Exporting ASCII File Format for more information about the ASCII file format.)

Save generates a single record in the output ASCII file for each record in the input data file. Upon completion, save displays the total number of records saved.

The tool produces the following messages:

The following two examples illustrate how to use the save command to retrieve records from a data file.

This example uses a newcrs.idx external index file to retrieve records from the course.mkd file and store them in an unformatted text file called course.txt:

The following example retrieves records from the course.mkd file using key number 3 and stores them in an unformatted text file called course.txt:

This section includes detailed information on creating and modifying data files using the following butil commands: Clone, Clrowner, Create, Drop, Index, Setowner, and Sindex. This section also includes information about removing unused space in a Btrieve data file, which is discussed in Compacting Btrieve Data Files.

The clone command creates a new, empty file with the same file specifications as an existing file (including any supplemental indexes, but excluding the owner name). The new data file includes all the defined key characteristics (such as key position, key length, or duplicate key values) contained in the existing file.

The clone command ignores all MicroKernel configuration options that affect file statistics (such as System Data) except file version. The clone command creates a new file using the database engine file version you specify with the Create File Version option.

Btrieve 6.0 and later allows a maximum of 23 key segments in a data file with a page size of 1024 bytes. Therefore, the clone command sets the page size in the new data file to 2048 bytes if the existing data file contains 24 key segments and has a page size of 1024 bytes. This occurs if the existing data file has a format earlier than 6.0 and the database engine was not loaded with the Create File Version option set to 5.x or 6.x.

If you are cloning a pre-7.x file, ensure that the database engine is configured to create the file format version that you want the new file to be. For example, if you want to clone a 6.15 file in 9.5 format, in the database engine Compatibility properties, set Create File Version to 9.5.

If you are trying to recover from receiving status code 30 (file specified is not a MicroKernel file) and you suspect that the header page of the source file might be damaged, try creating the new MicroKernel file using the Create command with a description file.

The following command creates the newcrs.mkd file by cloning the course.mkd file.

The CLROWNER command clears the owner name of a MicroKernel file.

The following command clears the owner name for the file tuition.mkd. The owner name is Sandy.

The CREATE command generates an empty MicroKernel file using the characteristics you specify in a description file. Before you can use the CREATE command, you must create a description file to specify the new key characteristics. For more information, see Description Files.

The following command creates a file named course.mkd using the description provided in the create.des description file.

The sample description file shown in Figure 33 creates a MicroKernel formatted file. The file is specified to have a page size of 512 bytes and 2 keys. The fixed-length portion of each record in the file is set to 98 bytes. The file specifies variable-length records with no blank truncation, record compression, and variable-tail allocation tables (VATs). The free space threshold is set to 20 percent. Allocation is set to 100 pages. The MicroKernel preallocates 100 pages, or 51,200 bytes, when it creates the file.

Key 0 is a segmented key with two duplicatable, nonmodifiable string segments and a null value of 20 hexadecimal (space) specified for both segments. Key 0 uses the collating sequence upper.alt.

Key 1 is a numeric, nonsegmented key that does not allow duplicates but permits modification. It is sorted in descending order.

The DROP command removes an index from a file and adjusts the key numbers of any remaining indexes, subtracting 1 from each subsequent key number. If you do not want to renumber the keys, you can add 128 to the key number you specify to be dropped. This renumbering feature is available only for 6.0 and later files.

In both of the following examples, course.mkd has three keys. The original keys in the file are numbered 0, 1, and 2.

In the first example, the butil -drop command drops key number 1 from the course.mkd file and renumbers the remaining key numbers as 0 and 1.

In the following example, the butil –drop command drops key number 1, but does not renumber the keys. The key numbers remain 0 and 2.

The INDEX command builds an external index file for an existing MicroKernel file, based on a field not previously specified as a key in the existing file. Before you can use the INDEX command, you must create a description file to specify the new key characteristics. For more information about description files, see Description Files.

The records in the new file consist of the following:

The INDEX command creates the external index file and then displays the number of records that were indexed. To retrieve the data file’s records using the external index file, use the Save command.

The description file shown in the following illustration defines a new key with one segment. The key begins at byte 30 of the record and is 10 bytes long. It enables duplicates, is modifiable, is a STRING type, and uses no alternate collating sequence.

The following command creates an external index file called newcrs.idx using a data file called course.mkd. The course.mkd file does not require an owner name. The description file containing the definition for the new key is called newcrs.des.

The SETOWNER command sets an owner name for a data file. See Owner Names for more information.

The following example creates a short owner for the course.mkd data file. The owner name is Sandy, and the restriction level is 1.

The following example creates a long owner name for the billing.mkd data file, encrypts the owner name and file, and restricts all access modes.

The SINDEX command creates an additional index for an existing MicroKernel file. By default, the key number of the new index is one higher than the previous highest key number for the data file, or you can instruct the database engine to use a specific key number. An exception is if a DROP command previously removed an index without renumbering the remaining keys, thus producing an unused key number; in this case, the new index receives the first unused number.

You can instruct the database engine to use a specific key number for the new index with the key number option. The key number you specify must be a valid key number that is not yet used in the file. If you specify an invalid key number, you receive status code 6.

If you do not use the SYSKEY option with this command, you must create a description file that defines key specifications for the index before you can use the SINDEX command. For more information about description files, see Description Files.

The following example adds an index to the course.mkd file. The name of the description file is newidx.des.

The following example adds the system-defined key to the course.mkd file. The system-defined key was dropped.

You can use several commands in the butil (Clone, Recover, and Load, respectively) to remove unused space in a data file to decrease its size.

To improve performance, butil allows you to manage page caching for a file using cache and purge commands.

When butil -cache and -purge commands are executed from a client cache or reporting engine, their actions apply only to the file in the local cache.

In order for a file to remain in the client cache, one of two things must be true:

When the client cache engine is installed as an application, it shuts down and empties the cache shortly after the client closes all files. This is not an issue for the client cache engine installed as a service or for the reporting engine.

The CACHE command preloads pages for a file into cache, returning when either the file is fully cached or the cache is full.

The PURGE command flushes all unneeded cached pages for a file. Returns immediately if the file has open handles.

This topic includes information about generating a report using STAT on characteristics and statistics of a data file.

The STAT command generates a report that contains defined characteristics of a data file and statistics about file contents. You can use this command to determine whether the database engine can log statistics on the file using the transaction durability feature. The STAT command reports indexes the same whether they were created by the Create Supplemental Index operation (in Btrieve 6.0 and later) or the Create operation.

The following example shows statistics for the file patients.dta.

The result of this command lists the following:

This example shows that the file version of patients.dta is 8.0, indicating the earliest Btrieve version that can read the file format. The file has a page size of 2048 bytes and no preallocated pages. This is not a key-only file, nor an extended file.

Sixteen records have been inserted into the file. The file was defined with a record length of 104 bytes, does not use record compression, and does not allow variable-length records.

The file has no available linked duplicate keys. It does not use balanced indexing. The MicroKernel performs logging using Key 1, and the file contains no system-defined data. It has three keys comprised of four key segments.

The statistics report also provides information about specific keys. For example, the report shows that Key 0 consists of two segments, allows duplicates, and is modifiable. Furthermore:

Key 1 is the key the database engine uses in logging this file. It consists of one segment. It starts in position 1, is 6 characters long, does not allow duplicates, is modifiable, and will be sorted as a string type. Sixteen unique values were inserted for this key. It uses the upper.alt alternate collating sequence file.

Key 2 consists of one segment. It starts in position 83, is 10 characters long, allows duplicates, is modifiable, and will be sorted as a string type. Seven unique key values were inserted for this key. It uses the upper.alt alternate collating sequence file.

When asked for the file format version of a file, the database engine gives the earliest engine version that can read the file. For example, if you have a file created in 5.x format, it may be reported as a version 3.x file because it uses no 4.x or 5.x features. Starting with the 6.x format, the file itself contains a version stamp. Before 6.x, the only way to determine file format version was to inspect the features used in the file, since each new file version has features not available in previous ones.

For version 5.x and earlier files, the following table shows the features used to determine the file format version.

This section includes detailed information about displaying the version of the MicroKernel Engine using the VER command.

The VER command returns the version number of both the MicroKernel Engine and the Requester (the access module).

When you run the VER command, the tool displays messages similar to the following:

Use the STOP command to unload the MicroKernel Engine and, if applicable, the Requester.

The commands pertaining to continuous operations, startbu and endbu, are discussed in the topic Logging, Backup, and Restore.

The Maintenance tool (GUI or butil command line) provides a way to roll forward archival log files into the data files. See also Logging, Backup, and Restore.

The butil rollfwd command recovers changes made to a data file between the time of the last backup and a system failure. If a system failure occurs, you can restore the backup copy of your data file and then use the butil rollfwd command, which applies all changes stored in the archival log to your restored data files. Do not use this command unless you have restored data files from backup.

You can also use the rollfwd command to produce an output file of logged operations. The rollfwd command can produce the output file either before you roll changes forward or at the same time as the roll forward.

You can roll forward a single file, all data files on a volume, all data files on a drive, or a list of files, volumes, and/or drives.

This section explains the syntax for the command line usage of Roll Forward.

Example A The following example recovers changes to the class.mkd file from the default archival log and log location.

For default file locations, see Where are the files installed? in Getting Started with Zen.

Example B This example recovers changes and outputs them to all files on the d:\ volume with the following options:

Example C The following example does not perform roll forward but only outputs the changes to the files listed in files.txt with the following dump options: