You can configure Btrieve by setting configuration options. When you load Btrieve with the INSTALL utility, these options are set to their default values (shown in Table 1).

However, your Btrieve application may require different values for these options. To determine which values your application requires, refer to the documentation included with that application.

IMPORTANT: BROUTER.NLM is the default Message Router that is loaded through the NetWare INSTALL utility. If you want Directory Services support, you need to unload BROUTER.NLM and load BDROUTER.NLM.

The following section discusses each configuration option individually. You can change the values for the configuration options by running the Btrieve Setup utility (as described in "Running the Setup Utility"). The Setup utility stores your changes in the BSTART.NCF NetWare command file.

Configuration Options

This section lists the configuration options in the order in which they appear in the Setup utility. For each option, the discussion includes the following:

• Range of acceptable values
• Default value
• Approximate memory required
• Description of the option

Number of Open Files

Range: 1 through 64,000 files

Default: 20 files

Approximate Memory Required: 425 bytes per file

This option specifies the maximum number of unique Btrieve files, including data dictionary (.DDF) files, that can be open at one time at the server.

The value you specify determines the size of the internal tables used to track active files. Each unique Btrieve file on the server counts as one file.

Number of Handles

Range: 1 through 64,000 file handles

Default: 60 handles

Approximate Memory Required: 200 bytes per handle

This option specifies the maximum number of file handles that the Btrieve NLM can use at one time.

Keep in mind that the number of handles is different from the number of open files. That is, if two sessions open the same file on the same server, Btrieve counts it as one open file, but two different file handles. See "Number of Locks" (next) for a definition of sessions.

NOTE: To calculate the maximum number of handles your system requires when accessing files on a workstation, multiply the value you specify for the Number of Open Files option by the maximum number of clients (that is, workstation tasks) that can access Btrieve at one time. (Each Scalable SQL client is also a Btrieve client. That is, each concurrent Scalable SQL request has an associated Btrieve client.)

Number of Locks

Range: 0 through 64,000 locks

Default: 20 locks per client session

Approximate Memory Required: 20 bytes per lock

This option sets the maximum number of records a client session can lock at the server at one time.

NOTE: A session occurs when a client uses the Btrieve Requester or Message Router to communicate with the Btrieve NLM, or when an NLM application calls Btrieve directly.

This maximum number of locks applies to whichever type of read lock (single record or multiple record) the client session is using. Single-record locks allow an application to lock only one record at a time. Multiple-record locks allow an application to lock more than one record at a time.

Number of Transactions

Range: 0 through 64,000 transactions

Default: 15 transactions

Approximate Memory Required: 20 bytes + (2 * maximum number of files)

This option sets the maximum number of Btrieve clients that can simultaneously have active transactions at the server. (Each of these clients can have only one active transaction at the server.)

For example, if you specify 6 transactions, Btrieve creates a transaction file at the server (BTRIEVE.TRN in the SYS:SYSTEM directory) and allows a maximum of 6 clients to have one active transaction each at the server.

If you specify a value of 0, no clients can perform a Btrieve transaction.

Largest Compressed Record Size

Range: 0 through 64 KB

Default: 8 KB

Approximate Memory Required: 2,048 bytes * specified value

This option allows you to allocate memory for a compression buffer that Btrieve can use when you access records in a Btrieve file created with the Data Compression file attribute enabled.

Btrieve allocates a compression buffer with a size of 2,048 bytes multiplied by the value you specify for this option. (This specified value can be determined by either the record size or the page size.)

Use the following guidelines when specifying the value for this option:

• If you use compressed Btrieve files, determine the size (in bytes) of the largest record in any of your compressed files. Round the record size to the next whole kilobyte.

  For example, if the largest record you need to access is 1,800 bytes, specify 2 for this option. Btrieve will allocate 4,096 bytes (that is, 2,048 * 2) of memory for the compression buffer.

• If every compressed file you use has Variable-tail Allocation Tables (VATs), set this option to the file's largest page size (in bytes) divided by 128.

  For example, if the largest page size is 1,024 bytes, specify 8 for this option. Btrieve will allocate 16,384 bytes (that is, 2,048 * 8) of memory for the compression buffer.

• If you do not use compressed files, set this value to 0. You cannot improve performance, and may waste memory, by specifying a value higher than you need.

Largest Record Size

Range: 600 through 64,000 bytes

Default: 8,192 bytes

Approximate Memory Required: recordLength * (remoteSessions / 5) + 1 + (remoteSessions * recordLength / 580) * 600 recordLength

Largest record size + 538 bytes remoteSessions Number of remote sessions

This option specifies the length of the largest record or record chunk that any remote Btrieve application (excluding other NLMs that call Btrieve, such as Scalable SQL^TM) can access at the server.

A record chunk is any arbitrary portion of a record, specified by its offset and length. Specify the length of the record (or record chunk) in bytes. Specifying a value higher than you need does not improve performance and may waste memory.

NOTE: For applications running on workstations, the maximum record length is 57,000 for the DOS Requester, 65,000 for the OS/2 Requester, and 57,000 for the MS Windows Requester.

Largest Page Size

Range: 512 through 4,096 bytes

Default: 4,096 bytes

Approximate Memory Required: Not applicable

This option specifies the maximum page size (in bytes) of any Btrieve file you want to access. The page size must be an even multiple of 512 bytes, but no greater than 4,096 bytes.

Setting the page size to 512, 1,024, 2,048, or 4,096 can improve performance because these page sizes correspond to disk block sizes. However, if you set the page size to 1,536, 2,560, 3,072, or 3,584, a given disk read may span two disk blocks and therefore require two disk accesses per page.

NOTE: NetWare Btrieve specifies that 6.0 and 6.1x files with a page size of 512 can be no larger than 2 gigabytes in size but does not enforce this limit. Therefore, when a file grows beyond the 512 page-size limit, NetWare Btrieve returns Status Code 132 (The file is full).

Number of Remote Sessions

Range: 1 through 64,000 sessions

Default: 15 sessions

Approximate Memory Required: 150 bytes * number of remote sessions

This option specifies the maximum number of SPX sessions that can access the remote Btrieve NLM at one time. (A session occurs when a client uses the Btrieve Requester or the Message Router to communicate with the remote Btrieve NLM.)

Each session is allocated two packet buffers for Btrieve requests.

NOTE: If you receive a Status Code 96 (A communications environment error occurred), increase the value for this option. However, do not specify a value higher than you need. Specifying a value that is too high does not improve performance; instead, it uses memory that NetWare or other processes might need.

Cache Allocation

Range: 32 through 64,000 KB

Default: 512 KB

Approximate Memory Required: Not applicable

This option specifies the size of the cache (in kilobytes) that Btrieve allocates.

To achieve best performance, allocate a cache size equal to the sum of the sizes of the files you are using. However, be careful not to take all available cache, especially if the server is running other applications. You cannot improve performance, and may waste memory, by specifying a value higher than you need.

Perform Index Balancing

Range: Yes or No

Default: No

Approximate Memory Required: Not applicable

When an index page becomes full, Btrieve automatically creates a new index page and splits the values in the full index page between the two index pages. The Perform Index Balancing option lets you avoid creating a new index page every time an old one fills up.

If you specify Yes for this option, Btrieve looks for available space in sibling index pages each time an index page becomes full. Btrieve then rotates values from the full index page into the pages that have space available.

Index balancing increases key page utilization, results in fewer index pages, and produces an even distribution of keys among nodes on the same level, thus increasing performance during Get operations.

However, when you specify Yes for this option, Btrieve requires extra time to examine more index pages and may require more disk I/O during insert, update, and delete operations.

NOTE: You can also specify index balancing on a file-by-file basis by setting a bit in the file flag's word when the file is created. If you specify Yes to the "Perform Index Balancing" option, Btrieve performs index balancing on every file regardless of the balanced file flag specification.

Logging of Selected Files

Range: Yes or No

Default: No

Approximate Memory Required: Not applicable

This option controls whether Btrieve logs operations executed on selected files.

If you specify Yes, Btrieve logs all operations that change any file listed in the BLOG.CFG file on Btrieve's server volume. If you specify No, Btrieve performs no logging.

NOTE: You specify the files you want Btrieve to log by adding entries to a \BLOG\BLOG.CFG file that you create on the drive that contains the files. If your files are on multiple drives, create a BLOG.CFG file for each drive. The entries in the log file can be in either pre-6.x or 6.x file format.

For more information about logging and using the Roll Forward utility, see "NetWare Btrieve Roll Forward Utility" in Chapter 5, "Using NetWare Btrieve Utilities."

Create Btrieve Files in Pre v6.x Format

Range: Yes or No

Default: No

Approximate Memory Required: Not applicable

This option specifies that all files be created in a Btrieve version prior to 6.x.

Use this option only if you need backward compatibility with a previous version of Btrieve. For example, if you want to create files with Btrieve 6.x and you want to use those files with Btrieve 5.x, specify Yes for this option.

NOTE: Btrieve 6.x can read files that previous versions of Btrieve created. In addition, it can write to files using the existing file format. In other words, it writes to 5.x files using the 5.x format and writes to 6.x files using the 6.x format.

Create Files as Transactional

Range: Yes or No

Default: No

Approximate Memory Required: Not applicable

This option controls whether Btrieve automatically flags each file as transactional when you create it.

The transactional flag indicates that the NetWare Transaction Tracking System^TM (TTS^TM) is protecting the file. TTS ensures that, when a file is being modified, either all changes are made or no changes are made, thus preventing data damage.

Configure BSTART.NCF to Load BROUTER

Range: Yes or No

Default: No

Approximate Memory Required: Not applicable

This option controls whether the Message Router is loaded during the execution of the BSTART.NCF NetWare command file.

The Message Router allows other NLMs (such as Scalable SQL) to communicate with remote servers on which Btrieve is loaded. If you want to access Btrieve data on a remote server, specify Yes for this option.

NOTE: BROUTER.NLM is the default Message Router that is loaded through the NetWare INSTALL utility. If you want Directory Services support, you need to unload BROUTER.NLM and load BDROUTER.NLM.

Running the Setup Utility

Use the Setup utility to set the NetWare Btrieve configuration options interactively. The utility automatically checks to see if the values you enter are within the correct ranges.

You can run the Setup utility either at the server console or at a workstation running the NetWare Remote Console utility (RCONSOLE). To run the Setup utility, complete the following steps:

NOTE: To get help with the Setup utility, press F1. The help information is context sensitive, relevant to your location in the program. To exit the utility, press the Esc key.

1. Enter the following command at the prompt to start the utility:

   load bsetup

   NOTE: If your SYS:SYSTEM directory does not contain the BSTART.NCF command file, the Setup utility displays a window asking if you want to create it. If that window appears on your screen, create the BSTART.NCF file at this time.

   The Available Options menu appears.
   

   This menu provides the following options:

   • Set Btrieve Configuration---Use this option to view or modify the current configuration options for NetWare Btrieve, as described in this procedure.
   • Set Rebuild Configuration---Use this option to run the Rebuild utility, view or modify the current Rebuild configuration options, and view the Rebuild log file. ( "Rebuilding Existing NetWare Btrieve Files" discusses the Rebuild utility and its configuration options.)
   • Set Directory Services---Use this option to install or remove a Btrieve Server object from the Directory. ( "Registering NetWare Btrieve with the Novell Directory Services" discusses using the NDS utility.)

2. To change configuration options, select the first available option, Set Btrieve Configuration.

   The Current Btrieve Configuration screen, shown in Figure 8, appears.

   Figure 8. Setup: Current Btrieve Configuration Screen
   

3. Use the Up- and Down-Arrow keys to highlight the configuration option you want to change, and press the Enter key.

   A flashing cursor, shown in Figure 8 highlighting the first configuration option (Number of Open Files), appears.

4. Use the Backspace key to remove the old value, type the new value, and press Enter.

   If you enter an invalid value for an option, the utility displays a message indicating the valid values.

   NOTE: To see the valid values for any option, move the cursor to that option, press Enter, and then press F1. Refer to "Configuration Options" for more information about these options and their values.

5. Repeat Steps 3 and 4 until you have changed all the options you want to modify.

6. When you are ready to exit the Current Btrieve Configuration screen, press the Esc key.

7. When the Save Configuration Changes? screen appears, select Yes to save your changes or No to back out of the screen without changing the values.

   If you select Yes, the Setup utility writes the configuration values you specified to the BSTART.NCF file.

   IMPORTANT: Do not edit the BSTART.NCF command file for Btrieve. Always use the Setup utility to make any modifications to the configuration values in the BSTART.NCF file.

   IMPORTANT: Before your configuration changes can take effect, you must unload the existing Btrieve NLM, BSPXCOM, Message Router, and BDIRECT (using the BSTOP command, described in the following section), and then reload them by entering the BSTART command.

   IMPORTANT: BSTOP.NCF does not unload BSPXSTUB, RSPXSTUB, or BDROUTER. To unload these modules, enter the UNLOAD command followed by the module name.

8. To exit the Setup utility, press the Esc key until the Exit window appears, and then select Yes in responde to the prompt.