#EDIR DATA#
Btrieve Installation and OperationDisclaimerNovell®, Inc. makes no representations or warranties with respect to the contents or use of this manual, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.Further, Novell, Inc. makes no representations or warranties with respect to any NetWare software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to make changes to any and all parts of NetWare software, at any time, without any obligation to notify any person or entity of such changes.TrademarksBtrieve, DR DOS, EXOS, LANalyzer, NetWare, OnLan/PC, Novell, and the N design are registered trademarks of Novell, Inc.Advanced NetWare, Boot Support Module, BSM, ElectroText, Hardware Specific Module, Hot Fix, HSM, Internetwork Packet Exchange, LAN Service, Link Support Layer, LSL, Media Support Module, MSM, Multiple Link Interface, MLI, Multiple Link Interface Driver, MLID, Multiple Protocol Interface, MPI, NetWare Access Server, NetWare Access Services, NetWare Core Protocol, NCP, NetWare Directory Services, NDS, NetWare DOS Requester, NDR, NetWare Express, NetWare Loadable Module, NLM, NetWare Management Agent, NetWare MultiProtocol Router, NetWare NFS, NetWare Requester, NetWare RPC, NetWare Runtime, Network Support Encyclopedia, NetWare 3270 LAN Workstation, NetWare 3270 LAN Workstation for DOS, NetWare 3270 LAN Workstation for Windows, NLM, NE/2, NE/2-32, NE1000, NE1500T, NE2000, NE2100, NE3200, NE32HUB, Novell Labs, Novell Virtual Terminal, NVT, NTR2000, Open Data-Link Interface, ODI, Packet Burst, RX-Net/2, SFT, Topology Specific Module, TSM, TSA, Transaction Tracking System, TTS, Turbo RX-Net, Virtual Loadable Module, and VLM are trademarks of Novell, Inc.NetWire is a service mark of Novell, Inc.Novell Authorized Reseller is a collective mark of Novell, Inc.3Com and 3+Share are registered trademarks of 3Com Corporation.ARCnet is a registered trademark of Datapoint Corporation.AT&T is a registered trademark of AT&T.Apple, AppleShare, AppleTalk, ImageWriter, LaserWriter, LocalTalk, and Macintosh are registered trademarks of Apple Computer, Inc.Citizen is a registered trademark of Tokei Kabushiki Kaisha.COMPAQ is a registered trademark of Compaq Computer Corporation.CompuServe is a registered trademark of CompuServe, Inc.DDS is a trademark of Sony Corporation.DEC is a trademark of Digital Equipment Corporation.Epson is a registered trademark of Seiko Epson Corporation.GE Information Services is a trademark of General Electric Company, USA, which is not connected with the General Electric Company p.l.c. of England.Hayes is a registered trademark of Hayes Microcomputer Products, Inc.Hewlett-Packard, Deskjet, HP, Laserjet, PCL, and Vectra are registered trademarks of Hewlett-Packard Company.IBM, AT, Micro Channel, NetView, OS/2, ProPrinter, and PS/2 are registered trademarks of International Business Machines Corporation.IBM Operating System/2 Local Area Network Server (LAN Server), Presentation Manager, SAA, and XT are trademarks of International Business Machines Corporation.Intel is a registered trademark of Intel Corporation.LAN Manager and LAN Manager Server are trademarks of Microsoft Corporation.Lotus is a registered trademark of Lotus Development Corporation.Microsoft and MS-DOS are registered trademarks of Microsoft Corporation.NFS is a registered trademark of Sun Microsystems, Inc.Okidata and Microline are registered trademarks of Oki Electric Industry Co., Ltd.Panasonic is a registered trademark of Panasonic Office Automation.Pinwriter, Spinwriter, and NEC are registered trademarks of NEC Corporation.PostScript is a registered trademark of Adobe Systems Incorporated.SDI is a registered trademark of Systems Data, Inc.SQL Server is a trademark of Sybase, Inc.Unicode is a registered trademark of Transoft Ltd.UNIX is a registered trademark of UNIX System Laboratories, Inc., a subsidiary of AT&T.WordPerfect is a registered trademark of WordPerfect Corporation.Xerox Diablo is a registered trademark of Xerox Corporation.Copyright Notices© Copyright 1983-1993 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.Novell, Inc.122 East 1700 SouthProvo, UT 84606U.S.A.LBL="0"ID="FM30949"About This ManualThis manual contains information on installing, configuring, executing, and monitoring the Btrieve(tm) record management system with the NetWare® v3.12 operating system. Btrieve is a complete key-indexed record management system designed for high-performance data handling and improved programming productivity.Novell would appreciate your comments and suggestions about this manual. Once you have become familiar with the manual, please complete the User Comments form that appears at the back. You may respond by fax or mail. Who Should Read This ManualThis manual provides information for systems administrators who are responsible for maintaining Btrieve databases on a network. This manual is also useful to programmers, systems developers, and systems integrators who are using Btrieve to develop workstation applications and NetWare Loadable Modules(tm) (NLMs(tm)) for the NetWare operating environment.OrganizationIDREF="FM10941"Chapter 1---Introduction to BtrieveThis chapter discusses Btrieve's client-server design, features, and v6.x enhancements.IDREF="FM24972"Chapter 2---Btrieve ArchitectureThis chapter describes the components of Btrieve and how Btrieve works with server and workstation applications. It also provides diagrams that illustrate how different applications use different Btrieve components.IDREF="FM13326"Chapter 3---Installing and Configuring BtrieveThis chapter describes installing, configuring, loading, and unloading Btrieve from the server console and from the workstation. It also discusses rebuilding existing Btrieve files to take advantage of Btrieve v6.x features. The chapter concludes with a discussion of using Btrieve with the NetWare Runtime(tm) serialized NetWare operating system.IDREF="FM41779"Chapter 4---Configuring and Using the RequestersThis chapter provides configuration options and instructions for loading and unloading the Btrieve Requester in the DOS, OS/2, and Windows environments.IDREF="FM11326"Chapter 5---Using Btrieve UtilitiesThis chapter describes the utilities available to monitor and maintain your database, either from the server console or from workstations on the network. IDREF="FM18833"Appendix A---Description FilesThis appendix explains the rules for creating description files, provides a description file example, and describes the individual description file elements.IDREF="FM17204"Appendix B---Status Codes and MessagesThis appendix lists and explains the Btrieve status codes and messages you may encounter while loading or running Btrieve applications.IDREF="FM32913"Appendix C---GlossaryIndexNotational ConventionsThis manual uses the conventions described in the following sections to present information.Icons idxid="w2244"book="_idx" docset="nw312" tidref="i1244"A Note points out an item that may be of interest but is not vital to the operation of the product.A Suggestion denotes a hint, a tip, or other information that may be helpful but is not critical.An Important denotes important information that you should read.Typography idxid="w2245"book="_idx" docset="nw312" tidref="i1244"Unless otherwise noted, command syntax, code, and code examples use the following conventions:WIDTH="60"CaseWIDTH="240"Commands and reserved words typically appear in  uppercase letters. Unless the manual states  otherwise, you can enter these items using  uppercase, lowercase, or both. For example, you can  type MYPROG, myprog, or MYprog.[ ]Square brackets enclose optional information, as in  [logName]. If information is not enclosed in square  brackets, it is required.|A vertical bar indicates an "either-or" choice of  information to enter, as in [filename|  @filename].< >Angle brackets enclose multiple choices for a  required item, as in <filename| @filename>.variableWords appearing in italics are variables that you  must replace with appropriate values, as in filename....An ellipsis following information indicates you can  repeat the information more than one time, as in [parameter...].Associated DocumentsThis manual explains how to install Btrieve and use the Btrieve utilities in a NetWare environment. For information about developing Btrieve applications, refer to the Btrieve Programmer's Manual (available only as part of the Btrieve Developer's Kit).Registering Your ProductYou are important to us, and it's important for us to know who our customers are. Registering your Novell database product enables us to provide you with better service and important notifications about your product. Please take a moment to complete the pre-addressed NetWare Product Registration Card included with this product and return it to us. If you need to contact us by mail, telephone, or fax, refer to IDREF="FM32110""Contacting Novell" on page xviii.Where to Get HelpNovell offers support through a wide range of programs. This section lists sources of help that are available for the Novell Database Products line.Telephone Technical Support idxid="w2246"book="_idx" docset="nw312" tidref="i6598"idxid="w2247"book="_idx" docset="nw312" tidref="i6760"Novell's telephone technical support program provides helpful information about getting the best results from your Novell product. Refer to IDREF="FMConta"page xviii for information about contacting Novell for technical support. If you are contacting Novell for a follow-up on a previous technical support issue, please be ready to provide your open call reference number.International Technical Support idxid="w2248"book="_idx" docset="nw312" tidref="i6598"idxid="w2249"book="_idx" docset="nw312" tidref="i2939"idxid="w2250"book="_idx" docset="nw312" tidref="i6760"International customers may find the Direct Connect SMFax International program useful. This program provides priority handling of fax support, which allows international customers to obtain technical support without worrying about high telephone costs and time zone differences. Novell encourages customers who reside outside the continental United States and Canada to contact their local Novell office or Novell authorized reseller for more information about international support options. The table on IDREF="FM32110"page xviii provides the fax number for international technical support.Education and Training idxid="w2251"book="_idx" docset="nw312" tidref="i6860"You can contact the Novell Education department (see IDREF="FMConta"page xviii) for information about specific courses and training available for users of Novell products.Product InformationThe Developer Relations group at Novell Austin (see IDREF="FMConta"page xviii) can provide information about Novell Database Products, technical support programs, and the Novell Professional Developers' Program. You can request detailed product information from the automated fax system or speak to a trained technician about product announcements, pricing, compatibility, services, and developer issues.Professional Developers' Program idxid="w2252"book="_idx" docset="nw312" tidref="i1401"idxid="w2253"book="_idx" docset="nw312" tidref="i6598"The Novell Professional Developers' Program provides programming tools and development support for developers who wish to take advantage of the features of Novell's software on any of the available platforms (NetWare operating system, communications, or database). By enrolling in this program, developers gain access to the latest programming tools. For information about enrolling, contact Novell Developer Relations (see IDREF="FMConta"page xviii).CompuServe ForumYou can find information about Novell Database Products under the NetWireSM section on CompuServe. NetWire provides 24-hour-a-day electronic information services. You can obtain the most recent online technical notes, problem reports and fixes, product news, and other helpful information. You can also post technical questions and receive answers from our technical support staff.If you already have a CompuServe account, type the following to access the NetWire section:  go novellFor information about subscribing to CompuServe, contact CompuServe, Inc. at 1-800-848-8199 (or 1-614-457-0802 in Ohio or outside the U.S. and Canada).ID="FM32110"Contacting Novell idxid="w2254"book="_idx" docset="nw312" tidref="i1229"Novell has established a comprehensive services strategy to support all network users and systems---small or large, domestic or international. We welcome hearing from you. The mailing address for Novell Austin is as follows:FILE="n312b60a.pbm"To contact us by telephone or fax, refer to the following table for the appropriate numberID="FMConta".WIDTH="108"ForWIDTH="96"TelephoneWIDTH="84"FaxWIDTH="108"Technical Support,   International Technical   Support, Developer  Relations, or Product  Information*WIDTH="96"1-800-NETWARE (1-800-638-9273)  or 1-801-429-5588  outside the U.S.WIDTH="84"1-512-794-1775Education Information1-800-233-EDUC (1-800-233-3382)  or 1-801-429-5508  outside the U.S.1-801-429-3900General Inquiries1-512-346-83801-512-345-7478WIDTH="312"* International customers can contact their local reseller for Novell  Database Products information and their local Novell office for  information about the Professional Developers' Program.LBL="1"ID="FM10941"Introduction to BtrieveThe Btrieve key-indexed record management system is designed for high-performance data handling and improved programming productivity. Btrieve allows your application to retrieve, insert, update, or delete records either by key value or by sequential or random access methods.Client-Server DesignBtrieve products include server-based Btrieve (also called NetWare Btrieve(tm)) and client-based Btrieve. In most cases, applications written for client-based Btrieve can run on server-based Btrieve and vice versa.Server-based Btrieve is provided with the NetWare operating system and includes the following:Server-based Btrieve Record Manager, which runs at the server and manages data I/O with the file system.Btrieve communications programs, which handle incoming requests from a remote source and which can route requests from a server-based application to a copy of the Record Manager running on a remote server.Btrieve Requesters, which run at the workstation and handle data I/O between the workstation and the server. The Requesters allow applications running at the workstation to communicate transparently with the Record Manager. Btrieve Requesters are available for DOS, OS/2, Windows, and UnixWare(tm) workstations.Btrieve utilities, which provide setup, rebuild, monitor, maintenance, and recovery programs for Btrieve users and files.This manual, which documents using Btrieve in a NetWare environment.Client-based Btrieve is available only as part of a Btrieve Developer's Kit (DOS, OS/2, or Windows), which must be purchased separately. Each Btrieve Developer's Kit includes the following:Client-based Record Manager for the applicable environment (DOS, OS/2, or Windows). The client-based Record Manager executes all processing on the workstation. It accesses all files through operating system calls. The operating system calls are either executed locally (for local files) or redirected to the server (for files on the server). Btrieve utilities, which provide setup, rebuild (Btrieve v5.x to v6.x files), monitor, maintenance, and recovery programs for Btrieve users and files.An installation and operation manual, which documents using Btrieve in the applicable environment (DOS, OS/2, or Windows).Btrieve Programmer's Manual, which documents the Application Programming Interface (API) and the language interfaces that allow Btrieve to be called from various programming languages.Btrieve Features idxid="w2255"book="_idx" docset="nw312" tidref="i794"The following sections introduce some of the features that make Btrieve a uniquely powerful record management system. Index Maintenance idxid="w2256"book="_idx" docset="nw312" tidref="i1982"idxid="w2257"book="_idx" docset="nw312" tidref="i2801"Btrieve automatically creates and maintains file indexes as records are inserted, updated, and deleted. In addition to automatic index maintenance, Btrieve supports the following index features:Up to 119 key segments per fileAdding or dropping any index after a file has been createdNumerous data types for key values: integer, float, date, time, decimal, money, logical, numeric, bfloat, string, lstring, zstring, unsigned binary, autoincrement, and sign trailing separateNumerous key attributes: linked/repeating duplicatable,  duplicatable/nonduplicatable, supplemental, modifiable/nonmodifiable, segmented/nonsegmented, descending/ascending sorting, case-sensitive/case-insensitive sorting, alternate collating sequence, null (any-segment/all-segment)/non-nullFile Specifications idxid="w2258"book="_idx" docset="nw312" tidref="i1982"idxid="w2259"book="_idx" docset="nw312" tidref="i2300"Btrieve offers these file specifications:idxid="w2260"book="_idx" docset="nw312" tidref="i2300"File sizes up to 4 billion bytes (4 gigabytes)Number of records limited only by the size limit of the fileConsistent file definition and management routines independent of the operating environmentConsistent file structuresidxid="w2261"book="_idx" docset="nw312" tidref="i3788"idxid="w2262"book="_idx" docset="nw312" tidref="i1982"Memory ManagementThe cache is an area of memory Btrieve reserves for buffering the pages that it reads. When your application requests a record, Btrieve first checks the idxid="w2263"book="_idx" docset="nw312" tidref="i875"cache to see if the page containing that record is already in memory. If so, Btrieve transfers the record from the cache to your application's data buffer. If the page is not in the cache, Btrieve reads the page from the disk into a cache buffer before transferring the requested record to your application.idxid="w2264"book="_idx" docset="nw312" tidref="i3197"idxid="w2265"book="_idx" docset="nw312" tidref="i191"idxid="w2266"book="_idx" docset="nw312" tidref="i3593"If every cache buffer is full when Btrieve needs to transfer a new page into memory, a least-recently-used (LRU) algorithm determines which page in the cache Btrieve should overwrite. The LRU algorithm reduces processing time by keeping the most recently referenced pages in memory.When your application inserts or updates a record, Btrieve first modifies the corresponding page in the cache and then writes that page to disk. The modified page remains in the cache until the LRU algorithm determines that Btrieve can overwrite the image of that page in cache with a new page.Generally, a larger cache improves performance because it allows more pages to be in memory at a given time. Btrieve allows you to specify the amount of memory to reserve for the I/O cache buffers. To determine this amount of memory, consider your application's memory requirements (if your application is an NLM), the total amount of memory installed on your server, and the combined size of all files your application will access. idxid="w2267"book="_idx" docset="nw312" tidref="i2910"idxid="w2268"book="_idx" docset="nw312" tidref="i1982"Data IntegrityThe following Btrieve features let you support concurrent access while ensuring the integrity of your files in a multiuser environment:Single-record and multiple-record locks.Concurrent and exclusive transactions. (See IDREF="FM14274""Concurrent Transactions" on page 1-9.)Deadlock detection (in a server-based environment).Shadow paging, which entails making changes to a copy of a page rather than to the original page when inserting, updating, or deleting a record. (See IDREF="FM25219""Shadow Paging" on page 1-10.)Logging feature, which records (in a log file) any changes made to a designated file.Roll Forward utility, which uses log files maintained by Btrieve's logging feature to recover data corrupted by a system or server failure.idxid="w2269"book="_idx" docset="nw312" tidref="i1302"idxid="w2270"book="_idx" docset="nw312" tidref="i6199"idxid="w2271"book="_idx" docset="nw312" tidref="i1982"Security ControlsBtrieve provides the following capabilities for enhancing idxid="w2272"book="_idx" docset="nw312" tidref="i1302"data security in a network environment:Assigning owner names to files idxid="w2273"book="_idx" docset="nw312" tidref="i4865"Specifying dynamic encryption and decryption of data idxid="w2274"book="_idx" docset="nw312" tidref="i1302"Providing NetWare file-level security (provided through the Btrieve Requesters)Btrieve EnhancementsBtrieve v6.x provides several new features and performance enhancements that support the requirements of today's powerful database management systems. The following sections describe these enhancements.The first section describes the enhancements that apply only to Btrieve v6.1. The second section describes enhancements that apply to Btrieve v6.x (that is, to both v6.0 and v6.1).idxid="w2275"book="_idx" docset="nw312" tidref="i794"Btrieve v6.1 EnhancementsThis section describes enhancements to Btrieve v6.1.Support for Operating on a Portion of a Record: Chunks idxid="w2276"book="_idx" docset="nw312" tidref="i794"Btrieve v6.1 allows you to operate on portions of a record, called chunks, rather than on the entire record. This enhancement provides new chunk operations that work on any file conforming to the Btrieve v6.x file format.New Operations to Support Records Larger than 64 KB idxid="w2277"book="_idx" docset="nw312" tidref="i794"Through the Get Direct/Chunk (23) and Update Chunk (53) operations, Btrieve v6.1 supports records larger than 64 KB. Applications can use chunk operations to build records larger than 64 KB in any Btrieve v6.x file that allows variable-length records.New File Structure to Support Very Long RecordsBtrieve v6.1 also allows an application to create Btrieve files that contain structures called Variable-Tail Allocation Tables (VATs) idxid="w2278"book="_idx" docset="nw312" tidref="i794"idxid="w2279"book="_idx" docset="nw312" tidref="i7278". VATs give 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.Multiple Alternate Collating Sequences idxid="w2280"book="_idx" docset="nw312" tidref="i794"idxid="w2281"book="_idx" docset="nw312" tidref="i3970"idxid="w2282"book="_idx" docset="nw312" tidref="i1008"Btrieve v6.1 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.Locale-Sensitive Collating Sequences idxid="w2283"book="_idx" docset="nw312" tidref="i794"idxid="w2284"book="_idx" docset="nw312" tidref="i3351"Btrieve v6.1 can 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. Index Balancing idxid="w2285"book="_idx" docset="nw312" tidref="i794"idxid="w2286"book="_idx" docset="nw312" tidref="i2801"When an index page becomes full, Btrieve automatically creates a new index page and splits the values in the full page between the two pages. Btrieve v6.1 now offers the option of using index balancing instead.When you use index balancing, 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 into 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.Performing Reads While Creating an Index idxid="w2287"book="_idx" docset="nw312" tidref="i794"idxid="w2288"book="_idx" docset="nw312" tidref="i1289"idxid="w2289"book="_idx" docset="nw312" tidref="i2801"With Btrieve v6.1, 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 operation.New Data Type idxid="w2290"book="_idx" docset="nw312" tidref="i794"idxid="w2291"book="_idx" docset="nw312" tidref="i1302"idxid="w2292"book="_idx" docset="nw312" tidref="i6344"Btrieve v6.1 allows you to specify a new data type for keys called sign trailing separate (STS). STS is a COBOL data type. Basically a numeric data type, it is represented as an ASCII string that is right-justified and padded with zeros.Percentage Operations idxid="w2293"book="_idx" docset="nw312" tidref="i794"idxid="w2294"book="_idx" docset="nw312" tidref="i5064"idxid="w2295"book="_idx" docset="nw312" tidref="i6155"Btrieve v6.1 provides two new operations that a window-oriented application can use for implementing scroll bars:The Find Percentage (45) operation finds either a record's physical location within a file, or the record's position relative to a key path. The location or position is expressed as a percentage value.The Get By Percentage (44) operation retrieves a record by that record's position in the Btrieve file, where the position is based on a percentage value you supply when you call the operation. You can specify whether the position is relative to a specified key path or represents the record's actual physical location in the file.No Currency Change Option idxid="w2296"book="_idx" docset="nw312" tidref="i794"idxid="w2297"book="_idx" docset="nw312" tidref="i4643"Btrieve v6.1 provides a No Currency Change option on inserts and updates. In previous versions of Btrieve, positioning was reestablished based on the key value of the inserted or updated record.New Ability to Specify Repeating- or Linked-Duplicatable Keys on Create Operations idxid="w2298"book="_idx" docset="nw312" tidref="i794"idxid="w2299"book="_idx" docset="nw312" tidref="i3038"idxid="w2300"book="_idx" docset="nw312" tidref="i5861"idxid="w2301"book="_idx" docset="nw312" tidref="i5861"On the Create (14) and Create Index (31) operations, Btrieve v6.1 allows you to specify a key as either a repeating-duplicatable key or a linked-duplicatable key.Improved Btrieve Requesters idxid="w2302"book="_idx" docset="nw312" tidref="i794"The Btrieve DOS and OS/2 Requesters now support MAP ROOT drives and NetWare file-level security. Since the Windows Requester requires the DOS Requester, Windows users can also take advantage of these features. When opening files in a NetWare v3.12 environment, Btrieve Requesters provide enhanced performance by reducing the bindery access for each file and reducing network traffic in general.The Btrieve v6.1 Requesters have three new features:Automatic support for double-byte character environments idxid="w2303"book="_idx" docset="nw312" tidref="i5873"Support for the NetWare Runtime serialized NetWare operating system idxid="w2304"book="_idx" docset="nw312" tidref="i5865"Optional compression of data prior to network transmission idxid="w2305"book="_idx" docset="nw312" tidref="i5865"Btrieve now provides a requester for the UnixWare environment. For information about this new UnixWare Requester, please refer to the Readme file that accompanies this release idxid="w2306"book="_idx" docset="nw312" tidref="i5865".Btrieve 6.x Enhancements idxid="w2307"book="_idx" docset="nw312" tidref="i794"This section describes ehancements that apply to Btrieve v6.x (that is, v6.0 and v6.1).New File Format idxid="w2308"book="_idx" docset="nw312" tidref="i794"idxid="w2309"book="_idx" docset="nw312" tidref="i2300"When creating files, Btrieve v6.x uses a new file format that allows faster data access than was possible with previous Btrieve versions. This format, introduced in Btrieve v6.0 and modified slightly in Btrieve v6.1, is responsible for many of the enhancements and new features available with these releases.Btrieve v6.0 operates on any file created with Btrieve v6.1 unless that file uses v6.1 features that have altered the Btrieve file format (such as multiple ACSs and VATs).Btrieve versions earlier than v6.x cannot open files that have a v6.x format. However, Btrieve v6.x can open files created with earlier versions of Btrieve. When Btrieve v6.x opens files from earlier versions, it does not convert the files to the v6.x file format.The Create Btrieve Files in Pre v6.x Format configuration option is   useful if you must use newly created files with versions of Btrieve earlier than v6.0.idxid="w2310"book="_idx" docset="nw312" tidref="i794"idxid="w2311"book="_idx" docset="nw312" tidref="i4820"Online BackupsThrough a feature called continuous operation, Btrieve v6.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 each original file in read-only, shareable 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 then deletes the temporary delta file.ID="FM14274"Concurrent Transactions idxid="w2312"book="_idx" docset="nw312" tidref="i794"idxid="w2313"book="_idx" docset="nw312" tidref="i1111"idxid="w2314"book="_idx" docset="nw312" tidref="i6875"Versions of Btrieve earlier than v6.0 support only one type of transaction: exclusive idxid="w2315"book="_idx" docset="nw312" tidref="i6875". 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 lockingidxid="w2316"book="_idx" docset="nw312" tidref="i2289". 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. If the file uses a Btrieve v6.x format, other users will not see changes that occur during the transaction until that transaction ends. (If the file uses the format of versions of Btrieve earlier than v6.x, other users can see such changes.)In addition to supporting exclusive transactions, Btrieve v6.x supports a new type of transaction: concurrent. Concurrent transactions allow one or more applications to run multiple transactions simultaneously for the same Btrieve file (if the file uses the Btrieve v6.x format). When a Btrieve v6.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 idxid="w2317"book="_idx" docset="nw312" tidref="i6875"idxid="w2318"book="_idx" docset="nw312" tidref="i1111":Locked pages remain locked for the duration of the transaction.If the transaction simply reads a record, Btrieve does not lock the corresponding page (unless a read lock is applied).Other users can read the data on the locked pages, but they cannot lock the pages (by updating or applying an explicit read lock).Other users cannot see the changes to a file in a transaction until the transaction ends. (That way, if a system failure occurs before the transaction completes, other users will not have read false data---that is, data that will be rolled back.)For compatibility, Btrieve v6.x  supports exclusive transactions, but with one difference from previous versions: if the exclusive transaction affects Btrieve v6.x files, other users cannot see the changes to those files until the transaction ends.ID="FM25219"Shadow Paging idxid="w2319"book="_idx" docset="nw312" tidref="i794"idxid="w2320"book="_idx" docset="nw312" tidref="i6325"With Btrieve file versions earlier than v6.0, Btrieve uses pre-imaging idxid="w2321"book="_idx" docset="nw312" tidref="i2300"idxid="w2322"book="_idx" docset="nw312" tidref="i5132" to protect files from corruption in case of a system failure. Before updating a file, 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.A new Btrieve v6.x page handling technique called shadow paging has replaced 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 within the same Btrieve file. Btrieve then makes the changes to the shadow page instead of to the original. 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. With shadow paging, each user works with a virtual copy of the page. Consequently, two users can access the same logical page, and neither user sees the other user's changes until the operation or transaction is complete. Also, shadow paging enhances reliability because the original file is always valid and internally consistent.New Caching Algorithm idxid="w2323"book="_idx" docset="nw312" tidref="i794"idxid="w2324"book="_idx" docset="nw312" tidref="i191"idxid="w2325"book="_idx" docset="nw312" tidref="i898"Btrieve v6.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 an existing cache across operations.idxid="w2326"book="_idx" docset="nw312" tidref="i794"idxid="w2327"book="_idx" docset="nw312" tidref="i2300"idxid="w2328"book="_idx" docset="nw312" tidref="i3160"idxid="w2329"book="_idx" docset="nw312" tidref="i1966"Better Usage of Large Data FileBtrieve v6.x provides faster access to and more efficient use of large data files. With Btrieve v6.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. ID="FM25437"idxid="w2330"book="_idx" docset="nw312" tidref="i794"idxid="w2331"book="_idx" docset="nw312" tidref="i3038"Up to 119 Key Segments idxid="w2332"book="_idx" docset="nw312" tidref="i794"idxid="w2333"book="_idx" docset="nw312" tidref="i3038"Btrieve v6.x supports up to 119 key segments in files with a page size of 4,096 bytes. The maximum number of key segments you can define for a file depends on the file's page size idxid="w2334"book="_idx" docset="nw312" tidref="i2300". Versions of Btrieve earlier than v6.0 supported a maximum of 24 key segments. Adding and Dropping Any Index idxid="w2335"book="_idx" docset="nw312" tidref="i794"idxid="w2336"book="_idx" docset="nw312" tidref="i2801"idxid="w2337"book="_idx" docset="nw312" tidref="i154"Btrieve v6.x supports adding and dropping any index. (In versions of Btrieve earlier than v6.0, you could add and drop only supplemental indexes.) Also, you can drop indexes without renumbering the remaining indexes.Specific Key Numbers Allowed When Creating a File or Index idxid="w2338"book="_idx" docset="nw312" tidref="i794"idxid="w2339"book="_idx" docset="nw312" tidref="i2300"idxid="w2340"book="_idx" docset="nw312" tidref="i2801"Btrieve v6.x allows an application to assign specific key numbers when creating a v6.x format file with indexes, or when creating an index for a preexisting v6.x file.Optional Renumbering of Keys idxid="w2341"book="_idx" docset="nw312" tidref="i794"idxid="w2342"book="_idx" docset="nw312" tidref="i4847"idxid="w2343"book="_idx" docset="nw312" tidref="i3038"With Btrieve v6.x, the Drop Index (32) operation allows an application to specify whether to renumber the remaining keys when dropping an index from a Btrieve file. (The file must use the Btrieve v6.x format.)Enhanced Support for Case-Insensitive Keys idxid="w2344"book="_idx" docset="nw312" tidref="i794"idxid="w2345"book="_idx" docset="nw312" tidref="i3038"idxid="w2346"book="_idx" docset="nw312" tidref="i619"With Btrieve v6.x, you can create case-insensitive keys without using an alternate collating sequence. When creating a file, you can use the key specifications to specify case-insensitive keys. With case-insensitive keys, the letter a is sorted the same as the letter A.Enhancement to autoincrement Key idxid="w2347"book="_idx" docset="nw312" tidref="i794"idxid="w2348"book="_idx" docset="nw312" tidref="i3038"In Btrieve v6.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. Reserved Space for Duplicate Pointers idxid="w2349"book="_idx" docset="nw312" tidref="i794"idxid="w2350"book="_idx" docset="nw312" tidref="i5102"idxid="w2351"book="_idx" docset="nw312" tidref="i1755"Btrieve v6.x allows reserving duplicate pointers on data records for linked duplicate keys. When creating a Btrieve v6.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).ID="FMRead "Key-Only File Modification idxid="w2352"book="_idx" docset="nw312" tidref="i794"idxid="w2353"book="_idx" docset="nw312" tidref="i2300"idxid="w2354"book="_idx" docset="nw312" tidref="i3055"With Btrieve v6.x, you can update and delete records in key-only files. In versions of Btrieve prior to v6.0, you could only insert records.New Stat Option idxid="w2355"book="_idx" docset="nw312" tidref="i794"idxid="w2356"book="_idx" docset="nw312" tidref="i6507"A new option in the Stat (15) operation 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 previous versions of Btrieve.Locking in Extended Operations idxid="w2357"book="_idx" docset="nw312" tidref="i794"idxid="w2358"book="_idx" docset="nw312" tidref="i1944"idxid="w2359"book="_idx" docset="nw312" tidref="i3383"Unlike previous versions of Btrieve, v6.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).Support for Referential Integrity idxid="w2360"book="_idx" docset="nw312" tidref="i794"idxid="w2361"book="_idx" docset="nw312" tidref="i5777"Btrieve v6.x supports the use of referential integrity (RI) constraints created through Novell's NetWare SQL(tm) 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 NetWare SQL.LBL="2"ID="FM24972"Btrieve ArchitectureIf you are new to Btrieve, you should read this chapter before installing and configuring Btrieve. It provides an introduction to the Btrieve components and how they work with Btrieve applications. If you have used Btrieve before, you may want to skip to the example diagrams of Btrieve architecture, which begin in IDREF="FM40230""Examples of Btrieve Architecture" on page 2-10.This chapter discusses the following topics:IDREF="FM41988"Components of BtrieveIDREF="FM14645"Btrieve Applications on a ServerIDREF="FM15346"Btrieve Applications on a WorkstationIDREF="FM40230"Examples of Btrieve ArchitectureID="FM41988"Components of BtrieveThe major components of server-based Btrieve are as follows:IDREF="FM32180"Server-Based Record ManagerIDREF="FM33587"Communications ProgramsIDREF="FM19158"Workstation RequestersIDREF="FM42358"Btrieve UtilitiesID="FM32180"Server-Based Record ManagerBtrieve's server-based Record Manager (BTRIEVE.NLM) must be loaded at every server that accesses Btrieve files. The Btrieve NLM consists of a library of Btrieve functions and handles these tasks:Performs disk I/O for Btrieve files at the server where it residesProvides concurrency and integrity controls on the server where it residesLogs all Btrieve requests that result in changes to a file (if logging is enabled for that file)ID="FM33587"idxid="w2362"book="_idx" docset="nw312" tidref="i6454"idxid="w2363"book="_idx" docset="nw312" tidref="i1092"idxid="w2364"book="_idx" docset="nw312" tidref="i6231"Communications ProgramsBtrieve provides the following communications programs:Btrieve Message Router (BROUTER.NLM)BSPXCOM.NLMBSPXSTUB.NLMRSPXSTUB.NLMBtrieve Message RouterThe Btrieve Message Router (BROUTER.NLM) handles outgoing requests from your server to a remote server. The Message Router allows a Btrieve application running as an NLM on the server to communicate with remote servers on which other Btrieve NLMs are loaded. Also, the Message Router maintains transaction concurrency controls during transactions involving Btrieve files on more than one server.If your server-based application needs to access files on another server, you must have the Message Router loaded on your server. When you request files from another server, the Message Router sends that request to BSPXCOM (discussed in the next section) on the remote server. BSPXCOM routes your request to the Btrieve NLM on that server and then sends the response back to the Message Router on your server.BSPXCOMidxid="w2365"book="_idx" docset="nw312" tidref="i788"BSPXCOM handles incoming requests to the Btrieve NLM from a remote source. The remote source could be a Requester at a workstation or the Message Router on another server. BSPXCOM must be loaded on servers that support remote requests. If no workstations or other servers make requests to the Btrieve NLM, you may not want to have BSPXCOM loaded at your server. For example, assume your Btrieve NLM receives calls only from other NLMs running at your server. In this case, you could choose not to load BSPXCOM for security reasons. (Not loading BSPXCOM allows you to restrict applications other than the ones on your server from accessing your Btrieve files.)BSPXSTUB and RSPXSTUBIf you do not load BSPXCOM and want to use the Btrieve Monitor utility, you must load either the BSPXSTUB or RSPXSTUB communications module. These modules resolve external references for the Monitor utility that BSPXCOM would otherwise resolve.Use the following guidelines to determine whether you need BSPXSTUB or RSPXSTUB:If you want to use the Btrieve Monitor utility but do not want to load BSPXCOM, and the NLMs on the server are accessing Btrieve files only on the local server, load BSPXSTUB at the server. If you want to use the Btrieve Monitor utility to monitor outgoing requests generated by the Message Router to another server and you do not want to load BSPXCOM, load RSPXSTUB instead of BSPXSTUB at the server.The Btrieve Monitor utility's Communication Statistics option (discussed in IDREF="FM11326"Chapter 5, "Using Btrieve Utilities") displays SPX communication statistics. The communications module you load affects the statistics displayed. For example, if you load BSPXCOM, you see incoming and outgoing SPX statistics for BSPXCOM. If you load BSPXSTUB, you see all zeros. If you load RSPXSTUB, you see incoming and outgoing SPX communication statistics from the Message Router.ID="FM19158"Workstation RequestersBtrieve provides the following Requesters for applications running on the workstation:BREQUEST.EXE---DOS RequesterBTRCALLS.DLL---OS/2 RequesterWBTRCALL.DLL---Windows RequesterBtrieve now provides a requester for the UnixWare environment. For information about this new UnixWare Requester, please refer to the Readme file that accompanies this release.A Btrieve Requester must be loaded at each workstation that makes Btrieve requests. The Requester receives Btrieve requests from an application and relays them via BSPXCOM to the Btrieve NLM running on the server. After the Btrieve NLM processes the request, BSPXCOM sends the results back to the Requester, which forwards them to the application. For information on starting the Requester in each operating environment, refer to IDREF="FM41779"Chapter 4, "Configuring and Using the Requesters."ID="FM42358"Btrieve UtilitiesBtrieve provides the following utilities for Btrieve file management:Setup and Rebuild utilities (BSETUP.NLM and BREBUILD.NLM)---You can use the Setup utility to change the settings of Btrieve configuration options, and you can use the Rebuild utility to convert existing Btrieve v5.x files to Btrieve v6.x format. (As IDREF="FM19000""Rebuilding Existing Btrieve Files" in Chapter 3 explains, you can choose to run the Rebuild utility from within the Setup utility.) Monitor utility (BTRMON.NLM)---You can use this utility to monitor the activity of Btrieve at the server. Maintenance utility (BUTIL.NLM)---You can use this utility to import and export Btrieve data and transfer data from one Btrieve file to another. This utility also lets you enable and disable continuous operation on your Btrieve files.Roll Forward utilities (BROLLFWD.EXE for DOS, PBROLL.EXE for OS/2, and WBROLL.EXE for Windows)---The Roll Forward utilities recover changes made to a Btrieve file between the time of the last backup and a system failure. The Roll Forward utilities are for workstation use only.For more information about the Btrieve Setup and Rebuild utilities, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve." For information about the Btrieve Monitor, Maintenance, and Roll Forward utilities, refer to IDREF="FM11326"Chapter 5, "Using Btrieve Utilities."ID="FM30141"ID="FM14645"Btrieve Applications on a ServerA Btrieve application running on a server (that is, an NLM) can access data on the local server or on a remote server, as follows:Accessing Local Data---The application makes a request for Btrieve data located on the local server. The Btrieve NLM processes the request on the server where the Btrieve request originated. Accessing Remote Data---The application makes a request for Btrieve data located on a remote server. The Btrieve NLM processes the request on the remote server. The following sections describe the events that occur when your NLM application makes local and remote requests.Server Application Accessing Local DataWhen an application running on a server is accessing data on that server, the Btrieve NLM must be loaded on that server. The following steps describe accessing data on the local server:The application sends a request to the Btrieve NLM. If the Message Router is not loaded, the call goes directly to the exported entry point of Btrieve on the local server. If the Message Router is loaded, it relays the call to Btrieve on the local server. Btrieve processes the request using the Btrieve library of function calls.If the Message Router is not loaded, Btrieve returns the appropriate data and status code directly to the calling application. If the Message Router is loaded, Btrieve returns the data and status code to the Message Router. The Message Router then transports the data and status code to the calling application.Server Application Accessing Remote DataWhen an application running on a local server is accessing data on a remote server, the Message Router and the Btrieve NLM must be loaded on the local server, and BSPXCOM and the Btrieve NLM must be loaded on the remote server. The following steps describe accessing data on a remote server:The application (running on the local server) makes a request to access a Btrieve file located on a remote server. The Message Router on the local server detects that the request is for a remote Btrieve file and sends the request to BSPXCOM on the remote server.BSPXCOM (remote) relays the request to the Btrieve NLM (remote) by making Btrieve function calls.The Btrieve NLM (remote) returns the appropriate data and status code to BSPXCOM (remote).BSPXCOM (remote) returns the data and status code to the local server, where the Btrieve request originated.The Message Router (local) returns the results to the calling application (local). The Message Router places the results in the application's memory at the location designated by the parameters passed to Btrieve in the function call. Control then returns to the calling application.ID="FM15346"Btrieve Applications on a WorkstationA Btrieve application running on a workstation can access local, remote, or local and remote data as follows:Accessing Local Data---The application makes a request for Btrieve data located on the workstation. Client-based Btrieve processes the request on the same workstation where the request originated. Accessing Remote Data---The application makes a request for Btrieve data located on a remote server. The request is sent to the Requester, which passes the request to the Btrieve NLM on the remote server. The Btrieve NLM processes the request. Accessing Local and Remote Data---The application makes a request for Btrieve data located on the local workstation or a remote server. The Requester intercepts the request for data. The Requester then determines whether the data is on the workstation or a remote server and routes the appropriate request to client-based Btrieve on the workstation or the Btrieve NLM on a remote server.The following sections explain what happens when your workstation application makes local and remote requests.Workstation Application Accessing Local DataWhen an application is accessing local data on the workstation, client-based Btrieve must be loaded on the workstation. The following steps describe accessing data on the workstation:The application makes a Btrieve request using a function call.The interface code that you link with your application makes the call to client-based Btrieve. (Novell provides the interface code.)In a Windows or OS/2 environment, you must import the function definition.Client-based Btrieve processes the request using the Btrieve library of function calls.Client-based Btrieve returns the appropriate data and status code directly to the calling application.Workstation Application Accessing Remote DataWhen an application is accessing data on a remote server from a workstation, the Requester must be loaded on the workstation, and BSPXCOM and the Btrieve NLM must be loaded on the server. The following steps describe accessing data on a server from an application running on the workstation:The application makes a Btrieve request using a function call.The interface code that you link with your application makes the call to the Requester. (Novell provides the interface code.)In a Windows or OS/2 environment, you must import the function definition.The Requester packages the request into a network message and routes the message to BSPXCOM on the remote server. BSPXCOM receives the network message, validates the parameters, and then executes the request by making function calls to the Btrieve NLM. The Btrieve NLM processes the request and returns the results to BSPXCOM. BSPXCOM forwards the results to the Requester at the workstation.The Requester returns the appropriate data and status code to the parameter variables in your application's memory and returns control to your application.Workstation Application Accessing Local and Remote DataWhen an application is accessing local and remote data from a workstation, the Requester and client-based Btrieve must be loaded on the workstation, and BSPXCOM and NetWare Btrieve must be loaded on the server. The following steps describe accessing local and remote data from an application running on the workstation:The application makes a Btrieve request using a function call.The interface code that you link with your application makes the call to the Requester. (Novell provides the interface code.)In a Windows or OS/2 environment, you must import the function definition.The Requester determines whether the server or the workstation should receive the request.This step varies, depending on whether the requested data is on the workstation or on a remote server:If the requested data is on the workstation, the Requester sends the request directly to client-based Btrieve. Btrieve processes the request using the Btrieve library of function calls. Client-based Btrieve returns the appropriate data and status code directly to the calling application.If the requested data is on a remote server, the Requester packages the request into a network message and routes the message to BSPXCOM on that server. BSPXCOM receives the network message, validates the parameters, and then executes the request by making function calls to the Btrieve NLM. The Btrieve NLM processes the request and returns the results to BSPXCOM. BSPXCOM forwards the results to the Requester at the workstation. The Requester returns the data and status code to the calling application.ID="FM40230"Examples of Btrieve ArchitectureThe diagrams in this section demonstrate how different Btrieve applications require different Btrieve components. This section discusses the following examples:IDREF="FM37708"Server Application Using the Btrieve NLMIDREF="FM41741"Server Application Using the Btrieve Message RouterIDREF="FM13177"Server Application Using the Btrieve Message Router and BSPXCOMIDREF="FM11694"Workstation Application Using the Requester and Client-Based BtrieveIDREF="FM38888"Server Application Using RSPXSTUBIDREF="FM33941"Server Application Using BSPXSTUBIDREF="FM20840"Server Application Using NetWare SQLThe following examples indicate remote requests with dashed lines and local requests with solid lines. ID="FM37708"Server Application Using the Btrieve NLMIDREF="FM17265"Figure 2-1 shows an application accessing Btrieve data on the local server. The application is making local requests to the local Btrieve NLM. Note that BSPXCOM is not loaded because there are no incoming requests to the Btrieve NLM from another server or workstation. LBL="2-1"ID="FM17265"Server Application Using the Btrieve NLMFILE="n312b21a.pbm"ID="FM41741"Server Application Using the Btrieve Message RouterIDREF="FM18899"Figure 2-2 shows an application running on Server A. It is making requests to the local Btrieve NLM (Server A) and to a remote Btrieve NLM (Server B) via the Btrieve Message Router. The Message Router handles outgoing requests from Server A to the remote Server B. The Message Router must be loaded on Server A in order to send the requests to Server B. BSPXCOM must be loaded on Server B to accept incoming requests from the Message Router.LBL="2-2"ID="FM18899"Server Application Using the Btrieve Message RouterFILE="n312b22a.pbm"ID="FM13177"Server Application Using the Btrieve Message Router and BSPXCOMIDREF="FM14760"Figure 2-3 illustrates a server application that requires both the Btrieve Message Router and BSPXCOM. In IDREF="FM14760"Figure 2-3, the Message Router handles outgoing requests from the local server to a remote server. BSPXCOM handles incoming requests to the Btrieve NLM from a remote source (either a Requester at a workstation or the Message Router on another server). The server is supporting incoming requests from a remote source and outgoing requests to a remote server.LBL="2-3"ID="FM14760"Server Application Using the Btrieve Message Router and BSPXCOMFILE="n312b23a.pbm"ID="FM11694"Workstation Application Using the Requester and Client-Based BtrieveIDREF="FM37403"Figure 2-4 shows an application running on a workstation. The application is accessing local data via client-based Btrieve and remote data via the Requester. The Requester passes requests for local data to client-based Btrieve. In this environment, the Requester on the workstation performs the same function as the Message Router in IDREF="FM14760"Figure 2-3. BSPXCOM handles incoming requests to the Btrieve NLM from a remote source.LBL="2-4"ID="FM37403"IDREF="FM11694"Workstation Application Using the Requester and Client-Based BtrieveFILE="n312b24a.pbm"ID="FM38888"Server Application Using RSPXSTUBIDREF="FM23661"Figure 2-5 shows an application running on Server A. It is accessing both local and remote data. The Btrieve Monitor utility (BTRMON.NLM) is also running on Server A. To run the Monitor utility, Server A must have either BSPXCOM, BSPXSTUB, or RSPXSTUB loaded. Since the Btrieve NLM on Server A is not accepting any incoming requests from workstations or remote servers, BSPXCOM is not loaded. Instead, RSPXSTUB is loaded on Server A; it allows users to see the Btrieve Message Router's communication statistics through the Monitor utility's Communication Statistics option. LBL="2-5"ID="FM23661"IDREF="FM38888"Server Application Using RSPXSTUBFILE="n312b25a.pbm"ID="FM33941"Server Application Using BSPXSTUBIDREF="FM17093"Figure 2-6 shows an application running on the server. The application is accessing local data. The Btrieve Monitor utility (BTRMON.NLM) is also running on the server. Since the Btrieve NLM is not accepting any incoming requests, BSPXCOM is not loaded. However, to run the Monitor utility, the server must have either BSPXCOM, BSPXSTUB, or RSPXSTUB loaded. Since the Btrieve Message Router is not loaded, BSPXSTUB is the appropriate communications module to have loaded. When BSPXSTUB is loaded, the Communication Statistics option in the Btrieve Monitor utility shows zeros for the SPX statistics, since there is no SPX activity.LBL="2-6"ID="FM17093"IDREF="FM33941"Server Application Using BSPXSTUBFILE="n312b26a.pbm"ID="FM20840"Server Application Using NetWare SQLIDREF="FM28827"Figure 2-7 shows NetWare SQL running on Server A. Since NetWare SQL needs to access data on both Server A and Server B, the Btrieve Message Router is loaded on Server A. In addition, NSSPXCOM is loaded on Server A because NetWare SQL is also responding to requests from a NetWare SQL Requester running on a remote workstation. (NSSPXCOM provides the same functionality for NetWare SQL as BSPXCOM provides for Btrieve.)LBL="2-7"ID="FM28827"IDREF="FM20840"Server Application Using NetWare SQLFILE="n312b27a.pbm"LBL="3"ID="FM13326"Installing and Configuring BtrieveThis chapter describes how to install and configure Btrieve. It discusses the following topics:IDREF="FM26626"Installing BtrieveIDREF="FM16159"Configuring BtrieveIDREF="FM36116"Starting and Stopping BtrieveIDREF="FM19000"Rebuilding Existing Btrieve FilesIDREF="FM28684"Using Btrieve with NetWare RuntimeID="FM26626"Installing BtrieveThe following sections discuss the system requirements and the installation procedure for Btrieve v6.1.System Requirementsidxid="w2366"book="_idx" docset="nw312" tidref="i6677"Make sure your system has the following:idxid="w2367"book="_idx" docset="nw312" tidref="i4443"NetWare v3.12Running Btrieve v6.1 in a NetWare v3.12 environment requires AFTER311.NLM, which Btrieve loads automatically.Adequate memory at the server to load the Btrieve NLM (approximately 528 KB) and the appropriate communications modules The memory required for the communications modules varies, depending on the values you specify for the Largest Record Size and Number of Remote Sessions configuration options.Adequate memory for the Btrieve Requester at each workstation. Memory requirements vary, depending on the parameters you specify when you load the Requester. These are the default parameters: The DOS Requester requires approximately 29 KB. The OS/2 Requester requires approximately 40 KB.The Windows Requester requires approximately 30 KB. (To use the Windows Requester, you must also have the DOS Requester loaded.)Btrieve also provides a requester for the UnixWare environment. For information about this new UnixWare Requester, please refer to the Readme file that accompanies this release.ID="FM34390"Using the NetWare INSTALL UtilityThe NetWare INSTALL utility lets you load Btrieve automatically at the server. For more information about the NetWare INSTALL utility, refer to your NetWare documentation.After loading Btrieve with the INSTALL utility, you can configure Btrieve according to your Btrieve application's requirements. Use the guidelines discussed in the next section, "Configuring Btrieve." You can then activate Btrieve as discussed in IDREF="FM36116""Starting and Stopping Btrieve" on page 3-12.ID="FM16159"Configuring Btrieveidxid="w2368"book="_idx" docset="nw312" tidref="i794"idxid="w2369"book="_idx" docset="nw312" tidref="i6323"You can configure Btrieve by setting configuration options. When you load Btrieve with the INSTALL utility, these options are set to their default values. (IDREF="FM22409"Table 3-1 shows the default values.) 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. LBL="3-1" INLINE="F"ID="FM22409"Default Values for Configuration OptionsWIDTH="168"Configuration OptionWIDTH="96"Default ValueWIDTH="168"IDREF="FM32420"Number of Open FilesWIDTH="96"20 filesIDREF="FM28507"Number of Handles60 handlesIDREF="FM10585"Number of Locks20 per clientIDREF="FM28162"Number of Transactions15 transactionsIDREF="FM12289"Largest Compressed Record Size0 KBIDREF="FM16820"Largest Record Size8,192 bytesIDREF="FM34626"Largest Page Size4,096 bytesIDREF="FM24233"Number of Remote Sessions15 sessionsIDREF="FM15854"Cache Allocation256 KBIDREF="FM29073"Perform Index BalancingNoIDREF="FM14268"Logging of Selected FilesNoIDREF="FM23854"Create Btrieve Files in Pre v6.x FormatNoIDREF="FM34868"Create Files as TransactionalNoIDREF="FM18303"Configure BSTART.NCF to Load BROUTERNoThe following section discusses each configuration option individually. You can change the values for the configuration options by running the Btrieve Setup utility (as described on IDREF="FM15225"page 3-10). idxid="w2370"book="_idx" docset="nw312" tidref="i7261"idxid="w2371"book="_idx" docset="nw312" tidref="i6323"The Setup utility stores your changes in the BSTART.NCF NetWare command file.After configuring Btrieve, you can activate Btrieve as described in IDREF="FM36116""Starting and Stopping Btrieve" on page 3-12.ID="FM35573"idxid="w2372"book="_idx" docset="nw312" tidref="i794"idxid="w2373"book="_idx" docset="nw312" tidref="i4848"Configuration OptionsThis section lists the Btrieve configuration options in the order in which they appear in the Setup utility. For each option, the discussion includes the following:Range of acceptable valuesDefault valueApproximate memory requiredDescription of the optionID="FM32420"idxid="w2374"book="_idx" docset="nw312" tidref="i1147"idxid="w2375"book="_idx" docset="nw312" tidref="i4826"idxid="w2376"book="_idx" docset="nw312" tidref="i4762"Number of Open Files Range: 1 through 64,000 filesDefault: 20 filesApproximate Memory Required: 425 bytes per file This option specifies the maximum number of unique Btrieve 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.ID="FM28507"idxid="w2377"book="_idx" docset="nw312" tidref="i1147"idxid="w2378"book="_idx" docset="nw312" tidref="i2598"idxid="w2379"book="_idx" docset="nw312" tidref="i4760"Number of Handles Range: 1 through 64,000 file handlesDefault: 60 handlesApproximate 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 "IDREF="FM10585"Number of Locks" (next) for a definition of sessions.ID="FM10585"idxid="w2380"book="_idx" docset="nw312" tidref="i1147"idxid="w2381"book="_idx" docset="nw312" tidref="i3378"idxid="w2382"book="_idx" docset="nw312" tidref="i4761"Number of Locks Range: 0 through 64,000 locksDefault: 20 locks per client sessionApproximate Memory Required: 20 bytes per lockThis option sets the maximum number of records a client session can lock at the server at one time. (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 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.ID="FM28162"idxid="w2383"book="_idx" docset="nw312" tidref="i1147"idxid="w2384"book="_idx" docset="nw312" tidref="i6875"idxid="w2385"book="_idx" docset="nw312" tidref="i4764"Number of TransactionsRange: 0 through 64,000 transactionsDefault: 15 transactionsApproximate 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.ID="FM12289"idxid="w2386"book="_idx" docset="nw312" tidref="i1147"idxid="w2387"book="_idx" docset="nw312" tidref="i3168"idxid="w2388"book="_idx" docset="nw312" tidref="i5768"idxid="w2389"book="_idx" docset="nw312" tidref="i1102"Largest Compressed Record SizeRange: 0 through 64 KBDefault: 0 KBApproximate Memory Required: 2,048 bytes * specified valueThis 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.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.ID="FM16820"idxid="w2390"book="_idx" docset="nw312" tidref="i1147"idxid="w2391"book="_idx" docset="nw312" tidref="i3171"idxid="w2392"book="_idx" docset="nw312" tidref="i5768"Largest Record Size Range: 600 through 64,000 bytesDefault: 8,192 bytes Approximate Memory Required:recordLength* (remoteSessions/5) + 1 + (remoteSessions* recordLength/ 580) * 600recordLength             Largest record size + 538 bytesremoteSessions       Number of remote sessionsThis option specifies the length of the largest record or record chunk that any remote Btrieve application (excluding other NLMs that call Btrieve, such as NetWare SQL) 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. 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 Windows Requester.ID="FM34626"idxid="w2393"book="_idx" docset="nw312" tidref="i1147"idxid="w2394"book="_idx" docset="nw312" tidref="i3169"idxid="w2395"book="_idx" docset="nw312" tidref="i4910"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 a 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. 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.ID="FM24233"idxid="w2396"book="_idx" docset="nw312" tidref="i1147"idxid="w2397"book="_idx" docset="nw312" tidref="i5835"idxid="w2398"book="_idx" docset="nw312" tidref="i4763"Number of Remote Sessions Range: 1 through 64,000 sessionsDefault: 15 sessionsApproximate Memory Required: 150 bytes * number of remote sessionsThis 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.If you receive a Status Code 96, 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.ID="FM15854"idxid="w2399"book="_idx" docset="nw312" tidref="i1147"idxid="w2400"book="_idx" docset="nw312" tidref="i874"Cache AllocationRange: 32 through 64,000 KBDefault: 256 KBApproximate Memory Required: Not applicableThis 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.ID="FM29073"idxid="w2401"book="_idx" docset="nw312" tidref="i1147"idxid="w2402"book="_idx" docset="nw312" tidref="i5065"idxid="w2403"book="_idx" docset="nw312" tidref="i2801"Perform Index BalancingRange: 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 index 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.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 IDREF="FM29073"Perform Index Balancing option, Btrieve performs index balancing on every file regardless of the balanced file flag specification.ID="FM14268"idxid="w2404"book="_idx" docset="nw312" tidref="i1147"idxid="w2405"book="_idx" docset="nw312" tidref="i6218"idxid="w2406"book="_idx" docset="nw312" tidref="i3411"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. For more information on logging and the Roll Forward utility, see IDREF="FM11326"Chapter 5, "Using Btrieve Utilities."ID="FM23854"idxid="w2407"book="_idx" docset="nw312" tidref="i1147"idxid="w2408"book="_idx" docset="nw312" tidref="i1266"idxid="w2409"book="_idx" docset="nw312" tidref="i5131"idxid="w2410"book="_idx" docset="nw312" tidref="i2487"Create Btrieve Files in Pre v6.x Format Range: Yes or NoDefault: NoApproximate Memory Required: Not applicableThis option specifies that all files be created in a Btrieve version prior to v6.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 v6.x and you want to use those files with Btrieve v5.x, specify Yes for this option.Btrieve v6.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 v5.x files using the v5.x format and writes to v6.x files using the v6.x format.ID="FM34868"idxid="w2411"book="_idx" docset="nw312" tidref="i1147"Create Files as TransactionalRange: 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 (TTS) 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.ID="FM18303"idxid="w2412"book="_idx" docset="nw312" tidref="i791"idxid="w2413"book="_idx" docset="nw312" tidref="i1164"idxid="w2414"book="_idx" docset="nw312" tidref="i1147"idxid="w2415"book="_idx" docset="nw312" tidref="i791"idxid="w2416"book="_idx" docset="nw312" tidref="i1164"Configure BSTART.NCF to Load BROUTERRange: 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 NetWare 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.ID="FM40936"idxid="w2417"book="_idx" docset="nw312" tidref="i6323"idxid="w2418"book="_idx" docset="nw312" tidref="i3323"idxid="w2419"book="_idx" docset="nw312" tidref="i7261"idxid="w2420"book="_idx" docset="nw312" tidref="i6323"ID="FM15225"Running the Setup UtilityUse the Setup utility to set the 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.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.Enter the following at the prompt to start the utility: load bsetupIf 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.FILE="n312b81p.pbm"This menu provides the following options:Set Btrieve Configuration---Use this option to view or modify the current configuration options for Btrieve.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. (IDREF="FM19000""Rebuilding Existing Btrieve Files" on page 3-14 discusses the Rebuild utility and its configuration options.)To change configuration options, select Set Btrieve Configuration.ID="FM27897"When the Current Btrieve Configuration screen appears, use the Up- and Down-Arrow keys to highlight the configuration option you want to change, and press the Enter key. A flashing cursor appears.FILE="n312b34p.pbm"Use the Backspace key to remove the old value; then, type the new value and press the Enter key. If you enter an invalid value for an option, the utility displays a message indicating the valid values.To see the valid values for any option, move the cursor to that option, press the Enter key, and then press the F1 key. You can also refer to IDREF="FM35573""Configuration Options" on page 3-4 for more information about these options and their values.Repeat Steps 3 and 4 until you have changed all the options you want to modify.When you are ready to exit the Current Btrieve Configuration screen, press the Esc key. When the Save Configuration Changes? screen appears, select Yes to save your changes or No to abandon the changes.If you select Yes, the Setup utility writes the configuration values you specified to the BSTART.NCF file.FILE="n312b35p.pbm"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.Before your configuration changes can take effect, you must unload the existing Btrieve NLM, BSPXCOM, and the Message Router (using the BSTOP command), and then reload them by entering the BSTART command.BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB. To unload these modules, type unload followed by the module name.To exit the Setup utility, press the Esc key until the Exit window appears, and then select Yes.ID="FM36116"idxid="w2421"book="_idx" docset="nw312" tidref="i794"idxid="w2422"book="_idx" docset="nw312" tidref="i7079"Starting and Stopping BtrieveThis section discusses starting and stopping Btrieve. Before starting Btrieve v6.x, you must first check for any extraneous pre-image files (files with a .PRE extension) and then unload the earlier version of Btrieve.If you need to preserve your Btrieve v5.x files, you can use Btrieve v6.x to read them.Checking for Extraneous Pre-Image FilesIf you have any extraneous .PRE files in your database, you must remove them before starting Btrieve v6.x. The following procedure explains how to check for and remove extraneous .PRE files. You must have Btrieve v5.x or v6.0 loaded before performing these steps.ID="FM20917"Using your existing version of Btrieve (such as v5.x or v6.0), open the Btrieve data file corresponding to the .PRE file in Exclusive mode.Perform a Get First operation.Perform an Update operation (this will not change the record).Close the Btrieve data file (this should delete the .PRE file).ID="FM19365"Any .PRE files that remain for the designated file after you perform Steps 1 through 4 are extraneous. Delete them now. Repeat Steps 1 through 5 to find and delete any other extraneous .PRE files.If you do not remove the extraneous .PRE files before starting Btrieve v6.x, file corruption may occur.Unloading the Earlier Version of BtrieveTo unload an earlier version of Btrieve from a server's memory, enter the following command at the server console or at a workstation running RCONSOLE:  idxid="w2423"book="_idx" docset="nw312" tidref="i793"bstopThe BSTOP command runs a NetWare command file (BSTOP.NCF) that unloads the following modules in the order shown:BROUTER.NLMBSPXCOM.NLM idxid="w2424"book="_idx" docset="nw312" tidref="i788"idxid="w2425"book="_idx" docset="nw312" tidref="i7079"BTRIEVE.NLMBSTOP.NCF does not unload BSPXSTUB or RSPXSTUB. To unload either of these modules, enter the UNLOAD command and the name of the module: unload bspxstub|rspxstubidxid="w2426"book="_idx" docset="nw312" tidref="i6485"idxid="w2427"book="_idx" docset="nw312" tidref="i794"Starting Btrieve v6.xAfter installing Btrieve v6.x (as discussed in IDREF="FM34390""Using the NetWare INSTALL Utility" on page 3-2), you can start it by entering the following at the server console or at a workstation running RCONSOLE:  idxid="w2428"book="_idx" docset="nw312" tidref="i793"bstartidxid="w2429"book="_idx" docset="nw312" tidref="i6532"idxid="w2430"book="_idx" docset="nw312" tidref="i794"Stopping Btrieve v6.xTo stop Btrieve v6.x, enter the following command at the server console or at a workstation running RCONSOLE: bstopThe BSTOP command runs a NetWare command file (BSTOP.NCF) that unloads the following modules in the order shown:BROUTER.NLM BSPXCOM.NLM idxid="w2431"book="_idx" docset="nw312" tidref="i788"idxid="w2432"book="_idx" docset="nw312" tidref="i7079"BTRIEVE.NLMBSTOP.NCF does not unload BSPXSTUB or RSPXSTUB. To unload these modules, type unload followed by the module name. ID="FM35949"ID="FM19000"idxid="w2433"book="_idx" docset="nw312" tidref="i7093"idxid="w2434"book="_idx" docset="nw312" tidref="i794"idxid="w2435"book="_idx" docset="nw312" tidref="i5759"idxid="w2436"book="_idx" docset="nw312" tidref="i2300"idxid="w2437"book="_idx" docset="nw312" tidref="i7261"idxid="w2438"book="_idx" docset="nw312" tidref="i5759"Rebuilding Existing Btrieve FilesIf your database contains files created with versions of Btrieve prior to v6.x, you may want to upgrade these files to take advantage of the Btrieve v6.x features. Btrieve v6.x works with v5.x files; however, it does not implement the v6.x features. The Btrieve Rebuild utility (BREBUILD.NLM) converts Btrieve data files to the v6.x format. You can run this utility from either the server console or a workstation running RCONSOLE. Use either of the following methods to run the Rebuild utility:Interactively through the Setup utility---When you run the Rebuild utility interactively, it checks the values you enter to ensure they are within the proper ranges.From the command line---When you use this method, the utility checks your entries and displays messages if the values you entered are not within the proper ranges. With this method, you can specify a command file.The following sections discuss running the utility interactively and from the command line.Before running this utility, make sure you have unloaded your previous version of Btrieve, started Btrieve v6.x, and backed up all your data files. Having a backup copy ensures against data loss if a power interruption occurs while you are running this utility.To ensure that your backup is successful, perform one of the following:Close all Btrieve files before running the backup utility.Use continuous operations.Use a backup utility that opens the Btrieve files in exclusive write mode so that other processes cannot write to the files. Ensure that the backup utility has exclusive rights to the files.ID="FM32941"idxid="w2439"book="_idx" docset="nw312" tidref="i3323"idxid="w2440"book="_idx" docset="nw312" tidref="i5759"idxid="w2441"book="_idx" docset="nw312" tidref="i5763"idxid="w2442"book="_idx" docset="nw312" tidref="i3323"Running the Rebuild Utility InteractivelyYou can run the Rebuild utility interactively through the Set Rebuild Configuration option on the Setup utility's Available Options menu. As the following sections explain, you can use the Set Rebuild Configuration option to do the following:Configure the Rebuild utilityExecute the Rebuild utilityCheck the utility's error logConfiguring the Rebuild UtilityComplete the following steps to set the configuration options that apply to rebuilding your Btrieve files:After starting Btrieve v6.x, load the Setup utility by entering the following at the prompt. load bsetupWhen the Available Options menu appears, select Set Rebuild Configuration to run the Rebuild utility.FILE="n312b82p.pbm"A warning appears, indicating you should back up your Btrieve data files before proceeding.FILE="n312b37p.pbm"If you do not have current backups, you should press Esc three times. When the Exit Btrieve Setup? prompt appears, select Yes. Create backups and then return to this utility.Provided you have current backups of your data files, press Esc to continue to the Rebuild Options menu.FILE="n312b38p.pbm"Select Set Rebuild Configuration to display the Rebuild Configuration Setup Form screen.FILE="n312b39p.pbm"Select the files you want to rebuild, as follows:With your cursor at Files To Be Converted, press Enter and then Insert. When the list of available volumes appears, highlight the volume you want and press Enter. The utility displays the directories available on the selected volume. Highlight the directory you want and press Enter.Continue highlighting directories (that is, subdirectories) and pressing Enter until you have reached the one that contains the file or files you want to rebuild. Then, press Esc.Choose the files you want to rebuild, as follows:To specify more than one file, enter the filenames manually, using wildcard characters (* or ?). For example, you might enter /*.* to specify all files in the selected directory, or you could enter /*.BTR to specify all files in that directory with the extension .BTR.To specify an individual file, press Enter to list the filenames in the specified directory. Highlight the filename you want, and press Enter to select it. (The input files that are listed are on the local server.) At Output Directory, specify the location you want to use for the rebuilt files, as follows. (The default location is the directory you specified for the Files To Be Converted field.)Press Enter. Either type the server or directory name manually and press Enter, or choose from the list of available directories on the current server by entering a valid path and pressing Insert. To select a directory name from the list, highlight the name and press Enter.If you want to place the rebuilt files on a different server, you must type the output server name, volume, and path manually. Then, press Enter. To place rebuilt files on a different server, Btrieve and the Message Router must be loaded on the server where the original data files reside, and the Btrieve and BSPXCOM NLMs must be loaded on the server that will contain the rebuilt files. Wherever you locate the rebuilt files, you will need enough disk space for the rebuilt files and the temporary files that the utility creates. The utility deletes the temporary files at the end of the conversion process.Do not use wildcard characters in the pathname that specifies the location for the rebuilt files.After specifying the output directory, use the Down-Arrow key to move to the Page Size field.At Page Size, type the size manually or choose from a list of sizes. To list the available page sizes, press Enter. In this list, the AUTO option (the default) means the utility will choose the optimum page size for the files. The EXISTING option means the utility will use the same page size as that of the original files. To select a size from the list, highlight it and press Enter.When you use the EXISTING option, the utility changes the page size if the original size will not work. For example, assume you have a Btrieve v5.x file with a page size of 1,024 and 24 keys. Since Btrieve v6.x supports only 23 keys for a file of that page size, the utility selects a new page size for the file and displays an informative message on the screen.At Key Number, specify a number between 0 and 23 on which to sort the records, or specify -1 to sort the records in physical order; then, press Enter.If you are using NetWare SQL, you must specify a key number of 0 when rebuilding the VIEW.DDF file.At Preserve TTS Setting, specify Y (for Yes) or N (for No) to indicate whether you want to preserve the Transaction Tracking System (TTS) bit during conversion; then, press Enter.If you specify Y, the utility preserves the bit. If you specify N (the default), the utility clears the bit when creating Btrieve v6.x files.At Conversion Method, select the conversion method as follows:Press Enter.Highlight either PRIMARY (the default) or SECONDARY, and then press Enter. The PRIMARY method clones the files, drops the indexes, copies the records into the new files, and rebuilds the indexes. Since this method is faster and creates smaller files, you should use this method whenever possible. However, if you are using NetWare SQL, you must not use this method when rebuilding the VIEW.DDF file. The SECONDARY method clones and copies the files without dropping and replacing indexes. This method may be slower than the Primary method. If you are using NetWare SQL, you must specify the SECONDARY method when rebuilding the VIEW.DDF file. The SECONDARY method may create a v6.x file in which the records are in a different physical order than in the original v5.x file.At Continue On Error, specify either Y (for Yes) or N (for No) and press Enter. If you specify Y, the utility continues if it encounters an error. (The utility notifies you of non-Btrieve files or other errors but continues rebuilding Btrieve files.) If you specify N, the utility stops if it encounters an error and aborts the rebuild process.At Convert Supplemental Indexes, specify Y (for Yes) or N (for No) and press Enter.If you specify Y, the utility converts Btrieve v5.x supplemental indexes (which allow duplicates) to Btrieve v6.x indexes with linked duplicates. Btrieve v5.x supplemental indexes have, by default, repeating duplicates. If you specify N (the default), the utility does not convert the v5.x supplemental indexes but preserves them as repeating duplicates.Do not use the Convert Supplemental Indexes option if you access your data files through NetWare SQL.Press Esc to leave the Rebuild Configuration Setup Form screen. When the utility asks whether to save your changes, select Yes to save them and return to the Rebuild Options menu or No to abandon the changes.The utility applies the Btrieve v5.x file's owner name and level to the Btrieve v6.x file.Executing the Rebuild UtilityAfter configuring the Rebuild utility, you are ready to rebuild your files. At the Rebuild Options menu, select Execute Rebuild to run the utility.FILE="n312b40p.pbm"The utility executes and also creates a log file. It then notifies you that the process has completed. To return to the Rebuild Options menu, press Esc. You can then check the log file as discussed in the following section.ID="FM29081"idxid="w2443"book="_idx" docset="nw312" tidref="i3384"Checking the Rebuild Log FileAfter rebuilding your files, be sure to check the utility's log file to see if any errors occurred during the conversion, as follows:Select View Rebuild Log File from the Rebuild Options menu.FILE="n312b41p.pbm"The utility displays a log of any errors that occurred while the utility was executing, similar to the following example:FILE="n312b42p.pbm"When you finish viewing the log, press Esc to return to the Rebuild Options menu. To exit both the Rebuild utility and the Setup utility, press Esc twice more and specify Yes at the Exit Btrieve Setup? prompt.idxid="w2444"book="_idx" docset="nw312" tidref="i3323"idxid="w2445"book="_idx" docset="nw312" tidref="i3323"idxid="w2446"book="_idx" docset="nw312" tidref="i5763"idxid="w2447"book="_idx" docset="nw312" tidref="i5759"Running the Rebuild Utility from the Command LineBefore running the Rebuild utility from the command line, make sure you have unloaded your previous version of Btrieve, started Btrieve v6.x, and backed up all your data files. Having a backup copy ensures against data loss if a power interruption occurs while you are running this utility.After rebuilding your files, be sure to check the utility's log file to see if any errors occurred during the conversion. The log file (BREBUILD.LOG) that the Rebuild utility creates is an ASCII text file. The .LOG file is placed in the SYS:SYSTEM directory. You can view it by using a text editor or by running the Rebuild utility interactively and selecting View Rebuild Log File from the Rebuild Options menu (as explained in IDREF="FM29081""Checking the Rebuild Log File" on page 3-21). To run the Rebuild utility from the command line, enter the following command at the prompt: LOAD BREBUILD [-option...] fileor LOAD BREBUILD @commandFileWIDTH="60"optionWIDTH="252"Specifies the configuration options for the utility.  Precede each option letter with a dash (-). Do not  place a space between the dash and the option  letter and between the option letter and its value.  You can enter the option letter in uppercase or  lowercase.WIDTH="60"WIDTH="60"-B[path]WIDTH="180"Specifies an alternate location for  the rebuilt files. (The default  location is the current directory.)  This option lets you rebuild large  files on a different volume or on a  different server.WIDTH="132"WIDTH="180"To locate the files on a different  server, the Btrieve NLM and the  Message Router must be loaded on  the server where the original data  files reside, and the Btrieve and  BSPXCOM NLMs must be loaded  on the server that will contain the  rebuilt files.Do not use wildcard characters in the pathname you specify with the -B option.WIDTH="60"WIDTH="60"-CWIDTH="180"Instructs the utility to continue with  the next file even if an error occurs.  The utility notifies you of non-Btrieve  files or other errors but continues  updating Btrieve files. This option is  useful if you have specified wildcard  characters for the rebuilt files.WIDTH="60"WIDTH="60"-DWIDTH="180"Converts Btrieve v5.x supplemental  indexes (which allow duplicates) to  v6.x indexes with linked duplicates.  (By default, the utility preserves the  indexes as repeating duplicates.) If you  access your data files only through  Btrieve and your files have a relatively  large number of duplicate keys, you  can use this option to enhance the  performance of the Get Next and Get  Previous operations. Do not use the -D option if you access your data files through NetWare SQL.WIDTH="60"WIDTH="60"-M0 | M2WIDTH="180"Specifies the conversion method, as  follows:WIDTH="132"WIDTH="60"M0WIDTH="108"Clones and copies the  files without dropping  and replacing indexes.  While this method is  slower than M2, it is  available in case you do  not want to rebuild  your indexes. If you are using NetWare SQL, you must use the -M0 and -K0 options to rebuild the VIEW.DDF file.WIDTH="132"WIDTH="60"M2WIDTH="108"(Default) Clones the  files, drops the indexes,  copies the records into  the new files, and  rebuilds the indexes.  Since this method is  faster and creates  smaller files, you should  use it whenever  possible. The M2 method may create a v6.x file in which the records are in a different physical order than in the original v5.x file.WIDTH="60"WIDTH="60"-P[nnn]WIDTH="180"Specifies the page size (in bytes) of the  new files. If you specify -P with no  page size, the utility chooses the  optimum page size for your file.If you do not specify the -P parameter, the utility will change the page size if the original size will not work.WIDTH="132"WIDTH="180"For example, assume you have a  Btrieve 5.x file with a page size of  1,024 and 24 keys. Since Btrieve v6.x  supports only 23 keys for a page size of  1,024, the utility automatically selects  a new page size for the file and  displays an informative message on  the screen.WIDTH="60"WIDTH="60"-K[nn]WIDTH="180"Specifies the key by which the utility  reads when rebuilding a file. If you do  not specify this option, the utility  reads the file in physical order.You must use the -K0 option when rebuilding NetWare SQL's VIEW.DDF file.WIDTH="60"WIDTH="60"-TWIDTH="180"Does not preserve the Transaction  Tracking System (TTS) bit during  conversion. If you specify this option,  the utility clears the TTS bit (if set)  when converting a Btrieve v5.x file to  a Btrieve v6.x file. If you do not specify  this option, the utility sets the TTS bit  when creating the Btrieve v6.x file if  the v5.x file had the TTS bit set.WIDTH="60"fileWIDTH="252"Specifies the set of files to convert. Use full directory  names, including the volume name. You may use  wildcards (* and ?) in these filenames. The Rebuild utility applies the Btrieve v5.x file's owner name and level to the Btrieve v6.x file.WIDTH="324"@commandFileWIDTH="60"WIDTH="252"Specifies a command file for the utility to execute.  You can include multiple entries in one command  file. Each entry in the command file contains the  utility options (if any) and the set of files to convert,  followed by <end> or [end]. When specifying the  files to convert, be sure to use full directory names,  including the volume name. You may use wildcards  (* and ?) in these filenames. The following is an  example of a Rebuild utility command file: -C sys:\mydir\*.* <end>-C -P1024 dta:\dir\*.* <end>-M0 -K0 sys:\nwsql\*.* <end>ID="FM30144"ExamplesThe first example places the rebuilt files on another server: load brebuild -Bserv-temp\sys:\newfiles -C -P4096 sys:\oldfiles\*.btrThe next example places the rebuilt files on the same server, but on a different volume: load brebuild -Bvol2:\btrfiles -C -P4096 -M2 sys:\btrfiles\*.btrDeleting Temporary FilesBy default, the Rebuild utility creates temporary files in the same directory in which the conversion takes place. (You can specify a different directory by using the -B option when running the Rebuild utility from the command line, or by using the Output Directory option on the Setup Form screen when running the utility interactively.) idxid="w2448"book="_idx" docset="nw312" tidref="i5759"You need enough disk space to accommodate the original file and the new file while the Rebuild utility is running.The Rebuild utility deletes the original file after rebuilding it, even if the new file is in a different directory.Normally, the Rebuild utility automatically deletes temporary files when the conversion is complete. However, if a power failure or other serious interruption occurs, the Rebuild utility may not delete the temporary files. If this occurs, look for filenames such as _T-xxxxx.TMP and delete them.ID="FM28684"idxid="w2449"book="_idx" docset="nw312" tidref="i4370"Using Btrieve with NetWare RuntimeThe NetWare Runtime serialized NetWare operating system differs from the other versions of NetWare in that it grants file service access to only one NetWare login client connection. This login is for system administration purposes. NetWare Runtime does not limit the number of SPX or AppleTalk connections between client applications and NLM-based services. Consequently, NetWare Runtime does not limit the number of users that can access Btrieve running on the Runtime server.IDREF="FM23585"Figure 3-1 illustrates the relationship between NetWare Runtime and a NetWare configuration that is not dedicated to database services.LBL="3-1"ID="FM23585"NetWare ConfigurationsFILE="n312b61a.pbm"Reasons to Use NetWare RuntimeRunning NetWare Btrieve on a server dedicated to database management ensures that all the server's processing power is directed toward database applications. If you anticipate heavy file service activity, a dedicated database server makes that activity more efficient because it frees the nondedicated server to devote all its resources to file services.Having a dedicated database server is also particularly effective in preventing slow performance on the network during periods of heavy file service activity. To optimize network performance, you can configure so as to include a dedicated database server in addition to other servers offering full NetWare services.IDREF="FM19768"Figure 3-2 shows an example installation for NetWare Runtime.LBL="3-2"ID="FM19768"NetWare Runtime InstallationFILE="n312b62a.pbm"Installing NetWare RuntimeThe installation procedure for NetWare Runtime is identical to installing the other versions of NetWare. Refer to the documentation that accompanies your NetWare Runtime software for instructions.Special Notes on NetWare RuntimeNetWare Runtime supplies a facility (NLICLEAR.NLM) that clears unused connections. NetWare Runtime provides only one available client connection. Even after the administrator logs out of the application server, a connection is maintained between the workstation and the server. If a second administrator wants to log on to the application server from a second workstation, the single connection will be unavailable. The NLICLEAR facility is important for NetWare Runtime because, at intervals, NLICLEAR automatically clears the unused connections left after an administrator logs out of the application server, allowing another administrator to log in to and administer the database server.Special Notes on BtrieveWhen you load the Btrieve DOS or OS/2 Requester using the option /C:1, username, password, Btrieve logs in to the NetWare Runtime server with the specified username and the corresponding password. Btrieve also obtains a temporary connection number, which it uses to distinguish between users. Btrieve verifies that the user has the acceptable rights to open or create a file. Btrieve then logs out of the server, using the temporary connection number. If the user has the appropriate file access rights, Btrieve continues; otherwise, it returns an error.The administrator must set up file access rights on the NetWare Runtime server.When you load the Btrieve DOS or OS/2 Requester using the /C:1 default option (without specifying a username and password) and then attempt to read a file on the NetWare Runtime server, the Requester must determine what login username Btrieve can use to maintain NetWare security. Btrieve then uses that username to log in temporarily for the client. In contrast, if the Requester detects that there is no connection, or if it cannot find a valid login username, the Requester returns an error.For more information about the NetWare Runtime server support option available with the DOS and OS/2 Requesters, see IDREF="FM41779"Chapter 4, "Configuring and Using the Requesters."LBL="4"ID="FM41779"Configuring and Using the RequestersID="FM13625"idxid="w2450"book="_idx" docset="nw312" tidref="i5865"idxid="w2451"book="_idx" docset="nw312" tidref="i794"Btrieve provides a IDREF="FM14474"DOS Requester, an IDREF="FM19748"OS/2 Requester, a IDREF="FM22327"Windows Requester, and a UnixWare Requester. This chapter provides configuration options and instructions for loading and unloading the Requester in each operating environment.The Btrieve Requesters have changed (primarily in key definition) between previous versions and Btrieve v6.1. Therefore, all workstations accessing the Btrieve v6.1 NLM must use the Btrieve v6.1 Requesters.For information about the new UnixWare Requester, please refer to the Readme file that accompanies this release. ID="FM14474"idxid="w2452"book="_idx" docset="nw312" tidref="i5865"idxid="w2453"book="_idx" docset="nw312" tidref="i1696"idxid="w2454"book="_idx" docset="nw312" tidref="i1696"idxid="w2455"book="_idx" docset="nw312" tidref="i794"DOS RequesterYou must load the Btrieve DOS Requester, BREQUEST.EXE, at a workstation running DOS before that workstation can access network Btrieve files using the Btrieve NLM. The DOS Requester loads into a DOS workstation's memory as a Terminate and Stay Resident (TSR) program. You can access local as well as remote files by running both client-based (local) Btrieve and the Requester at your workstation.Client-based Btrieve is available only as part of the Btrieve Developer's Kit and must be purchased separately.idxid="w2456"book="_idx" docset="nw312" tidref="i1147"idxid="w2457"book="_idx" docset="nw312" tidref="i1696"idxid="w2458"book="_idx" docset="nw312" tidref="i4848"DOS Requester Configuration OptionsThere are five configuration options for the Btrieve DOS Requester: NetWare Runtime Server Support (/C), Data Message Length (/D), DOS Session Load (/L), Real-Time Data Compression (/O), and Help (/?). Previous versions of the DOS Requester also supported the /S and /R options. The DOS Requester v6.x accepts the /S and /R options for backwards compatibility, but otherwise ignores them.NetWare Runtime Server Support (/C)Range: NoneDefault: /C:1Memory Required: Not applicableThis option allows you to enable or disable NetWare Runtime server support.  /C:0 |/C:1 |/C:1,username,passwordWIDTH="48"/C:0 WIDTH="264"Disables NetWare Runtime server support.WIDTH="48"/C:1 WIDTH="264"Enables NetWare Runtime server support. Btrieve  looks at the username for the drive (current  server) on which you are presently running.If the username is SUPERVISOR, Btrieve searches  for another username in the table of usernames  for the servers onto which you are logged.If the username is not SUPERVISOR, Btrieve  searches for that username on the NetWare  Runtime server. If it is not a valid username,  Btrieve returns an error at the time of the Open or  Create request.WIDTH="324"/C:1,username,passwordWIDTH="48"WIDTH="264"Enables NetWare Runtime server support. Btrieve  verifies the specified username and password for  the NetWare Runtime server. Btrieve returns an  error if the specified username is not found or the  password is invalid.WIDTH="48"WIDTH="72"usernameWIDTH="180"Preferred login name on the NetWare  Runtime server. If you specify SUPERVISOR for the username, Btrieve returns an error and the DOS Requester will not load.WIDTH="48"WIDTH="72"passwordWIDTH="180"Login password for the specified user.For information on using Btrieve with NetWare Runtime, see IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."Data Message Length (/D)Range: 532 through 57,000 bytesDefault: 4,096 bytes Memory Required: 538 bytes + data message lengthThis option specifies the length of the largest record (or the largest portion or chunk of a record) you want to access through Btrieve. (If you omit this option, the Requester uses the default value, 8,192.) The Requester uses this value to calculate the length of the data message buffer reserved for passing records between Btrieve and your applications. The Requester maintains one copy of the data message buffer. The value you enter here should not exceed the largest record size you configure for Btrieve through the Setup utility since that is the maximum message that BSPXCOM can receive. (For more information, refer to the section IDREF="FM16820""Largest Record Size" on page 3-6.)Specify the data message length in bytes. For example, if the largest record your application uses is 3,000 bytes, specify the /D option as follows:  /d:3000Specifying a higher value than you need for the /D option does not improve performance and may waste memory.DOS Session Load (/L)Range: Not applicableDefault: Not applicableMemory Required: Not applicableThis option allows you to load another instance of BREQUEST even if it is already loaded. This option is useful if you want to run Windows applications using the DOS Requester while running DOS VM applications that are also using the DOS Requester.To run Windows applications that use the DOS Requester, you must load BREQUEST before starting Windows. In order to run DOS applications in Windows, you must load BREQUEST in each DOS session. However, if you load BREQUEST outside Windows, you cannot load it again in a DOS session. For Windows applications using the DOS Requester, load BREQUEST outside Windows. In each Windows DOS session that will be running a Btrieve application, load BREQUEST with the /L option. Doing so loads another instance of BREQUEST that is available only to the DOS session. This operation provides the DOS session with its own copy of BREQUEST and prevents the DOS session from using the instance of BREQUEST that you loaded before starting Windows.Real-Time Data Compression (/O)Range: NoneDefault: No compressionMemory Required: Approximately 32 KB on the workstation and 32 KB per client on the serverIn many cases (such as when implementing extended reads and VATs), this option can help reduce network traffic by reducing the number of packets required to complete a request to Btrieve. This option may, however, adversely affect memory and performance.Compressing and decompressing data takes extra CPU time on both the server and client sides. Because of overhead, you should not use this option with fast networks or with slow workstations for clients.Help (/?)The /? option lists the other options that are available (/C, /D, and /O) and mentions that although the /S and /R options are accepted for backwards compatibility, Btrieve v6.x ignores them.idxid="w2459"book="_idx" docset="nw312" tidref="i1696"idxid="w2460"book="_idx" docset="nw312" tidref="i3323"Loading the DOS RequesterLoad the DOS Requester at the workstation by entering the following command:  [path] brequest [option]WIDTH="48"pathWIDTH="252"The pathname to the directory where the DOS  Requester is stored. You can omit the pathname if the  DOS Requester is stored on the default drive, or if it is  located in a directory in your search path. optionAny of the configuration options (/C, /D, /L, /O, or /?).For example, if the Requester is on the default drive and you want to specify a 2,048-byte data message length, enter the following: brequest /d:2048 The forward slash (/) before the configuration option is the only valid character you can use. If you specify a dash (-) or a backslash (\), the Requester may load improperly.idxid="w2461"book="_idx" docset="nw312" tidref="i1696"Unloading the DOS RequesterTo unload the DOS Requester, use the DOS Requester utility, BREQUTIL.EXE. At the workstation where the DOS Requester is loaded, enter the following: brequtil -stopTo determine the version number of your DOS Requester, enter  brequtil -verIf files remain open (as happens, for example, when an application does not issue a Close operation for each open file), simply logging out of one or more servers from a workstation does not close Btrieve files or terminate the Btrieve SPX connection to the server. To close Btrieve files and terminate the connection, use the BREQUTIL -STOP command.ID="FM19748"idxid="w2462"book="_idx" docset="nw312" tidref="i5865"idxid="w2463"book="_idx" docset="nw312" tidref="i4856"idxid="w2464"book="_idx" docset="nw312" tidref="i794"OS/2 RequesterThe following files must be loaded in a directory listed in an OST2 workstation's LIBPATH before a Btrieve application can access the Btrieve NLM from that workstation:BTRCALLS.DLL---The Btrieve dynamic link Requester for OS/2 workstations.NDBCOMM.DLL---The communications Requester for OS/2 workstations. NDBCOMM.DLL provides the necessary data communications between the workstation and the Btrieve NLM.You can access local as well as remote files by running both client-based (local) Btrieve and the Requester at your workstation.If you want to run both client-based Btrieve and the Requester, you must use the OS/2 Conversion utility (NDBCNVT.EXE) to convert the client-based BTRCALLS.DLL to BTRLOCL.DLL. (By default, the Requester and client-based Btrieve have the same name.) Client-based Btrieve is available only as part of the Btrieve Developer's Kit and must be purchased separately.idxid="w2465"book="_idx" docset="nw312" tidref="i1147"idxid="w2466"book="_idx" docset="nw312" tidref="i4856"idxid="w2467"book="_idx" docset="nw312" tidref="i4848"OS/2 Requester Configuration OptionsYou are not required to specify any configuration options for the OS/2 Requester. Since the internal tables that control the options are not fixed, the tables will grow as needed.There are three configuration options for the OS/2 Requester: NetWare Runtime Server Support (/C), Data Message Length (/D), and Number of Servers (/S).Although you can set the initial size of the tables using the Data Message Length (/D) and the Number of Servers (/S) options, setting table sizes is not recommended.NetWare Runtime Server Support (/C)Range: NoneDefault: /C:1Memory Required: Not applicableThis option allows you to enable or disable NetWare Runtime server support.  /C:0 |/C:1 |/C:1,username,passwordWIDTH="48"/C:0 WIDTH="264"Disables NetWare Runtime server support.WIDTH="48"/C:1 WIDTH="264"Enables NetWare Runtime server support. Btrieve  looks at the username for the drive (current  server) on which you are presently running.If the username is SUPERVISOR, Btrieve searches  for another username in the table of usernames  for the servers onto which you are logged.If the username is not SUPERVISOR, Btrieve  searches for that username on the NetWare  Runtime server. If it is not a valid username,  Btrieve returns an error at the time of the Open or  Create request.WIDTH="324"/C:1,username,passwordWIDTH="48"WIDTH="264"Enables NetWare Runtime server support. Btrieve  verifies the specified username and password for  the NetWare Runtime server. Btrieve returns an  error if the specified username is not found or the  password is invalid.WIDTH="48"WIDTH="72"usernameWIDTH="180"Preferred login name on the NetWare  Runtime server. If you specify SUPERVISOR for the username, Btrieve returns an error and the OS/2 Requester will not load.WIDTH="48"WIDTH="72"passwordWIDTH="180"Login password for the specified user.For information on using Btrieve with NetWare Runtime, see IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."Data Message Length (/D)Range: 532 through 65,000 bytesDefault: 4,096 bytes Memory Required: 538 bytes + data message lengthThe /D option specifies the length of the largest record (or the largest portion or chunk of a record) you want to access through Btrieve. The OS/2 Requester uses this value to calculate the length of the data message buffer reserved for passing records between Btrieve and your applications. The Requester maintains one copy of the data message buffer.The value you enter here should not exceed the value you specified for the Largest Record Size configuration option in the Setup utility. (For more information, refer to the section IDREF="FM16820""Largest Record Size" on page 3-6.) The value for this option represents the maximum message length that BSPXCOM can receive. Specify the record length in bytes. For example, if the largest record your application uses is 3,000 bytes, specify the /D option as follows:  /d:3000Specifying a higher value than you need for the /D option does not improve performance.Number of Servers (/S)Range: 1 through 255Default: 8Memory Required: 27 bytes per serverThe /S option specifies the number of servers that have the Btrieve NLM active on the network.idxid="w2468"book="_idx" docset="nw312" tidref="i4856"Configuring the OS/2 RequesterSet the Requester configuration options using the following command:  set brqparms=optionWIDTH="48"optionWIDTH="252"Any of the three configuration options (/C, /D, or /S).Do not include a space between BRQPARMS and the equal sign. You can, however, insert a space between each configuration option you specify.For example, to specify a 10,240-byte data message length and four servers, issue the following command:  set brqparms=/d:10240  /s:4The forward slash (/) before the configuration option is the only valid character you can use. If you specify a dash (-) or a backslash (\), the Requester may load improperly.idxid="w2469"book="_idx" docset="nw312" tidref="i3323"idxid="w2470"book="_idx" docset="nw312" tidref="i4856"Loading the OS/2 RequesterAn application may load the Btrieve for OS/2 Requester in one of the following two ways:Implicitly---Your application can implicitly load the OS/2 Requester either by linking with the import library BTRCALLS.LIB or by specifying imported functions in the application definition file. In either case, the operating system loads the OS/2 Requester automatically when the application is started.Explicitly---Your application can load the OS/2 Requester explicitly using the operating system API functions. When the application loads the Requester explicitly, the operating system does not load the OS/2 Requester until notified to do so.idxid="w2471"book="_idx" docset="nw312" tidref="i4856"Unloading the OS/2 RequesterAt an OS/2 workstation, the operating system removes the dynamic link routines from memory when the application terminates or when the application explicitly unloads the OS/2 Requester using the operating system API.If files remain open (as happens, for example, when an application does not issue a Close operation for each open file), simply logging out of one or more servers from a workstation does not close Btrieve files or terminate the Btrieve SPX connection to the server. To close files and terminate the connection, you must either unload the Requester or restart the workstation.ID="FM22327"idxid="w2472"book="_idx" docset="nw312" tidref="i5865"idxid="w2473"book="_idx" docset="nw312" tidref="i7455"idxid="w2474"book="_idx" docset="nw312" tidref="i794"Windows RequesterIn the Windows environment, you must load the DOS Requester, BREQUEST.EXE, before starting Windows. Windows-based Btrieve applications access the Requester by means of a DLL, WBTRCALL.DLL, which uses the DOS Protected Mode Interface (DPMI) that Windows provides.The Windows Requester (that is, WBTRCALL.DLL) is the Btrieve interface DLL for Windows v3.x. The DLL provides the same API as client-based Btrieve and requires no modification to the application. You can access local as well as remote files by running both client-based (local) Btrieve and the Requester at your workstation. If you want to run both client-based Btrieve and the Requester, you must run the Windows Conversion utility (WNDBCNVT.EXE) to convert the client-based WBTRCALL.DLL to WBTRLOCL.DLL. Client-based Btrieve is available only as part of the Btrieve Developer's Kit and must be purchased separately.idxid="w2475"book="_idx" docset="nw312" tidref="i1147"idxid="w2476"book="_idx" docset="nw312" tidref="i7455"idxid="w2477"book="_idx" docset="nw312" tidref="i4848"Windows Requester Configuration OptionsThe following list describes the available configuration options for the Windows Requester. These options should be specified in the NOVDB.INI file under [brequestDPMI].NOVDB.INI is the Novell initialization file for the Windows Requester. It is included on the distribution disketteWIDTH="108"Tasks=# WIDTH="168"Specifies how many concurrent tasks  may use the Windows Requester. The  range is 1 through 255. The default  value is 10.Local=Yes/NoInstructs the Windows Requester to  use client-based Btrieve for accessing  files locally. The default value is No.Chkparms=Yes/NoInstructs the Windows Requester to  validate pointers passed to it. You  should use this option only during  development. The default value is No.Free Memory=Yes/NoAllocates and frees real-mode memory  on each request. The Windows  Requester uses a buffer of real-mode  memory to communicate with the  DOS Requester. Since real-mode  memory is a scarce resource in  Windows, your application should  not retain it long term. The default  value is No.Specifying Yes to the Free Memory option degrades performance.idxid="w2478"book="_idx" docset="nw312" tidref="i3323"idxid="w2479"book="_idx" docset="nw312" tidref="i7455"Loading the Windows RequesterThe DOS Requester must be loaded before the Windows Requester can load. If you want to run Windows Btrieve applications, the DOS Requester must be loaded in the DOS environment before you start Windows. To load the DOS Requester, use the WINSTART.BAT file or type the following at the DOS prompt before loading Windows: brequest An application may load the Windows Requester in one of the following two ways:Implicitly---Your application can implicitly load the Windows Requester by either linking with the import library WBTRCALL.LIB or by specifying imported functions in the application definition file. When an application loads a DLL implicitly, the operating system automatically loads the DLL when the application is started. Explicitly---Your application may load the Windows Requester explicitly using the operating system API functions. The operating system does not load the DLL until notified to do so.If you want to run a DOS Btrieve application in the DOS box and a Windows Btrieve application at the same time, you must have the DOS Requester loaded in each DOS session. However, if you have already loaded the DOS Requester before loading Windows, you cannot load the DOS Requester in any subsequent DOS session. Consequently, you cannot run the DOS Btrieve application in the DOS box. For Windows applications using the DOS Requester, load BREQUEST outside Windows. In each Windows DOS session that will be running a Btrieve application, load BREQUEST with the /L option. Doing so loads another instance of BREQUEST that is available only to the DOS session. This operation provides the DOS session with its own copy of BREQUEST and prevents the DOS session from using the instance of BREQUEST that you loaded before starting Windows.idxid="w2480"book="_idx" docset="nw312" tidref="i7455"Unloading the Windows RequesterAt a Windows workstation, the operating system removes the dynamic link routines from memory when the application terminates or when the application explicitly unloads the DLLs using the operating system API functions.If Btrieve files remain open in an application because the application did not issue a Close operation, simply logging out of one or more servers from a workstation does not close the files or terminate the Btrieve SPX connection to the server. The files remain open until you restart the workstation or unload the DOS Requester using the BREQUTIL -STOP command. Also, keep in mind that a Reset operation closes files but does not unload the DOS Requester.LBL="5"ID="FM11326"Using Btrieve UtilitiesThis chapter provides the following sections:IDREF="FM21271""Btrieve Monitor Utility"---This utility monitors the activity of Btrieve.IDREF="FM13318""Btrieve Maintenance Utility"---This utility imports and exports Btrieve data and transfers data from one Btrieve file to another.IDREF="FM11782""Roll Forward Utility"---This utility recovers changes made to a Btrieve file between the time of the last backup and a system failure.ID="FM21271"Btrieve Monitor UtilityThe Btrieve Monitor utility (BTRMON.NLM) allows you to monitor Btrieve activities on a server. It provides information that is useful for both database administration and application programming diagnostics.The information you receive from the Btrieve Monitor utility pertains only to the activity of the NLMs on the current server.The Btrieve Monitor utility runs as an NLM at the server. You can access it at the server console or through RCONSOLE at your workstation.idxid="w2481"book="_idx" docset="nw312" tidref="i6677"idxid="w2482"book="_idx" docset="nw312" tidref="i840"idxid="w2483"book="_idx" docset="nw312" tidref="i840"idxid="w2484"book="_idx" docset="nw312" tidref="i840"System RequirementsTo run the Btrieve Monitor utility, be sure that the following software is loaded on your server:NetWare v3.12Btrieve v6.1 or laterBSPXCOM, BSPXSTUB, or RSPXSTUBRunning Btrieve v6.1 in a NetWare v3.12 environment requires AFTER311.NLM, which Btrieve loads automatically.In addition, the following files must be located in the SYS:SYSTEM directory of the server:BTRMON.NLMBTRMON.HLPThe NetWare INSTALL utility automatically places these files in the SYS:SYSTEM directory.idxid="w2485"book="_idx" docset="nw312" tidref="i840"idxid="w2486"book="_idx" docset="nw312" tidref="i3323"Starting the Btrieve Monitor UtilityTo start the Btrieve Monitor utility, enter the following command at the server console prompt: load btrmonAlternatively, you can include the command line option /R with the LOAD command. The /R option specifies the update time for the statistics screens that the utility dynamically updates. The range of valid values for this option is from 500 to 60,000 milliseconds; the default value is 2,000 milliseconds. For example, if you want to start the Btrieve Monitor utility and instruct it to update the statistics screens every 3,500 milliseconds, enter the following command: load btrmon /r3500Selecting Options from the Available Options MenuThe Available Options menu is the first screen you see after starting the Btrieve Monitor utility:FILE="n312b43p.pbm"You can select one of the following options from the Available Options menu:idxid="w2487"book="_idx" docset="nw312" tidref="i840"Active Resources---Displays information about active Btrieve data files. For more information, see IDREF="FM33793"page 5-4.User Information---Displays information about the users currently using the Btrieve NLM. This option also allows you to delete a user's SPX connection. For more information, see IDREF="FM20836"page 5-5.idxid="w2488"book="_idx" docset="nw312" tidref="i840"Resource Usage---Shows current, peak, and maximum usage statistics for the Btrieve NLM. For more information, see IDREF="FM27894"page 5-10.Communication Statistics---Displays Sequenced Packet Exchange (SPX) protocol statistics for the communications module you have loaded (BSPXCOM, BSPXSTUB, or RSPXSTUB). For more information, see IDREF="FM20928"page 5-12.When you are using the Btrieve Monitor utility, the statistics on the File Information, User Information, Resource Usage, and Communication Statistics screens are updated regularly. On the Active Btrieve Files and Active Btrieve Users screens, you must press the Insert key to see updated statistics.While running the Btrieve Monitor utility, you can return to the previous screen at any time by pressing the Esc key. To exit the utility, press Esc at the Available Options menu. When the Exit window appears, select Yes to verify that you want to exit.ID="FM33793"Monitoring Btrieve Files with the Active Resources Optionidxid="w2489"book="_idx" docset="nw312" tidref="i840"You can use the Active Resources option on the Available Options menu to do the following:List all active (open) filesDisplay additional information about a particular fileList all users accessing a particular fileidxid="w2490"book="_idx" docset="nw312" tidref="i840"Listing Active FilesTo list all active Btrieve files, select Active Resources from the Available Options menu. The utility displays a scrollable list of active Btrieve files:FILE="n312b63p.pbm"The file pathnames appear in alphabetic order. To update the list of active Btrieve files, press Insert.Displaying Additional Information About an Active FileFor further information about a particular file, highlight the desired file listed in the Active Btrieve Files screen and press Enter. The utility displays a File Information screen similar to the following, providing information about the file you selected.FILE="n312b64p.pbm"Since the utility dynamically updates the statistics shown on this screen, you may notice the values changing as you view the screen.For a description of each field that appears on this screen, refer to IDREF="FM18831"Table 5-1 on page 5-8. IDREF="FM18831"Table 5-1 lists, in alphabetic order, all fields associated with the Active Resources and User Information options.Listing Users Accessing a FileFrom the Active Resources option's File Information screen, you can list all users accessing the designated file. Press Enter to display a scrollable list of active Btrieve users. (See IDREF="FM18831"Table 5-1 on page 5-8 for a description of each field on this screen.)FILE="n312b65p.pbm"To update the list of active users, press Insert.ID="FM20836"Monitoring Btrieve Users with the User Information OptionYou can use the User Information option on the Available Options menu to do the following:List all active Btrieve usersList the files that a specific user is accessingDelete a user's SPX connection to BtrieveListing All UsersTo list all Btrieve users active on the current server, select User Information from the Available Options menu. The Btrieve Monitor utility displays a scrollable list of active Btrieve users:FILE="n312b66p.pbm"The utility identifies each active user based on user location, as follows:If the user is located at a workstation, the utility displays the username (such as JDOE).If the user is located at a local server, the utility displays either the process-supplied, two-character agent ID or the full name of the process (such as NetWare SQL). If the user is located at a remote server, the utility displays either the process-supplied, two-character agent ID or the full name of the process (such as NetWare SQL) provided the utility can determine the full name.To update the list of active users, press Insert.To display information about a user, highlight the user and press Enter. A User Information screen similar to the following appears. For a description of each field that appears on this screen, refer to IDREF="FM18831"Table 5-1 on page 5-8.FILE="n312b67p.pbm"Since the utility dynamically updates the statistics shown on this screen, you may notice the values changing as you view the screen.Listing Files Accessed by a UserWhile the User Information screen is displayed, you can press Enter to list all Btrieve files currently accessed by that user. A screen similar to the following appears.FILE="n312b68p.pbm"To update the list of active Btrieve files, press Insert.Deleting User ConnectionsDeleting a user's connection removes the user from the list of active Btrieve users and terminates the user's SPX connection to Btrieve. Use the following steps to delete a user's SPX connection:Select the User Information option on the Available Options menu.On the Active Btrieve Users screen, highlight the user connection that you want to delete, and press the Delete key. If the Btrieve Monitor utility does not list a connection number for the user you want to delete, but the NetWare connection has been terminated, then a Btrieve session is still active for that user. You must restart the workstation that originated the Btrieve session to delete the user for that session. You can avoid this problem by ensuring that your application issues a Btrieve Reset operation to close active Btrieve files and release all resources held by the application.In the prompt box that appears, select Yes if you are sure you want to delete the specified user. Otherwise, select No or press Esc.LBL="5-1" INLINE="F"ID="FM18831"Active Resources and User Information Field DescriptionsWIDTH="84"FieldWIDTH="336"Description WIDTH="84"Cache AccessesWIDTH="336"Shows the number of times the user has made Btrieve calls that accessed the Btrieve  cache buffers.WIDTH="84"ConnectionNumberWIDTH="336"Displays the NetWare connection number of the process if the process originates at a  workstation. If the process originates at a server, this column is empty.WIDTH="84"Disk AccessesWIDTH="336"Shows the number of times the user has made Btrieve calls that required disk I/O.WIDTH="84"HandlesWIDTH="336"Shows the number of Btrieve handles the user has as a result of opening files. Btrieve  creates a handle each time a user opens a file; therefore, a single user can have several  handles for the same file.WIDTH="84"Locks AvailableWIDTH="336"Indicates the total number of read locks available to the user.WIDTH="84"Locks UsedWIDTH="336"Indicates the number of locks that the user has explicitly requested. The number of  locks in use varies, depending on whether the user is in a transaction, as follows:WIDTH="84"WIDTH="336"If the user is outside a transaction, this number indicates the number of records  that the user has explicitly locked.WIDTH="84"WIDTH="336"If the user is inside a concurrent transaction, this number indicates the number of  pages in the file that the user has explicitly locked. Although the user actually  requests record locks, these are converted to page locks inside a concurrent  transaction. Consequently, five record locks are shown as two page locks if the five  records are stored on two pages.WIDTH="84"WIDTH="336"If the user is inside an exclusive transaction or the user holds no locks, this number  is zero.WIDTH="84"Open ModeWIDTH="336"Indicates the mode used to open the file:WIDTH="84"WIDTH="60"AcceleratedWIDTH="264"The application that opened the file has shared, read/write access.  With Btrieve v6.x, Accelerated mode is equivalent to Normal mode  unless the file is flagged transactional.WIDTH="84"WIDTH="60"ExclusiveWIDTH="264"The application that opened the file has exclusive access. Other  applications cannot open the file until the calling application closes it.WIDTH="84"WIDTH="60"NormalWIDTH="264"The application that opened the file has normal shared, read/write  access.WIDTH="84"WIDTH="60"Read onlyWIDTH="264"The application that opened the file has read-only access; the  application cannot modify the file.WIDTH="84"Page SizeWIDTH="336"Indicates the page size (in bytes) of this file. (A page is the smallest unit of storage that  Btrieve moves between main memory and the disk.)WIDTH="84"Read-Only FlagWIDTH="336"Indicates whether the file is flagged through NetWare as read only. WIDTH="84"Record LocksWIDTH="336"Shows the lock status of the current record:WIDTH="84"WIDTH="336"s---Single-record lock outside a transactionsWIDTH="84"WIDTH="336"S---Single-record lock within a transactionWIDTH="84"WIDTH="336"m---Multiple-record lock outside a transactionWIDTH="84"WIDTH="336"M---Multiple-record lock within a transactionWIDTH="84"WIDTH="336"N---No record locksWIDTH="84"WIDTH="336"Single-record locks allow a user to lock only one record at a time. Multiple-record locks allow a user to lock more than one record at a time.WIDTH="84"Records DeletedWIDTH="336"Number of records the user has deleted.WIDTH="84"Records InsertedWIDTH="336"Number of records the user has inserted.WIDTH="84"Records ReadWIDTH="336"Number of records the user has read.WIDTH="84"Records UpdatedWIDTH="336"Number of records the user has updated.WIDTH="84"SiteWIDTH="336"Specifies the location of the user process, as follows:WIDTH="84"WIDTH="336"LS---Local serverRS---Remote serverWS---WorkstationWIDTH="84"Task NumberWIDTH="336"Contains the process-supplied task number if the process originates at the server, a  Windows workstation, or an OS/2 workstation. If the process originates at a DOS  workstation, this column contains the SPX socket number.WIDTH="84"Transaction LockWIDTH="336"Indicates whether the entire file is locked by a transaction. A transactional file lock  exists only as long as the application that opened the file is processing a transaction.  Y indicates the entire file is locked. N indicates the file is not locked.WIDTH="84"idxid="w2491"book="_idx" docset="nw312" tidref="i840"idxid="w2492"book="_idx" docset="nw312" tidref="i6873"TTS FlagWIDTH="336"Indicates whether TTS is being used with the file. (For more information on TTS, refer  to your NetWare documentation.) WIDTH="84"User LocationWIDTH="336"Identifies the user process, as follows:WIDTH="84"WIDTH="336"If the user is located at a workstation, this column contains the network number  and node address.WIDTH="84"WIDTH="336"If the user is located at the server, this column contains the server name.ID="FM27894"idxid="w2493"book="_idx" docset="nw312" tidref="i840"Monitoring Resources with the Resource Usage OptionThe Resource Usage option on the Available Options menu shows you (in real time) the total resources in use by the Btrieve NLM since it was loaded. When you select this option, the Btrieve Monitor utility displays the Btrieve Resource Usage screen. FILE="n312b48p.pbm"Since the utility dynamically updates the statistics shown on this screen, you may notice the totals changing as you view the screen.The Current values on the Btrieve Resource Usage screen are cumulative from the time you enter the screen. IDREF="FM33230"Table 5-2 shows the field descriptions for the Resource Usage screen in alphabetic order.LBL="5-2" INLINE="F"ID="FM33230"Resource Usage Field DescriptionsWIDTH="60"FieldWIDTH="156"DescriptionWIDTH="204"Statistics WIDTH="60"ClientsWIDTH="156"Number of Btrieve processes.WIDTH="48"Current WIDTH="144"Number of active Btrieve processes.A process can be a BSPXCOM thread  representing a client, a Message  Router thread representing a client, or  a client NLM on the present server.PeakHighest number of processes  simultaneously active since the Btrieve  NLM was loaded.WIDTH="228"WIDTH="48"MaximumWIDTH="144"Value set for the Number of Remote  Sessions configuration option.FilesNumber of active Btrieve files.CurrentNumber of active Btrieve files.WIDTH="228"WIDTH="48"PeakWIDTH="144"Highest number of Btrieve files that  have been open simultaneously since  the Btrieve NLM was loaded.WIDTH="228"WIDTH="48"MaximumWIDTH="144"Value set for the Number of Open Files  configuration option.HandlesNumber of handles issued for Btrieve  files.CurrentNumber of active file handles.WIDTH="228"WIDTH="48"PeakWIDTH="144"Highest number of handles used  simultaneously since the Btrieve NLM  was loaded.WIDTH="228"WIDTH="48"MaximumWIDTH="144"Value set for the Number of Handles  configuration option.LocksNumber of implicit (system) page locks  involved in concurrent transactions.CurrentNumber of implicit active page locks.WIDTH="228"WIDTH="48"PeakWIDTH="144"Highest number of implicit page locks  used simultaneously since the Btrieve  NLM was loaded.WIDTH="228"WIDTH="48"MaximumWIDTH="144"Maximum simultaneous page locks  that the system will allow.ThreadsNumber of programs or program  threads calling Btrieve simultaneously.CurrentLast system snapshot of active  programs or program threads calling  Btrieve simultaneously.WIDTH="228"WIDTH="48"PeakWIDTH="144"Maximum value ever encountered for  the Current value since the NLM was  loaded.TransactionsNumber of concurrent and exclusive  transactions.CurrentNumber of active concurrent and  exclusive transactions.WIDTH="228"WIDTH="48"PeakWIDTH="144"Highest number of transactions active  simultaneously since the Btrieve NLM  was loaded.WIDTH="228"WIDTH="48"MaximumWIDTH="144"Value set for the Number of  Transactions configuration option.ID="FM20928"idxid="w2494"book="_idx" docset="nw312" tidref="i840"Monitoring SPX Activity with the Communication Statistics OptionThe Communication Statistics option on the Available Options menu shows you (in real time) the network requests, packet buffers, and sessions in use for the communications module you have loaded. When you select this option, the Btrieve Monitor utility displays the Communications Statistics screen for BSPXCOM, BSPXSTUB, or RSPXSTUB. FILE="n312b71p.pbm"The communication activity shown on this screen reflects the communication activity of the communications module loaded at your server: If you loaded BSPXCOM, you see incoming and outgoing SPX statistics.If you loaded BSPXSTUB, you see all zeros for the communication statistics.If you loaded RSPXSTUB, you see incoming and outgoing SPX communication statistics from the Message Router. This screen does not show the communication activity of any remote NLMs.The Total values shown on this screen are cumulative from the time Btrieve is loaded. The Current values are cumulative from the time you display the screen. IDREF="FM31684"Table 5-3 shows field descriptions for the Communication Statistics option, in alphabetic order.LBL="5-3" INLINE="F"ID="FM31684"Communication Statistics Field DescriptionsWIDTH="72"FieldWIDTH="132"DescriptionWIDTH="216"Statistics WIDTH="72"Btrieve RequestsWIDTH="132"Number of network requests  the NLM has processed from  workstations or remote  server-based applications.WIDTH="48"CurrentWIDTH="156"Current value since the last screen  update.WIDTH="216"WIDTH="48"TotalWIDTH="156"The number of requests received  since the Btrieve NLM was loaded.Concurrent  ProcessesNumber of remote requests the  NLM processes at one time.CurrentCurrent value since the last screen  update.WIDTH="216"WIDTH="48"MaxWIDTH="156"The maximum number of remote  clients the Btrieve NLM can process at  one time. SPX Packet BuffersNumber of SPX packet buffers  available to the NLM.AvailableCurrent number of available packet  buffers (as of the last screen update).WIDTH="216"WIDTH="48"MaxWIDTH="156"Value set for the maximum number of  available packet buffers. Each session  is allocated two packet buffers for  Btrieve requests.SPX Packets  ReceivedNumber of SPX packets the  NLM has received from  applications.CurrentCurrent value since the last screen  update.WIDTH="216"WIDTH="48"TotalWIDTH="156"The number of packets received since  the communications NLM was  loaded.SPX Packets SentNumber of SPX packets the  NLM has sent to other  applications.CurrentCurrent value since the last screen  update.WIDTH="216"WIDTH="48"TotalWIDTH="156"The number of packets sent since the  communications NLM was loaded.  The total packets sent may be larger  than the total packets received  because a single request received  might produce several packets sent.SPX Requests  ProcessedNumber of SPX requests the  NLM has processed.CurrentCurrent value since the last screen  update.WIDTH="216"WIDTH="48"TotalWIDTH="156"The number of requests processed  since the communications NLM was  loaded.SPX SessionsNumber of remote clients who  have established SPX sessions  with the communications  NLM.CurrentCurrent value since the  communications NLM was loaded.WIDTH="216"WIDTH="48"MaxWIDTH="156"Value set for the Number of Remote  Sessions configuration option.WIDTH="216"WIDTH="48"PeakWIDTH="156"Highest value since the  communications NLM was loaded.  This value indicates the highest  number of SPX clients that have  simultaneously had concurrent active  sessions with the communications  NLM.Unprocessed SPX  PacketsNumber of SPX packets the  NLM has received but not yet  processed.CurrentCurrent value since the last screen  update.ID="FM13318"idxid="w2495"book="_idx" docset="nw312" tidref="i3683"idxid="w2496"book="_idx" docset="nw312" tidref="i7261"idxid="w2497"book="_idx" docset="nw312" tidref="i3683"Btrieve Maintenance UtilityThe Btrieve Maintenance utility (BUTIL.NLM) is a command line utility that allows you to create, manipulate, and recover Btrieve data files. It runs as an NLM at the server. You can access it at the server console or at a workstation through the RCONSOLE utility. You can execute the Maintenance utility commands from the server command line or from a command file.idxid="w2498"book="_idx" docset="nw312" tidref="i3683"idxid="w2499"book="_idx" docset="nw312" tidref="i6677"To run the Maintenance utility, be sure that the following are installed on your server:NetWare v3.12Btrieve v6.1 or laterRunning Btrieve v6.1 in a NetWare v3.12 environment requires AFTER311.NLM, which Btrieve loads automatically.idxid="w2500"book="_idx" docset="nw312" tidref="i3683"Utility OverviewThis section provides information you need to know before using the Maintenance utility commands. It discusses the required command format, the concepts you should understand before running the Maintenance utility, and the use of command files.If you have used the utility before, you may want to skip to the individual command discussions, which begin on IDREF="FM23924"page 5-20. (The commands are discussed in alphabetic order.)Command Formatidxid="w2501"book="_idx" docset="nw312" tidref="i3683"The format for the Maintenance utility commands is as follows: LOAD BUTIL [-command [parameter...]] | @commandFileWIDTH="84"-commandWIDTH="228"A Maintenance utility command, such as COPY.  You must precede the command with a dash (-),  and you must enter a space before the dash. IDREF="FM21619"Table  5-4 lists the Maintenance utility commands.WIDTH="84"parameterWIDTH="228"Information that the command may require. The  discussions of the individual commands  (beginning on IDREF="FM23924"page 5-20) provide details when  applicable.WIDTH="84"commandFileWIDTH="228"Full pathname of a command file.LBL="5-4" INLINE="F"ID="FM21619"Maintenance Utility CommandsWIDTH="60"CommandWIDTH="252"Description WIDTH="60"IDREF="FM23924"CLONEWIDTH="252"Creates a new, empty Btrieve file using an existing file's  specifications.IDREF="FM22435"CLROWNERClears the owner name of a Btrieve file.IDREF="FM41760"COPYCopies the contents of one Btrieve file to another.IDREF="FM24833"CREATECreates a Btrieve file.IDREF="FM36822"DROPDrops an index.IDREF="FM25977"ENDBUEnds continuous operation on Btrieve files defined for  backup.IDREF="FM18693"INDEXCreates an external index file.IDREF="FM42733"LOADLoads the contents of a sequential file into a Btrieve file.IDREF="FM40237"RECOVERReads data sequentially from a Btrieve file and writes the  results to a sequential file.IDREF="FM21054"SALVAGEExamines a file's Page Allocation Table (PAT) to determine  if corruption has occurred and if repair is required.IDREF="FM14628"SAVEReads data along a key path and writes the results to a  sequential file.IDREF="FM39345"SETOWNERAssigns an owner name to a Btrieve file.IDREF="FM13473"SINDEXCreates an index.IDREF="FM36899"STARTBUStarts continuous operation on files defined for backup.IDREF="FM36492"STATReports statistics about file attributes and current sizes of  Btrieve files.IDREF="FM20037"VERDisplays the version of the Btrieve NLM that is loaded at  the server.idxid="w2502"book="_idx" docset="nw312" tidref="i3683"ConceptsThe following paragraphs describe concepts you should understand before using the Maintenance utility commands. FilenamesThe Maintenance utility runs as an NLM. The NLM environment does not recognize drive letters or environment variables. Thus, for commands that require a filename, the name must include the full pathname, such as SYS:\NWSQL\DEMODATA\PATIENTS.DTA. If you do not specify a volume, the utility assumes SYS: is the volume.Owner Namesidxid="w2503"book="_idx" docset="nw312" tidref="i4865"Btrieve allows you to restrict access to a file by specifying an owner name. Since owner names are optional, the files you use with this utility may or may not require an owner name.If the file requires an owner name, you must specify it using the /O option. (Alternatively, you can use a dash with this option, as in -O.) Owner names are case sensitive; that is, Sandy and SANDY are not considered to be the same. You can follow the /O option with an owner name or an asterisk (*). If you use an asterisk, the utility prompts you for an owner name. ID="FM23668"idxid="w2504"book="_idx" docset="nw312" tidref="i1356"idxid="w2505"book="_idx" docset="nw312" tidref="i3683"Description FilesA description file is an ASCII file containing information that the Maintenance utility commands CREATE, INDEX, and SINDEX need to perform their operations. Description files contain one or more elements. An element consists of a keyword, followed by an equal sign (=), followed by a value (with no space separator). Each element in the description file corresponds to a particular characteristic of a Btrieve file or key definition. IDREF="FM18833"Appendix A, "Description Files," provides more information.ID="FM13253"Continuous OperationContinuous operation is a Btrieve feature that allows you to back up files while they are in use by Btrieve applications. Two Maintenance utility commands, STARTBU and ENDBU, begin and end continuous operation on a file or set of files. When continuous operation begins, Btrieve creates a temporary Btrieve file (called a delta file) for each data file in order to record any changes made to the data file while the backup is taking place. This temporary delta file may surpass the size of the original data file if users make extensive changes to the file during continuous operation. When continuous operation ends, Btrieve updates the master Btrieve files with the changes stored in the delta files. Btrieve deletes the delta files as soon as all applications close the corresponding Btrieve data files. idxid="w2506"book="_idx" docset="nw312" tidref="i1234"idxid="w2507"book="_idx" docset="nw312" tidref="i1234"idxid="w2508"book="_idx" docset="nw312" tidref="i4820"As indicated above, when you place a Btrieve file into continuous operation mode, Btrieve creates a temporary delta file with the same name as the data file but with a .^^^ extension. Therefore, do not create multiple Btrieve files with the same names but different extensions. For example, do not use a naming scheme such as INVOICE.HDR and INVOICE.DET for your Btrieve files.idxid="w2509"book="_idx" docset="nw312" tidref="i626"To back up files using continuous operation, first issue the BUTIL -STARTBU command, followed by the file or set of files. Next, run your backup program. To stop continuous operation, issue the BUTIL -ENDBU command.The best time to place Btrieve data files into continuous operation for backup is when the fewest users will be making modifications to the files.idxid="w2510"book="_idx" docset="nw312" tidref="i3683"Command FilesYou can use a command file to do either of the following: Execute a command that is too long to fit on the command lineExecute a command that you use often (by entering the command once in the command file and then executing the command file as often as you want)Command files contain the same information as that required on the command line.Rules for Command FilesObserve the following rules when creating a Maintenance utility command file:You must limit each line to 130 characters.Lines longer than 130 characters could cause the server to end abnormally. For this reason, do not place long Maintenance utility commands in a server command (.NCF) file.You cannot split a single parameter across two lines.You can specify only one command per command file.Command File ExampleThe following is an example command file, COPYPATS.CMD. The file calls the BUTIL -CLONE command to clone the file PATIENTS.DTA. -clone sys:\nwsql\demodata\allpats.dtasys:\nwsql\demodata\patients.dta The following command uses the COPYPATS.CMD file: load butil @sys:\nwsql\demodata\copypats.cmdMaintenance Utility CommandsThis section describes the Maintenance utility commands and explains when and how to use each one. At any time while using the Maintenance utility commands, you can enter LOAD BUTIL to see the Maintenance utility commands. The utility responds with the following screen.FILE="n312b69p.pbm"ID="FM23924"CLONEThe CLONE command creates a new, empty Btrieve file with the same file specifications as an existing file (including any supplemental indexes, but excluding the owner name). The new Btrieve file includes all the defined key characteristics (such as key position, key length, or duplicate key values) contained in the existing file. Format LOAD BUTIL -CLONEoutputBtrvFile sourceBtrvFile [/Oowner]WIDTH="84"outputBtrvFileWIDTH="216"The full pathname you want to use for the  new, empty Btrieve file.sourceBtrvFileThe full pathname of the existing Btrieve file  that you want to replicate.ownerThe owner name, if any, for the source  Btrieve file. The new Btrieve file will not have  an owner name.RemarksBtrieve v6.x allows a maximum of 23 key segments in a Btrieve file with a page size of 1,024 bytes. Therefore, the CLONE command sets the page size in the new Btrieve file to 2,048 bytes if the existing Btrieve file contains 24 key segments and has a page size of 1,024 bytes. This occurs if the existing Btrieve file has a format earlier than Btrieve v6.0 and the Btrieve NLM was not loaded with the Create Btrieve Files in Pre v6.x Format configuration option.ExampleThe following command creates the NEWAPP.DTA file by cloning the PATIENTS.DTA file. load butil -clonesys:\nwsql\demodata\newapp.dta sys:\nwsql\demodata\patients.dta If you are trying to recover from receiving Status Code 30 and you suspect that the header page of the source file might be damaged, try creating the new Btrieve file by using the BUTIL -CREATE command with a description file.ID="FM22435"CLROWNERThe CLROWNER command clears the owner name of a Btrieve file.Format LOAD BUTIL -CLROWNER btrvFile /OownerWIDTH="60"btrvFileWIDTH="240"The full pathname of the Btrieve file.ownerThe owner name to be cleared.ExampleThe following command clears the owner name for the PATIENT1.DTA file. The owner name for the file is Sandy. load butil -clrownersys:\nwsql\demodata\patient1.dta /OSandyID="FM41760"COPYThe COPY command copies the contents of one Btrieve file to another. COPY retrieves each record in the input Btrieve file and inserts it into the output Btrieve 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 Btrieve file.COPY performs in a single step the same function as a RECOVER command followed by a LOAD command.By using the COPY command, you can create a Btrieve file that contains data from an old file, but has new key characteristics. To do so, proceed as follows:Use the CREATE command to create an empty Btrieve file with the desired key characteristics (key position, key length, or duplicate key values). Use the COPY command to copy the contents of the existing Btrieve file into the newly created Btrieve file.Format LOAD BUTIL -COPY inputBtrvFile outputBtrvFile [/Oowner1 [/Oowner2]]WIDTH="84"inputBtrvFileWIDTH="216"The full pathname of the Btrieve file from  which you want to transfer records.outputBtrvFileThe full pathname of the Btrieve file into  which you want to insert records. The output  Btrieve file can contain data or be empty.owner1The owner name of the input Btrieve file, if  required. If only the output Btrieve file  requires an owner name, specify /O followed  by a blank for owner1 (as illustrated in the  example).owner2The owner name of the output Btrieve file, if  required.ExampleThe following command copies the records in PATIENTS.DTA to NEWPATS.DTA. The PATIENTS.DTA input file does not require an owner name, but the NEWPATS.DTA output file uses the owner name Pam. load butil -copysys:\nwsql\demodata\patients.dta sys:\nwsql\demodata\newpats.dta /O /OPam If you omit the first /O from this example, the utility assumes that the owner name Pam belongs to the input Btrieve file, not the output Btrieve file.ID="FM24833"CREATEThe CREATE command generates an empty Btrieve 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 IDREF="FM18833"Appendix A, "Description Files."Format LOAD BUTIL -CREATE btrvFile descriptionFileWIDTH="84"btrvFileWIDTH="216"The full pathname of the Btrieve file you  want to create. If the pathname is the name  of an existing Btrieve file, this command  creates a new, empty Btrieve file in place of  the existing Btrieve file. Any data that was  stored in the existing Btrieve file is lost and  cannot be recovered. However, Btrieve does  not create a new Btrieve file if you specify replace=n in the description file. (For an  example, see IDREF="FM33539""Replace Existing File" on  page A-11 in Appendix A.)descriptionFileThe full pathname of the description file  containing the specifications for the new  Btrieve file.ExampleThe following command creates a Btrieve file named PATIENTS.DTA using the description provided in the BUILD.DES description file. load butil -create sys:\nwsql\patients.dtasys:\nwsql\build.desSample Description File for the CREATE Command The sample description file shown in the following illustration creates a Btrieve file. The Btrieve file is specified to have a page size of 512 bytes and 2 keys. The fixed-length portion of each record in the Btrieve file is set to 98 bytes. Variable-length records with no blank truncation, data compression, and Variable-tail Allocation Tables (VATs) are specified. The free space threshold is set to 20 percent. Allocation is set to 100 pages. Btrieve will preallocate 100 pages, or 51,200 bytes, when it creates the Btrieve file. FILE="n312b57a.pbm"idxid="w2511"book="_idx" docset="nw312" tidref="i2300"idxid="w2512"book="_idx" docset="nw312" tidref="i7096"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.ID="FM36822"DROPThe DROP command removes an index from a Btrieve 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 Btrieve v6.x files.Format LOAD BUTIL -DROP btrvFile keyNumber [/Oowner]WIDTH="72"btrvFileWIDTH="228"The full pathname of the Btrieve file from which  you are dropping the index.keyNumberThe number of the index you want to remove. If  you want to preserve the original key numbers,  add a 128 bias to the key number you specify.ownerThe owner name for the Btrieve file, if required.ExamplesIn both of the following examples, PATIENTS.DTA has three keys. The original keys in the file were numbered 0, 1, and 2.In the first example, the BUTIL -DROP command drops key number 1 from the PATIENTS.DTA file and renumbers the remaining key numbers as 0 and 1. load butil -dropsys:\nwsql\demodata\patients.dta 1In the following example, the BUTIL -DROP command drops key number 1 and does not renumber the keys. The key numbers remain 0 and 2. load butil -dropsys:\nwsql\demodata\patients.dta 129 ID="FM25977"ENDBUThe ENDBU command ends continuous operation on a Btrieve file or set of Btrieve files previously defined for backup. Execute this command after you have issued the STARTBU command and your backup utility has finished running. (For more information on the STARTBU command, see IDREF="FM36899""STARTBU" on page 5-39. For more information on continuous operation, see IDREF="FM13253""Continuous Operation" on page 5-18.)To back up Btrieve files using continuous operation, first issue the LOAD BUTIL -STARTBU command, followed by the Btrieve file or set of Btrieve files. Next, run your backup program. Then, stop continuous operation by issuing the LOAD BUTIL -ENDBU command.When you place a Btrieve file into continuous operation mode, Btrieve creates a temporary delta file with the same name as the Btrieve data file, but with a .^^^ extension. Therefore, do not create multiple Btrieve files with the same names but different extensions. For example, do not use a naming scheme such as INVOICE.HDR and INVOICE.DET for your Btrieve files.Format LOAD BUTIL -ENDBU [btrvFile|@filename]WIDTH="60"btrvFileWIDTH="240"The full pathname of the Btrieve file for which you  want to end continuous operation.@filenameThe name of a text file containing a list of Btrieve  files for which you want to end continuous  operation. The text file must contain the full  pathname for each Btrieve file, and you must  separate these pathnames with a space or a carriage  return/line feed. Typically, this list of Btrieve files  is the same as the list used with the STARTBU  command.If you do not specify any Btrieve files with the LOAD BUTIL -ENDBU command, the utility stops continuous operation on all Btrieve files initialized by BUTIL -STARTBU and currently running in continuous operation mode.ExampleThe following example ends continuous operation on the PATIENTS.DTA file. load butil -endbu sys:\nwsql\demodata\patients.dta ID="FM18693"INDEXidxid="w2513"book="_idx" docset="nw312" tidref="i2300"idxid="w2514"book="_idx" docset="nw312" tidref="i2801"The INDEX command builds an external index file for an existing Btrieve 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 on description files, see IDREF="FM18833"Appendix A, "Description Files.")The external index file created is a key-only Btrieve file. The records in the new file consist of the following:The 4-byte address of each record in the existing Btrieve fileThe new key value on which you want to sortIf the key length you specify in the description file is 10 bytes, the record length of the external index file would be 14 bytes (10 plus the 4-byte address).Format LOAD BUTIL -INDEX btrvFile indexFile descriptionFile [/Oowner]WIDTH="84"btrvFileWIDTH="216"The full pathname of the existing Btrieve file  for which you want to build an external  index.indexFileThe full pathname of the index file in which  Btrieve should store the external index.descriptionFileThe full pathname of the description file you  have created containing the new key  definition. The description file should  contain a definition for each segment of the  new key. ownerThe owner name for the Btrieve file, if  required.RemarksThe INDEX command creates the external index file and then displays the number of records that were indexed. If you want to retrieve the Btrieve file's records using the external index file, use the SAVE command (described in IDREF="FM14628""SAVE" on page 5-35).Sample Description File for the INDEX CommandThe 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 allows duplicates, is modifiable, is a string type, and uses no alternate collating sequence.FILE="n312b58a.pbm"ExampleThe following command creates an external index file called NEWPAT.IDX using a Btrieve file called PATIENTS.DTA. The PATIENTS.DTA file does not require an owner name. The description file containing the definition for the new key is called NEWIDX.DES. load butil -indexsys:\nwsql\demodata\patients.dta sys:\nwsql\demodata\newpat.idx sys:\nwsql\demodata\newidx.desWhen you place a Btrieve file into continuous operation mode, Btrieve creates a temporary delta file with the same name as the data file, but with a .^^^ extension. Therefore, do not create multiple Btrieve files with the same names but different extensions. For example, do not use a naming scheme such as INVOICE.HDR and INVOICE.DET for your Btrieve files.ID="FM42733"LOADThe LOAD command inserts records from an input sequential file into a Btrieve file. LOAD performs no conversion on the data in the input sequential file. After the utility transfers the records to the Btrieve file, it displays the total number of records loaded.Before running the LOAD command, you must create the input sequential file and the Btrieve file. You can create the input sequential file using a standard text editor or an application; the input sequential file must have the required file format (as explained subsequently). You can create the Btrieve file using either the IDREF="FM24833"CREATE or the IDREF="FM23924"CLONE command (BUTIL -CREATE or BUTIL -CLONE). Format LOAD BUTIL -LOAD inputFile btrvFile[/Oowner]WIDTH="60"inputFileWIDTH="240"The full pathname of the ASCII sequential file  containing the records to be loaded into a Btrieve  file.btrvFileThe full pathname of the Btrieve file into which  you want to insert the records.ownerThe owner name for the Btrieve file, if required.ID="FM23004"Required File FormatRecords in the input sequential file must be in the following format:The first field must be a left-adjusted integer (in ASCII) that provides the length of the record. This field does not include the carriage return or line feed.For files with fixed-length records, the length you specify should equal the record length of the Btrieve file.For files with variable-length records, the length you specify must be at least as long as the minimum fixed length of the Btrieve file.A separator (either a comma or a blank) must follow the length field.The record data follows the separator. The length of the data must be the exact number of bytes specified by the length field.A carriage return/line feed (0D0A hexadecimal) must terminate each line. The carriage return/line feed is not included in the length value at the beginning of the line, and LOAD does not insert the carriage return/line feed into the Btrieve file.The last line in the file must consist of the end-of-file character (Ctrl+Z or 1A hexadecimal). The SAVE and RECOVER commands and most text editors automatically insert this character in the file.You can create an input sequential file using either a text editor or an application, as follows:If you use a text editor to create the input sequential file, pad each record with blank spaces as necessary to fill the record to the length you specified at the beginning of the record. Fields containing binary data cannot be edited with most text editors.If you use an application to create the input sequential file, append a carriage return/line feed to the end of each record and include an end-of-file character (Ctrl+Z or 1A hexadecimal) as the last line in the file. The sequential I/O calls provided by most high-level language processors insert carriage return, line feed, and end-of-file characters automatically.The following illustration shows the correct format for records in the input sequential file. For this example, the Btrieve file has a defined record length of 40 bytes.FILE="n312b59a.pbm"ExampleThe following example loads sequential records from the PATIENTS.ADR file into the PATIENTS.DTA file. The owner name of the PATIENTS.ADR file is Sandy. load butil -load sys:\nwsql\demodata\patients.adr sys:\nwsql\demodata\patients.dta /OSandy ID="FM40237"idxid="w2515"book="_idx" docset="nw312" tidref="i5773"idxid="w2516"book="_idx" docset="nw312" tidref="i1302"RECOVERThe RECOVER command extracts data from a Btrieve file and places it in a sequential file that has the same format as the input sequential file used by the LOAD command. This is often useful for extracting some or all of the data from a damaged Btrieve 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 Btrieve file.The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable.The RECOVER command performs the following actions:Checks the file's Page Allocation Table (PAT) and reconstructs it, if users request this. The PAT is the part of the Btrieve file that maintains a map of each page's physical location.Reads records in physical order from the Btrieve file, using Btrieve Step operations.Creates a sequential file that is compatible with the required format for the LOAD command. (See IDREF="FM23004""Required File Format" on page 5-30 for more information about the format.)Displays the total number of recovered records.Format LOAD BUTIL -RECOVER btrvFile outputFile [/Oowner]WIDTH="60"btrvFileWIDTH="240"The full pathname of the Btrieve file from which  you want to recover data.outputFileThe full pathname of the ASCII sequential file  where the utility should store the recovered  records.ownerThe owner name for the Btrieve file, if required.RemarksIf the file's PAT is damaged, a prompt similar to the following appears: The file's Page Allocation Table seems to be damaged. BUTIL *strongly* recommends that you make a backup copy before continuing. Continue? 1=Yes 2=NoBy default, the prompt displays 2 (indicating No) on the next line. This allows you to exit the RECOVER command and back up the Btrieve file before proceeding. If you have already backed up the Btrieve file, enter 1 to continue running the RECOVER command.The RECOVER command allows you to set the Btrieve file's page size. It displays the following prompt: Enter the page size or 0 to quit: 512The value displayed at this prompt is the result of an attempt to determine the original page size of the Btrieve file. If this value is incorrect, enter the correct page size. If you enter a page size that differs from the original page size, the result is unpredictable. If you are unsure of the correct page size, change the value as prompted by the utility.If the logical disk drive containing your output sequential file becomes full before the entire Btrieve file has been recovered, the utility stops, indicates the number of records already recovered, and displays the following prompt: The disk volume is full. Enter new file name to continue or a period to quit.To continue running the RECOVER command using an additional output sequential file, complete one of the following steps:If you are recovering the Btrieve file to diskettes, remove the full diskette and replace it with another formatted diskette.If you are recovering the Btrieve file to a hard disk, specify another logical disk drive that has space available.In either case, enter the full pathname of the Btrieve file you want to use to continue storing records, and then press the Enter key. The utility continues copying records from the Btrieve file to the new output sequential file. This process creates multiple sequential files that you must load separately with the LOAD command.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 output sequential file and continues the recovery process.Upon completion, the utility displays a message similar to the following: 16 records recovered. Operation completed successfully.ExampleThe following example extracts records from the PATIENTS.DTA file and writes them into the SEQPAT.DAT file. load butil -recover sys:\nwsql\patients.dta sys:\nwsql\seqpat.datID="FM21054"idxid="w2517"book="_idx" docset="nw312" tidref="i6116"SALVAGEThe SALVAGE command examines the records in a file's PAT to determine if corruption has occurred. (The PAT maintains a map of the physical location of each page in the Btrieve file.) If corruption has occurred, the utility asks if you want to repair the PAT. Format LOAD BUTIL -SALVAGE btrvFile [/Oowner]WIDTH="60"btrvFileWIDTH="240"The full pathname of the Btrieve file containing  the records you want to check.ownerThe owner name for the Btrieve file, if required.RemarksIf the file's PAT is damaged, the utility reminds you that you should have a backup of the Btrieve file before proceeding and asks if you want to repair the file now. If you have already backed up the Btrieve file, enter Y (for Yes). If you have not backed up the Btrieve file, enter N (for No).After you enter Y, the utility asks you to enter a page size and provides you with the result of its attempt to determine the original page size. If you suspect that the value shown is incorrect, enter a new value. The utility then attempts to repair the Btrieve file, using the new value. If the utility cannot repair the Btrieve file, it sends a message identifying the reason why.The SALVAGE command does not save the records to a sequential file.ID="FM14628"idxid="w2518"book="_idx" docset="nw312" tidref="i5930"idxid="w2519"book="_idx" docset="nw312" tidref="i1256"SAVEThe SAVE command retrieves records from a Btrieve file using a specified index path and places them in a sequential file that is compatible with the required format for the LOAD command. You can then edit the sequential file and use the LOAD command to store the edited data in another Btrieve file. (IDREF="FM42733"See "LOAD" on page 5-29 for more information about LOAD.)SAVE generates a single record in the output sequential file for each record in the input Btrieve file. Upon completion, SAVE displays the total number of records saved.The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable.Format LOAD BUTIL -SAVE btrvFile outputFile [YindexFile| N keyNumber] [/Oowner]WIDTH="72"btrvFileWIDTH="228"The full pathname of the Btrieve file containing  the records you want to save.outputFileThe full pathname of the ASCII sequential file in  which you want the utility to store the records.indexFileThe full pathname of an external index file by  which you want to save records if you do not  want to save records using the default of the  lowest key number.keyNumberThe key number (other than 0) by which you  want to save records if you do not want to save  records using the default of the lowest key  number.ownerThe owner name for the Btrieve file, if required.RemarksIf the logical disk drive containing your output sequential file becomes full before the entire Btrieve file has been saved, the utility stops, indicates the number of records already saved, and displays the following message: The disk volume is full. Enter new file name to continue or a period to quit.To continue the SAVE operation in another output sequential file, complete one of the following steps:If you are saving the Btrieve file to diskettes, remove the full diskette and replace it with another formatted diskette.If you are saving the Btrieve file to a hard disk, specify another logical disk drive that has space available.In either case, enter the full pathname of the Btrieve file you want to use to continue storing records, and press the Enter key. The utility continues copying records from the Btrieve file to the new output sequential file. Keep in mind that this process creates multiple sequential files that you must load separately with the LOAD command.ExamplesThe following two examples illustrate how to use the SAVE command to retrieve records from a Btrieve file.The first example uses the NEWPAT.IDX external index file to retrieve records from the PATIENTS.DTA file and store them in an unformatted text file called PATIENTS.SAV:  load butil -savesys:\nwsql\demodata\patients.dta sys:\nwsql\demodata\patients.sav sys:\nwsql\demodata\newpat.idx The next example retrieves records from the PATIENTS.DTA file using key number 3 and stores them in an unformatted text file called PATIENTS.SAV: load butil -savesys:\nwsql\demodata\patients.dta sys:\nwsql\demodata\patients.sav N 3 ID="FM39345"SETOWNERThe SETOWNER command creates an owner for a Btrieve file.Format LOAD BUTIL -SETOWNER btrvFile /Oowner levelWIDTH="48"btrvFileWIDTH="252"The full pathname of the Btrieve file.WIDTH="48"ownerWIDTH="252"The owner name to be set. WIDTH="48"levelWIDTH="252"The type of access restriction for the Btrieve file. The  possible values for this parameter are as follows:WIDTH="48"WIDTH="12"0WIDTH="228"Requires an owner name for any access mode (no  data encryption)1Permits read access without an owner name (no  data encryption)2Requires an owner name for any access mode (with  data encryption)3Permits read access without an owner name (with  data encryption)ExampleThe following example creates an owner for the PATIENTS.DTA file. The owner name is Sandy, and the restriction level is 1. load butil -setowner sys:\nwsql\demodata\patients.dta /OSandy 1 ID="FM13473"idxid="w2520"book="_idx" docset="nw312" tidref="i2801"idxid="w2521"book="_idx" docset="nw312" tidref="i6597"SINDEXThe SINDEX command creates an additional index for an existing Btrieve file. The key number of the new index is one higher than the previous highest key number for the Btrieve file. 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.Before you can use the SINDEX command, you must create a description file to define key specifications for the index. For more information on description files, see Appendix A.Format LOAD BUTIL -SINDEX btrvFile descriptionFile [/Oowner]WIDTH="84"btrvFileWIDTH="216"The full pathname of the Btrieve file for  which you are creating the index.descriptionFileThe full pathname of the description file  containing the description of the index you  want to create.ownerThe owner name for the Btrieve file, if  required.ExamplesThe following example adds an index to the PATIENTS.DTA file. The name of the description file is SUPPIDX.DES. load butil -sindexsys:\nwsql\demodata\patients.dta sys:\nwsql\suppidx.des ID="FM36899"STARTBUThe STARTBU command places a file or set of files into continuous operation for backup purposes. To back up files using continuous operation, first issue the LOAD BUTIL -STARTBU command, followed by the Btrieve file or set of Btrieve files. Next, run your backup program. Then, issue the LOAD BUTIL -ENDBU command to stop continuous operation. For more information on the ENDBU command, see IDREF="FM25977""ENDBU" on page 5-26. For more information on continuous operation, see IDREF="FM13253""Continuous Operation" on page 5-18.When you place a Btrieve file into continuous operation mode, Btrieve creates a temporary file with the same name as the data file, but with a .^^^ extension. Therefore, do not create multiple Btrieve files with the same names but different extensions. For example, do not use a naming scheme such as INVOICE.HDR and INVOICE.DET for your Btrieve files.Format LOAD BUTIL -STARTBU <btrvFile | @filename>WIDTH="60"btrvFileWIDTH="240"The full pathname of the Btrieve file on which to  begin continuous operation for backup.@filenameThe name of a text file containing the full  pathnames of files on which to begin continuous  operation. Separate these pathnames with a space  or a carriage return/line feed.This command begins continuous operation only on the files you specify. You cannot use wildcards with the STARTBU command.ExampleThe following example starts continuous operation on the PATIENTS.DTA file. load butil -startbusys:\nwsql\demodata\patients.dta ID="FM36492"idxid="w2522"book="_idx" docset="nw312" tidref="i2300"idxid="w2523"book="_idx" docset="nw312" tidref="i6524"STATThe STAT command reports the defined characteristics of a Btrieve file and statistics about the file's contents. Format LOAD BUTIL -STAT btrvFile [/Oowner]WIDTH="60"btrvFileWIDTH="240"The full pathname of the Btrieve file for which you  want to display statistics.ownerThe owner name for the Btrieve file, if required.ExampleThe following example retrieves the file statistics for the PATIENTS.DTA file. The Btrieve file does not have an owner name. load butil -statsys:\system\515\patients.dta The following illustration shows the resulting output screen:FILE="n312b70p.pbm"This example shows that the file called PATIENTS.DTA was defined with a record length of 104 bytes, does not allow variable-length records, has 3 keys, and has a page size of 2,048 bytes. Sixteen records have been inserted into the file. The file does not use data compression and is using all its preallocated pages.The Btrieve file version is 6.0. (If you created the Btrieve file with VATs or multiple alternate collating sequences, the STAT command displays file version 6.1. Otherwise, it displays file version 6.0.)The STAT command designates case-insensitive keys and key segments with the letter I, descending keys with the symbol <, manual keys with the letter M, alternate collating sequence keys with an asterisk (*), and repeating-duplicatable keys with the letter R. Indexes created with SINDEX are also designated with the letter R by default unless you specified the Reserved Duplicate Pointer element.The remainder of the screen provides information about specific keys. For example, the screen shows that Key 0 allows duplicates, is modifiable, and consists of two segments:The first segment starts in position 21, is 20 characters long, allows duplicates, is modifiable, and will be sorted as a string type. The dashes indicate that a null value was not defined. The Total column indicates that 16 unique key values were inserted for this key.The second segment starts in position 7, is 12 characters long, allows duplicates, is modifiable, and will be sorted as a string type. Sixteen unique key values were inserted for this key.Key 1 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 key values were inserted for this key.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.The STAT command handles indexes the same whether they were created by the Btrieve Create Supplemental Index operation (in Btrieve v6.x) or the Btrieve Create operation. The information displayed by the STAT command does not differentiate between these indexes.ID="FM20037"VERThe VER command returns the version number of the Btrieve NLM loaded at the server.Format LOAD BUTIL -VER RemarksWhen you run the VER command, the utility displays messages similar to the following: Btrieve Version is 6.1 NLM. Operation completed successfully.ID="FM11782"idxid="w2524"book="_idx" docset="nw312" tidref="i7261"idxid="w2525"book="_idx" docset="nw312" tidref="i6008"Roll Forward Utilityidxid="w2526"book="_idx" docset="nw312" tidref="i1302"idxid="w2527"book="_idx" docset="nw312" tidref="i5773"The Roll Forward utility is a workstation utility that recovers changes made to a Btrieve file between the time of the last backup and a system failure. The changes are stored in a log file. If a system failure occurs, you can restore the backup copy of your Btrieve file and run the Roll Forward utility. The utility applies the changes stored in the log file to your backup copy. Roll Forward utilities are available for DOS, OS/2, and Windows operating environments, as follows:idxid="w2528"book="_idx" docset="nw312" tidref="i6008"BROLLFWD.EXE---The Roll Forward utility for the DOS operating environment. You run BROLLFWD from the command line.idxid="w2529"book="_idx" docset="nw312" tidref="i6008"PBROLL.EXE---The Roll Forward utility for the OS/2 environment. You run PBROLL interactively.idxid="w2530"book="_idx" docset="nw312" tidref="i6008"WBROLL.EXE---The Roll Forward utility for the Windows environment. You run WBROLL interactively.The procedure for running PBROLL and WBROLL is the same.Setting Up Files for LoggingTo take advantage of Btrieve's logging feature and the Roll Forward utility, you must first set up your Btrieve files for logging, as follows: idxid="w2531"book="_idx" docset="nw312" tidref="i3386"idxid="w2532"book="_idx" docset="nw312" tidref="i6008"Activate Btrieve's logging configuration option (using the Setup utility, BSETUP.NLM). Create the log configuration file, BLOG.CFG.Back up your data files before the logging begins. The following sections explain each step.Activating the Btrieve Logging OptionYou can activate Btrieve's logging feature by specifying Yes for the Logging of Selected Files configuration option in the Setup utility. The default setting for this option is No. If you did not specify Yes for this option when you configured Btrieve, complete the following steps to activate Btrieve logging:Run the Setup utility (BSETUP.NLM).When the Available Options menu appears, select Set Btrieve Configuration. When the Current Btrieve Configuration screen appears, specify Yes for the Logging of Selected Files option. Press the Escape key. When the Save Configuration Changes? window appears, select Yes. To have your changes take effect, unload Btrieve using the BSTOP command and then reload it using the BSTART command. Btrieve reloads with the logging feature activated.ID="FM14400"idxid="w2533"book="_idx" docset="nw312" tidref="i717"idxid="w2534"book="_idx" docset="nw312" tidref="i6008"idxid="w2535"book="_idx" docset="nw312" tidref="i2300"Creating the Log Configuration FileBLOG.CFG is the log configuration file. It specifies all Btrieve files for which you want to log changes on a given volume.You should create a BLOG directory at the root of each volume that contains Btrieve files for which you want to log changes. You can then create a BLOG.CFG file in each BLOG directory and place entries in it, as follows:Create the BLOG.CFG file.Open the BLOG.CFG file. For each Btrieve file for which you want to log operations, create an entry using the following format: \directory1\btrvFile[=\directory2\logFile]WIDTH="60"directory1WIDTH="228"The path to the Btrieve file to be logged. Do not include server names, volume names, or DOS drive letters.WIDTH="60"btrvFileWIDTH="228"The name of the Btrieve file to be logged.directory2The path to the log file. If the log file and the  Btrieve file are on the same volume, you can  omit the server and volume names. If they are  on different volumes, you must include the  server and volume names.When including the server name, place a double backslash (\\) before it.WIDTH="60"logFileWIDTH="228"The name of the log file. Although the log file  and the Btrieve file can be on different  volumes, they cannot be on different servers.Make sure each entry fits completely on one line. You can place multiple entries on the same line, but they must be separated by at least one space. Each line can contain a maximum of 256 characters.If you do not provide a log name, Btrieve (at the time the file is first opened) assigns the original filename to the log file and gives it a .LOG extension. For example, if you did not specify a log name for the Btrieve file TEST01.DAT in the directory TEST, Btrieve would assign the full name \TEST\TEST01.LOG to the associated log file. In this case, the default log file shares the same directory as the Btrieve file.The next three examples show sample entries in the file \BLOG\BLOG.CFG on the SYS: volume of the CORP server. Each of these entries causes activity in the file \DATA\B.BTR on the CORP server's SYS: volume to be logged into the file \DATA\B.LOG on the CORP server's SYS: volume.  \data\b.btr \data\b.btr=\data\b.log \data\b.btr=\\corp\sys:\data\b.logThe next example (again, a sample entry in \BLOG\BLOG.CFG on the CORP server's SYS: volume) shows how to log activity to a volume other than the Btrieve data file's volume. This entry directs Btrieve to log activity in the file \DATA\B.BTR on the CORP server's SYS: volume into the log file \DATA\B.LOG on the VOL1: volume of the CORP server. \data\b.btr=\\corp\vol1:\data\b.logBacking Up Data FilesBe sure to make a backup copy of your Btrieve data files before logging begins. When logging is activated for a given file, Btrieve records (in the corresponding log file) all the operations that change that file. Btrieve continues appending subsequent operations to the end of this log file until the log file is deleted. Consequently, it is important to perform periodic maintenance to reduce the size of the log files.Every time you back up your Btrieve data files, delete the associated log files before executing any further operations that could change the files. Synchronization of the backup data files and the associated log files is critical to recovering operations successfully.idxid="w2536"book="_idx" docset="nw312" tidref="i6008"Running the Roll Forward Utility in a DOS Environmentidxid="w2537"book="_idx" docset="nw312" tidref="i770"To run the Roll Forward utility in a DOS environment, enter the BROLLFWD command using the following format: BROLLFWD <btrvFile | @listFile | /A> [/D:nn] [/T:nn] [/K:nn] [/H] [/V] [/L] [/O:ownerName]The following list describes the BROLLFWD command syntax:WIDTH="60"btrvFileWIDTH="240"Specifies the name of a single Btrieve file to be  recovered. @listFileSpecifies the name of a text file that contains a list  of Btrieve filenames separated by one or more  spaces. Use a list file to recover multiple files. /ASpecifies that you want to recover all the Btrieve  files in the BLOG.GFG file./D:Specifies the data buffer size (in kilobytes) that the  Roll Forward utility allocates for Btrieve log  operations. /D: is optional. The default size is 8 KB,  the minimum is 1 KB, and the maximum is 64 KB.  You can specify the length in increments of 1 KB. /T:Specifies the length of the data (in bytes) that will  be printed in the list file for each operation that is  rolled forward. /T: is optional. Valid data lengths range from 1 through the value  of the data buffer size specified with the /D:  option. The default value is 40 bytes./K:Specifies the length of the key (in bytes) that will  be printed in the list file for each operation that is  rolled forward. /K: is optional. Valid lengths for printing keys range from 1  through 255 bytes. The default value is 10 bytes./HSpecifies that the Btrieve operations in the list file  will be printed in hexadecimal format. The default  prints the data and key in decimal numbers. /H is  optional./VSpecifies that for each logged file in the list file, the  utility will add the time stamps of the Roll Forward  operation and log file creation. For each logged  operation, it adds the name of the user who  performed the operation, the internetwork address  of the source workstation, the time stamp  indicating when the operation was performed, and  the record length and key number used in the  operation. /V is optional./LSpecifies that you want only to list the logged  operations. The logged operations will not be  executed. The operations will be listed to the  standard output device. /L is optional./O:Specifies an owner name. If the backup copy of the  Btrieve file you want to recover has a Btrieve owner  name, you must provide this option. This protects  the owned files from being changed inadvertently.Typically, all owned files in an application have  the same owner name. Therefore, the utility  assumes that all Btrieve files listed in the file list  have the same owner name. However, some Btrieve files in a file list may have  different owners. If a Btrieve file has an owner  name, that file has only one owner name. In that  case, the utility prompts you to enter the owner  name. Similarly, if you do not specify /O and the  utility encounters a Btrieve file that requires an  owner name, BROLLFWD prompts you for that  owner name.ownerNameSpecifies the owner name of the Btrieve files to be  accessed. When you use /O, you must specify an  owner name. idxid="w2538"book="_idx" docset="nw312" tidref="i6008"Running the Roll Forward Utility in an OS/2 or Windows EnvironmentThe following list shows a few ways you can run the Roll Forward utility:WIDTH="108"From This PositionWIDTH="192"Do ThisWIDTH="108"OS/2 command lineWIDTH="192"Type PBROLLPresentation ManagerDouble click on the Roll Forward iconWindowsDouble click on the Roll Forward icon, or choose  Run... from the File pulldown menu and type WBROLLThe following documentation applies to both OS/2 and Windows operating environments, but the screen examples show Windows screens only.To use the Roll Forward utility in the OS/2 and Windows environments, you need to complete the following steps:Set the Roll Forward utility's program options.Place in the utility's queue all the items you intend to roll forward.Start rolling forward the items in the queue.Following a brief description of the Roll Forward utility's pulldown menus, subsequent sections describe each of these steps in detail.Using the Roll Forward Pulldown MenusAfter starting the Roll Forward utility, you can access two pulldown menus: Queue and Options.If you are not using a mouse, you can access the menus by pressing and holding the Alt key while typing the letter highlighted in the menu selection. For example, to select the Queue pulldown menu, hold down the Alt key and press Q. To move between fields in the dialog boxes, use the Tab key.idxid="w2539"book="_idx" docset="nw312" tidref="i6008"Queue MenuWhen you select Queue from the main menu, a pulldown menu offers the following:WIDTH="60"Add...WIDTH="240"Generates a dialog box in which you can specify items  to be placed in the queue.View...Generates a dialog box in which you can view the  queued items. If no items are in the queue, this  selection is disabled.StartBegins the process of rolling forward all items in the  queue. Like the View... selection, this selection is  disabled if no items are in the queue.ExitExits the utility. In the Windows and OS/2  environments, you can also press F3 to exit. idxid="w2540"book="_idx" docset="nw312" tidref="i6008"Options MenuWhen you select Options from the main menu, a pulldown menu offers the following:WIDTH="60"Options...WIDTH="240"Generates a dialog box that lets you set the data buffer  length and the list options.About...Displays the version of the Roll Forward utility that  you are running.Setting Options for the Roll Forward UtilityYou should set program options for the Roll Forward utility before using the utility to roll forward changes. These options control the following:Size of the data buffer used to retrieve recordsMultitasking operationContents of the list file (BROLL.LST)IDREF="FM17831"Table 5-5 describes each of these options in detail. Subsequent sections describe the two methods you can use to set the program options:By using the Options pulldown menu.By editing the initialization file. (The NOVDB.INI file for OS/2 cannot be edited.)LBL="5-5" INLINE="F"ID="FM17831"Roll Forward Program OptionsWIDTH="84"Program OptionWIDTH="228"Description WIDTH="84"Data LengthWIDTH="228"Specifies the number of kilobytes allocated for the data  buffer that the utility uses to process the logged entries.  This number should be at least as large as the largest  record to be rolled forward. The default is 4 KB.WIDTH="84"Exclusive OperationWIDTH="228"Runs in one of two ways, depending on your  operating system:WIDTH="84"WIDTH="60"WindowsWIDTH="156"Windows v3.x emulates multitasking and  lets you run more than one application  concurrently. If you select Exclusive  Operation, the Roll Forward utility uses  the CPU time exclusively. If you do not  select this option, the utility shares CPU  time with other applications.WIDTH="156"WIDTH="156"If you plan to run recorder-type programs  or batch execution programs with Roll  Forward, check this box to ensure  correct operation. Selecting Exclusive  operation also enhances performance  slightly.OS/2OS/2 provides true multitasking; the Roll  Forward utility can always run  concurrently with other applications.  You can, however, vary the priority of the  Roll Forward thread to accommodate  other threads that are running. The  following priorities are available:WIDTH="156"WIDTH="156"Idle---Runs only when no other tasks are  waiting for the CPUWIDTH="156"WIDTH="156"Low---Lower priority than normalWIDTH="156"WIDTH="156"Normal---The default thread priorityWIDTH="156"WIDTH="156"High---Higher priority than normalWIDTH="84"List FilesWIDTH="228"Specifies the listing options for the list file BROLL.LST.  You can select one of the following:VerboseFor each logged file, this option adds the  time stamps of the Roll Forward  operation and log file creation to the list  file. For each logged operation, it adds  the name of the user who performed the  operation, the internetwork address of  the source workstation, the time stamp  indicating when the operation was  performed, and the user-defined lengths  of data and key numbers used in the  operation.Data to listSpecifies the length of the data buffer  that will be printed in the list file for each  operation that is rolled forward.Key to listSpecifies the length of the key buffer that  will be printed in the list file for each  operation that is rolled forward.ASCIILists the Btrieve operation values in ASCII  mode.HexLists the Btrieve operation values in  hexadecimal mode.Setting Options from the Options MenuTo set Roll Forward options using the Options pulldown menu, complete the following steps:Select Options from the Roll Forward main menu.Select Options... from the Options pulldown menu to display the following dialog box: FILE="n312b54p.pbm"Set the options using the guidelines provided in IDREF="FM17831"Table 5-5.After setting the options, select one of the following:Save---accepts and saves the changes you have made to the .INI file.OK---accepts the changes but does not save them to the .INI file.CANCEL---cancels the changes and returns to the previous screen.Setting Options in the Initialization FileYou can also change the setting of the Roll Forward utility's program options by editing the initialization file idxid="w2541"book="_idx" docset="nw312" tidref="i2300"idxid="w2542"book="_idx" docset="nw312" tidref="i4674"NOVDB.INI (for Windows). These settings are specified under [wbroll] in NOVDB.INI. An example specification for [wbroll] follows: [wbroll]  datalength=4  exclusive=no  outputmode=ASCII  listverbose=yes  datalist=32  keylist=16Placing Items in the Queueidxid="w2543"book="_idx" docset="nw312" tidref="i6008"The Roll Forward utility works on a queued-job basis. When you specify the Btrieve files that are to be rolled forward, the utility places them in the queue. This section discusses the Roll Forward utility's queue and explains how to do the following:Add items to the queueDelete items from the queueChange list options for a queued itemView items in the queueAdding Items to the QueueThe queue can hold a maximum of 32 items. Any of the following represents one item:An individual Btrieve fileA text file listing several Btrieve filesAll files from a specified volumeTo add items to the queue, complete the following steps:Select Add... from the Queue pulldown menu. The Add... dialog box (similar to the following) appears:FILE="n312b52p.pbm"Select the Btrieve file or files to be rolled forward, as follows:To select the entire volume, click on the Entire Volume check box.To select a particular file, scroll the Directories list box (the list box on the right) to find your directory or drive. Double click on the directory name and then choose the filename from the Files list box (the list box on the left). To enter a text file containing a list of files, enter the filename in the Filename text box. To select all available files with a certain extension, you can enter a wildcard character for the filename, followed by the extension. Then, press Enter.To select the parent directory from the Directories list box, set "show dots=on" in your NET.CFG file. Refer to your NetWare documentation for more information on NET.CFG.Specify the list option for the queue item you are adding, as follows:If you want only to list the Btrieve operations to be rolled forward (without actually rolling the logged operations forward), click on the List Only and List File check boxes. The operations will be listed in the file BROLL.LST in the BLOG directory.If you want to list the operations in BROLL.LST and roll forward the operations, click on the List File check box.If you do not want to list the operations that are rolled forward but you do want to roll the operations forward, do not click on either the List Only or List File checkbox.If the Btrieve file has an owner name, specify the owner name in the Owner text box. Click on the Add button to add the item to the queue.Repeat Steps 2 through 5 to add each additional item to the queue.To review the items you have placed in the queue, click on the Queue... button. The items selected appear on a screen similar to the following:FILE="n312b53p.pbm"When you are finished, click on the OK button.At any time, you can click on the CANCEL button to cancel your changes and return to the previous screen.Deleting Items from the QueueIf you need to delete an item from the queue, complete the following steps:Select View... from the Queue pulldown menu.Select the item you want to delete.Click on the Delete button to remove the item from the queue.Click on the OK button.If you change your mind and want to cancel your deletion, click on the CANCEL button instead of OK.Changing List Options for a Queued ItemYou can use either of the following methods to change the list options (that is, your choices regarding the List Only and List File check boxes) for a given queue item:Select Add... from the Queue menu and then click on the Add button. Next, select the relevant item and choose the list option you prefer.Select View... from the Queue menu, select the relevant item, and choose the list option you prefer.Viewing Items in the QueueYou can use either of the following methods to view items in the queue:From the Queue pulldown menu, select View... to display a dialog box that lists the queued items. (You can select this option only if the queue has one or more items in it.)While you are adding items to the queue, click on the Queue... button to list the files in the queue.idxid="w2544"book="_idx" docset="nw312" tidref="i6008"Rolling Forward Items in the QueueOnce the queue contains all the items for which you want to roll forward changes, you are ready to start the roll forward process. Select Start from the Queue pulldown menu.FILE="n312b72p.pbm"The Roll Forward utility allows a maximum of 250 concurrent transactions per Btrieve file during the roll forward process.After you select Start, the utility lists each Btrieve file being rolled forward and specifies the number of logged entries for each file. (The number of logged entries is shown to the left of the filename.)FILE="n312b56p.pbm"LBL="A"ID="FM18833"Description FilesA description file is an ASCII file containing information that the Maintenance utility commands CREATE, INDEX, and SINDEX need to perform their operations. Description files contain one or more elements. An element consists of a keyword, followed by an equal sign (=), followed by a value (with no space). Each element in the description file corresponds to a particular characteristic of a Btrieve file or key definition.The sections in this appendix discuss the following topics:IDREF="FM33709"Rules for Description FilesIDREF="FM19638"Description File ExampleIDREF="FM27334"Description File ElementsID="FM33709"Rules for Description FilesUse the following rules when creating a description file.Enter elements in lowercase, as in the following example: type=flo Separate elements from each other with a separator (blank space, tab, or carriage return/line feed), as in the following example: record=4000 key=24Specify the description file elements in the proper order. IDREF="FM28099"Table A-1 presents the elements in the appropriate order.The order of the elements required for the CREATE, INDEX, and SINDEX commands is the same. However, these commands do not all require the same elements. Address all element dependencies. For example, consider the following Null Key element: null=y If you specify this element in the description file, you must also include the Null Key Value element.Define as many keys as you specify with the Key Count element. The following example specifies 12 keys for the file: key=12In this case, you must define 12 keys in the description file, each consisting of one or more segments. For a key with multiple segments, you must define the following elements for each key segment:Key PositionKey LengthDuplicate Key Values Modifiable Key Values Key TypeAlternate Collating SequenceThe Descending Sort Order element is optional for each segment.If any key in the file uses an alternate collating sequence, include either an alternate collating sequence filename or a country ID and code page ID. You can include this information as either the last element of the key segment or the last element in the description file. If a description file element is optional, you can omit it from the description file.Make sure the description file contains no text formatting characters. Some word processors embed formatting characters in a text file.ID="FM19638"Description File ExampleThe sample description file shown in Figures A-1, A-2, and A-3 creates a Btrieve file. This Btrieve file has a page size of 512 bytes and 2 keys. The fixed-length portion of the record is 98 bytes long. The file allows variable-length records but does not use blank truncation. The file uses data compression, allows for Variable-tail Allocation Tables (VATs), and has the free space threshold set to 20 percent. Btrieve preallocates 100 pages, or 51,200 bytes, when it creates the file. The file has two keys: Key 0 and Key 1. Key 0 is a segmented key with two segments.LBL="A-1"ID="FM22277"Sample Description File Using Alternate Collating Sequence FilenameFILE="n312b57a.pbm"In IDREF="FM22277"Figure A-1, an alternate collating sequence filename (UPPER.ALT) is specified for Key 0.If you specify y for the Alternate Collating Sequence element for a key, you must supply an alternate collating sequence filename or a country ID and code page ID.LBL="A-2"ID="FM12483"Sample Description File Using Alternate Collating Sequence IDFILE="n312b73a.pbm"In IDREF="FM12483"Figure A-2, a country ID and code page ID are specified (countryid=-1 and codepageid=-1). If you specify the name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) at the end of the description file, Btrieve uses it as the default alternate collating sequence. That is, if you specify alternate=y for a given key but do not include a name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) for that key, Btrieve uses the name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) specified at the end of the description file.LBL="A-3"ID="FM41006"Sample Description File Using Alternate Collating Sequence Filename on a File SegmentFILE="n312b74a.pbm"In IDREF="FM41006"Figure A-3, a different alternate collating sequence filename is specified for Key 0 and Key 1. If you want to use different alternate collating sequences for different keys, you must specify the name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) for each key that uses a different alternate collating sequence. Different segments of the same key cannot have different alternate collating sequences. You can specify only one alternate collating sequence per key, and you must provide an alternate collating sequence filename (or values for the countryid=nnn and codepageid=nnn elements) for each segment of the key. The filename for the name=sequenceFile element (or values for the countryid=nnn and codepageid=nnn elements) must be the same for each segment. In IDREF="FM41006"Figure A-3, the filename specified for each segment in Key 0 is LOWER.ALT. The filename specified for Key 1 is UPPER.ALT.ID="FM27334"Description File ElementsIDREF="FM28099"Table A-1 lists the description file elements in the order in which they must appear in the description file. For each element, IDREF="FM28099"Table A-1 specifies the required format, the range of acceptable values, and the associated commands. An asterisk (*) after the element name indicates that the element is optional. Descriptions of the individual elements follow the table.LBL="A-1" INLINE="F"ID="FM28099"Summary of Description File ElementsWIDTH="108"ElementWIDTH="108"FormatWIDTH="72"RangeWIDTH="108"CommandWIDTH="108"IDREF="FM26479"Record LengthWIDTH="108"record=nnnnWIDTH="72"4-4,088WIDTH="108"CREATEIDREF="FM39575"Variable-Length Recordsvariable=<y|n>N/ACREATEIDREF="FM20979"Reserved Duplicate Pointer*dupkey=<nnn>1-119CREATEIDREF="FM13925"Blank Truncation*truncate=<y|n>N/ACREATEIDREF="FM36163"Data Compression*compress=<y|n>N/ACREATEIDREF="FM13742"Key Countkey=nnn0-118CREATEIDREF="FM39576"Page Sizepage=nnnn512-4,096CREATEIDREF="FM13129"Page Preallocation*allocation=nnnnn1-65,535CREATEIDREF="FM33539"Replace Existing File*replace=<y|n>N/ACREATEIDREF="FM26746"Include Data*data=<y|n>N/ACREATEIDREF="FM25745"Free Space Threshold*fthreshold=<10|20|30>N/ACREATEIDREF="FM22942"Variable-Tail Allocation  Tables (VATs)huge=<y|n>N/ACREATEIDREF="FM21340"Balanced Index*balance=<y|n>N/ACREATEIDREF="FM28259"Key Positionposition=nnnn1-4,088CREATE, INDEX, SINDEXIDREF="FM38759"Key Lengthlength=nnnkey type limitCREATE, INDEX, SINDEXIDREF="FM20568"Duplicate Key Valuesduplicates=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM33611"Modifiable Key Valuesmodifiable=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM16254"Key Typetype=validBtrieveKe yTypeN/ACREATE, INDEX, SINDEXIDREF="FM41254"Descending Sort Order*descending=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM14468"Alternate Collating  Sequence*alternate=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM25049"Case-Insensitive Key*caseinsensitive=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM42029"Repeating Duplicates*repeatdup=<y|n>N/ACREATE, SINDEXIDREF="FM39032"Manual Key*manual=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM28735"Null Keynull=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM21159"Null Key Valuevalue=nn1-byte hexCREATE, INDEX, SINDEXIDREF="FM15748"Segmented Keysegment=<y|n>N/ACREATE, INDEX, SINDEXIDREF="FM13994"Alternate Collating Sequence  Filename/IDname=sequenceFileor countryid=nnn and  codepageid=nnnvalid path or  values valid to  operating  system or -1  (default)CREATE, INDEX, SINDEXID="FM26479"Record Length idxid="w2545"book="_idx" docset="nw312" tidref="i1356"idxid="w2546"book="_idx" docset="nw312" tidref="i5768"Format: record=nnnnRange: 4 through 4,088 bytesCommand: CREATEThe Record Length element defines the logical data record length in bytes. For fixed-length records, this value should correspond to the length of the data buffer parameter that performs operations on the file. For variable-length records, this value should correspond to the fixed-length portion of the record.The data record length must be at least 4 bytes and must be large enough to contain all the keys defined for the file. The record length (including its duplicate key overhead and usage count overhead) plus 6 bytes must not exceed the file's page size. ID="FM39575"Variable-Length Records idxid="w2547"book="_idx" docset="nw312" tidref="i1356"idxid="w2548"book="_idx" docset="nw312" tidref="i7277"Format: variable=<y|n>Range: Not applicableCommand: CREATEThe Variable-Length Records element specifies whether the file will contain variable-length records. If a record is variable length, the maximum fixed-length record is decreased by 4 bytes. Specify y if you want the file to allow variable-length records; otherwise, specify n.ID="FM20979"Reserved Duplicate Pointer idxid="w2549"book="_idx" docset="nw312" tidref="i5903"idxid="w2550"book="_idx" docset="nw312" tidref="i1755"Format: dupkey=nnnRange: 1 through 119Command: CREATEThe Reserved Duplicate Pointer element is optional. It specifies the number of duplicate key pointers to preallocate for the file when it is created. Each reserved duplicate pointer adds 8 bytes of extra storage space to the fixed record length. These reserved pointers can be used when keys that allow duplicates are added after the file is created and if you do not specify y for the Repeating Duplicates element.ID="FM13925"Blank Truncation idxid="w2551"book="_idx" docset="nw312" tidref="i1356"idxid="w2552"book="_idx" docset="nw312" tidref="i705"Format: truncate=<y|n>Range: Not applicableCommand: CREATEThe Blank Truncation element is optional. It specifies whether Btrieve performs blank truncation on variable-length records. The truncate element has an effect only if you specify y for the Variable-Length Records element.Specify y if you want Btrieve to use blank truncation. Otherwise, either specify n or omit this element from your description file.ID="FM36163"Data Compression idxid="w2553"book="_idx" docset="nw312" tidref="i1356"idxid="w2554"book="_idx" docset="nw312" tidref="i1302"Format: compress=<y|n>Range: Not applicableCommand: CREATEThe Data Compression element is optional. It specifies whether Btrieve performs data compression on records that are inserted into the file. Specify y if you want Btrieve to perform data compression. Otherwise, either specify n or omit this element from your description file.ID="FM13742"Key Count idxid="w2555"book="_idx" docset="nw312" tidref="i1356"idxid="w2556"book="_idx" docset="nw312" tidref="i3038"Format: key=nnnRange: 0 through 118 (see IDREF="FM17355"Table A-2)Command: CREATEThe Key Count element specifies the number of keys to be defined in the file. If you specify a value of 0 for this element, Btrieve creates a data-only file. If you specify a value greater than 0, Btrieve creates either a standard file or a key-only file, depending on the value you specify for the Include Data element. The file's page size limits the amount of key segments a file can have. IDREF="FM17355"Table A-2 shows the maximum key count values for each possible page size. This value represents the number of key segments, not the number of keys. There may actually be more segment definitions than the key count. For example, assume a file contains three keys: key 0 has 2 segments, key 1 has 4 segments, and key 2 has 2 segments. In this example, the file has a page size of 512, the value specified for the Key Count element is 3, and the maximum number of key segments is 8.LBL="A-2" INLINE="F"ID="FM17355"Key Segment Count ValuesWIDTH="60"Page Size (in bytes)WIDTH="60"Maximum  Number of Key SegmentsWIDTH="60"512WIDTH="60"81,024231,536242,048-3,584544,096119ID="FM39576"Page Size idxid="w2557"book="_idx" docset="nw312" tidref="i1356"idxid="w2558"book="_idx" docset="nw312" tidref="i4910"Format: page=nnnnRange: 512 through 4,096 bytesCommand: CREATEThe Page Size element specifies the physical page size (in bytes) for the file. You can specify any multiple of 512, up to 4,096. For optimum performance, set the page size to 512, 1,024, 2,048, or 4,096 bytes.ID="FM13129"Page Preallocation idxid="w2559"book="_idx" docset="nw312" tidref="i1356"idxid="w2560"book="_idx" docset="nw312" tidref="i5133"Format: allocation=nnnnnRange: 1 through 65,535Command: CREATEThe Page Preallocation element is optional. It specifies the number of pages to preallocate to the file. If you do not want to preallocate any pages, either specify n or omit this element from your description file.ID="FM33539"Replace Existing File idxid="w2561"book="_idx" docset="nw312" tidref="i1356"idxid="w2562"book="_idx" docset="nw312" tidref="i5862"Format: replace=<y|n>Range: Not applicableCommand: CREATEThe Replace Existing File element is optional. If you do not want to create a new, empty file over an existing Btrieve file of the same name, specify n. If you want to replace an existing Btrieve file with a new, empty file of the same name, either specify y or omit this element from your description file.ID="FM26746"Include Data idxid="w2563"book="_idx" docset="nw312" tidref="i6481"idxid="w2564"book="_idx" docset="nw312" tidref="i1356"idxid="w2565"book="_idx" docset="nw312" tidref="i3055"idxid="w2566"book="_idx" docset="nw312" tidref="i1356"idxid="w2567"book="_idx" docset="nw312" tidref="i1316"Format: data=<y|n>Range: Not applicableCommand: CREATEThe Include Data element is optional. It specifies the file type that the utility creates. To create a key-only file, specify n. To create a standard file, either specify y or omit the element from the description file. To create a data-only file, specify y and set the Key Count element to 0.ID="FM25745"Free Space Threshold idxid="w2568"book="_idx" docset="nw312" tidref="i1356"idxid="w2569"book="_idx" docset="nw312" tidref="i2532"Format: fthreshold=<10|20|30>Range: Not applicableCommand: CREATEBtrieve stores the variable-length portions of records on their own pages (called variable pages), separate from the fixed-length portion of the record (which is stored on a data page). Btrieve maintains the Free Space List for variable pages. The Free Space List indicates which variable pages contain the same or more free space than that specified by the Free Space Threshold file specification.You can specify a value for the Free Space Threshold element when you create the file. This value is expressed as a percentage and tells Btrieve how much free space must remain on a variable page in order for that page to appear on the Free Space List. When Btrieve adds new variable-length records to the file, it uses pages in the Free Space List before using new variable pages. After each Insert, Update, or Delete operation, Btrieve rechecks the remaining space on the affected variable page to see if it is still above the threshold to qualify for the Free Space List. The free space threshold feature provides a means of reducing the fragmentation of variable-length records across several pages. A higher free space threshold reduces fragmentation at the cost of requiring more disk space for the file.You can specify any two-digit number for this element, and the utility rounds it to 10, 20, or 30. Btrieve uses a default free space threshold of 5 percent if either of the following is true:You specify a value less than 10.You do not specify a value here but have specified y for the Variable-Length Records element.If the Btrieve file does not allow variable-length records, do not include this element in the description file.ID="FM22942"Variable-Tail Allocation Tables (VATs) idxid="w2570"book="_idx" docset="nw312" tidref="i7278"Format: huge=<y|n>Range: Not applicableCommand: CREATEThe Variable-tail Allocation Tables (VATs) element is optional. Btrieve v6.1 allows an application to create Btrieve files that contain structures called Variable-tail Allocation Tables (VATs), which are implemented as linked lists. To accelerate random access to portions of records, Btrieve uses VATs with each record. VATs are also helpful in files using data compression to limit the size of the compression buffer that Btrieve uses. If you want to create a file that uses VATs, specify y. Otherwise, either specify n or omit this element from your description file. For more information about VATs, refer to the Btrieve Programmer's Manual.ID="FM21340"Balanced Index idxid="w2571"book="_idx" docset="nw312" tidref="i1356"idxid="w2572"book="_idx" docset="nw312" tidref="i3721"idxid="w2573"book="_idx" docset="nw312" tidref="i3038"Format: balance=<y|n>Range: Not applicableCommands: CREATEThe Balanced Index element is optional. This feature allows you to use index balancing. With index balancing, Btrieve looks for available space in sibling index pages each time an index page becomes full and then rotates values from the full page into the pages with 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, thus enhancing performance during Get operations. However, the use of this feature also means that Btrieve requires extra time to examine more index pages and may require more disk I/O during Insert, Update, and Delete operations. You can specify index balancing on a file-by-file basis when the file is created. When you specify index balancing for a specific file, Btrieve will always balance that file's keys. You can also turn index balancing on and off for files that are not flagged as balanced by specifying Yes to the Perform Index Balancing configuration option in the Setup utility.To use index balancing, specify y. Otherwise, either specify n or omit this element from the description file.ID="FM28259"Key Position idxid="w2574"book="_idx" docset="nw312" tidref="i1356"idxid="w2575"book="_idx" docset="nw312" tidref="i3038"Format: position=nnnnRange: 1 through value specified for Record Length element (up to 4,088)Commands: CREATE, INDEX, SINDEXThe Key Position element indicates the position of the key segment in the record. The key position value must be at least 1 and cannot exceed the value you specified for the Record Length element.ID="FM38759"Key Length idxid="w2576"book="_idx" docset="nw312" tidref="i1356"idxid="w2577"book="_idx" docset="nw312" tidref="i3038"Format: length=nnnRange: 1 through limit determined by key typeCommands: CREATE, INDEX, SINDEXThe Key Length element defines the length of the key or key segment field. The value you specify here cannot exceed the limit dictated by the key type, which the Key Type element specifies. The key length must be an even number if the key is a binary key type. The total of the key's length and starting position cannot exceed the file's defined record length.ID="FM20568"Duplicate Key Values idxid="w2578"book="_idx" docset="nw312" tidref="i1356"idxid="w2579"book="_idx" docset="nw312" tidref="i1755"idxid="w2580"book="_idx" docset="nw312" tidref="i3038"Format: duplicates=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Duplicate Key Values element specifies whether more than one record in the file can contain the same value for this key field. Specify y if you want to allow duplicate values for the key field; otherwise, specify n. If you define duplicate key values for one segment of a segmented key, you must define duplicate key values for every segment of that key. For a segmented key that does not allow duplicates, the segments may contain duplicates between multiple records only if the key value is unique for each record.ID="FM33611"Modifiable Key Values idxid="w2581"book="_idx" docset="nw312" tidref="i1356"idxid="w2582"book="_idx" docset="nw312" tidref="i3927"idxid="w2583"book="_idx" docset="nw312" tidref="i3038"Format: modifiable=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Modifiable Key Values element specifies whether the key value can be modified during an Update operation. Specify y if you want the values for this key to be modifiable; otherwise, specify n. If you define modifiable key values for one segment of a segmented key, you must define modifiable key values for every segment of that key because the key, as a whole, is modifiable.ID="FM16254"Key Type idxid="w2584"book="_idx" docset="nw312" tidref="i1356"idxid="w2585"book="_idx" docset="nw312" tidref="i3038"idxid="w2586"book="_idx" docset="nw312" tidref="i6412"Format: type=validBtrieveKeyTypeRange: Not applicableCommands: CREATE, INDEX, SINDEXThe Key Type element specifies the Btrieve data type for the key. This element determines how Btrieve will sort the bytes specified for this key segment. Btrieve does not perform any validation on the data inserted. You can specify the entire word (as in float) or just the first three letters of the word (as in flo for float). The Btrieve key types are as follows:WIDTH="60"autoincWIDTH="60"integerWIDTH="144"stringbfloatlogicaltimedatelstringunsigned binarydecimalmoneyzstringfloatnumericsign trailing separateSTS (sign trailing separate) is a COBOL data type. It is basically a numeric data type, represented as an ASCII string. STS is right justified and padded with leading ASCII zeros, and it has the sign byte at the end.ID="FM41254"Descending Sort Order idxid="w2587"book="_idx" docset="nw312" tidref="i1356"idxid="w2588"book="_idx" docset="nw312" tidref="i1355"idxid="w2589"book="_idx" docset="nw312" tidref="i3038"Format: descending=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Descending Sort Order element is optional. It specifies whether Btrieve will collate the index or index segment in descending order. Specify y if you want Btrieve to collate the key values in descending order. If you want Btrieve to collate the index in ascending order, either specify n or omit this element from the description file.ID="FM14468"Alternate Collating Sequence idxid="w2590"book="_idx" docset="nw312" tidref="i1356"idxid="w2591"book="_idx" docset="nw312" tidref="i202"Format: alternate=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Alternate Collating Sequence element is optional. This element allows you to specify one or more alternate collating sequences for a given file. An alternate collating sequence specifies whether Btrieve will sort a key by a collating sequence other than the standard ASCII sequence.You can specify a different alternate collating sequence for each key. However, each segment of the key can have only one alternate collating sequence. Alternate collating sequences are valid only for string, lstring, and zstring key types. If you want the key to take advantage of an alternate collating sequence, specify y. Otherwise, either specify n or omit this element from the description file.When using a description file to create an additional index for an existing Btrieve file, if you want the index to use an alternate collating sequence file other than the first one in the Btrieve file, specify alternate=y and caseinsensitive=y.If you specify alternate=y and caseinsensitive=n and use an alternate collating sequence file other than the first one in the Btrieve file, the index will not be created.ID="FM25049"Case-Insensitive Key idxid="w2592"book="_idx" docset="nw312" tidref="i1356"idxid="w2593"book="_idx" docset="nw312" tidref="i927"idxid="w2594"book="_idx" docset="nw312" tidref="i3038"Format: caseinsensitive=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Case-Insensitive Key element is optional. It specifies that the key (or key segment) you are defining is case insensitive. You can specify this key element only for keys that are of type string, zstring, or lstring. By default, Btrieve is case sensitive when sorting key strings; that is, it sorts string key values based on whether the letters are uppercase or lowercase. Btrieve sorts the values by placing the uppercase value first, followed by the lowercase value. For example, key values starting with A would appear before those starting with a in the index. Case sensitivity, however, does not apply if Btrieve sorts a key according to the collating sequence specified with the Alternate Collating Sequence element.To specify that Btrieve ignore case when sorting the key value, specify y for this element. Otherwise, either specify n or omit this element from the description file.ID="FM42029"Repeating Duplicates idxid="w2595"book="_idx" docset="nw312" tidref="i1356"idxid="w2596"book="_idx" docset="nw312" tidref="i927"idxid="w2597"book="_idx" docset="nw312" tidref="i3038"Format: repeatdup=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXBtrieve uses two methods for storing duplicatable keys internally. The keys are stored as either linked-duplicatable keys or repeating-duplicatable keys.Linked-duplicatable key---In a Btrieve v6.1 file, Btrieve stores duplicatable keys as linked-duplicatable keys by default on a Create operation. (On a Create Index operation, Btrieve uses linked-duplicatable keys if they are available; otherwise, it uses repeating-duplicatable keys, as explained in the following section.) Using this method, Btrieve stores the key extracted from the first record of a duplicatable key on an index page. Other records with keys containing duplicate values are stored in the form of a linked list, with pointers at the end of each record in a data page pointing to the next and the previous records that have the same duplicate key values.Repeating-duplicatable key---If no room is available to create a linked-duplicatable key (that is, if no duplicate pointers were reserved at file creation, or if no index has been dropped to free existing pointers), Btrieve stores duplicatable keys as repeating-duplicatable keys. Using this method, Btrieve stores every key value of a repeating-duplicatable key both in a data page and in an index page.Key-only files always use repeating-duplicatable keys because the key-only files use only the index pages and not the data pages.Specify y to create repeating-duplicatable keys. Otherwise, either specify n or omit this element from the description file.For a segmented key, all segments must have the same repeatdup=y/n specification. For a nonsegmented key, if you specify repeatdup=y, you must also specify duplicate=y.ID="FM32267"ID="FM39032"Manual Key idxid="w2598"book="_idx" docset="nw312" tidref="i1356"idxid="w2599"book="_idx" docset="nw312" tidref="i3722"idxid="w2600"book="_idx" docset="nw312" tidref="i3038"Format: manual=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Manual Key element is optional. It specifies that the key or key segment you are defining is manual. A manual key is a modified form of the null key and can be used to exclude particular records from the index. Manual keys have all the attributes of a null key with one exception: in a manual key, if every byte of one segment of the key contains the null value, Btrieve excludes the key from the index even if other segments do not contain this null value. If you define one segment of a key as a manual key, you must define a null value for that segment, and you must define all other segments of that key as manual. However, Btrieve allows you to define different null values for different segments in a segmented key.To create a manual key or key segment, specify y; otherwise, specify n or omit this element from your description file.The Btrieve Programmer's Manual refers to manual keys as any-segment null keys.ID="FM28735"Null Key idxid="w2601"book="_idx" docset="nw312" tidref="i1356"idxid="w2602"book="_idx" docset="nw312" tidref="i4757"idxid="w2603"book="_idx" docset="nw312" tidref="i3038"Format: null=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Null Key element specifies whether the key you are defining has a null value. You can include the Null Key element in a description file for the INDEX command. However, to maintain consistent formats for the CREATE, INDEX, and SINDEX description files, INDEX disregards any null value you specify.If you define a null value for one segment of a segmented key, you must define a null value for every segment of that key. However, Btrieve allows you to define different null values for different segments in a segmented key.Specify y if you want to define a null value for this key. Otherwise, specify n.TheBtrieve Programmer's Manual refers to null keys as all-segment null keys.ID="FM21159"Null Key Value idxid="w2604"book="_idx" docset="nw312" tidref="i1356"idxid="w2605"book="_idx" docset="nw312" tidref="i4757"Format: value=nnRange: Any 1-byte hexadecimal valueCommands: CREATE, INDEX, SINDEXThe Null Key Value element specifies the null character value (in hexadecimal) for the key. Typical null values are 20 hexadecimal (blank) and 0 hexadecimal (binary zero). Include this element only if you defined the key as allowing null values. If you specify n for both the Null Key element and the Manual Key element, the Null Key Value element is not required in the description file. ID="FM15748"Segmented Key idxid="w2606"book="_idx" docset="nw312" tidref="i1356"idxid="w2607"book="_idx" docset="nw312" tidref="i6217"idxid="w2608"book="_idx" docset="nw312" tidref="i3038"Format: segment=<y|n>Range: Not applicableCommands: CREATE, INDEX, SINDEXThe Segmented Key element specifies whether the key you are defining has any more segments. Specify y if the key has another segment. Specify n if you are defining either a nonsegmented key or the last segment of a segmented key. ID="FM13994"Alternate Collating Sequence Filename/ID idxid="w2609"book="_idx" docset="nw312" tidref="i1356"idxid="w2610"book="_idx" docset="nw312" tidref="i202"Format: name=sequenceFile or countryid=nnn codepageid=nnnRange: Any valid, fully qualified pathname; or a valid country ID and code page ID; or -1 (the default)Commands: CREATE, INDEX, SINDEXThe Alternate Collating Sequence Filename/ID element specifies the pathname of the file that contains an alternate collating sequence for the file you are creating. You can include up to 256 bytes of directory levels in the pathname (plus the filename).If you specified n for the Alternate Collating Sequence element for every key, do not include this element in your description file. If you specified y for the Alternate Collating Sequence element for a key, you must supply either an alternate collating sequence filename or a country ID and a code page ID.If you want all the keys in the file to use the same alternate collating sequence filename, you can either specify this element as the last element in the description file or specify the alternate collating sequence name for each key. If you want to use different alternate collating sequences, you must specify this element for each key that uses an alternate collating sequence. You can specify only one alternate collating sequence per key, and each segment of the key should have an alternate= and name= pair.To use an alternate collating sequence ID, you must specify countryid=nnn and codepageid=nnn. Use a valid country ID and code page ID. If you want to use the current locale, specify countryid=-1 and codepageid=-1.The first 265 bytes of an alternating collating sequence file contain the definition of a collating sequence other than the standard ASCII sequence. If you want to create an alternate collating sequence file, generate a file in the format that IDREF="FM14567"Table A-3 specifies.LBL="A-3" INLINE="F"ID="FM14567"Alternate Collating Sequence File FormatWIDTH="36"OffsetWIDTH="48"LengthWIDTH="204"DescriptionWIDTH="36"0WIDTH="48"1WIDTH="204"Signature byte. This byte should always contain  the value ACh.18An 8-byte name that uniquely identifies the  alternate collating sequence to Btrieve.9256A 256-byte table containing the sort value for  every character. Store the value for each sort  character at the offset corresponding to the  character's representation in the ASCII collating  sequence. For example, to sort the character A  as something other than 41h, store the new  sort value at offset 41h in the table.For example, assume you want to insert a character with a 5Dh between the letters U (55h) and V (56h) in your sequence. In this case, byte 5Dh in the sequence should contain the value 56h, and bytes 56h through 5Ch in the sequence should contain the values 57h through 5Dh.LBL="B"ID="FM17204"Status Codes and MessagesThis appendix describes the Btrieve status codes and messages. The codes are listed first and appear in numeric order. The messages follow the codes and are listed in alphabetic order.ID="FM25949"idxid="w2611"book="_idx" docset="nw312" tidref="i6528"idxid="w2612"book="_idx" docset="nw312" tidref="i1007"Status CodesThis section lists and describes the status codes that the Btrieve v6.x Record Manager, client-based Btrieve for OS/2 and Windows, and Btrieve Requesters can return. IDREF="FM12795"Table B-1 shows the numeric ranges dedicated to each type of code.LBL="B-1" INLINE="F"ID="FM12795"Status Code RangesWIDTH="72"RangeWIDTH="240"Type of CodeWIDTH="72"1- 199WIDTH="240"Btrieve Record Manager1000-1999Client-Based Btrieve for OS/2 and Windows2000-2099Btrieve Requestersidxid="w2613"book="_idx" docset="nw312" tidref="i6528"Btrieve Record Manager Status CodesThe Btrieve Record Manager returns a status code after each operation that an application performs. If the operation is successful, Btrieve returns Status Code 0. If the operation is not successful, Btrieve returns one of the nonzero status codes described in this section.01: The operation parameter is invalid.The operation parameter specified in the call is invalid. 02: Btrieve encountered an I/O error. Btrieve encountered an error while reading from or writing to the disk. One of the following has occurred:The file is damaged and must be recreated.There is a large pre-image file inside a transaction, and there is not enough space for a write to the pre-image file.  Pre-image files are used only for files created by Btrieve versions earlier than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format configuration option set to Yes.For Btrieve v5.x files, there is one pre-image file for multiple data files. For example, if you name the data files CUSTOMER.ONE and CUSTOMER.TWO, both files will have pre-image files named CUSTOMER.PRE.There is not enough space to append a new page to the data file.Client-based Btrieve attempted to write to a Btrieve file flagged shareable while server-based Btrieve had the file open.03: The file is not open.The operation cannot be executed because the file is not open. The application must perform a successful Open operation before Btrieve can process any other operations.This status code may also be returned if the application passed an invalid position block for the file, or if the application passed a position block with a different client ID than the client ID used to open the file. 04: Btrieve cannot find the key value.Btrieve cannot find the specified key value in the index path. 05: The record has a key field containing a duplicate key value.Btrieve cannot add or update a record for the designated index because the record has a key field that contains a duplicate key value, and the index does not allow duplicate values. 06: The key number parameter is invalid.The value stored in the key number parameter is not valid for the file being accessed. The key number must correspond to one of the keys defined for the file. Valid key numbers are 0 through 118.07: The key number has changed. The key number parameter changed before a Get Next, Get Next Extended, Get Previous, Get Previous Extended, Update, or Delete operation. The operation requires the same key number parameter as the previous operation because Btrieve uses positioning information relative to the previous key number. If you need to change key numbers between consecutive Get Next, Get Next Extended, Get Previous, Get Previous Extended, Update, or Delete operations, use a Get Position operation followed by a Get Direct/Record operation to reestablish positioning for the new index path. 08: The current positioning is invalid.The current position must be established to update or delete a record. Perform a Get or Step operation to establish the current position. This status code may also be returned if the application passed an invalid position block for the file. 09: The operation encountered an end-of-file condition. This status code indicates one of the following conditions has occurred:The operation encountered an end-of-file boundary or tried to read past a file boundary (end-of-file or start-of-file).In a Get Next Extended, Get Previous Extended, Step Next Extended, or Step Previous Extended operation, the number of records satisfying the filtering condition is less than the number of specified records to be returned, and the reject count has not been reached. When reading a file in ascending order according to an index path, Btrieve has already returned the last record in that index path. When reading a file in descending order according to an index path, Btrieve has already returned the first record in the index path. When using the Get By Percentage operation, either the value supplied for the percentage is too high---that is, it exceeds 10,000 decimal (0x2710)---or the file contains no records.10: The key field is not modifiable.During an Update operation, an attempt was made to modify a key field that is defined as nonmodifiable.11: The specified filename is invalid.This status code indicates one of the following conditions is true:The filename specified does not conform to file naming conventions. Make sure the filename is valid for the environment.An attempt was made to open a file that has .^^^ as its extension. This extension is reserved for Btrieve to use during a continuous operation.The data buffer for a Begin or End continuous operation is not set up correctly.12: Btrieve cannot find the specified file.Check the key buffer parameter to make sure the pathname is terminated with a blank or a binary zero. Also, check to be sure the file exists.14: Btrieve cannot create or open the pre-image file.There are four possible causes for this status code: Pre-image files are used only for files created by Btrieve versions earlier than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format configuration option set to Yes.Btrieve cannot create a new pre-image file because the disk directory is full. Btrieve must be able to create a pre-image file.Btrieve cannot open the pre-image file to restore file integrity. If the pre-image file is erased or damaged, Btrieve cannot restore the file's integrity. In this case, either use the RECOVER command in the Btrieve Maintenance utility to retrieve the damaged file's data records in a sequential file, or replace the file with its most recent backup. Client-based Btrieve cannot assign a handle to the pre-image file because Btrieve was not started by a user with access rights to the pre-image file.The file structure of a pre-image file created by Btrieve v6.x is different from the file structure of a pre-image file created by Btrieve v5.x. If you have an extraneous .PRE file in Btrieve v5.x format and you are using Btrieve v6.x, Status Code 14 is returned when you try to open the Btrieve file to which the .PRE file belongs.15: Btrieve encountered an I/O error during pre-imaging.This status code indicates either the disk is full or the pre-image file is damaged.  Pre-image files are used only for files created by Btrieve versions earlier than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format configuration option set to Yes.When this status code occurs, proceed as follows: If the disk is full, erase any unnecessary files or extend the file to gain additional disk space. If the pre-image file is damaged, the integrity of the Btrieve file cannot be ensured. Either use the RECOVER command in the Btrieve Maintenance utility to retrieve the damaged file's data records in a sequential file, or replace the file with its most recent backup. 16: Btrieve encountered an expansion error. Btrieve encountered an error while writing the directory structure to disk prior to creating the expanded file partition. Either Btrieve cannot close the file, or a new page was added to the file and Btrieve cannot close and reopen the file to update the directory structure. Check for a disk hardware failure.17: Btrieve encountered a close error. Btrieve encountered an error while writing the directory structure to disk prior to closing the file. Either Btrieve cannot close the file, or a new page was added to the file and Btrieve cannot close and reopen the file to update the directory structure. Check for a disk hardware failure. This status code may also be returned if the application passed an invalid position block for the file. 18: The disk is full.This status code can be returned in the following situations:The disk is full, and the file cannot be expanded to accommodate additional records. Either erase any unnecessary files or extend the file to gain additional disk space. The pre-image file is out of disk space. If you are working with files created by Btrieve versions earlier than v6.x and you are in a transaction, the pre-image file size increases for the duration of the transaction. If you receive this status, either reduce the number of operations in the transaction or obtain more disk space.The NetWare owner name for the file is no longer valid, and your application tried to insert or update records in the file, thus causing the file to expand. In this case, this status code is returned when Btrieve needs to add a page to the file, regardless of how much disk space is available. To check for an owner name, use the NetWare utility NDIR. To add an owner name, use the NetWare utility Filer.You can limit the amount of disk space available to each user in NetWare. This status code indicates an attempt was made to expand a Btrieve file beyond the amount of disk space allocated to the file's owner in NetWare.19: The application encountered an unrecoverable error. To ensure file integrity, either use the RECOVER command in the Btrieve Maintenance utility to retrieve the damaged file's data records in a sequential file, or replace the Btrieve file with its most recent backup. 20: The Record Manager or Requester is inactive.You must load Btrieve and, if applicable, the Btrieve Requester before generating any requests.21: The key buffer parameter is too short. The key buffer parameter is not long enough to accommodate the key field for the index path requested. Verify that the length of the key buffer equals the defined length of the key specified in the key number parameter. Only language interfaces that track the buffer length can return this status code.22: The data buffer parameter is too short.The data buffer parameter is not large enough to accommodate the length of the data record defined when the file was created. Verify that the length of the data buffer is at least as long as the file's defined record length. For Get or Step operations, Btrieve returns as much data as it can and a Status Code 22, indicating that it cannot return the entire record.For an Insert operation, Btrieve does not insert the record if the data buffer is shorter than the fixed-length portion of the record. For an Update operation, if the data buffer is too short to contain the fixed-length portion of a record, Btrieve does not update the record. For the Create, Stat, and Create Supplemental Index operations, the data buffer is not long enough to contain all the file specifications, the key specifications, and (if specified) the alternate collating sequence definition.For the Get By Percentage or Find Percentage operation, the data buffer length is less than 4 bytes. 23: The position block parameter is not 128 bytes long.Only language interfaces that track the position block length can detect and return this status code.24: The page size or data buffer size is invalid.Two possible reasons for receiving this status code are as follows:The page size is invalid. The page size must be a multiple of 512 bytes and cannot exceed 4,096 bytes.During a Create operation, the page size is the first file specification Btrieve checks. A Status Code 24 at this point may indicate an invalid data buffer parameter.In versions prior to Btrieve v6.1, this status code can be returned from the Open operation. In this case, Btrieve cannot open the file because the file's page size exceeds the Largest Page Size configuration option. To successfully open the file, you must increase the value of the Largest Page Size configuration option and then reload Btrieve. Btrieve v6.1 will not return Status Code 24 from the Open operation.25: Btrieve cannot create the specified file. Possible causes are a full disk directory or a full disk. If the application is creating a file over an existing file, Btrieve returns this status code when the existing file is open or when the operating system prevents the operation for some other reason (for example, because the file is flagged transactional).26: The number of keys specified is invalid. The number of keys specified for the page size is invalid. The number of key segments must be within the following limits:WIDTH="48"Page SizeWIDTH="60"Max. Number  Key SegmentsWIDTH="48"512WIDTH="60"81,024231,536242,048542,560543,072543,584544,09611927: The key position is invalid. The key field position specified is less than 1 or exceeds the defined record length for the file. Either the key position is greater than the record length or the key position plus the key length exceeds the record length. 28: The record length is invalid. The record length specified (plus overhead for duplicates, record usage count, variable record pointers, record length, and blank truncation information) must be less than or equal to the page size minus 8 bytes, and greater than or equal to 4 bytes.29: The key length is invalid. The key length specified must be greater than 0 but cannot exceed 255 bytes. The length of a binary key must be an even number. Btrieve requires that each key page in the file be large enough to hold at least eight keys. If the page size is too small to accommodate eight occurrences of the specified key length (plus overhead), either increase the file's page size or decrease the key length. 30: The file specified is not a Btrieve file. Either Btrieve did not create the file, or a version of Btrieve earlier than v3.x created it. This status code can also indicate that the first page of the file is damaged. Use a backup copy of your data file.31: The file is already extended.The application tried to specify a file that has already been extended. A file can be extended only once. Files on a NetWare v3.x server using the Btrieve NLM cannot be extended.32: The file cannot be extended. The application tried to specify a file that cannot be extended. Possible causes for receiving this status code are that the directory is full, the disk is full, or the disk is write protected. 34: The specified extension name is invalid.The application specified an invalid filename for the extended partition. Check the validity of the filename.35: Btrieve encountered a directory error.Either a Get Directory operation specified a drive that does not exist, or a Set Directory operation specified an invalid pathname. Check the validity of both the drive and the pathname.36: Btrieve encountered a transaction error.Btrieve tried to perform a Begin Transaction operation without configuring Btrieve to allow transactions. Run the Setup utility and specify a higher value for the Number of Transactions configuration option. Next, stop and then restart Btrieve using BSTOP and BSTART so that your changes will take effect.37: Another transaction is active.The application issued a Begin Transaction operation while another transaction was active by the same client (it can be an NLM or application). Btrieve does not accommodate nesting transactions. 38: Btrieve encountered a transaction control file I/O error. Btrieve encountered an error when it tried to write to the transaction control file. Possible causes for receiving this status code are that the disk is full, the disk is write protected, the transaction control file (BTRIEVE.TRN) that is created when you load Btrieve has been deleted or the transaction control file is flagged read only. 39: A Begin Transaction operation must precede an End/Abort Transaction operation. The application issued an End or Abort Transaction operation without a corresponding Begin Transaction operation. Make sure that each End or Abort Transaction operation in your program has a corresponding Begin Transaction operation.40: The file access request exceeds the maximum number of files allowed. The application tried to access more than the maximum number of files allowed within a transaction. The maximum number of different files that can be accessed during a logical transaction is set when Btrieve is configured.  This status code applies only to Btrieve versions earlier than v6.x.41: Btrieve does not allow the attempted operation.This status code is returned for one of the following reasons:The application tried to perform an operation that is not allowed at this time. Btrieve does not allow some operations under certain operating conditions. For example, Btrieve returns this status code if the application attempts to perform a Step operation on a key-only file or a Get operation on a data-only file.The key number parameter of a continuous operation call is not 0, 1, or 2.Also, Btrieve prohibits certain operations during transactions because they have too great an effect on the file or on Btrieve's performance. These operations include Set Owner, Clear Owner, Extend, Create Supplemental Index, and Drop Supplemental Index. 42: A file previously opened in Accelerated mode was not closed. Either the application tried to open a Btrieve v5.x file that was previously accessed in Accelerated mode by Btrieve v5.x and never successfully closed, or the application tried to open a file for which Btrieve v6.x encountered an unrecoverable error during a Set or Clear Owner operation. The file's integrity cannot be ensured. Either use the RECOVER command in the Btrieve Maintenance utility to build a new file or restore the file using the latest backup.43: The specified record address is invalid.This status code is returned for one of the following reasons:The record address specified for a Get Direct/Record operation is invalid. The address is outside the file's boundaries, it is not on a record boundary within a data page or on a data page, or the record at the specified address has been deleted. For a Get Direct/Record operation, specify the 4-byte address obtained by a Get Position operation.When using Btrieve with NetWare and the files are Btrieve v5.x files, this error may indicate a file access conflict. For example, workstation 1 has a file locked in an exclusive transaction. Workstation 2 is reading records from the same file and tries to update a record that the transaction either inserted or updated. If workstation 2 reads the record and then workstation 1 aborts the transaction, workstation 2 receives this status code when issuing the Update operation.For a Find Percentage operation that is seeking a percentage based on a record's physical location within the file, the specified record address is invalid.The file may be corrupt, and you must rebuild it.44: The specified key path is invalid.The application tried to use the Get Direct/Record operation to establish an index path for a key whose value is null in the corresponding record. Btrieve cannot establish positioning based on a null key value. 45: The specified key flags are invalid.The key flags specification on a Create operation is inconsistent. If a key has multiple segments, the duplicate, modifiable, and null attributes should be the same for each segment in the key. Also, you cannot use the Null or Manual key attributes in a key-only file.This status code is also returned if an attempt is made to specify a different alternate collating sequence for two or more segments of a segmented key.46: Access to the requested file is denied.This status code is returned for one of the following reasons:The application opened a file in read-only mode and tried to perform an Insert, Update, or Delete on that file.An attempt was made to perform an Insert, Update, or Delete on a file that is flagged read-only to NetWare.The owner name required for updates was not specified correctly when the file was opened.47: The number of files opened exceeds the maximum allowed. The number of files opened in Accelerated mode exceeded the number of buffers available in Btrieve's cache. When a file is opened in Accelerated mode, Btrieve reserves one of its cache buffers for the file. Btrieve always reserves five empty buffers for index manipulation. In client-based Btrieve, you should reconfigure Btrieve with a smaller /P configuration option to allocate more buffers and a larger /M option. In server-based Btrieve, you will not encounter this error code. 48: The alternate collating sequence definition is invalid.The first byte of an alternate collating sequence definition (the identification byte) does not contain the hexadecimal value AC. Make sure that the first byte contains the proper value.49: The extended key type is invalid. You tried to create a file or a supplemental index with an invalid extended key type, or you tried to assign an alternate collating sequence to a binary key or key segment. You can assign an alternate collating sequence only to a string, lstring, or zstring key type.This status code is also returned if you define a supplemental index requiring an alternate collating sequence, but no alternate collating sequence definition exists (either in the file or in the key definition passed in the data buffer).Another possibility is that you defined an alternate collating sequence with case insensitivity. These two definitions are incompatible. Only Btrieve v6.0 interprets this condition as an error.A final possibility is that you are attempting to create a Btrieve file that contains multiple alternate collating sequences but your server has a version of Btrieve loaded that predates v6.1.50: The file owner is already set. The application tried to perform a Set Owner operation on a file that already has an owner. Use the Clear Owner operation to remove the previous owner before specifying a new one. 51: The owner name is invalid. The possible causes for this status code are as follows:If the application received this status code after a Set Owner operation, the owner names specified in the key buffer and data buffer do not match.If this status code occurred during an Open operation, the application attempted to open a file that has an owner name assigned to it. The application must specify the correct owner name in the data buffer.If an NLM received this status code when dealing with a file in continuous operation mode, then the client ID of the calling NLM differs from the client ID of the application that originally put the file into continuous operation mode.53: The language interface version is invalid.An application tried to access a file containing variable-length records with a language interface from Btrieve v3.15 or earlier. To access files with variable-length records, you must use a v4.x or later interface.54: The variable-length portion of the record is corrupt. During a Get or Step operation, Btrieve cannot read all or part of the variable-length portion of a record. Btrieve returns as much data as possible to the application. This status code usually indicates one or more pages used to store variable length records is corrupt. Use BUTIL -RECOVER to recover as much data as possible.55: The application specified an invalid attribute for an autoincrement key.The application tried to specify either the segmented or duplicate attribute for an autoincrement key type. An autoincrement key cannot be part of a segmented key and cannot allow duplicates.56: An index is incomplete. An index can be damaged if a Create Index operation (31) or a Drop Index operation (32) is interrupted before it runs to completion. Perform a Drop Index operation to completely remove the damaged index from the file, and then rebuild the index with the Create Index operation, if so desired. 58: The compression buffer length is too short.The application tried to read or write a record that is longer than the value specified for the size of the compression buffer. Reconfigure Btrieve using the Setup utility, specifying a higher value for the Largest Compressed Record Size option.59: The specified file already exists.This status code is returned for the Create operation if the application specified -1 in the key number parameter and the name of an existing file in the key buffer parameter. If you want to overwrite the existing file, remove the -1 from the key number parameter. If you want to preserve the existing file, alter the filename specified in the key buffer parameter.60: The specified reject count has been reached.Btrieve rejected the number of records specified by the reject count before a Get Next Extended, Get Previous Extended, Step Next Extended, or Step Previous Extended operation found the requested number of records that satisfy the filtering condition. Check the first two bytes returned in the data buffer for the number of records that were retrieved.61: The work space is too small.The Get Next Extended, Get Previous Extended, Step Next Extended, and Step Previous Extended operations use a buffer as work space. This status code indicates that the work space (set by default to 16 KB) is not large enough to hold the filtering data buffer structure and the largest record to be received. 62: The descriptor is incorrect.The descriptor (data buffer structure), which is passed for a Get Next Extended, Get Previous Extended, Step Next Extended, or Step Previous Extended operation, is incorrect. The descriptor length (the first two bytes of the data buffer) on the extended operation call must be the exact length of the descriptor. This requirement does not apply to the data buffer length option, which can still be declared longer than necessary.On a Get Direct/Chunk operation, the descriptor structure in the data buffer is incorrect, or it is inconsistent (either internally or in respect to the data buffer length). See the discussion of the Get Direct/Chunk operation in Chapter 4 of the Btrieve Programmer's Manual for information about the correct descriptor format.63: The data buffer parameter specified on an Insert Extended operation is invalid.An Insert Extended operation provided an invalid buffer. Either the buffer length is less than 5 bytes, or the number of records specified is 0. Correct the buffer length or the number of records.64: The filter limit has been reached.During a Get Next Extended, Get Previous Extended, Step Next Extended, or Step Previous Extended operation, a rejected record was reached; no other record can satisfy the given filtering condition, going in the direction that the operation specified. This is applicable only if the first segment of the key that the key number specified is also used as the first term of the filtering field.65: The field offset is incorrect.The field offset in the extractor of a Get Next Extended, Get Previous Extended, Step Next Extended, or Step Previous Extended operation is invalid based on the length of the retrieved record. Make sure that the field offset is a valid value (from 0 through the record length minus 1).66: The maximum number of open databases has been exceeded.The application has tried to open too many SQL databases configured for referential integrity checking at one time. The maximum number of databases that can be opened concurrently for referential integrity checking is a configurable startup option for Btrieve. The default is set to 20. Refer to your NetWare SQL documentation for more information on referential integrity.67: Btrieve cannot open the SQL data dictionaries.This status code may indicate that an application opened a data file containing referential integrity definitions but Btrieve cannot open one of the NetWare SQL data dictionary files (FILE.DDF or RELATE.DDF) or the configuration file (DBNAMES.CFG).Be sure that DBNAMES.CFG is present in the SYS:SYSTEM directory, and that the FILE.DDF and RELATE.DDF files for that named database are placed in the dictionary location that the Setup utility defines. Refer to your NetWare SQL documentation for more information on referential integrity.68: Btrieve cannot perform the RI Delete Cascade operation.Btrieve cannot enforce the Delete Cascade rule on a file under referential integrity control because the record that the application attempted to delete has more than 16 levels of descendants. Delete records from the lower levels, and then try again to delete the record that the application was attempting to delete initially. Refer to your NetWare SQL documentation for more information on referential integrity.69: The Delete operation cascades to a record in a file that is damaged.The application encountered an error while Btrieve was attempting to enforce the Delete Cascade rule in response to a Delete operation. This status code indicates that the related file has been damaged and must be recreated.Refer to your NetWare SQL documentation for more information on referential integrity and the Delete Cascade rule.71: There is a violation of the RI definitions.If you have attempted an Insert operation on a file under referential integrity control, you may receive this status code if a foreign key value in the record to be inserted does not have a corresponding primary key in the referenced file.If you are performing an Update operation, there are two possible causes for this status code:You are attempting to change the value of a primary key.You are attempting to change the value of a foreign key to a value that does not exist for the defined primary key.If you have attempted a Delete operation, the Restrict rule is being enforced, and a primary key value in the record you are trying to delete references a foreign key in the referenced file. Refer to your NetWare SQL documentation for more information on referential integrity.72: Btrieve cannot open the RI referenced file opened.The referenced file cannot be found at the location that FILE.DDF and DBNAMES.CFG specify. This status code is returned only on a first attempt to delete or insert in a file under referential integrity control, or on a first attempt to update when that operation would change a foreign key in the specified file.Be sure that the referenced file is in one of the data file locations that the Setup utility specified. Also, verify that the file location does not contain a drive letter. Refer to your NetWare SQL documentation for more information on referential integrity.73: The RI definition is out of sync.You have attempted to open a file for which the referential integrity definition either disagrees with the definition in RELATE.DDF or refers to a database not found in DBNAMES.CFG. This status code can also occur on an Insert or Delete operation, or an Update operation that would change a foreign key.Run the NetWare SQL RIUTIL utility, and use the CHECK command. For information on the RIUTIL utility and on referential integrity, refer to your NetWare SQL documentation.74: Btrieve aborted the transaction.This is an informative status code. Btrieve replaced an End Transaction operation with an Abort Transaction after detecting an error for a Transaction Tracking System (TTS) file inside the transaction. In addition, Btrieve executed the Abort Transaction operation.76: There is a conflict on the referenced file.The application has attempted to perform an Update, Insert, or Delete operation on an RI-controlled file that references another file. The application cannot open the referenced file for referential integrity checking because it is already opened in Exclusive mode. Wait until the referenced file is closed or is opened in a mode other than Exclusive, and then retry the operation. Refer to your NetWare SQL documentation for more information on referential integrity.77: The application encountered a wait error.Either a wait lock bias is specified for an operation but another user has locked the requested resource, or the application is currently processing a wait transaction and tried to access a file that another user has locked.When you are using the Btrieve Requester to access Btrieve, the Requester waits and retries if a requested resource is locked. When a server-based application, such as NetWare SQL, is accessing Btrieve and the requested resource is locked, a wait is also required. In this case, Btrieve would be expected to perform the wait. Since this would occupy Btrieve and lock out other users who might be trying to release the requested resource, Btrieve does not perform the wait. Instead, it returns a Status Code 77, and the server-based application must retry later.78: Btrieve detected a deadlock condition.The application should clear all resources (for example, by aborting or ending the transaction, or releasing all record locks) before proceeding. This breaks the deadlock, allowing other applications to access the resources for which they are waiting.79: A programming error occurred.Although very rare, it is possible to receive this status code when there is a malfunction that Btrieve cannot specifically detect or from which Btrieve cannot recover. Retry the operation again. If the error persists, there may be a system corruption; try to clear the system by restarting, and then try the operation again. 80: The application encountered a record-level conflict.Btrieve did not perform the Update or Delete operation because of a record-level conflict. For example, station A reads a record, station B reads the same record and updates it, and then station A attempts to update the record. The application should reread the record prior to resending an Update or Delete operation.81: The application encountered a lock error. This status code can result from one of the following conditions:The Btrieve lock table is full. Decrease the number of locks that the application uses, or use the Setup utility to specify a higher value for the Number of Locks option.The application tried to unlock one record that is locked with a multiple record lock, but the record position stored in the data buffer does not correspond to any record locked in the associated file.The application tried to unlock a single-record lock with a multiple-record lock or vice-versa.82: The application lost positioning.When performing a Get Next or Get Previous operation on a key with duplicates, the application tried to retrieve a record that was deleted or whose key value was modified by another application. Use a Get Equal or a Get Direct/Record operation to reestablish positioning. 83: The application attempted to change a record that was read outside the transaction.The application tried to update or delete a record within a transaction, but the record was not read within the transaction. The application must read the record within the transaction before attempting to modify the data. 84: The record is locked.The application tried to apply a nowait lock on a record that is currently locked by another application, or the application tried to access a file in a nowait transaction while another application holds an active record lock(s) in that file.This status code can also occur if the application tried to update or delete a record locked by another application.The application can use either of the following recovery methods:Retry the operation until it is successful. Under light-to- moderate network use, this may be the simplest and quickest solution.Use the wait option (+100/+300) instead of the nowait option.Btrieve may return this status code on an Insert operation when it attempts to lock an index page to update the key value specified for a newly inserted record. If another user has already locked the record in question, then Btrieve returns a Status Code 84 when it attempts to update the key value. Have your application check for this status code and retry the operation if the status code is returned.85: The file is locked.Any of the following can cause this status code to occur: Client-based Btrieve has a file open, and another workstation that has the Requester loaded tries to open the same file. Btrieve cannot open the file since it cannot obtain exclusive access. The workstation that has the Requester loaded receives Status Code 85. Another workstation has the Requester loaded and has a file open, and client-based Btrieve tries to open the same file.A file is in transition into continuous operation mode. A retry will eventually work.While one user has a file locked in an exclusive transaction, another user attempts to lock all or part of that file.A user has two Btrieve files with the same filename but different extensions (for example, INVOICE.HDR and INVOICE.DET). One file is open and in continuous operation mode, causing Btrieve to generate a delta file (for example, INVOICE.^^^). Btrieve returns Status Code 85 if the user attempts to open the second file.86: The file table is full.Using the Setup utility, specify a higher value for the Number of Open Files configuration option. For more information, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."87: The handle table is full.This status code is applicable only in the server-based Btrieve environment. Using the Setup utility, specify a higher value for the Number of Handles configuration option. For more information, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."88: The application encountered an incompatible mode error.When you are using continuous operation, this status code can indicate any of the following:You have attempted to remove a file from continuous operation, but the file is not in a continuous state.You have attempted to include two files that have the same name but different extensions in continuous operation.You have attempted to include a file in continuous operation, but the file is already in a continuous state.If an application opens a file in Exclusive mode, all other applications get this status code when they try to open the same file in any mode.If an application opens a file in any mode other than Exclusive, all other applications get this status code when they try to open the same file in Exclusive mode.91: The application encountered a server error. You can receive this status code in the following situations:The Requester cannot establish a session with the server. Either Btrieve is not loaded or the server is not active. The setting for the Number of Remote Sessions configuration option is too low. Return to the Setup utility and specify a higher value for this option.An application specified a path for a file and did not include the volume name in the path.92: The transaction table is full.The maximum number of active transactions was exceeded. Using the Setup utility, specify a higher value for the Number of Transactions configuration option. For more information, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."93: The record lock types are incompatible. The application tried to mix single-record locks (+100/+200) and multiple-record locks (+300/+400) in the same file at the same time. All locks of one type must be released before a lock of the other type can be executed. 94: The application encountered a permission error.You can receive this status code in the following situations:The application tried to open or create a file in a directory without the proper privileges. Btrieve does not override the network privileges assigned to users. The designated server is in the server routing table, but your particular workstation is not logged into that server.Served-based BREQUEST and client-based Btrieve are trying to access the same file at the same time.Btrieve was unable to log in to the NetWare Runtime server using the given username. The user either does not exist on the Runtime server or does not have the appropriate rights to open or create a file.95: The session is no longer valid.The previously established session is no longer active due to an error at the workstation, at the file server, or on the network. Verify that the workstation is still attached to the server, and then unload and reload the Btrieve Requester as discussed in IDREF="FM14474""DOS Requester" in Chapter 4.This status code can also indicate that the maximum number of sessions for Btrieve has been reached. Use the Communication Statistics option of the Btrieve Monitor utility to see if the maximum number of sessions has been reached. If so, use the Setup utility to specify a higher value for the Number of Remote Sessions configuration option. For more information, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."96: A communications environment error occurred. You tried to attach to Btrieve on a server but the SPX connection table or the Btrieve client table is full. Use the Setup utility to specify a higher value for the Number of Remote Sessions configuration option. For more information, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."When this status is returned to an NLM application, verify that all clients are being properly reset.97: The communications buffer is too small. The application tried to read or write a record that is longer than the current settings for Btrieve or the Btrieve Requester allow, as follows: For an Update, Insert, or Create operation, the application receives this status code if the data buffer length it specifies for the record exceeds Btrieve's internal communications buffer length.For a Get, Step, or Stat operation, the application receives this status code if Btrieve's internal communications buffer is shorter than the length of the data Btrieve would return, regardless of the data buffer length specified in the application. For a Get Chunk or Update Chunk operation, the total size of the retrieved or updated chunk exceeds Btrieve's internal communications buffer length.Btrieve calculates the length of its communications buffer using as a base the values of the Largest Record Size option (from the Setup utility) and the Data Message Length (/D) option (specified when the Btrieve Requester and/or BSPXCOM was loaded).To increase the size of the communications buffer, use the Setup utility to specify a higher value for the Largest Record Size option. Then, reload the Btrieve Requester, and specify a higher value for the Data Message Length (/D) option. For more information, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."98: Btrieve detected an internal transaction error. Btrieve detected an error while executing the operation on a NetWare TTS file. The application can perform only an Abort Transaction operation at this point.99: The Requester cannot access the NetWare Runtime server.The DOS Requester returns this status code when NetWare Runtime server support is enabled (/C:1) and the Requester either detects no existing connection or cannot find a valid login username. If the Requester cannot find a login username other than SUPERVISOR, there is no valid name to pass.100: No cache buffers are available.Btrieve has used all the cache buffers it allocated at load time. Using the Setup utility, you can increase the value for the Cache Allocation configuration option. Alternatively, you can change the Number of Remote Sessions configuration option to decrease the number of concurrent Btrieve users. For more information, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."101: Insufficient operating system memory is available.There is not enough operating system memory available to perform the requested operation. Decrease the value for the Cache Allocation configuration option (using the Setup utility), decrease the number of concurrent Btrieve users (using the Number of Remote Sessions configuration option in the Setup utility), or add memory to the server. For more information on the configuration options, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve."102: Insufficient stack space is available.Btrieve has run out of stack space. To increase the amount of stack space available to your application, relink the application, setting the stack size to a higher value. Only the NLM applications calling Btrieve on the local server get this message.103: The chunk offset is too big.A Get Direct/Chunk operation has specified an offset beyond the end of the record, either explicitly or through the use of the next-in-record bias to the subfunction value. Unless Btrieve returns this status while processing the first chunk, the operation was partially successful. Check the data buffer length parameter immediately after the call to see how much data (and therefore how many chunks) Btrieve retrieved.This code can also be returned by the Update Chunk operation when the specified offset is more than one byte beyond the end of the record. However, in this situation, Status Code 103 indicates that Btrieve made no changes to the record.104: The locale information could not be found.The Create or Create Index function returns this status code to indicate that the operating system was not able to return a collation table for the country ID and code page specified. Check that the application specified the locale's country ID and code page correctly and that the operating system is configured to support the country ID and code page.105: The file cannot be created with Variable-tail Allocation Tables (VATs).The application specified that a Btrieve file should be created with Variable-tail Allocation Tables (VATs); however, the application failed to specify that the file was to use variable-length records (a precondition for files to use VATs). This status applies to key-only files as well as regular data files.106: The operation cannot get the next chunk.The application called the Get Direct/Chunk operation to retrieve a chunk from a record and used the next-in-record bias on the descriptor subfunction. However, after the application established its positioning in the record (but prior to this call), the target record was deleted.107: Chunk updates/retrievals cannot be performed on the file.The application tried to use either a Get Direct/Chunk operation or an Update Chunk operation on a pre-v6.0 formatted file.idxid="w2614"book="_idx" docset="nw312" tidref="i6528"Client-Based Btrieve for OS/2 and Windows Status CodesClient-based Btrieve may return the following status codes in an OS/2 or Windows environment.1001: The Multiple Locks option is out of range.The number specified for the Multiple Locks configuration option must be between 1 and 255, inclusive. 1002: Btrieve cannot allocate the memory needed.Make sure that the workstation has enough memory to load all the programs it requires. 1003: The Memory Size is too small.Make sure the value for the Memory Size configuration option is large enough to accommodate the required cache size.1004: The Page Size option is out of range.The value of the Page Size configuration option must be an even multiple of 512, and it must be between 512 and 4,096, inclusive.1005: The Pre-Image File Drive option is invalid.You must specify a valid drive letter for the Pre-Image File Drive configuration option. Pre-image files are used only for files created by Btrieve versions earlier than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format configuration option set to Yes.1006: The Pre-Image Buffer Size option is out of range.The Pre-Image Buffer Size configuration option must be between 1 and 64, inclusive. Pre-image files are used only for files created by Btrieve versions earlier than v6x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format configuration option set to Yes.1007: The Open Files option is out of range.The Open Files configuration option must be between 1 and 255, inclusive.1008: The Configuration options are invalid.The configuration options specified contain invalid or unidentifiable values. For more information on configuration options, refer to the installation and operation manual for your operating environment.1009: The Transaction Filename option is invalid.The filename specified for the Transaction Filename configuration option is not valid. Check to make sure that the transaction filename is correct.1011: The Compression Buffer Size specified is out of range.The Compression Buffer Size configuration option must be between 1 and 64, inclusive.1013: The task table is full (Windows only).The Btrieve DLL may return this status code if the task entry table is full. You can remedy this situation by increasing the number of available task entries; use the tasks initialization option (tasks=xxx) under the [BTRIEVE] or [BREQUESTDPMI] headings in NOVDB.INI. The minimum value for this option is 1; the maximum value is 255.1014: The application encountered a stop warning.WBTRVSTOP ( ) returns this status code if the application still has open files or an active transaction. The application must close all files and end all transactions before calling WBTRVSTOP ( ).1015: A pointer parameter is invalid.One of the pointer parameters passed into Btrieve is invalid.1016: Btrieve is already initialized.The Btrieve DLL may return this status code if an attempt is made to initialize Btrieve when it is already initialized. To reinitialize Btrieve, close all files, end/abort all transactions, and call WBTRVSTOP ( ) before calling the initialization function.1017: The resource file WBTRVRES.DLL cannot be found.The WBTRCALL.DLL returns this status code when it cannot find the resource file WBTRVRES.DLL. You can remedy this situation by placing a copy of the WBTRVRES.DLL file in the same directory as the WBTRCALL.DLL file.idxid="w2615"book="_idx" docset="nw312" tidref="i6528"Btrieve Requester Status CodesThis section lists the status codes that the Btrieve Requesters may generate. 2001: The memory allocation is insufficient. In an OS/2 environment, the Requester cannot allocate enough memory for the parameters specified with the BRQPARMS environment variable. In a DOS environment, reduce the value specified for the /D configuration option.2002: The option is invalid or out of range.In an OS/2 environment, either one of the options specified with the BRQPARMS environment variable is invalid (such as /P instead of /D) or the value specified for a parameter is out of range. Check the SET BRQPARMS statement to make sure it is correct.2003: The Requester does not allow local access to the specified file.The application attempted to access a file stored on a local drive. The version of WBTRCALL.DLL installed at the workstation does not allow access to local files. 2004: SPX is not installed.Install the NetWare SPX v1.3 or later communications software for OS/2.2005: An incorrect version of SPX is installed.Install the NetWare SPX v1.3 or later communications software for OS/2.2006: There is no available SPX connection.SPX has already established the maximum number of sessions it can handle. To increase the maximum, edit the NET.CFG file. Refer to your NetWare documentation for more information on NET.CFG.2007: A pointer parameter is invalid.One of the pointer parameters passed to Btrieve is invalid. Check the program to ensure that the pointer parameters are correct.idxid="w2616"book="_idx" docset="nw312" tidref="i3839"MessagesThis section lists and describes the messages that Btrieve v6.1 can return. The following conventions are used in the descriptions of the messages: nn or xx refers to a software-supplied number (for example, a status code, operation code, or number of records) and xxxx refers to a software-supplied name (for example, a filename, a key type, or a command). Consult the screen message to get the value for nn, xx, or xxxx.Btrieve NLM and Requester MessagesThe messages in this section are sent by the Btrieve NLM and the Btrieve DOS Requester. The messages from the Btrieve NLM are listed first.Btrieve NLM MessagesThe following messages are sent by the Btrieve NLM.BTRIEVE-6.1-1: The value specified for the Cache Allocation option is invalid.The Btrieve NLM returns this message when the value specified for the Cache Allocation option is invalid. Use the Setup utility and specify a value between 32 through 64,000 for this option.BTRIEVE-6.1-2: The value specified for the Largest Compressed Record Size option is invalid.The Btrieve NLM returns this message when the value specified for the Largest Compressed Record Size option is invalid. Return to the Setup utility and specify a valid value for the Largest Compressed Record Size option. BTRIEVE-6.1-4: The value specified for the Number of Open Files option is invalid.The Btrieve NLM returns this message when the value specified for the Number of Open Files option is invalid. Use the Setup utility and specify a value between 1 and 64,000 for this option. BTRIEVE-6.1-7: The value specified for the Number of Handles option is invalid.The Btrieve NLM returns this message when the value specified for the Number of File Handles option is invalid. Use the Setup utility and specify a value between 1 and 64,000 for this option. BTRIEVE-6.1-9: The value specified for the Number of Remote Sessions option is invalid.The Btrieve NLM returns this message when the value specified for the Number of Remote Sessions option is invalid. Use the Setup utility and specify a value between 1 and 64,000 for this option. BTRIEVE-6.1-12: The value specified for the -option option is invalid.The Btrieve NLM returns this message when the value for an option is not valid. Return to the BSTART.NCF file and enter the correct value. BTRIEVE-6.1-13: The option specified is not a valid option.The Btrieve NLM returns this message when the option specified is not a valid option. Return to the BSTART.NCF file and remove the invalid option.BTRIEVE-6.1-14: Continuous operation is active on one or more files. Roll-in could not be completed. Please free some disk space if you wish to end continuous operation before unloading the BTRIEVE NLM.The Btrieve NLM returns this message when the server has insufficient disk space to allow Btrieve to complete the roll in. Free some disk space in order to end continuous operation and unload the Btrieve NLM.BTRIEVE-6.1-16: The server has insufficient memory to complete the operation.The Btrieve NLM returns this message when the server has insufficient memory to allow Btrieve to load as it is configured. Use the Setup utility to reconfigure Btrieve to use less memory, or unload any unnecessary NLMs. BTRIEVE-6.1-17: The header in log file xxxx is invalid.The Btrieve NLM returns this message when the header in log file xxxx is invalid. The file xxxx is expected to be a log file according to BLOG.CFG but it is not. If you receive this message, either delete file xxxx and create a new log file, or change BLOG.CFG to specify a different log file.BTRIEVE-6.1-18: The log file xxxx cannot be created in the location specified.The Btrieve NLM returns this message when log file xxxx cannot be created in the location specified. Check that the disk is not full and that the user has rights to create and write to log file xxxx. BTRIEVE-6.1-19: Logging is not active for file xxxx; check the file specification in BLOG.CFG.The Btrieve NLM returns this message when logging is not active for the file xxxx; check the file specification in BLOG.CFG. This message is always displayed with the Invalid Header in Log File xxxx message or the Unable to Create Log File xxxx message. BTRIEVE-6.1-20: The log file xxxx cannot be written. Check disk space.The Btrieve NLM returns this message when log file xxxx cannot be written. Check the disk space. If the disk is full, free some space by deleting any unnecessary files.BTRIEVE-6.1-21: Logging has stopped for file xxxx.The Btrieve NLM returns this message when logging has stopped for file xxxx. The log file xxxx cannot be written. Check the disk space. If the disk is full, free some space by deleting unnecessary files. BTRIEVE-6.1-22: Files have been found in continuous operation; files in continuous operation are being rolled in.The Btrieve NLM returns this message when files have been found in continuous operation; files in continuous operation are being rolled in (updated).BTRIEVE-6.1-23: Files have been found in continuous operation; an error was detected while rolling in these files.The Btrieve NLM detected files in continuous operation; an error was detected while rolling in (updating) these files. Check to see if the disk is full or if any other disk problems exist.BTRIEVE-6.1-24: Files have been found in continuous operation; these files have been successfully rolled in.The Btrieve NLM detected files in continuous operation; these files have been successfully rolled in (updated).BTRIEVE-6.1-25: The file xxxx is rolling back.The Btrieve NLM returns this message when the file xxxx is rolling back. (Rolling back refers to aborting a transaction and undoing all changes made to the database during the transaction, thus restoring the database to the state it was in before the transaction began.)BTRIEVE-6.1-26: The transaction roll back cannot be completed. Check the memory available on the server.The Btrieve NLM returns this message when it is rolling back the transaction but the transaction roll back cannot be completed. (Rolling back refers to aborting a transaction and undoing all changes made to the database during the transaction, thus restoring the database to the state it was in before the transaction began.) Check the memory available on the server. Free memory by unloading NLMs or reconfiguring NLMs to use less memory. BTRIEVE-6.1-27: The transaction control file cannot be created. The Btrieve NLM returns this message when the transaction control file (BTRIEVE.TRN) cannot be created. Btrieve was unable to open or create SYS:SYSTEM/BTRIEVE.TRN. Make sure that no user has that file open. Btrieve Requester MessagesThe following messages are sent by the Btrieve DOS Requester (BREQUEST.EXE). BREQUEST-6.1-1: The message file xxxx is invalid; BREQUEST cannot be loaded.The Btrieve Requester returns this message when the message file is invalid. Specify a valid message file so that BREQUEST.EXE can be loaded. BREQUEST-6.1-3: The option specified is not a valid option.The Btrieve Requester returns this message when the option specified is not a valid option. Specify a valid option.BREQUEST-6.1-4: The value specified for the Data Message Length (/d) option is invalid.The Btrieve Requester returns this message when the value specified for the Data Message Length (/D) option is invalid. Specify the /D option as /D:n, where n is an integer. BREQUEST-6.1-5: The workstation has insufficient memory to load BREQUEST.The Btrieve Requester returns this message when the workstation has insufficient memory to load the Requester. Unload unnecessary programs or try a smaller value for the /D option. BREQUEST-6.1-6: BREQUEST is already loaded.The Btrieve Requester returns this informational message to indicate that BREQUEST.EXE is already loaded. BREQUEST-6.1-7: XQL or NSREQ is already loaded; BREQUEST must be loaded first.The Btrieve Requester returns this message when XQL or NSREQ is already loaded; the DOS Requester must be loaded first. Unload XQL or NSREQ and then load the DOS Requester.BREQUEST-6.1-8: DOS 2.00 or greater is not loaded; load DOS 2.00 or greater.The Btrieve Requester returns this message. DOS v2.x or later is not loaded; you must load DOS v2.x or later to proceed.BREQUEST-6.1-9: The SPX.COM file is not loaded; load the file SPX.COM.The Btrieve Requester returns this message when the file SPX.COM is not loaded. Load SPX.COM. BREQUEST-6.1-10: The function SPXInitialize returned an error. Make sure the file IPX.COM is loaded.The Btrieve Requester returns this message when the SPXInitialize function encounters an error. You must make sure that the file IPX.COM is loaded. BREQUEST-6.1-11: The IPX socket table is full.The Btrieve Requester returns this message when the IPX socket table is full. BREQUEST-6.1-13: The value specified for the Runtime server support (/C) option is invalid.The Btrieve Requester returns this message when an invalid value is specified for the NetWare Runtime Server Support option (/C). Specify this option in one of these forms:WIDTH="24"/C:0WIDTH="264"To disable NetWare Runtime server support./C:1To enable NetWare Runtime server support.To authenticate requests on the NetWare Runtime server,  provide a username and password, separating them with  commas, as follows:/C:1,username,passwordFor more information about this option, see IDREF="FM41779"Chapter 4, "Configuring and Using the Requesters."Btrieve Communications ModulesThis section includes messages sent by the Btrieve Message Router (BROUTER.NLM) and the Btrieve SPX communications module (BSPXCOM.NLM).Btrieve Message Router MessagesThe following messages are sent by BROUTER.BROUTER-6.1-1: The server has insufficient memory to execute BROUTER. BROUTER returns this message when the server has insufficient memory to load the file BROUTER.NLM. Free some memory by unloading NLMs or reconfiguring NLMs to use less memory.BROUTER-6.1-2: The value specified for a configuration option is invalid.BROUTER returns this message when the value specified for a configuration option is invalid. Reload BROUTER.NLM using valid options.BROUTER-6.1-3: An internal error has occurred; the SPXOpenSocket function failed.BROUTER returns this message if an internal diagnostic error occurs. The SPXOpenSocket function failed. Another NLM may be using the socket number reserved for BROUTER. If you receive this message, unload all other NLMs and then load BTRIEVE.NLM and BROUTER.NLM. Finally, reload the other NLMs. This process reveals the NLM that is using BROUTER's socket number.BROUTER-6.1-6: BROUTER is loaded.BROUTER returns this message to indicate that BROUTER.NLM is now loaded.Btrieve SPX Communications MessagesThe following messages are sent by the Btrieve SPX communications module (BSPXCOM.NLM).BSPXCOM-6.1-1: The option specified is not a valid option.The Btrieve SPX communications module returns this message when the option specified is not a valid option. Specify a valid option.BSPXCOM-6.1-2: The server has insufficient memory to execute BSPXCOM.The Btrieve SPX communications module returns this message if the server has insufficient memory to load the file BSPXCOM.NLM. If you receive this message, you must free memory by unloading NLMs or reconfiguring NLMs to use less memory.BSPXCOM-6.1-3: An internal error has occurred. BSPXCOM detected a semaphore allocation failure.The Btrieve SPX communications module returns this message when an internal diagnostic error occurs. BSPXCOM detected a semaphore allocation failure.BSPXCOM-6.1-4: The Service Request Block (SRB) function code nn contains invalid data. Check for an incompatible version of the file BSPXCOM.NLM.The Btrieve SPX communications module returns this message if the Service Request Block (SRB) function code contains invalid data. Check that BSPXCOM's version is compatible with the version number of the workstation's Btrieve Requester.BSPXCOM-6.1-6: An internal error has occurred. The session was not found in ConnTable.The Btrieve SPX communications module returns this message when an internal diagnostic error occurs. The session was not found in ConnTable.BSPXCOM-6.1-7: Another NLM is using the socket number reserved for BSPXCOM.The Btrieve SPX communications module detected another NLM using the socket number reserved for BSPXCOM. Unload all other NLMs and then load BTRIEVE.NLM and BSPXCOM.NLM. Finally, reload the other NLMs. This process reveals the NLM that is using BSPXCOM's socket number. BSPXCOM-6.1-8: An SPX-level receive I/O error (hexadecimal code nn) has occurred. The connection has been lost.The Btrieve SPX communications module returns this message when an SPX-level receive I/O error occurs. The connection has been lost.BSPXCOM-6.1-9: An SPX-level send I/O error (hexadecimal code nn) has occurred. The connection has been lost.The Btrieve SPX communications module returns this message when an SPX-level send I/O error occurs. The connection has been lost.BSPXCOM-6.1-10: An internal error (hexadecimal code nn) has occurred. BSPXCOM detected a Dequeue error.The Btrieve SPX communications module returns this message when an internal diagnostic error (a dequeue error) occurs.BSPXCOM-6.1-11: Bad connection ID detected on receive. The SPX connection was lost after the initial request began.The Btrieve SPX communications module detected a bad connection ID on a receive. The SPX connection was lost after the initial request began. No action is needed if this message appears occasionally when you restart your workstation. However, if this message appears frequently when you have not restarted your workstation, you must increase your workstation's SPX Timeout parameter. Also, you can check for NLMs monopolizing the CPU time.BSPXCOM-6.1-12: Bad connection ID detected on send. The SPX connection was lost after the initial request began.The Btrieve SPX communications module returns this message when it detects a bad connection ID on a send. The SPX connection was lost after the initial request began. No action is needed if this message appears occasionally when you reboot your workstation. However, if this message appears frequently when you have not restarted your workstation, you must increase your workstation's SPX Timeout parameter. Also, you can check for NLMs monopolizing the CPU time or for a hardware failure.BSPXCOM-6.1-13: An error (hexadecimal code nn) was detected while trying to establish an SPX session requested by a remote workstation.The Btrieve SPX communications module detected an internal diagnostic error while it was trying to establish an SPX connection requested by a remote workstation.BSPXCOM-6.1-15: The request for statistics from the Btrieve Monitor utility was not recognized. Check for an incompatible version of the utility or BSPXCOM.The Btrieve SPX communications module returns this message if the request for statistics from the Btrieve Monitor utility was not recognized. Check for an incompatible version of the utility or BSPXCOM. BSPXCOM-6.1-16: The session was rejected; the session limit was reached. Increase the value specified for the Number of Remote Sessions option.The Btrieve SPX communications module returns this message to indicate the session was rejected because the session limit was reached. Increase the value specified for the Number of Remote Sessions configuration option. Unload and then reload BSPXCOM.NLM so that the new value can be used. (For more information about this option, refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve.")BSPXCOM-6.1-17: An internal error has occurred. BSPXCOM did not recognize the GET_EIM_STATS function.The Btrieve SPX communications module returns this message when an internal diagnostic error occurs. BSPXCOM did not recognize the GET_EIM_STATS function. Check to see if the version of BSPXCOM is compatible with that of the Btrieve Monitor utility (BTRMON.NLM).Btrieve UtilitiesThis section includes messages sent by the Btrieve Maintenance, Monitor, Rebuild, Requester, Roll Forward, and Setup utilities.Maintenance Utility MessagesThe following messages are sent by the Maintenance utility (BUTIL.NLM).BUTIL-6.10-1: The keyword compression is no longer supported. Use truncate.The compress keyword is no longer used in description files. However, you may reduce the file size for files that contain variable-length records by specifying y for the truncate keyword. The truncate keyword has no effect unless the file contains variable-length records.BUTIL-6.10-2: An error occurred while BUTIL was accessing the description file.The Maintenance utility returns this message when an error occurs during access of a description file. Make sure the file has not been corrupted and that the information it contains is properly formatted.BUTIL-6.10-6: The BUTIL command is invalid.The Maintenance utility returns this message when the syntax of the command you entered is incorrect. Verify the syntax before reentering the command.BUTIL-6.10-8: The command completed, but one or more errors occurred.An error occurred when you executed a command that performed a number of Btrieve operations. These commands include COPY, LOAD, or CLONE. This message is accompanied by additional messages that can help you identify the problem.BUTIL-6.10-9: The command did not complete due to an unrecoverable error.The Maintenance utility returns this message when the command you entered did not complete successfully due to an unrecoverable error. Verify that the syntax you entered is correct before reentering the command. This message is accompanied by additional messages that can help you identify the problem.BUTIL-6.10-10: The command line contains a syntax error.The Maintenance utility returns this message when the syntax of the command you entered is incorrect. Verify the syntax before reentering the command.BUTIL-6.10-11: The command line requires the index file.If you specify the BUTIL -INDEX or -SAVE command (modified by the Y parameter) to the Btrieve Maintenance utility, you must specify the full pathname of an external index file.BUTIL-6.10-12: The command line requires the key number.If you specify the DROP command or the SAVE command (modified by the N parameter) to the Btrieve Maintenance utility, you must specify the key number of the key you want to drop or by which you want to save the Btrieve file.BUTIL-6.10-13: The key size for key of type xxxx is invalid.The Maintenance utility returns this message when you specify an invalid key size for the key type. In a description file, the specified value of the Key Length element for a particular key is incorrect. Make sure that the value of each Key Length element is appropriate for the matching Key Type element.BUTIL-6.10-14: The key type is invalid.The Maintenance utility returns this message when you specify an invalid key type. In a description file, the type specified for one of the keys is invalid. Make sure that all the Key Type elements in the file are assigned a valid type.BUTIL-6.10-15: The key segment descriptor value nn is invalid for a manual or null key.The Maintenance utility returns this message when you specify an invalid value for the key segment descriptor. The value for the key segment descriptor can be any hexadecimal value from 00 to FF. An example of an invalid value is GL.BUTIL-6.10-16: BUTIL could not open the description file.The Maintenance utility cannot open the description file. Before attempting to reenter the CREATE, INDEX, or SINDEX commands, make sure that the file exists and that you specify the correct full pathname.BUTIL-6.10-18: An error occurred during access of the sequential file.The Maintenance utility returns this message when an error occurs during access of a sequential file. Check to see if the Btrieve source file is valid.BUTIL-6.10-19: BUTIL could not open the alternate collating sequence file.The Maintenance utility cannot open the alternate collating sequence file that you specified in a description file. Make sure the Alternate Collating Sequence Filename element in the description file is assigned a valid pathname.BUTIL-6.10-20: An error occurred during access of the alternate collating sequence file.An error occurred when the Maintenance utility accessed the alternate collating sequence file. Make sure the information in the alternate collating sequence file is formatted correctly.BUTIL-6.10-21: The file version is earlier than 6.0.The Maintenance utility returns this message when the RECOVER command cannot recover data from a Btrieve v5.x file, or the SALVAGE command cannot repair or salvage a Btrieve v5.x file.BUTIL-6.10-23: The /D parameter specified to the Requester was too small for BUTIL to receive the entire record. BUTIL is writing only nn bytes.The Maintenance utility is writing only as many bytes as the value of the /D option allows. If you want the utility to write all the bytes in the record, specify a value for the /D option that is at least as large as the affected record.BUTIL-6.10-25: The /D parameter specified to BUTIL was too small for BUTIL to receive any part of the record.The Maintenance utility returns this message when you specify an invalid value for the /D option. Return to the Setup utility and increase the value specified for the Largest Record Size configuration option.BUTIL-6.10-26: The data buffer is too small to hold any part of the record.Btrieve cannot return any data in the data buffer because the data buffer is too small to hold it. Return to the Setup utility and increase the value specified for the Largest Record Size configuration option.BUTIL-6.10-27: An error occurred during the access of the variable page. BUTIL is writing the obtainable portion of the variable page.The Maintenance utility returns this message when an error occurs during the recovery of a file with variable-length records. The file has been corrupted.BUTIL-6.10-30: The key position cannot exceed the record length.The Maintenance utility returns this message when the range of the key position you specified is invalid. The key position you specify on a Btrieve call must be within the range of the record's length. For example, for a record that is 100 bytes long, a key position of 50 is within the correct range. However, a key position of 150 is not.BUTIL-6.10-31: The key position plus key length cannot exceed the record length.The Maintenance utility returns this message when the range of the key position you specified is invalid. The key position of a key plus its length cannot be larger than the record length. Verify that the key is defined so that its position plus its length does not exceed the record length.BUTIL-6.10-32: The key length must be an even number for key type xxxx.The Maintenance utility returns this message when you specified an invalid key length for the key type. Some key types must contain an even number of bytes. Respecify the Key Length element correctly. BUTIL-6.10-36: The page size must be a multiple of 512, from 512 to 4,096.The Maintenance utility returns this message if the page size you specified is not a multiple of 512, from 512 to 4,096. Specify an appropriate page size.BUTIL-6.10-37: The record length cannot exceed the page size.The Maintenance utility returns this message if the record length you specified is invalid. In the description file, the record length you specified for the Record Length element is larger than the page size you specified for the Page Size element. Specify a record length that is smaller than the page size or increase the page size.BUTIL-6.10-38: The record length must be at least 4 and no greater than 4,096.The Maintenance utility returns this message if the record length you specified is invalid. Specify a record length between 4 and 4,096 (inclusive) for Btrieve v5.x, or between 4 and 4,088 for Btrieve v6.x.BUTIL-6.10-41: The alternate collating sequence cannot be found.The Maintenance utility cannot find the alternate collating sequence file you specified in the definition file. Verify that the alternate collating sequence file exists and that the name is correct in the definition file.BUTIL-6.10-43: The file exists, but the Replace option was not specified.The Maintenance utility did not create a file when you specified the BUTIL -CREATE command because the file already exists. To recreate this file, specify the Replace Existing File element in the description file as y.BUTIL-6.10-44: The file access error nn occurred for file xxxx.The Maintenance utility returns the appropriate status code and filename for a file on which a file access error occurred during the beginning or end of continuous operation. The corrective measure depends on the status code received. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BUTIL-6.10-45: The number of duplicate keys must be between 1 and 119.The number of duplicate keys you specified is invalid. Check the value specified for the Duplicate Key element in the description file.BUTIL-6.10-47: BUTIL cannot open the command file.The Maintenance utility returns this message when it cannot open the specified command file. Make sure the command file exists and that you specified the command file location and filename correctly.BUTIL-6.10-48: The command file is empty.The Maintenance utility returns this message if the command file you specified does not contain characters. Specify the desired commands in the command file before attempting to use the command file again. In addition, make sure you specified the correct command filename.BUTIL-6.10-49: The command file exceeds 1,000 bytes.A command file cannot contain more than 1000 bytes. Verify that the command file adheres to this requirement.BUTIL-6.10-50: An internal error caused BUTIL to terminate.The Maintenance utility detected an internal diagnostic error that caused it to terminate.BUTIL-6.10-52: Btrieve cannot be stopped when NetWare SQL is loaded.The Maintenance utility returns this message when you attempt to unload Btrieve while NetWare SQL is loaded. Unload NetWare SQL before attempting to unload Btrieve again.BUTIL-6.10-53: Btrieve error nn occurred for file or command xxxx.The Maintenance utility returns a status code related to a particular file or command. The corrective measure depends on the status code received. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BUTIL-6.10-56: BUTIL is processing source file record nn.This is an informational message from the Maintenance utility. No action is required.BUTIL-6.10-57: BUTIL has copied nn records so far.The Maintenance utility copied the stated number of records since you issued the BUTIL -COPY command. After you receive this message, the command is still executing.BUTIL-6.10-58: BUTIL copied nn records.The Maintenance utility copied the stated number of records after you issued the BUTIL -COPY command. This is the total number of records BUTIL copied while the command executed.BUTIL-6.10-59: BUTIL read nn records.This is an informational message from the Maintenance utility. No action is required. When you issue a BUTIL -RECOVER command, the utility reads records in physical order from the specified file. When you issue a BUTIL -SAVE command, the utility reads records from the specified file using an index path.BUTIL-6.10-60: The end of the file occurred while BUTIL was expecting keyword xxxx on key segment descriptor nn.While the Maintenance utility was creating a file, it found a syntax error in the description file. Check the syntax of the description file.BUTIL-6.10-61: The end of the file occurred while BUTIL was expecting keyword xxxx.While the Maintenance utility was creating a file, it found a syntax error in the description file. Check the syntax of the description file.BUTIL-6.10-62: BUTIL was expecting keyword xxxx on key segment descriptor nn.While the Maintenance utility was creating a file, it found a syntax error in the description file. Check the syntax of the description file.BUTIL-6.10-63: BUTIL was expecting keyword xxxx.While the Maintenance utility was creating a file, it found a syntax error in the description file. Check the syntax of the description file.BUTIL-6.10-64: nn records have been indexed.This is an informational message from the utility. The utility displays the number of records that were indexed since you issued the BUTIL -INDEX command. No action is required.BUTIL-6.10-65: BUTIL has loaded no records.The Maintenance utility did not load any records after you specified the BUTIL -LOAD command. Verify that you specified the command correctly and that the input file is in the correct format.BUTIL-6.10-66: BUTIL has loaded nn records so far.The Maintenance utility loaded the stated number of records since you issued the BUTIL -LOAD command. When you receive this message, the command is still executing.BUTIL-6.10-67: BUTIL is processing sequential record nn.This is an informational message from the Maintenance utility. No action is required.BUTIL-6.10-68: BUTIL has loadednn records.The Maintenance utility loaded the stated number of records after you issued the BUTIL -LOAD command. This is the total number of records BUTIL loaded while the command executed.BUTIL-6.10-69: BUTIL has read nn sequential records.This is an informational message from the Maintenance utility. No action is required.BUTIL-6.10-70: The Btrieve error nn occurred on closing a file.The Maintenance utility returns this status code while closing a file. The corrective measure depends on the status code received. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BUTIL-6.10-71: BUTIL has recovered nn records so far.The Maintenance utility recovered the stated number of records since you issued the BUTIL -RECOVER command. After you receive this message, the command is still executing.BUTIL-6.10-72: BUTIL has recovered nn records.The Maintenance utility recovered the stated number of records after you issued the BUTIL -RECOVER command. This is the total number of records BUTIL recovered while the command executed.BUTIL-6.10-73: BUTIL is scanning the file.The Maintenance utility is scanning a file while performing a BUTIL -SALVAGE command. No action is required.BUTIL-6.10-74: Btrieve error nn was returned for the Stop Command.The Maintenance utility returns this status code after the BUTIL -STOP command was issued. The corrective measure depends on the status code received. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix. This message applies only to the DOS environment.BUTIL-6.10-76: When BUTIL wrote the Page Allocation Table at page #nn, an error occurred.The Maintenance utility returns this message while salvaging a file if the file is corrupted or when a hardware error occurs.BUTIL-6.10-77: When BUTIL wrote a mirror copy of the Page Allocation Table at page #nn, an error occurred.The Maintenance utility returns this message while salvaging a file if the file is corrupted or when a hardware error occurs.BUTIL-6.10-82: The file format is incorrect.The Maintenance utility returns this message when the format for the file is prior to Btrieve v6.x. Check the format of the file.BUTIL-6.10-83: BUTIL is checking Page Allocation Table page #nn of #nn.The Maintenance utility returns this message while performing a BUTIL -SALVAGE. No action is required.BUTIL-6.10-84: The Page Allocation Table entry nn on page nn at offset nn points to an invalid page.The Maintenance utility returns this message when it encounters file corruption while performing a BUTIL -SALVAGE. You may lose some data. Check the salvaged file.BUTIL-6.10-86: The file's Page Allocation Table appears damaged.The Maintenance utility returns this message while performing a BUTIL -SALVAGE. You may lose some data. Check the salvaged file.BUTIL-6.10-90: BUTIL could not allocate enough memory.The Maintenance utility cannot continue with the BUTIL -SALVAGE command due to inadequate memory at the server. Free some memory at the server by unloading unused NLMs.BUTIL-6.10-91: BUTIL could not determine the size of the file.The Maintenance utility cannot continue with the BUTIL -SALVAGE command. The file cannot be salvaged. Try to recover the file using the BUTIL -RECOVER command.BUTIL-6.10-92: The user terminated BUTIL.The Maintenance utility returns this message to indicate that the user entered 0 to quit when prompted by the utility.BUTIL-6.10-93: BUTIL has saved nn records so far.The Maintenance utility saved the stated number of records since you issued the BUTIL -SAVE command. When you receive this message, the command is still executing.BUTIL-6.10-94: BUTIL has saved nn records.The Maintenance utility saved the stated number of records after you issued the BUTIL -SAVE command. This is the total number of records BUTIL saved while the command executed.BUTIL-6.10-128: The Btrieve Version is n.n.The Maintenance utility returns the version of Btrieve that you are currently running.BUTIL-6.10-131: BUTIL was unable to create or open the sequential file.The Maintenance utility returns this message when it is unable to create or open the specified file. Check the sequential file to make sure it exists and has the read-only attribute set.BUTIL-6.10-132: The disk volume is full.The Maintenance utility returns this message when the disk volume is full. You must have more disk space to create or enlarge any Btrieve files.BUTIL-6.10-134: BUTIL was unable to create or open the new file.The Maintenance utility returns this message when it is unable to create or open the specified file. Check the file specified for the BUTIL -SAVE, -SALVAGE, or -RECOVER command. The file may already exist.BUTIL-6.10-136: BUTIL was unable to write the new backup file.The Maintenance utility returns this message when it is unable to write the new backup file. Verify that you specified the correct path and filename for the backup file. Also, make sure you have enough disk space for the file to be written.BUTIL-6.10-152: There was an error opening filexxxx.While performing the BUTIL -SALVAGE command, the Maintenance utility could not open the file. Check the Btrieve file attributes, path, and filename.BUTIL-6.10-155: BUTIL cannot open the Btrieve file xxxx.The Maintenance utility returns this message when it cannot open the specified file. Check the path, filename, and file attributes.Monitor Utility MessagesThe following messages are sent by the Btrieve Monitor utility (BTRMON.NLM).BTRMON-6.1-43: The utility cannot allocate memory sufficient for the operation.Press Esc to continue. The Btrieve Monitor utility makes five attempts to allocate enough memory for the operation and, if unsuccessful, displays message 118.BTRMON-6.1-118: There is still insufficient memory for the operation.The Btrieve Monitor utility displays this message when it has completed five unsuccessful attempts to allocate enough memory for the operation. You must either unload some NLMs, if possible, or wait for a time when server usage is less heavy.BTRMON-6.1-124: The utility cannot find the help file BTRMON.HLP.The Btrieve Monitor utility displays this message when it cannot find the help file. Check your SYSTEM directory to make sure that the help file is present.BTRMON-6.1-128: This Btrieve file is no longer open. Please press the <Insert> key to update the file list.The Btrieve Monitor utility displays this message when you select a file that was open when you began viewing active resources but is now closed.Rebuild Utility MessagesThe following messages are sent by the Rebuild utility (BREBUILD.NLM).BREBUILD-1.1-2: BREBUILD could not allocate memory.The Rebuild utility displays this message when the server does not have adequate memory. Acquire more memory for the server. BREBUILD-1.1-3: BREBUILD could not rename xxxx to xxxx.The Rebuild utility displays this message when the specified file does not exist. Check to see if the file exists.BREBUILD-1.1-4: An incorrect Btrieve version is loaded.The Rebuild utility displays this message when an incorrect Btrieve version is loaded. Unload the current version of Btrieve, and reload using Btrieve v6.x.BREBUILD-1.1-5: BREBUILD could not delete xxxx.The Rebuild utility displays this message when it cannot delete the specified file. Check to see if the file is open. If it is open, close it. The Rebuild utility cannot delete a file while it is open.BREBUILD-1.1-6: An internal program error occurred.The Rebuild utility detected an internal diagnostic error.BREBUILD-1.1-7: BREBUILD could not open xxxx. The Btrieve status was nn.The Rebuild utility displays this message when it cannot open the specified file. Btrieve returns the specified status code. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BREBUILD-1.1-8: BREBUILD could not open xxxx in the accelerated mode. The Btrieve status code was nn.The Rebuild utility displays this message when it cannot open the specified file in Accelerated mode. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BREBUILD-1.1-9: BREBUILD could not create the new file or files with the Btrieve 6.x advanced features. Ensure that the correct version of Btrieve is loaded with the Create Btrieve Files in Pre v6.x Format option set to No.The Rebuild utility displays this message when it cannot create the new Btrieve files in v6.x format. Unload Btrieve by executing BSTOP, or unload Btrieve at the server console or at a workstation running RCONSOLE.BREBUILD-1.1-10: An invalid option was specified.Change the configuration options for the Rebuild utility through the Setup utility. Refer to IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve," for more information. When you run the Rebuild utility interactively, it checks the values you enter to ensure they are within the proper ranges.BREBUILD-1.1-11: Indexes are not consecutively numbered. Indexes will not be dropped.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-12: BREBUILD has copied nn records so far.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-13: BREBUILD is rebuilding nn key number nn.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-14: BREBUILD did not rebuild for the following reason: xxxxThe Rebuild utility was not able to rebuild the file specified and returned this message. Eliminate the cause for this message and try to rebuild the file again.BREBUILD-1.1-15: Btrieve returned status nn for the following reason: xxxxBtrieve returned the specified status code. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BREBUILD-1.1-16: The xxxx file is already in 6.x format.The Rebuild utility displays this message when the specified file is already in Btrieve v6.x format. You do not need to rebuild the file.BREBUILD-1.1-17: The xxxx file is not a Btrieve file.The file you specified to rebuild is not a valid Btrieve file. The Rebuild utility cannot rebuild the file. BREBUILD-1.1-18: BREBUILD could not obtain the characteristics of the xxxx. The Btrieve status was nn.The Rebuild utility returns the specified Btrieve status code. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BREBUILD-1.1-19: BREBUILD could not change to directoryxxxx.The directory name you specified for the output directory is not valid. Specify a valid output directory name for the Rebuild utility on the command line or through the Setup utility. BREBUILD-1.1-20: BREBUILD is processing xxxx.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-21: BREBUILD is copying thexxxx to the temporary file xxxx.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-22: The file was rebuilt successfully.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-23: The utility could not open sys:\system\brebuild.log.The Rebuild utility displays this message if the file BREBUILD.LOG either does not exist or has been left open.BREBUILD-1.1-24: An error occurred accessing xxxx.The Rebuild utility displays this message when you specify an invalid filename. Make sure you specified a valid filename.BREBUILD-1.1-25: BREBUILD is setting the owner name of an empty target file.The Rebuild utility displays this message when an error occurs during the setting of an empty target file's owner name. You need to rerun the Rebuild utility.BREBUILD-1.1-26: BREBUILD is dropping the indexes of an empty target file.The Rebuild utility displays this message when an error occurs during the dropping of an empty target file's indexes. You need to rerun the Rebuild utility.BREBUILD-1.1-27: BREBUILD is reading the first record from the old file.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-28: BREBUILD is inserting records into the new file.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-29: BREBUILD is reading records from the old file.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-30: BREBUILD is putting back indexes on the new file.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-31: BREBUILD could not create xxxx. The Btrieve status code was nn.The Rebuild utility displays this message when it cannot create the specified file. The utility returns the specified Btrieve status code. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BREBUILD-1.1-32: BREBUILD copied a total of nn records.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-33: BREBUILD start time is nn.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-34: Key number nn is invalid.The Rebuild utility displays this message when the key specified for the Key Number (-K) option is invalid. Specify a valid key number for the Rebuild utility on the command line or through the Setup utility. BREBUILD-1.1-35: Page sizenn is invalid.The Rebuild utility displays this message when the page size specified for the Page Size (-P) option is invalid. Specify a valid page size for the Rebuild utility on the command line or through the Setup utility. BREBUILD-1.1-36: The page size will be changed to nn.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-37: The rebuild process has ended.This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-38: BREBUILD was terminated by the user.The user entered Ctrl+C and the Rebuild utility was unloaded.BREBUILD-1.1-39: BREBUILD was unloaded by the user.The user unloaded Btrieve and the Rebuild utility was unloaded.BREBUILD-1.1-40: BREBUILD could not open the file xxxx.The Rebuild utility displays this message when it cannot open the specified file. The file may be open or may not exist. Check for one of these conditions.BREBUILD-1.1-42: The specified local server xxxx is invalid.The Rebuild utility displays this message when the specified server name is not a local server.BREBUILD-1.1-44: BREBUILD could not clone xxxx. The Btrieve status was nn.The Rebuild utility displays this message when it cannot clone the specified file. Btrieve returns the specified Btrieve status code. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix.BREBUILD-1.1-45: The command line file xxxx does not have an <end> delimiter.Each entry in the command file contains the utility options (if any) and the set of files to convert. Each entry must be followed by <end> or [end]. Edit the command file to include the necessary delimiter.BREBUILD-1.1-48: BREBUILD could not initialize the user interface library.The Rebuild utility displays this message when the server has insufficient memory to initialize the user interface library.BREBUILD-1.1-63: BREBUILD could not initialize localized message table.The Rebuild utility displays this message when the server has insufficient memory to initialize the localized message table.BREBUILD-1.1-64: BREBUILD is currently processing the following file:This is an informational message from the Rebuild utility. No action is required.BREBUILD-1.1-66: BREBUILD could not open the xxxx.The Rebuild utility displays this message when it cannot open the specified file. The file may be open or may not exist. Check for one of these conditions.Requester Utility MessagesThe following messages are sent by the Requester utility (BREQUTIL.NLM).BREQUTIL-6.1-3: The single-user version of Btrieve vn.n is loaded.This is an informational message from the Requester utility. No action is required.BREQUTIL-6.1-4: The network version of Btrieve vn.n is loaded. This is an informational message from the Requester utility. No action is required.BREQUTIL-6.1-5: The multi-user version of Btrieve vn.n is loaded. This is an informational message from the Requester utility. No action is required.BREQUTIL-6.1-6: The OS/2 DynaLink for Btrieve vn.n is loaded. This is an informational message from the Requester utility. No action is required.BREQUTIL-6.1-7: Btrieve version vn.n is loaded. This is an informational message from the Requester utility. No action is required.BREQUTIL-6.1-8: Btrieve is not loaded.Either the Btrieve Requester (BREQUEST.EXE) or Record Manager (BTRIEVE.EXE) is not loaded. BREQUTIL-6.1-9: Btrieve operation xx was unsuccessful. The number of the applicable Btrieve status code is nn.The Requester utility returns the specified Btrieve status code. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix. For information about the Btrieve operation xx, see Chapter 4, "Btrieve Operations," in the Btrieve Programmer's Manual.BREQUTIL-6.1-16: Btrieve cannot be removed from memory while NetWare SQL is loaded.This is an informational message from the Requester utility. No action is required.Roll Forward Utility MessagesThe following messages are sent by the Roll Forward utilities for the DOS, OS/2, and Windows operating environments.Roll Forward Utility for DOSThis section lists and describes the messages that the Roll Forward utility for the DOS environment can send.BROLLFWD-6.1-1: This workstation has insufficient memory to complete the operation.The workstation does not have enough memory for the DOS Roll Forward utility to complete the current operation. Free some memory on the workstation and restart the Roll Forward process.BROLLFWD-6.1-2: The log file was created at nn:nn.This is an informational message from the DOS Roll Forward utility. No action is required.BROLLFWD-6.1-3: An internal program error has occurred.The DOS Roll Forward utility detected an internal program error.BROLLFWD-6.1-4: The specified owner name is invalid. Please reenter the owner name:The DOS Roll Forward utility returns this message when the specified owner name is invalid. Specify a valid owner name and start the roll forward process again. The maximum length for an owner name is 8 bytes. Enter a valid owner name.BROLLFWD-6.1-21: The utility is unable to open xxxx. The number of the applicable system error code is nn.The DOS Roll Forward utility returns this message when it cannot open the specified file. The file may be open or may not exist.BROLLFWD-6.1-22: An error occurred while the utility was reading xxxx. The DOS Roll Forward utility returns this message when it cannot read the specified file. Verify that the file exists. If the file exists, ensure that the file is closed.BROLLFWD-6.1-23: File xxxx ended unexpectedly during the roll forward process.The DOS Roll Forward utility returns this message when the specified file ended unexpectedly during the roll forward process. The associated log file is corrupt. You cannot use this log file.BROLLFWD-6.1-24: The utility could not find the log file header information in xxxx.The DOS Roll Forward utility returns this message when no log file header information was found for the specified file. The associated log file is corrupt. You cannot use this log file.BROLLFWD-6.1-25: The xxxx file contains incorrect syntax in the log file header.The DOS Roll Forward utility returns this message when the log file header for the specified file contains incorrect syntax. The associated log file is corrupt. You cannot use this log file.BROLLFWD-6.1-26: Btrieve operation xx was unsuccessful. The number of the applicable Btrieve status code is nn.Btrieve returns the specified Btrieve operation and status codes to the DOS Roll Forward utility. The specified Btrieve operation was unsuccessful. Consult the screen message to get the value for nn, which corresponds to a numeric status code listed in the section IDREF="FM25949""Status Codes" in this appendix. For more information about the Btrieve operation xx, refer to the Btrieve Programmer's Manual.BROLLFWD-6.1-27: The utility could not find xxxx in the BLOG.CFG file.The DOS Roll Forward utility returns this message when the specified file is not found in the log configuration file, BLOG.CFG. Edit the BLOG.CFG file to add the filename specified. For more information about the BLOG.CFG file, refer to the section IDREF="FM14400""Creating the Log Configuration File" in Chapter 5.BROLLFWD-6.1-28: The record size of the Btrieve file file xxxx exceeds the size of the data buffer specified with the /d parameter.The DOS Roll Forward utility returns this message when the value specified for the /D option is invalid. Increase the value for the /D option.BROLLFWD-6.1-29: The length of the data to be printed, specified with the /t option, is invalid. Valid data lengths range from 1 through the value of the data buffer size specified with the /d option.The DOS Roll Forward utility returns this message when the value specified for the /T option is invalid. Change the value for this option.BROLLFWD-6.1-30: The length of the key to be printed, specified with the /k option, is invalid. Valid lengths for printing keys range from 1 through 255 characters.The DOS Roll Forward utility returns this message when the value specified for the /K option is invalid. Enter a value in the range 1 through 255.BROLLFWD-6.1-31: 0/1 entry in the log file has been processed.This is an informational message from the DOS Roll Forward utility. No action is required.BROLLFWD-6.1-32: xx in the log file have been processed.This is an informational message from the DOS Roll Forward utility. No action is required.BROLLFWD-6.1-42: The disk is full.The disk is full. Free some space on the disk and run the DOS Roll Forward utility again.BROLLFWD-6.1-43: The utility started the roll forward process at nn:nn.This is an informational message from the DOS Roll Forward utility. No action is required.Roll Forward Utility for OS/2This section lists and describes the messages that the Roll Forward utility for the OS/2 environment can send.PBROLL-6.10-1: Window creation failed.The underlying cause of this condition is insufficient free memory. To complete the operation, you must free some of the memory currently allocated or terminate some of the active applications.PBROLL-6.10-2: Window positioning failed.The OS/2 Roll Forward utility returns this message when memory has been corrupted. Try turning your computer off and on to reinitialize the memory.PBROLL-6.10-3: Cannot open the following file: filename.The OS/2 Roll Forward utility cannot open the specified file (Btrieve file, log file, or listing file). Make sure that the specified file exists and then specify the correct, full pathname.PBROLL-6.10-4: An error occurred during input or output for the following file: filename.Btrieve either cannot read from or cannot write to the disk. Make sure that the file attributes are set correctly. You may also try running server diagnostics or checking the disk subsystem.PBROLL-6.10-5: The following file ended unexpectedly: filename.The OS/2 Roll Forward utility returns this message when the log file for the specified Btrieve file is corrupt. You cannot use this log file.PBROLL-6.10-6: There is no header information in the following file: filename.The OS/2 Roll Forward utility cannot find the log file header information in the specified log file because the log file is corrupt. You cannot use this log file.PBROLL-6.10-7: There is incorrect header syntax in the following file: filename.The OS/2 Roll Forward utility returns this message when the specified log file is corrupt and contains incorrect syntax in the log file header. You cannot use this log file.PBROLL-6.10-8: The following file was not found in BLOG.CFG: filename.The OS/2 Roll Forward utility returns this message when it cannot find the specified file in the log configuration file. Edit the BLOG.CFG file to add the filename specified. For more information about the BLOG.CFG file, refer to the section IDREF="FM14400""Creating the Log Configuration File" in Chapter 5. PBROLL-6.10-9: The length of the record exceeds the current data buffer size for the following file: filename.The record size of the specified Btrieve file exceeds the data length you specified in the Options dialog box. Change the data length accordingly.PBROLL-6.10-10: Btrieve error: Operation: xx Status Code: nnBtrieve returns the specified Btrieve operation and status codes to the OS/2 Roll Forward utility. The specified Btrieve operation was unsuccessful. Consult the screen message to get the value of Status Code nn, which corresponds to a numeric status code listed in the "IDREF="FM25949"Status Codes" section of this appendix. For more information about the Btrieve operation xx, refer to the Btrieve Programmer's Manual.PBROLL-6.10-11: The following unknown error occurred: nn.The OS/2 Roll Forward utility detected an internal diagnostic error.PBROLL-6.10-12: There was an invalid owner name.The OS/2 Roll Forward utility returns this message when the specified owner name is invalid. Specify a valid owner name and start the roll forward process again. The maximum length for an owner name is 8 bytes. Enter a valid name in the Owner text box.PBROLL-6.10-13: Unable to add the item to the queue.The OS/2 Roll Forward utility works on a queued-job basis. The maximum number of files allowed in the queue is 32. That is, the utility cannot roll forward more than 32 files at one time. If you want to roll forward all the files on a specified volume, edit the log configuration file, BLOG.CFG, as needed to ensure that no more than 32 files are specified. If you want to roll forward individual files, make sure that you do not specify more than 32 files at one time.PBROLL-6.10-14: There is not enough memory available.The workstation does not have enough memory for the OS/2 Roll Forward utility to complete the current operation. Free some memory on the workstation and restart the roll forward process.PBROLL-6.10-15: The data length value is invalid. It must be between 1 and 64.The OS/2 Roll Forward utility returns this message when the specified data length is invalid. The Data Length option in the Options dialog box specifies the number of kilobytes allocated for the data buffer that the utility uses to process the logged entries. The value specified for the Data Length option should be at least as large as the largest record to be rolled forward. Specify an appropriate value for the Data Length option in the Options dialog box.PBROLL-6.10-16: Could not allocate the data buffer.The OS/2 Roll Forward utility returns this message when the system is low on memory. Free some system memory or specify a smaller data buffer, and run the utility again. PBROLL-6.10-17: Could not open the list file.The OS/2 Roll Forward utility returns this message when the pathname you entered for the new list file (when the disk ran out of space) is invalid. Specify a valid pathname for the new list file.PBROLL-6.10-18: ABORT---The data files may be left in an inconsistent state. Please confirm abort. The OS/2 Roll Forward utility returns this message when you select the Abort option during the roll forward process. Selecting Abort prevents the utility from applying the rest of the logged operations to the backup copy of the corresponding Btrieve file. Confirming the abort can leave the Btrieve file that is currently being rolled forward in an inconsistent state (that is, only partially updated). Select Yes to confirm you want to abort or No to cancel the abort and continue the roll forward process.PBROLL-6.10-19: This utility could not open NOVDB.INI.The OS/2 Roll Forward utility returns this message when it cannot open the initialization file, NOVDB.INI. Check the file attributes of the NOVDB.INI file to ensure that you have access rights to it. This file should be in the directory you selected when choosing the options for the utility.PBROLL-6.10-20: This item or volume is already in the queue.The OS/2 Roll Forward utility returns this message when the item or volume you entered in the queue has already been entered. Enter a different item or volume.PBROLL-6.10-21: The listing length exceeds the buffer length.The OS/2 Roll Forward utility returns this message when the specified listing length is invalid. In the Options dialog box, the Data to List option exceeds the value you entered for the Data Length option. The Data to List option specifies the length of the data buffer that will be printed in the list file for each operation that is rolled forward. The Data Length option specifies the number of kilobytes allocated for the data buffer that the utility uses to process the logged entries. Make sure the value you enter for the Data to List option does not exceed the value you entered for the Data Length option.PBROLL-6.10-22: The listing length is invalid.The OS/2 Roll Forward utility returns this message when the specified listing length is invalid. You entered an invalid value for the Data to List or the Key to List option in the Options dialog box. The Data to List option specifies the length of the data buffer that will be printed in the list file for each operation that is rolled forward. Similarly, the Key to List option specifies the length of the key buffer that will be printed in the list file for each operation that is rolled forward. In the options dialog box, make sure the value you enter for the Data to List option does not exceed the value you entered for the Data Length option and the Key to List option does not exceed 255 bytes.PBROLL-6.10-23: The key listing length cannot exceed 255.The OS/2 Roll Forward utility returns this message when the specified key listing length is invalid. The value you entered for the Key to List option in the Options dialog box exceeds 255 bytes. The Key to List option specifies the length of the key buffer that will be printed in the list file for each operation that is rolled forward. Make sure the value you enter for the Key to List option does not exceed 255 bytes.PBROLL-6.10-24: Only one instance is allowed to run.You tried to run the OS/2 Roll Forward utility, but it is already running.Roll Forward Utility for WindowsThis section lists and describes the messages that the Roll Forward utility for the Windows environment can send.WBROLL-6.1-1: Could not open configuration file BLOG.CFG.The Windows Roll Forward utility cannot open the log configuration file, BLOG.CFG. Make sure that the file is in the system directory SYS:\SYSTEM. For more information about the BLOG.CFG file, refer to the section IDREF="FM14400""Creating the Log Configuration File" in Chapter 5. WBROLL-6.1-2: Continue roll forward?The Windows Roll Forward utility returns this message when one of the files cannot be rolled forward. You can continue rolling forward the other files, or you can stop the roll forward process. Select Yes to continue or No to stop. Stopping the roll forward process prevents the Roll Forward utility from applying the rest of the logged operations to the backup copy of the corresponding Btrieve file. This can leave your Btrieve files in an inconsistent state (that is, only partially updated).WBROLL-6.1-3: Cannot open the following file: filename.The Windows Roll Forward utility cannot open the specified file (Btrieve file, log file, or listing file). Make sure that the specified file exists and then specify the correct, full pathname.WBROLL-6.1-4: An error occurred during input or output for the following file: filename.Btrieve either cannot read from or cannot write to the disk. Make sure that the file attributes are set correctly. You may also try running server diagnostics.WBROLL-6.1-5: The following file ended unexpectedly: filename.The Windows Roll Forward utility returns this message when the log file for the specified Btrieve file is corrupt. You cannot use this log file.WBROLL-6.1-6: There is no header information in the following file: filename.The Windows Roll Forward utility cannot find the log file header information in the specified log file because the log file is corrupt. You cannot use this log file.WBROLL-6.1-7: There is incorrect header syntax in the following file: filename.The Windows Roll Forward utility returns this message when the specified log file is corrupt and contains incorrect syntax in the log file header. You cannot use this log file.WBROLL-6.1-8: The following file was not found in BLOG.CFG: filename.The Windows Roll Forward utility returns this message when the specified file is not found in the log configuration file, BLOG.CFG. Edit the BLOG.CFG file to add the filename specified. For more information about the BLOG.CFG file, refer to the section IDREF="FM14400""Creating the Log Configuration File" in Chapter 5. WBROLL-6.1-9: The length of the record exceeds the current data buffer size for the following file: filename.The Windows Roll Forward utility returns this message when the specified record length is invalid. The record size of the specified Btrieve file exceeds the data length you specified in the Options dialog box. Change the data length accordingly.WBROLL-6.1-10: Btrieve error: Operation: xx Status Code: nnBtrieve returns the specified Btrieve operation and status codes to the Windows Roll Forward utility. The specified Btrieve operation was unsuccessful. Consult the screen message to get the value of Status Code nn, which corresponds to a numeric status code listed in the IDREF="FM25949""Status Codes" section of this appendix. For more information about the Btrieve operation xx, refer to the Btrieve Programmer's Manual.WBROLL-6.1-11: The following unknown error occurred: nn.The Windows Roll Forward utility detected an internal diagnostic error.WBROLL-6.1-12: There was an invalid owner name.The Windows Roll Forward utility returns this message when the specified owner name is invalid. Specify a valid owner name and start the roll forward process again. The maximum length for an owner name is 8 bytes. Enter a valid name in the Owner text box.WBROLL-6.1-13: The utility was unable to add the item to queue.The Windows Roll Forward utility works on a queued-job basis. The maximum number of files allowed in the queue is 32. That is, the utility cannot roll forward more than 32 files at one time. If you want to roll forward all the files on a specified volume, edit the log configuration file, BLOG.CFG, as needed to ensure that no more than 32 files are specified. If you want to roll forward individual files, make sure that you do not specify more than 32 files at one time.WBROLL-6.1-14: There is not enough memory available.The workstation does not have enough memory for the Windows Roll Forward utility to complete the current operation. Free some memory on the workstation and restart the roll forward process.WBROLL-6.1-15: The data length value is invalid. It must be between 1 and 64.The Windows Roll Forward utility returns this message when the specified data length is invalid. The Data Length option in the Options dialog box specifies the number of kilobytes allocated for the data buffer that the utility uses to process the logged entries. The value specified for the Data Length option should be at least as large as the largest record to be rolled forward. Specify an appropriate value for the Data Length option in the Options dialog box.WBROLL-6.1-16: Could not allocate the data buffer.The Windows Roll Forward utility returns this message when the system is low on memory. Free some system memory or specify a smaller data buffer, and run the utility again. WBROLL-6.1-17: Could not open the list file.The Windows Roll Forward utility returns this message when the pathname you entered for the new list file (when the disk ran out of space) is invalid. Specify a valid pathname for the new list file.WBROLL-6.1-18: ABORT --- The data files may be left in an inconsistent state. Please confirm abort. The Windows Roll Forward utility returns this message when you select the Abort option during the roll forward process. Selecting Abort prevents the Roll Forward utility from applying the rest of the logged operations to the backup copy of the corresponding Btrieve file. Confirming the abort can leave the Btrieve file that is currently being rolled forward in an inconsistent state (that is, only partially updated). Select Yes to confirm you want to abort or No to cancel the abort and continue the roll forward process.WBROLL-6.1-19: Log file name too long. Max = 120.The Windows Roll Forward utility returns this message when the length of the log filename you specified is greater than 120 bytes. Specify an appropriate length for the log file.WBROLL-6.1-20: This item or volume is already in the queue.The Windows Roll Forward utility returns this message when the item or volume you entered in the queue has already been entered. Enter a different item or volume.WBROLL-6.1-21: The listing length exceeds the buffer length.The Windows Roll Forward utility returns this message when the specified listing length is invalid. In the Options dialog box, the Data to List option exceeds the value you entered for the Data Length option. The Data to List option specifies the length of the data buffer that will be printed in the list file for each operation that is rolled forward. The Data Length option specifies the number of kilobytes allocated for the data buffer that the utility uses to process the logged entries. Make sure the value you enter for the Data to List option does not exceed the value you entered for the Data Length option.WBROLL-6.1-22: Pathname is too long.The Windows Roll Forward utility returns this message when the pathname you specified is greater than 240 bytes. Specify a shorter pathname.WBROLL-6.1-24: Only one instance is allowed to run.You tried to run the Windows Roll Forward utility, but it is already running.Setup Utility MessagesThe following messages are sent by the Setup utility (BSETUP.NLM).BSETUP-6.1-40: The Btrieve Setup utility was unable to save the file.The Setup utility was not able to save the Btrieve configuration options to the BSTART.NCF file. Retry the operation.BSETUP-6.1-43: The attempted memory allocation failed.The Setup utility cannot allocate enough internal memory to display the Rebuild log file.BSETUP-6.1-63: The BSTART.NCF file is incomplete or invalid.The Setup utility is unable to save the configuration option changes to BSTART.NCF because the file is incomplete or invalid. You may want to delete BSTART.NCF and recreate it in the Setup utility.BSETUP-6.1-73: The Btrieve Setup utility could not find the BSTART.NCF file, which must reside in the SYS:SYSTEM directory on the server.The Setup utility cannot find the BSTART.NCF file. If BSTART.NCF does not exist, you must create it through the Setup utility.BSETUP-6.1-75: To implement the configuration changes, first unload BSPXCOM.NLM and BTRIEVE.NLM, and then use the BSTART.NCF file to reload BSPXCOM.NLM and BTRIEVE.NLM.For the changes you made to the configuration options to take effect, you must unload BSPXCOM.NLM and BTRIEVE.NLM and then reload them using BSTART.NCF.BSETUP-6.1-100: The BSTART.NCF file was created with the default configuration settings. To view or change these settings, select the Set Btrieve Configuration option on the Available Options menu.Select the stated option within the Setup utility to change the configuration options for Btrieve in the BSTART.NCF file.BSETUP-6.1-121: WARNING: Before running the Btrieve Rebuild utility, be sure to back up all your Btrieve data files.Before running the Rebuild utility, make sure you have backed up all your Btrieve data files. Having a backup copy ensures against data loss if a power interruption occurs while you are running the utility. Another reason it is better to keep a backup is that the Rebuild utility deletes the original Btrieve files.BSETUP-6.1-122: You must specify the Rebuild Configuration parameters before you can execute the Rebuild utility.Before you can run the Rebuild utility, you must specify appropriate values for the Rebuild configuration options in the Setup utility. Please do so before attempting to run the Rebuild utility again.BSETUP-6.1-131: The Output Directory pathname does not require a file specification.Do not specify a filename as part of the output directory path.BSETUP-6.1-132: Before rebuilding Btrieve files on a remote server, make sure the following files are loaded: BROUTER.NLM and BTRIEVE.NLM on the local server, and BSPXCOM.NLM and BTRIEVE.NLM on the remote server.The NLMs listed in the message must be loaded on a local server and a remote server before attempting to rebuild files on a remote server.BSETUP-6.1-148: The Btrieve Setup utility could not find the file BREBUILD.NLM in the system directory, so you cannot invoke the Rebuild utility at this time.The Setup utility returns this message when it cannot find the file BREBUILD.NLM. The file BREBUILD.NLM must be in the system directory. Please verify that it is in the correct directory.BSETUP-6.1-152: Either the Input Directory pathname is invalid, or no matching files could be found. Please check the pathname.The Setup utility returns this message when the path specified for the Files To Be Converted field is invalid or when no files exist in the directory specified.BSETUP-6.1-153: Either the Output Directory pathname is invalid, or no matching files could be found. Please check the pathname.The Setup utility returns this message when the path specified for the Output Directory field does not exist on the local server.BSETUP-6.1-158: The Btrieve Setup utility could not create a screen for the Rebuild utility, so you cannot invoke the Rebuild utility at this time.The Setup utility cannot invoke the Rebuild utility because too many screens are active at this time. Try the Rebuild utility again later when there is less activity on the server. BSETUP-6.1-159: The Btrieve Setup utility could not open the Rebuild error log file.When you attempted to view the Rebuild log file, the Setup utility was not able to open the log file. Verify that the file exists before retrying the operation.BSETUP-6.1-160: The attempt to read the Rebuild error log file failed.The Setup utility was not able to read the Rebuild log file when you attempted to view it. Check to see that the log file exists.BSETUP-6.1-162: The Rebuild utility cannot be loaded because the BTRIEVE.NLM is not loaded. Please load Btrieve using the BSTART.NCF file.Btrieve must be loaded before you run the Rebuild utility. Load BTRIEVE.NLM using BSTART.NCF.BSETUP-6.1-166: The utility found no files in the specified directory path. Please check the pathname.The Setup utility cannot find any Btrieve files to rebuild in the chosen directory (specified for Files To Be Converted). Verify that you specified the correct directory.BSETUP-6.1-167: The Rebuild utility could not be invoked at this time.The Setup utility returns this message when it cannot invoke the Rebuild utility. Check to make sure that the version 1.1 of BREBUILD.NLM is loaded at the server. If it is not, load it at this time.BSETUP-6.1-168: The Btrieve Setup utility could not create the semaphore which synchronizes BSETUP.NLM and BREBUILD.NLM, so you cannot invoke the Rebuild utility at this time.The semaphore used to synchronize the Setup utility and the Rebuild utility could not be created. Try the utility at a later time when there is less activity at the file server or use the command line version of BREBUILD.LBL="C"ID="FM32913"Glossaryalternate collating sequenceA sorting sequence other than the standard ASCII sequence that specifies the order in which Btrieve sorts keys.applicationA program or set of programs, such as a spreadsheet or a payroll application, that performs a task or a group of related tasks. Also, a program written by or for a user to apply to the user's work.application interfaceA program that allows access to Btrieve files from an application program.ascendingA key attribute that instructs Btrieve to collate an index in ascending order.ASCIIAn acronym for American Standard Code for Information Interchange. ASCII is a 7-bit information code that defines 128 standard characters, including control characters, letters, numbers, and symbols.BtrieveA key-indexed record manager for file handling. A function call from a standard programming language or from NetWare SQL invokes Btrieve. Btrieve RequesterThe Btrieve Requester program for the applicable DOS, OS/2, Windows, or UnixWare environment. The program resides at a workstation and provides communication between Btrieve and a workstation application making Btrieve calls.bufferA storage area in memory that is used to store data temporarily.cacheThe area of memory in which Btrieve stores images of physical disk pages. Btrieve uses the cache to reduce the number of physical disk I/O requests.case insensitiveA key characteristic that instructs Btrieve to sort an index so that values in uppercase letters are sorted in the same order as values in lowercase letters. (For example, SANDY is equal to sandy.) chunkAny arbitrary portion of a record, specified by its offset and length. Btrieve v6.1 allows applications to update and retrieve portions of very large records, called chunks, rather than the entire record.command fileA user-defined file that contains a sequence of commands.ID="FM33087"concurrency controlsThe methods Btrieve uses to resolve possible conflicts when two applications attempt to access the same data. Controls include passive control, record locking, and transaction control.configurationThe customization of a program such as Btrieve. You can customize Btrieve through the Setup utility.configuration optionsSpecifications defined for Btrieve when it is loaded. Configuration options control the way in which Btrieve operates. You can use the Setup utility to change the configuration options.connection numberThe unique identifier number that NetWare assigns when a workstation attaches to a server.ID="FM11085"continuous operationA Btrieve feature that allows you to back up data files while they are open and in use. Btrieve opens the files in read-only mode to allow backup utilities to access the files' static images. Btrieve stores changes to the original files in temporary files called delta files. When the backup is complete, Btrieve automatically updates the original files with the changes stored in the delta files. Btrieve deletes each temporary file as soon as all applications close the Btrieve data file corresponding to that delta file.databaseA set of one or more records or files that contain information on a related subject.defaultA preset option or value. For example, the default directory or disk drive is the one in which you are currently working. description fileAn ASCII file containing information that the Maintenance utility commands CREATE, INDEX, and SINDEX need to perform their operations.directoryA disk structure that contains files. A directory may also contain subdirectories.DOSThe DR DOS, MS-DOS, or PC-DOS operating system.duplicatableA key attribute specifying that multiple records in a file can have the same value in the key field.dynamic link library (DLL)A program library that contains related modules of compiled code. At runtime, the application reads the functions in the DLL. This process is called dynamic linking.dynamic link routineIn OS/2 and Windows v3.x, a program that the operating system loads on demand (dynamically) and terminates automatically. fieldThe smallest meaningful unit of data in a file.fileA collection of records stored on a disk. A file is sometimes also referred to as a physical file.ID="FM12813"indexA key or a group of keys that Btrieve uses to sort a file. See also IDREF="FM34449"key.index balancingThe process of searching for available space in sibling index pages when a given index page becomes full, and then rotating values from the full page into the pages that have space available. Index balancing is a new feature you can activate in Btrieve v6.1 (as explained in IDREF="FM13326"Chapter 3, "Installing and Configuring Btrieve").integrity controlA method of ensuring that data in a file is complete and accurate. Btrieve uses concurrency controls and shadow paging to guarantee data file integrity. See also IDREF="FM33087"concurrency controls and IDREF="FM29935"shadow paging.ID="FM34449"keyA field in a Btrieve file by which the file can be sorted. See also IDREF="FM12813"index.manual keyA modified form of the null key, useful in excluding particular records from the index. In a manual key, if every byte of one segment contains the null value, Btrieve excludes the key from the index. (The Btrieve Programmer's Manual refers to manual keys as "any-segment null keys.")modifiableA key attribute that allows you to modify the key field during an update to a file. If a key is not modifiable, you cannot change the value in the key field.NetWare Loadable Module (NLM)A server program built into server memory with NetWare. You can load or unload an NLM while the server is running. The NLM becomes part of the operating system and can access NetWare directly. NetWare SQLNovell's relational data access system, which resides at the server as an NLM.null keyA key field that can be a user-defined character. For null keys, Btrieve does not include the record in the index if the record's key value matches the null value. (The Btrieve Programmer's Manual refers to null keys as "all-segment null keys.")owner nameA password that protects data files from unauthorized access by Btrieve applications. You can assign an owner name using the Maintenance utility or by implementing a Set Owner record operation.pageA unit of a data file. A page is the smallest unit of storage that Btrieve moves between main memory and disk. Pages contain a multiple of 512 bytes (up to 4,096 bytes).pathnameThe server name, volume, directory path, and filename that uniquely identify a file.pre-imagingStoring the image of a file page before updating a record on the page. Btrieve v5.x and earlier use pre-imaging to provide recovery capabilities in case a file is damaged or a system failure occurs during an update to the file.record lockingA type of concurrency control that enables an application to lock the record it is accessing within a file. Other users can read the record, but no other user can lock, update, or delete the record until the application that holds the lock releases it. Record ManagerThe server-based Btrieve Record Manager is a program that resides at the server and handles data I/O with the file system. The client-based Btrieve Record Manager resides at the workstation and handles data I/O with the file system through operating system calls.referential integrity (RI)The assurance that when a field in one table references a field in another table, changes to these fields are synchronized.RequesterA program that resides at a workstation and passes requests from an application to a server-based application. ID="FM25235"roll backAborting a transaction and undoing all the changes made to a file during the transaction, thus restoring the file to the state it was in before the transaction began. See also IDREF="FM16624"transaction.roll forwardRecovering changes made to a Btrieve file between the time logging is initiated and a system failure. See also IDREF="FM25235"roll back and IDREF="FM25661"roll in.ID="FM25661"roll inWriting to a Btrieve original file all the changes made to the corresponding temporary file during the continuous operation backup period. When the backup is complete, Btrieve automatically updates the original file with the changes and deletes the temporary file. See also IDREF="FM11085"continuous operation.segmentedA key attribute that allows a key to consist of one or more fields (or segments).Sequenced Packet Exchange (SPX)A Novell communication protocol that monitors network transmission to ensure successful delivery. SPX runs on top of Novell's Internetwork Packet Exchange (IPX).ID="FM29935"shadow pagingA technique that Btrieve v6.x uses to ensure data integrity. When a user needs to change a page, Btrieve makes the change to a physical shadow page, which is a virtual copy of the original page. When the change is committed, Btrieve designates the shadow page as the current page, and the original page becomes available for reuse. sign trailing separate (STS) A COBOL data type that is basically a numeric data type, represented as an ASCII string. STS is right justified and padded with leading zeros, and it has the sign byte at the end.supervisorThe person responsible for the administration and maintenance of a network, a database, or both. A supervisor has access rights to all volumes, directories, and files.threadA separate stream of execution within a program.ID="FM16624"transactionA set of related operations that constitutes a logical unit of work. The application performing the transaction requires that either all or none of these operations be performed.userSomeone who is authorized to log in to a network and/or database when security is installed and who has access rights to specific filenames, directories, and files.Variable-tail Allocation Table (VAT)An array of pointers to locations within the variable-length portion of a Btrieve record. 