Enhancements to NetWare Btrieve

NetWare Btrieve 6.x includes many features and performance enhancements that support the requirements of today's powerful database management systems. The following two sections describe these enhancements.


Enhancement to NetWare Btrieve 6.1x

This section describes enhancements that apply to NetWare Btrieve 6.1x.


New Operations

NetWare Btrieve 6.1x supports the following new Btrieve operations.


Operating on Chunks

NetWare Btrieve 6.1x allows you to operate on portions of a record, called chunks, rather than on the entire record. NetWare Btrieve 6.1x provides the Get Direct/Chunk (23) and Update Chunk (53) functions that work on any file conforming to the Btrieve 6.x file format.

Applications can use these chunk operations to build records larger than 64 KB in files that use the NetWare Btrieve 6.0 file format. Applications can use chunk operations to build records longer than 64 KB in any Btrieve 6.x file that allows variable-length records.

NOTE:  For more information about these operations, refer to the Btrieve Programmer's Manual included in the NetWare Btrieve v6.1 Developer's Kit Supplement, which is available through the Novell Professional Developers' Program (PDP).


Supporting Records Larger than 64 KB

When NetWare Btrieve 6.0x operates on files containing records larger than 64 KB, the following restrictions apply:

For more information, see Accessing Records by Chunks in Appendix A.


Record Locking in Concurrent Transactions

NetWare Btrieve 6.1x provides additional concurrency by allowing true record-level locking in concurrent transactions (explained in Concurrent Transactions). An explicit record lock (set by adding a bias to Get and Step operations) does not lock the corresponding data page---it locks only that particular record. Additionally, NetWare Btrieve 6.1x provides the ability to share locks between multiple cursors of the same file in an application.

Successful locking of a record (inside or outside a transaction) guarantees that no other user is able to update or delete that record. In other words, when a user performs an Update (3) or Delete (4) operation on a record that he or she has previously locked, he or she will eventually succeed unless a deadlock situation is detected.

NOTE:  A deadlock occurs when two or more users are each waiting on resources that one of the users has not yet released.

If an application opens the same file multiple times, the locks issued by different cursors do not block each other. The cursors are still independent in the sense that they cannot explicitly unlock (using an Unlock [27] operation) the records that were locked by the other cursors.

After a cursor has read a record with a lock, a second cursor can update or delete the record regardless of whether this second cursor locked the record. The first cursor will not get an error until it tries to delete or update that record.

In general, when implementing multiple cursors within a concurrent transaction, locks obtained on a cursor before the application starts a concurrent transaction are automatically released when the cursor becomes an active participant of that transaction.

NOTE:  A cursor becomes an active participant of a concurrent transaction if a lock is requested or an Insert/Delete/Update operation is executed with that cursor.

The transaction does not have any effect on the inactive cursors. That is, locks obtained before the transaction are still maintained after ending/aborting the transaction of inactive cursors.

For more information, see Locks in Appendix A.


New File Structure to Support Accessing Very Long Records

NetWare Btrieve 6.1x allows an application to create Btrieve files that contain structures called Variable-tail Allocation Tables (VATs). VATs give NetWare Btrieve faster access to data residing at large offsets in very long records. VATs also significantly reduce the buffers sizes Btrieve needs to process records in files that use data compression.

For more information, see Storing Variable-Length Records: Variable Tails and VATs in Appendix A.


Multiple Alternate Collating Sequences

NetWare Btrieve 6.1x allows you to specify a separate alternate collating sequence (ACS) for each key in a file. Btrieve files with multiple keys are no longer restricted to having only one ACS.

For more information, see Alternate Collating Sequence in Appendix A.


Locale-Specific Collating Sequences

NetWare Btrieve 6.1x lets you instruct Btrieve to build an ACS that is sensitive to the specified locale's character sorting order. This ability allows Btrieve to sort according to a character set specified by a particular country ID and code page.

For more information, see Locale-Specific ACS in Appendix A.


Index Balancing

When an index page becomes full, NetWare Btrieve automatically creates a new index page and splits the values in the full page between the two pages. NetWare Btrieve 6.1x offers the option of using index balancing instead.

When you use index balancing, NetWare Btrieve looks for available space in other index pages associated with the same key each time an index page becomes full. Btrieve then rotates values from the full page onto the pages that have space available. Index balancing increases index page utilization, results in fewer pages, and produces an even distribution of keys among nodes on the same level.

For more information, see Index Balancing in Appendix A.


Performing Reads While Creating an Index

With NetWare Btrieve 6.1x, you can perform reads while a Create Index (13) operation is executing. Previous versions of Btrieve locked the entire file when executing a Create Index (13) operation.

NOTE:  For more information about the Create Index (13) operation, refer to the Btrieve Programmer's Manual included in the NetWare Btrieve v6.1 Developer's Kit Supplement, which is available through the Novell Professional Developers' Program (PDP).


New Data Type: sign trailing separate

NetWare Btrieve 6.1x allows you to specify a new data type for keys called a sign trailing separate (STS). STS is based on a COBOL data type Numeric sts.

Basically a numeric data type, it is represented as an ASCII string that is right-justified and padded with zeros. However, the sign trailing separate data type stores either a `+' (ASCII 0x2B) or a `-' (ASCII 0x2D) in the right-most byte of its value.

For more information, see Key Types in Appendix A.


No Currency Change Option

NetWare Btrieve 6.1x provides a No Currency Change option on inserts and updates. In previous versions of Btrieve, positioning was reestablished based on a key value of the inserted or updated record.


New Ability to Specify Repeating- or Linked-Duplicatable Keys on Create Operations

On the Create (14) and Create Index (31) operations, NetWare Btrieve 6.1x allows you to specify that a key should be created as either a repeating-duplicatable key or a linked-duplicatable key.

For more information, see Linked-Duplicatable and Repeating-Duplicatable Keys in Appendix A.


Improved NetWare Btrieve DOS and OS/2 Requesters

The NetWare Btrieve DOS and OS/2 Requesters support MAP ROOT drives and NetWare file-level security. Since the MS Windows Requester requires the DOS Requester to access NetWare Btrieve, MS Windows users can also take advantage of these features then they are running in a NetWare 3 or NetWare 4 environment.

When opening files in a NetWare 3.12 environment, Btrieve Requesters provide enhanced performance by reducing the bindery access for each file and reducing network traffic in general.

NOTE:  To run NetWare Btrieve 6.1x in a NetWare 3.11 environment, you need to load AFTER311.NLM.

The NetWare Btrieve 6.1x DOS and OS/2 Requesters have two new features:

In addition, the DOS Requester also has the following new options:

These options are discussed in detail in DOS Requester Configuration Options in Chapter 4, "Configuring and Using the Requesters."


Enhanced Communications Programs

An enhanced NetWare Btrieve Message Router (BROUTER.NLM) and a new communications module (BTRVSTUB.NLM) were provided with NetWare Btrieve 6.10b to support NLMs that need to run in the IOEngine of a NetWare SFT III server.

BROUTER.NLM redirects all Btrieve calls from the IOEngine to NetWare Btrieve running in the MSEngine (Mirror Server Engine).

For detailed information about these new programs, see Communications Programs in Chapter 2, "NetWare Btrieve Architecture."

For information about running NLMs that require Btrieve in the IOEngine, see Using NetWare Btrieve with a NetWare SFT III Server in Chapter 3, "Installing and Configuring NetWare Btrieve."


Enhancements to NetWare Btrieve 6.x

This section describes enhancements that apply to NetWare Btrieve 6.x (that is, to versions 6.0x as well as versions 6.1x).


Registration with Novell Directory Services

NetWare Btrieve 6.x registers with Novell Directory Services (NDS). NDS is a part of NetWare 4 that organizes network resources as objects in a hierarchical tree structure called the Directory. Although the Directory replaces the bindery, NetWare 4 still provides compatibility with previous versions of NetWare through a bindery emulator.

Since NDS organizes the network in terms of objects, NetWare Btrieve registers with NDS as an object of class Btrieve Server. The Btrieve Server class identifies the server name, the type of communications protocol supported, and the object's internet address.

See Registering NetWare Btrieve with the Novell Directory Services in Chapter 3, "Installing and Configuring NetWare Btrieve," for information on installing Btrieve as an object in the Directory.

For more information on NDS, refer to the Cobra Installation Guide manual.


New File Format

When creating files, NetWare Btrieve 6.x uses a new file format that allows faster data access than was possible with previous Btrieve releases. This format, introduced in Btrieve 6.0 and modified in Btrieve 6.1, is responsible for many of the enhancements and new features available with these releases.

When working with Btrieve files created with different versions of Btrieve, consider the following points:

If your database contains files created with versions of NetWare Btrieve prior to 6.1x, you may want to upgrade them to take advantage of the NetWare Btrieve 6.1x features. The Btrieve Rebuild utility converts Btrieve data files to the 6.1x file format, as described in Rebuilding Existing NetWare Btrieve Files.


New Utilities

NetWare Btrieve 6.x includes several utilities to help you use your Btrieve-based applications and monitor your Btrieve operations.


Btrieve Monitor Utility (BTRMON.NLM)

The NetWare Btrieve 6.x Monitor utility (BTRMON.NLM) replaces the NetWare Btrieve 5.x Console utility (BCONSOLE.NLM).

In terms of functionality, BTRMON is much like BCONSOLE, but it includes new features to help you monitor the performance of your Btrieve-based applications.

IMPORTANT:  NLM applications that call NetWare Btrieve must issue a Btrieve Reset before unloading. Failure to do so may lead to a server abend when you try to use the Btrieve Monitor utility to monitor the NLM application's activity.

For additional information about the Monitor utility, refer to NetWare Btrieve Monitor Utility in Chapter 5, "Using NetWare Btrieve Utilities."


Rebuild Utility (BREBUILD.NLM)

The new Rebuild utility allows you to upgrade files created with versions of Btrieve prior to 6.0x. Use this utility to upgrade your files to take advantage of the Btrieve 6.1x features.

For more information about rebuilding your existing files, refer to Rebuilding Existing NetWare Btrieve Files.

NOTE:  Before running the Rebuild utility (either from the command line or through the Setup utility), you must start NetWare Btrieve v6.1x.


Roll Forward Utilities (BROLLFWD.EXE, PBROLL.EXE, and WBROLL.EXE)

The NetWare Btrieve 6.x BROLLFWD.EXE file for DOS workstations replaces the NetWare Btrieve 6.0x file DBROLL.EXE.

For detailed information about using the Roll Forward utilities, see NetWare Btrieve Roll Forward Utility in Chapter 5, "Using NetWare Btrieve Utilities."


Online Backups

Through a feature called continuous operation, Btrieve 6.x now lets you back up Btrieve files while they are open and in use. This feature is important for applications that conduct transactions 24 hours a day.

When you enable the continuous operation feature, Btrieve opens the original file in read-only, sharable mode to allow backup utilities to access the file's static image. Any changes to the original file that occur during the backup are stored in a temporary file called a delta file. When the backup ends, Btrieve automatically updates the original file with the changes from the delta file and deletes the temporary delta file.


Concurrent Transactions

Concurrent transactions allow one or more applications (or instances of the same application) to run multiple transactions simultaneously for the same Btrieve file, if that file uses the Btrieve 6.x file format.

Versions of Btrieve earlier than 6.0x support only one type of transaction: exclusive. When an application reads, updates, inserts, or deletes a record from a file in an exclusive transaction, Btrieve locks the entire file for the duration of the transaction. This type of locking is known as file-level transaction locking.

Once a file is locked in an exclusive transaction, other users can still read the file, provided they are not involved in exclusive transactions and are not attempting to lock the file themselves. They cannot, however, make any changes to the file, and they cannot see changes made to the file during a transaction until that transaction ends (regardless of which version of Btrieve was used to create the file originally).

NOTE:  This is true only for local clients---that is, clients on the same workstation running under the same Btrieve engine. However, if the exclusive transaction affects pre-v6.0 files, remote clients---clients on different workstations, running under different Btrieve engines---can see the changes to those files before the transaction ends.

In addition to supporting exclusive transactions, Btrieve 6.x supports a new type of transaction: concurrent. When a Btrieve 6.x file is included in a concurrent transaction, modifications cause Btrieve to lock only the page (or pages, if the record is variable length) that contains the record, as well as its associated index pages.

This allows other users to modify or include the same file in their own concurrent transaction, as long as no concurrent transaction has already locked the pages that contain the records to be modified (or any affected index pages).

Concurrent transactions have the following additional features:

For more information, see Using Btrieve Transactions in Appendix A.


Shadow Paging

Versions of Btrieve prior to 6.0x used pre-imaging to protect files from corruption in case of a system failure. Btrieve 6.x also uses this method to protect files that employ the pre-6.0x file format.

NOTE:  Before updating a file using the pre-imaging feature, Btrieve creates a temporary pre-image file. This file contains the pages to be updated from the original file. Btrieve then performs the update on the original file. If the system fails during the update, Btrieve can restore the original file using the pre-image file. For more informations about pre-image files, see Pre-imaging in Appendix A.

For files using the Btrieve 6.x file format, a new Btrieve 6.x page handling technique called shadow paging replaces pre-imaging.

When a user needs to change a page (either inside or outside a transaction), Btrieve creates a shadow page---a virtual copy of the original page. Btrieve then selects and locks a free physical location in the Btrieve file for the shadow page, but it does not write the shadow page to the new location at this point.

Instead, it makes the requested changes to the shadow page (rather than to the original page) while the shadow page is still in memory. After making the requested changes, Btrieve writes the shadow page to the new physical location.

When the changes are committed (either when the operation is complete or the transaction ends), Btrieve designates the shadow page as the current page, and the original page becomes available for reuse. If a system failure occurs before the changes are committed, Btrieve drops the shadow page, and the current page remains in its original condition.

When a user first attempts to change a page inside a transaction, Btrieve creates a shadow page that corresponds to the original logical page. While inside the transaction, all changes the client makes are actually made to the shadow page.

If other users need to access the same logical page, they will see the original (unchanged) page---that is, they do not see the first client's uncommitted changes. Shadow paging thus enhances reliability because the original file is always valid and internally consistent.

For more information about shadow paging, see Shadow Paging in Appendix A.


New Caching Algorithms

Btrieve 6.x provides new caching algorithms that improve memory management for concurrent users. These new algorithms include hashing search methods for improved access, concurrent sharing of a single cache, and use of existing cache across operations.


Better Use of Large Data Files

Btrieve 6.x provides faster access and more efficient use of large data files than previous versions of Btrieve provided. With Btrieve 6.x, you can create additional indexes for large data files more quickly than in previous versions, and new merge sorts take advantage of whatever cache is available.


More Key Segments Allowed

Btrieve 6.x has increased the maximum number of key segments allowed in a file, supporting up to 119 key segments in files with a page size of 4,096 bytes. (Versions of Btrieve earlier than 6.0x supported a maximum of 24 key segments.)

The maximum number of key segments you can define for a file depends on the file's page size, as indicated in the following table:

Page Size Maximum Key Segments

512

8

1,024

23

1,536

24

2,048

54

2,560

54

3,072

54

3,584

54

4,096

119

For more information, see Segmented and Nonsegmented Keys in Appendix A.


Adding and Dropping Any Index

Btrieve 6.x supports adding and dropping any index. In versions prior to Btrieve 6.0x, you could add and drop only supplemental indexes---that is, only those indexes that were not originally produced during a Create operation (14). Also, you can drop indexes without renumbering the remaining indexes.

This feature requires that an application take extra precautions when accessing a Btrieve file that may be shared with other applications. To be certain that the file being opened contains all the keys application 1 is expecting and that those keys are in the proper order, application 1 should preform a Stat operation(15) before using a particular index.

For more information, see Indexes in Appendix A.


Specific Key Numbers Allowed When Creating a File or Index

Btrieve 6.x allows an application to assign specific key numbers when creating a 6.x format file with indexes, or when creating an index for a preexisting 6.x file.

Btrieve 6.x files are not required to number keys consecutively; they may have gaps between key numbers. When a key is added, Btrieve by default assigns the lowest available key number to that index.

However, some applications may require a different key number than the one assigned by default. For this reason, Btrieve 6.x provides a way to specify which key number the Create Index operation (31) assigns to the index being created.

This capability complements the ability to delete a key and not have Btrieve renumber all keys that have a key number greater than that of the deleted key (described in the next section).

For example, assume that an application drops an index and instructs Btrieve not to renumber higher-numbered keys. If a user then clones the affected Btrieve file without assigning specific key numbers, the cloned file would have different key numbers than the original.

For more information, see Keys in Appendix A.


Optional Renumbering of Keys

With Btrieve 6.x, the Drop Index operation (32) allows an application to specify whether to renumber the remaining keys when dropping a key from a Btrieve file. (The file must use the Btrieve 6.x file format.)

When an application dropped a key in earlier versions of Btrieve, Btrieve renumbered the remaining keys that had a key number higher than that of the dropped key. To renumber these keys, Btrieve decremented each higher key number by one so that no key numbers were skipped.

In 6.x, an application can specify that when an index is dropped, no automatic renumbering should take place. In this case, the remaining higher numbered keys retain their original key numbers after Btrieve drops the specified key.

For more information, see Indexes in Appendix A.


Enhanced Support for Case-Insensitive Keys

Btrieve 6.x allows you to create case-insensitive keys without using an alternate collating sequence (ACS). When creating a file, you can use the key specifications to designate case-insensitive string, lstring, or zstring key types.

When using case-insensitive keys, Btrieve treats lowercase and uppercase letters the same. For example, the lowercase letter a and the uppercase letter A are treated as the same letter for sorting purposes.

For more information, see Case-Insensitive and Case-Sensitive Keys in Appendix A.


Enhancement to autoincrement Key

In Btrieve 6.x, you can initialize the value of a field in every record of a file to zero and later add an index of type autoincrement. This feature allows you to prepare for an autoincrement key without actually building the index until you need it.

When you add the index, Btrieve changes the zero values in each field appropriately, beginning its numbering with a value equal to the greatest value currently defined in the field, plus one. If nonzero values exist in the field, Btrieve does not alter them. However, Btrieve returns an error if nonzero duplicate values exist in the field.

In Btrieve versions earlier than 6.0x, Btrieve returned a duplicates error if a user added an autoincrement key as an index and the field being indexed contained more than one zero.

NOTE:  If an error occurs on a Create Index operation (31) after any values have been altered, those values remain altered.

For more information, see Key Types in Appendix A.


Reserved Space for Duplicate Pointers

Btrieve 6.x allows reserving duplicate pointers on data records for linked duplicate keys. When creating a Btrieve 6.x file, an application can reserve space in the data records for extra, unused duplicate pointers.

Later, when an application adds an index that allows duplicate values, Btrieve stores pointers to those duplicate values in the reserved space (unless the Repeating Duplicates key attribute has been specified).


Key-Only File Modification

With Btrieve 6.x, you can update and delete records in key-only files. In versions of Btrieve prior to 6.0x, you could only insert records in this type of file.

For more information, see Key-Only Files in Appendix A.


New Stat Option

A new option in the Stat operation (15) allows an application to obtain additional information such as a file's Btrieve version and the number of unused duplicate pointers. This feature also works with files created with earlier versions of Btrieve.


Locking in Extended Operations

Unlike previous versions of Btrieve, 6.x allows an application to use locks on the extended operations: Get Next Extended (36), Get Previous Extended (37), Step Next Extended (38), and Step Previous Extended (39).

For more information, see Locks in Appendix A.


Support for Referential Integrity

Btrieve 6.x supports the use of referential integrity (RI) constraints created through the Novell® Scalable SQLTM or client-based SQL relational data access system. RI ensures that dependent data stays synchronized throughout the database.

No Btrieve operations currently exist to manipulate RI constraints directly. You must use either Scalable SQL or the client-based version of SQL.