Clarion Community Help

Client/Server

For Client/Server-based Btrieve, Netware Btrieve is a server-based version of Btrieve that runs on a Novell server.

Collating Sequence

NOCASE Key Attribute

NLM 5 does not support case insensitive indexing. When necessary, you must supply an alternate collating sequence which implements case insensitive sorting.

Btrieve supports an alternate collating sequence. However, NLM 6 does not support both NOCASE and an alternate collating sequence. If you specify both, the NOCASE attribute takes precedence. No error is returned fromThe SEND function.

Changing the Collating Sequence

Btrieve stores the collating sequence inside the file. So to change the collating sequence you have to change the .ENV file, then create a new Btrieve file based on the modified .ENV file, then copy the data from the old file to the new file.

Error Codes

All Btrieve error codes up to 2007 are now mapped to appropriate error messages.

File Sharing

Btrieve lets you open a file in five different formats: NORMAL, ACCELERATED, READ-ONLY, VERIFY, or EXCLUSIVE. The equivalent Clarion OPEN() states are:

Btrieve State   Clarion OPEN/SHARE access mode

ACCELERATED     Read/Write with FCB compatibility mode (2H)

READ-ONLY       Read Only  (0H,10H,20H,30H,40H)

VERIFY          Write Only with FCB compatibility mode (1H)

EXCLUSIVE       Write Only with any Deny flag (11H,21H,31H,41H);

               Read/Write with Deny All, Read or Write (12H,22H,32H)

NORMAL          Read/Write with Deny None (42H)

Btrieve allows a file to have a specified owner. See the /READONLY driver string for details on setting this flag. The file may also be encrypted with the ENCRYPT attribute. A file can only be encrypted when an owner name is supplied.

File Structure

A single file normally holds the data and all keys. Data filenames default to a *.DAT file extension. By default, the driver stores memos in a separate file, or optionally in the data file itself, given the appropriate driver string.

Because Btrieve is a data-model independent, indexed record manager, it does not store field definitions within the data itself. The application accessing the data determines how to interpret the Btrieve record. Absent .DDF files describing the Btrieve file, it is very difficult for an application that does not create or maintain the file to meaningfully interpret its data.

The Btrieve file format stores minimal file structure information in the file. As far as possible, the driver validates your description against the information in the file. However, it is possible to successfully open a Btrieve file that has key definitions that do not exactly match your definition. You must make certain that your file and key definitions accurately match the Btrieve file.

KEY Definitions

When defining a file, the key definition does not need to exactly match the underlying file. For example, you can have a physical file with a single component STRING(20). You can define this as a key with two string components with a total length of 20. The rule is that the data types must match and the total size must match. However, if your Clarion definition does not exactly match the underlying file, the driver cannot optimize APPEND() or BUILD() statements.

A Key's NAME attribute can add additional functionality.

KEY,NAME('MODIFIABLE=true|false')

Btrieve lets you create a key that cannot be changed once created. To use this feature you can use the name attribute on the key to set MODIFIABLE to FALSE. It defaults to TRUE.

KEY,NAME('ANYNULL')

Btrieve lets you create a key that will not include a record if any key components are null. To create such a key you specify ANYNULL in the key name.

For example, to create a key that is non-modifiable and excludes keys if any component is null:

   Key1   KEY(+pre:field1,-pre:field2),NAME('ANYNULL MODIFIABLE=FALSE')

KEY,NAME('AUTOINCREMENT')

The Clarion CREATE statement creates a Btrieve autoincrement key.

KEY,NAME('REPEATINGDUPLICATE')

By default Btrieve version 6 stores a reference to only the first record in a series of duplicate records in a key. The other occurrences of the duplicate key value are obtained by following a link list stored at the record. To create an index where all duplicate records are stored in the key you use the NAME('REPEATINGDUPLICATE'). This produces larger keys, but random access to duplicate records is faster (this feature is only available for version 6 files).

Keys and Indexes

KEYs are dynamic, and automatically update when the data file changes.

INDEXes are stored separately from data files. INDEX files receive a temporary file name, and are deleted when the program terminates normally. INDEXes are static–they are not automatically updated when the data file changes. The BUILD statement creates or updates index files.

Page Size

To determine the physical record length, add 8 bytes for each KEY that allows duplicates. Add 4 bytes if the file allows variable record lengths. Finally, allow 6 bytes for overhead per page.

For example: If the record size is 300 bytes and the file has three KEYs that allow Duplicates, the total record size is:

A page size of 512 would only hold one such record, and 182 bytes per page would go unused (512 - 6 - 324). If the page size were 1024, three records could be stored per page and only 46 bytes would go unused (1024 - 6 - (324 * 3)).

You must load BTRIEVE.EXE with a page size equal to or greater than the largest page size of any file that you will be accessing.

Record Lengths

The driver stores records less than 4K as fixed length. It stores records greater than 4K as variable length. The minimum record length is 4 bytes. One record can be held in each open file by each user.

Record Pointers

Btrieve uses an unsigned long for its internal record pointer; negative values are stripped of their sign. We recommend the ULONG data type for your record pointer.

Transaction Framing

You cannot create files inside a transaction frame with Btrieve. This means that if you have “Defer opening files until accessed” template option checked in your applications, you must make sure that all files exist before entering transaction frames (initiated with LOGOUT). The easiest way to ensure this is that on startup of an application, it should detect if a file exists, and if it does not, then create a routine that creates the files as needed (by simply calling FileManager.Open for all the files).