Btrieve ® July-September 1994 Developer’s Journal Vol. II No. 3 THE INDEPENDENT SOURCE OF NEWS AND INFORMATION ABOUT BTRIEVE AND SCALABLE SQL Scalable SQL Supports New Platforms Smithware Releases New Relational Database Product Line Based on NetWare SQL Class Library for Austin, Texas — Earlier this month, which is the Btrieve record manager Btrieve Btrieve Technologies, Inc. announced the engine. The Btrieve layer has already been introduction of their DOS and Windows updated for the DOS, Windows, and New Version Supports versions of Scalable SQL. Built upon NetWare client-server environments to Extended Datatypes and DDF proven NetWare SQL technology, the new facilitate the migration of Scalable SQL Manipulation products will fill out the workstation end from NetWare to the other platforms. Nashville, Tennessee — Through an of the company’s relational database Scalable SQL relies on the Btrieve agreement between Smithware, Inc., and product line, bringing the same relational “microkernel” engine to provide record Object Resource Corporation of Dallas, database functionality to laptop and storage and retrieval, concurrent Texas, Smithware will begin shipping desktop machines that users of client/ transaction processing, caching, security, Smithware Class Library for Btrieve in server NetWare SQL have enjoyed. The data integrity, and relational integrity. September. Formerly called ORC Scalable SQL for Windows engine is due According to BTI documents, Component Classes for Btrieve, Smithware for release in mid-August. The DOS and “The Microkernel Database Architecture Class Library for Btrieve Version 3.1 is a NetWare versions are scheduled to follow separates the database model,” the comprehensive C++ object interface library within two months. relational model used by SQL in this case, for Btrieve version 5.x and 6.x. Scalable SQL features include “from the common database functions, The product includes a support for client/server, peer-to-peer, and allowing users to take full advantage of cooperating set of platform-independent single-user database applications. new applications with different data types component classes which encapsulate all Applications will be able to access the while avoiding the expense of a database of the functionality of the Btrieve API in a ANSI SQL / IBM SAA compatible SQL migration.” The primary advantage to this straightforward conceptual manner. The engine through API’s or via ODBC. The architecture is that Btrieve legacy data can class library is compatible with Borland, product supports full transaction be moved incrementally into Scalable Microsoft, and other C/C++ compilers, processing with logging and roll-forward SQL. and may be used as a linkable library or as capabilities, read-after-write verification “Most relational database a DLL. Class design is based upon the and data entry validation, declarative vendors ask customers to re-create their main abstractions that programmers deal referential integrity, dynamic data entire system using the vendor’s tools, and with when writing database applications, encryption and decryption, and standard then one day they cut over to the new files, records, keys, and fields. Developers SQL GRANT and REVOKE syntax for system and pray everything works,” says using the class library may distribute their defining User and Group privileges down Ron Harris, president and CEO of Btrieve applications royalty-free. to the data column level. Technologies. “Our research shows that The Smithware Class Library for Future plans call for Scalable most small to medium companies can’t Btrieve includes support for all Btrieve SQL server support on Windows NT and bear that kind of risk. Scalable SQL is a functionality including extended UNIX, and workstation database engines better answer because customers can add operations, huge record chunk operations, for Windows NT and OS/2. Scalable SQL relational modules where that technology exclusive and concurrent transaction uses what BTI is calling its “Microkernel can have the most impact, and leave the processing, and percentage operations. It Database Architecture,” the foundation of remainder of their applications intact.” ² supports both standard and Smithware extended DDF’s, and handles translation IN THIS ISSUE of all Btrieve key data types and Smithware extended data types. Technical Corner... Btrieve Windows Development... Steve “It’s a very comprehensive and Technologies contributes the latest technical Mook takes an in depth view of the status of Btrieve powerful tool,” said Henry Savage, information about Btrieve and Scalable SQL application development in Windows...... Page 12 Smithware product manager, “for any available...... Page 17 programmer who needs optimum perfor- Just how do Btrieve Benchmarks... mance and who needs a high level of Inside Btrieve... Doug Reilly looks at various versions and platforms of Btrieve compare multi-user application development with Btrieve in speed? We test Btrieve versions 5 and 6...... Page 34 control. The Field and Query classes allow and locks...... Page 9 complete abstraction of the data while Magic PC... Larry Cartee of Magical maintaining performance comparable to Guest Review... Rich Bogard of Custom Programming reviews the most popular direct Btrieve API access. The logical Information Architects demonstrates his database development tool in Europe which just company's Btrieve debugging tool...... Page 25 happens to be based on Btrieve...... Page 9 See Smithware on page 7... BTI Ships New Developer’s Smithware Finishes The SourceBook Kit for Windows and DOS Catalog Puts Complete Btrieve Product OS/2 on Tap for Next Release president for sales and channel marketing Information in each BTI Package for Btrieve Technologies, the new Btrieve Nashville, Tennessee — Smithware, Inc., Austin, Texas — On May 31, 1994, v6.15 client engines have been improved exactly one month after their agreement to the publishers of Btrieve Developer’s over their 5.x counterparts in several Journal, has begun shipping The take control of the Btrieve product line areas. These changes include: improved from networking giant Novell, Btrieve SourceBook catalog of Btrieve and application performance; support for the Scalable SQL add-on products. Beginning Technologies began shipping their new management of very large records over Btrieve Developer’s Kit for Windows August 29th, each product package that 64K; more efficient data integrity and Btrieve Technologies ships will contain a v6.15 and the new Btrieve Client Engine reliability controls; and a more flexible for Windows v6.15. In conjunction with copy of The SourceBook. development environment. “We were very pleased with the this announcement came a new program The Btrieve v6.15 Client Engines for future Btreve distribution and product response that we had with this first edition have the same version 6.x Btrieve file of the catalog,” said Carolyn Lighty, direction. format first developed for the NetWare Since Btrieve was first advertising manager for The SourceBook Btrieve NLM Client Engine. and Btrieve Developer’s Journal. “This introduced in 1982, the Btrieve The new Btrieve Developer’s Kit Developer’s Kit has given the software clearly is the best place for Btrieve for DOS v6.15 and Btrieve Client Engine developers to get complete information developer the right to develop Btrieve- for DOS v6.15 began shipping in late July. based applications and to distribute the about the products and services that are Both the Btrieve Developer’s Kit for available on the market for Btrieve and Btrieve engine (BTRIEVE.EXE for DOS Windows and DOS retail for $595 and and WBTRCALL.DDL for Windows) to Scalable SQL.” both Client Engines retail for $995. Until In addition to being part of the end-users of those applications royalty- September 15, 1994, registered developers free. Many developers have expressed the new BTI product packaging, a copy of the can upgrade to either Developer’s Kit for catalog will be mailed, free of charge, to desire to distribute the Btrieve utilities $295 each and the Client Engine for $300 (BUTIL.EXE for example) and all names on the Btrieve Technologies each. registered users list. For more information documentation about Btrieve setup and Sources at BTI predict the new operation to their end-users along with the on having your product or service Btrieve Developer’s Kit for OS/2 v6.15 included in future editions of The database engine. will be released by late September. With the incresed complexity in ² SourceBook, contact Carolyn Lighty at the Btrieve engines’ design over the years (800) 685-2403 or (201) 712-0044. ² and with the increased popularity of data analysis tools like Microsoft Access, it has become more important that end-users of Microsoft Pledges ODBC Speed Gains Btrieve-based applications have access to utilities and documentation associated Btrieve Access Should Improve with ODBC Desktop Drivers 2.0 with the engines so that problems with Redmond, Washington — With the bugs and offer major increases in speed performance and operation can be solved realese of thier ODBC Desktop Drivers for selected queries. The same Microsoft more quickly and accurately. 2.0, slated to enter beta testing by early officials indicated, however, that speed According to Nancy Woodward, September, Microsoft Corp. plans to increases could not be generalized. Chairman of Btrieve Technologies, “With substantially improve Btrieve database For ODBC processes with the the release of Btrieve v6.15, the Btrieve access by replacing the current query new drivers, access speeds for Btrieve, Client Engines will include all Btrieve processor with the same Jet 2.0 database Paradox, dBase, and other Idexed client engine files, reproducible engine used in their popular Access 2.0 Sequential Access Management (ISAM) documentation covering engine product. databases should be comparable to those installation and operation, applicable The database engine is the part of of Access 2.0, according to Colleen utilities, and a license that will grant the the system that allows OBDC drivers to Lambert, Microsoft’s ODBC product developer the right to copy and distribute access Btrieve data. The Microsoft ODBC manager. the engine files, engine documentation driver pack currently uses the Simba In related news, Microsoft is also and utilities at no additional charge.” query processor licensed from PageAhead striving to improve the ODBC The Btrieve developer’s kits will Software, Inc. of Seattle. The pack has specification so that it will comply with continue to include the Btrieve API’s and been strongly criticized for its poor international SQL standards. ODBC 3.0 developer documentation as well as a five- Btrieve performance and data translation will bring ODBC into line with the SQL user client engine for developent and problems. Access Group’s (SAG) Call Level testing use. According to Microsoft officials, Interface (CLI), which will provide greater According to Lori Baldwin, vice the new ODBC drivers should fix many See Microsoft on page 7...

2 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Btrieve Developer’s Journal ISSN 1071-7463, published quarterly by Smithware, Inc. From the Publisher... Staff Although it has been only a few months since Btrieve Technologies, Inc. Publisher: Scott Smith received control of the Novell database Editor: Steve Mook product line, I have been truly amazed at the Contributors: Richard Bogard, Dale Hunscher, Doug Reilly, Steve Troxell pace at which change has taken place in Contributors to Technical Corner: Austin, Texas. Linda Anderson, Laura Heater, Kirk First of all, on May 31, 1994, merely Humphries, Kyle Humphries, Nancy one month after the Btrieve product transfer Kromar, Mad Poarch, Jose Pruneda, took place, Btrieve Technologies began Carol Rylander shipping the Btrieve Developer’s Kit for Graphic Design: Tania Owen Studio Windows v6.15 and the new Btrieve Client Photographer: Dean Dixon Engine for Windows v6.15. Both Illustrator: Albrecht Dürer corresponding products for DOS shipped in Advertising Manager: Carolyn Lighty Circulation Manager: Cindi Gourley late July. This not only represented a tremendous advance in Btrieve technology, but Subscriptions it also demonstrated how energetic and Annual subscriptions are for four issues per responsive the new company plans to be. year at $49/year for delivery inside the Other changes came with the new United States, and $79/year for delivery product announcement as well. Since the early outside the United States. Photo By Dean Dixon days of Btrieve, developers only had the right Back issues are available Back Issues: SCOTT A. SMITH, PUBLISHER to distribute the engine itself. With the new for $20.00 per issue. Contact Cindi Developer Kit/Client Engine Kit structure, this Gourley at (615) 386-3100 for additional has changed. Btrieve Developer Kits now give developers license to create and test Btrieve-based information. applications, and include a 5-user version of the particular platform’s engine. The Client Engine How to Contact BDJ Kit grants to the developer the right to distribute, with their applications, the platform’s Btrieve You may address news items, new product engine, all utilities, and all documentation, royalty-free. Now all users of distributed applications announcements, tips, advice, comments, based on Btrieve can have all Btrieve tools and documentation at their disposal. This is indeed a complaints, praise, or any other refreshing change of approach from the past. correspondence to: The introduction of Smithware’s The SourceBook of Btrieve and Scalable SQL add-on Btrieve Developer's Journal products has been an exciting sign of change as well. If you have not already received your copy 2416 Hillsboro Road, Suite 201 by now, you will soon. This sister publication of Btrieve Developer’s Journal has 40 pages of Nashville, TN 37212 products and services that are available on the market today. This catalog is actually being placed Telephone: (615) 386-3100 inside all products distributed by Btrieve Technologies. In addition, the introduction of the Facsimile: (615) 386-3135 “Technical Corner” section of this issue’s Btrieve Developer’s Journal is yet one more sign of 73173,2731 CompuServe: how Btrieve Technologies plans to be as responsive as possible to the requirements of their 5905654 MCI Mail: customers. Internet: [email protected] Are you still not convinced that BTI is determined to do everything possible to keep Advertising Btrieve the best database engine available? Well then, how about ODBC? In recent months, when it had become more and more evident that ODBC support for Btrieve data was seriously lacking, For information about advertising your BTI made an active commitment to solve the problem. How? Our sources at BTI have told us that product or service in Btrieve senior engineers from Q+E/INTERSOLV, manufacturers of an OBDC driver for Btrieve, have Developer's Journal, call Carolyn recently been in Austin to take a detailed look at how to improve the current driver. BTI engineers Lighty, Advertising Manager, at (800) have learned how they can make the Btrieve engine work better with the ODBC API, and Q+E/ 685-2403 or (201) 712-0044. INTERSOLV engineers have learned how the ODBC driver can be improved and optimized to work better with existing technology. It is clear, at least, the with the new release of the Q+E/ Copyright 1994 by Smithware, Inc. All rights reserved. INTERSOLV ODBC driver in late September, ODBC access to Btrieve data will be improved. With the exception of the “Technical Corner” secition, Sources at BTI have made it clear, however, that they are keeping all options open when it comes this publication is produced independently of Btrieve Technologies, Inc. to ODBC support, including taking ODBC on as an internal project. No part of this publication may be reproduced in any Although the past few months have been tremendously exciting for the Btrieve form by any means without permission in writing from the publisher. development community, it is clear that the Btrieve and XQL are registered trademarks and best is yet to come! Stay tuned as we cover the NetWare SQL, NetWare Btrieve, and Xtrieve Plus are on-going events surrounding Btrieve and trademarks of Btrieve Technologies, Inc. Smithware is a trademark of Smithware, Inc. All other names are Scalable SQL right here in the pages of Btrieve the trademark of their respective manufacturers. Developer’s Journal.

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 3 The database manager will provide both Liant Gives COBOL Access to ODBC read and write access capabilities. This access is concurrent with all legacy Makes Non-Relational Data Appear Relational to the ODBC App applications. Austin, Texas — Liant Software multiple rows, with each element “In a client/server application Corporation announced the release of represented as a column, or as multiple environment, developers and end-users Relativity for RM/COBOL, an ODBC columns. It gives developers the tools to must be able to access all business interface designed specifically to work make COBOL data look as third-tier information stored throughout the with RM/COBOL-based application data normal as they want.” This representation organization. However, as much as 80 files including Btrieve files. This ODBC serves as the foundation of an efficient percent of this data exists outside of driver uses its own data definition and and flexible ad-hoc query facility, as well relational databases and is managed by conversion algorithms, the goal being to as the basis for integration of legacy traditional COBOL applications,” said manipulate data files in exactly the same application data with new client Bruce Flory, Liant corporate director of way as the underlying COBOL legacy application development. marketing. “Relativity provides the applications, while adding a virtual The database definitions are missing link by enabling developers and relational database layer for ODBC created and maintained by a Windows- end-users to access legacy data directly, access. based database designer. Because thereby leveraging their investments in Bill Mitchell, one of the Relativity imports file descriptions existing legacy systems.” designers responsible for the product, directly from COBOL application Liant plans to introduce a version explained that, “Relativity makes data programs, the database designer can of Relativity for Micro Focus COBOL in which is not relational, maintained by automatically and accurately recover the near future, and support is planned for COBOL applications, look relational at every aspect of the file structure from other COBOL dialects and file systems in the ODBC level. It can select a subset of existing applications. the coming year. For product information records from a file which contains Relativity’s database manager contact Liant Software Corporation, different types of records, and present manipulates data files exactly the same Austin, Texas, 800-RM-COBOL (762- those records as a table. It can define way as COBOL, and supports every data 6265) or (512) 343-1010. ² OCCURS structures as a separate table of type and nuance of the COBOL language.

of business client/server development. For accesses PC databases such as ASCII, INTERSOLV Acquires Q+E, it gives them direct worldwide Btrieve, dBase, Microsoft Access, Q+E Software and distribution to complement their OEM/ Microsoft Excell, and others. VAR channel.” Seagate Technology designs, Seagate Acquires After the Q+E acquisition is manufactures, and markets data storage Crystal Services completed, INTERSOLV will have annual products and components for the Rockville, Maryland — INTERSOLV, revenues over $100 million, with over computer systems and data technology Inc., a leading provider of client/server 325,000 product licenses at more than industries. Steve Luczo, senior vice development tools, today announced the 14,000 customer sites around the world. president at Seagate, explained that, acquisition of Q+E Software of Raleigh, INTERSOLV may be reached at (800) “Crystal fits well with other software North Carolina. Q+E is the leading 777-8858 or (301) 230-3200. companies with whom we are currently in discussions. These companies are focused supplier of database access tools in the Scotts Valley, California — Seagate client/server market. The company’s on providing data management solutions Technology acquired Crystal Computer in client/server environments.” products include Q+E Database Editor, Services, Inc. (also known as Crystal ² Q+E Database Library, Q+E Multilink for Services) of Vancouver, British Colombia. Visual Basic, and the new Q+E ODBC The company was accquired in a stock Btrieve Forum Delayed Pack. These products are used by more transaction valued at approximately $18.6 than 100,000 developers to gain access to million. Crystal Services will continue The new BTRIEVE forum on CompuServe, 30 different databases. operations in Vancouver, and operate as a which was to have been on-line by mid- August 1994, has been delayed. Btrieve “Our business has been growing wholly owned subsidiary. rapidly over the past several years,” said operations and technical support are still Crystal Services manufactures being performed in the Novell forums Richard Holcomb, President of Q+E. the Crystal Reports line of Microsoft “INTERSOLV gives us instant access to NDEVSUP and NDEVINFO until the new Windows-based data access and reporting BTRIEVE forum is activated. According to worldwide markets, multiple distribution tools. Since May of 1992 when the Chris Ojeda, the Sysop from Btrieve channels, and the critical mass required to Crystal Reports product was introduced, Technologies for the new forum, troubling reach our full potential faster.” more than 350,000 units have shipped language in the agreement between According to Tim Harmon, worldwide. Crystal Reports is bundled CompuServe and Btrieve Technologies has program director at META Group, “This with Microsoft Visual Basic Professional caused the delay. Sources at BTI indicate that the agreement should be concluded makes a lot of sense for both companies. Edition, and is to be bundled with Borland For INTERSOLV, this extends their within a few weeks and the forum should International’s dBase for Windows when definately be on-line by early September. market reach beyond centralized IS to line it ships later this year. The product

4 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Solomon Offers Support for Developers “Partners for Integrating Solomon III for Btrieve Change” to be Held Program Provides Assistance to Encourage Development of August 17-20 Interfaced Products Fourth Annual Solomon Findlay, Ohio — Solomon Software, a which assist Solomon Software and its Solutions Conference Co- leading provider of microcomputer distribution channel in offering business Sponsored by BTI and BDJ accounting solutions, has revised its solutions to clients. Findlay, Ohio — Solomon Software independent software developer’s Contact Solomon Software at will hold its fourth annual Solomon program for Solomon III for Btrieve. (800) 879-2767 or (419) 424-0422 to get a Solutions Conference for users of Solomon III is recognized for its free copy of their program brochure. the company’s line of accounting customizability, accounting data integrity, In related news, Solomon also systems. The conference, being held and the intuitive design of its character- has released a new booklet entitled, from August 17-20 in Columbus, based user interface. “Reengineering Your Accounting System Ohio, is to cover “a wide variety of A sixteen-page brochure is to Fit Your Business Operations Today.” technical and business development available from Solomon for independent The booklet is designed to serve as a topics all focusing on the software developers interested in guide to companies with $1 million to unprecedented opportunities being interfacing their products with Solomon $100 million in annual revenues seeking created by new technologies, our III for Btrieve. The Solomon III for assistance in dealing with growth and changing industry, and the changing Btrieve Independent Developers Program change. needs of businesses,” according to is open to any developer of products ² Gary Harpst, president and chairman of Solomon. News Briefs... Hockessin, Delaware — Swfte Btrieve Technologies International, Ltd. has released the president and CEO Ron Harris will present a seminar entitled, Berkshire, England — Tetra has latest version of their MCI Mail “Strategies and Direction” which announced that its Chameleon 2000 management system The Wire 3.0. will provide attendees the Business Software Suite is available The first two versions of this opportunity to learn first-hand about for Novell NetWare. The full system were widely criticized for BTI’s strategy for Btrieve and functionality of the package, their slow and sometimes unreliable Scalable SQL and how the including its 26 modules, has been retrieval of MCI Mail messages. The technology will continue to give enhanced for NetWare including biggest improvement is that version Solomon the edge in the client/ the fact that it uses Btrieve as its file 3.0 now utilizes Btrieve instead of server marketplace. In addition, manager. Paradox. The Wire is much faster and senior engineers and customer Chamelion 2000 is a multi- more dependable. support personnel from BTI will be company package capable of The new version 3.0 costs on hand to present several seminars working in multi-currency format. $99.95 while users of version 2.x can including Inside Btrieve 6.1x, The company claims that the upgrade for $15.00. Contact Swfte at Advanced Btrieve Tuning, and product can accommodate several (800) 237-9383 or (302) 234-1740. Using Btrieve Database Repair companies needs in terms of Tools. The event is being co- accounting, financial management, Surrey, England — Southdown sponsored by Microsoft, Novell, distribution, and manufacturing. House has is now a source of Btrieve Btrieve Technologies, and Btrieve Tetra Limited may be support for the United Kingdom. Developer’s Journal. reached in the UK at 628-770939 Instead of contacting Btrieve ² (Country code from the US is 44). Technologies technical support department in Austin, Btrieve United Kingdom’s “pioneer user” of Nashville, Tennessee — Having developers and users in the United Btrieve over ten years ago. They are outgrown their offices in the Kingdom have the option of calling also skilled in third-party Btrieve Nashville suburb of Madison, Southdown House for assistance. products and data access methods, Smithware, Inc. has relocated into According to Jon Grieve, including Microsoft Access, ODBC, larger quarters. Their new address Btrieve Support Manager, “Dealing Smithware Controls for Btrieve and is 2416 Hillsboro Road, Suite 201, with the five hour time difference has DDF Builder for Windows. Nashville, TN 37212. The new been a problem for many of the Contact Southdown House main phone number is (615) 386- people who use Btrieve here. We can at 0306-877998. 3100 with (615) 386-3135 for provide in-depth, ‘hands-on’ Facsimiles. experience for all aspects of Btrieve.” Southdown House was the

6 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Smithware... Continued from page 1 BTI to Host inheritance hierarchy really simplifies the Microsoft Access and task of using Btrieve.” Visual Basic Tips “The Summit” "Probably the major advantage of Strategic Briefing to be this programming approach is that, ž T he Access/Jet 2.0 Btrieve driver no matter how object oriented it is, the now recognizes 8-byte integer Held October 10-11 in fact that the classes are related through definitions in a DDF as the Microsoft inheritance, that each successive class in Currency data type. Btrieve will sort Austin the hierarchy encapsulates another level of eight-byte integers correctly as key Austin, Texas — Btrieve Technologies, functionality using previously defined segments, but because eight-byte Inc. plans to host a strategic briefing classes, means that adding new classes or integers are not one of the SQL data using existing ones requires very little called “The Summit” in Austin, Texas types, Xtrieve Plus and some other debugging. Especially when compared to programs which create DDF's may on October 10 and 11, 1994. using the C interface to Btrieve," said According to Nancy not allow an 8-byte integer definition. Chuck McWilliam, one of the product's Smithware's DDF Builder for Woodward, BTI Chairman, “The designers. Summit is designed to be a forum for Windows will not allow an 8-byte In addition to the agreement with integer definition, but it does file the the interchange of ideas, strategic Smithware, Object Resource Corporation "Visual Basic Currency" extended information, and future directions. At has also concluded an agreement with data type as an 8-byte integer in The Summit, you will have the AG-Tech Corporation of Nagoya, Japan, FIELD.DDF. opportunity to meet people ‘behind’ to manufacture and Btrieve Technologies, get an inside distribute this class library in the Japanese ž The Access/Jet 2.0 Btrieve driver, track on our products and programs, market. BTRV200.DLL, has been patched to Smithware can be reached at provide input on future development, fix a bug which appeared when (800) 828-7438 or (615) 386-3100. discuss business issues and explore ² accessing Btrieve version 6 files. The initial release version would partnering opportunities.” Microsoft... Continued from page 2 occasionally return the error message The cost to attend The Summit "Unexpected error from external will be $395 per person which will interoperability with other SQL products. database driver [7]" when opening a cover the conference program, materials According to Kyle Geiger, Microsoft’s Btrieve version 6 file. The patched and meals. Attendance to The Summit is ODBC Architect, “It’s not a lot of new version is available on the limited. Contact The Summit hotline at functions, but it’s making the model more CompuServe MSACCESS forum (800) 580-6715 or (512) 892-6715 for consistent with the embedded SQL library as BTR200.EXE, a self- extracting zip file. additional information. ² standard.” Two Great Btrieve Books! The Illustrated Guide to Btrieve The Illustrated Guide to Btrieve for 5.x Users... for 6.x Users... Introduction to Btrieve version 5.x Upgrading to NetWare Btrieve version 6.x Tools for Btrieve Programming NetWare Btrieve version 6.x Features Interfacing with Btrieve for DOS, Windows, OS/2 Continuous Operations and Version Control Basic and advanced file access techniques Indexing, Integrity Processing, Caching Btrieve Operation Codes Transaction Processing, Chuncking, Record Btrieve Extended Key Types Grouping Source code for COBOL, BASIC, Turbo Pascal, C Multi-user Programming, Writing Btrieve NLM’s Operation code Quick Reference Table Flow of Control, NetWare SQL

The Illustrated Guide to Btrieve 5.x...... $29.95 The Illustrated Guide to Btrieve 6.x...... $39.95 Btrieve 5.x Tutorial Diskette...... $19.95 Btrieve 6.x Utility Diskette...... $24.95 (Include $5.00 Shipping/Handling per book, $2.00 for each additional book)

To order by phone, call (404) 565-4684 ˜ Major Credit Cards Accepted ˜ or, send Check or Money Order to: MIDI America, Inc. 896 Fairfield Drive N.E. Marietta, GA 30068 (404) 565-4684

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 7 Enough history, I want to tell you about the product. Simply put Magic Software allows an application developer to concentrate on “what” instead of “how.” The entire process is so elegantly simple it is difficult sometime for experienced Hands-On Review programmers to change their way of thinking. Those of us Handicapping Magic Software who use this product call it “Thinking Magic.” The data file definitions, the program definitions, the report definitions, By Larry Cartee, Magical Custom Programming and the application data itself are all laid out in a set of related tables. So the programmer’s job is really just a matter This is not an unbiased review. This is a true life of defining those tables. story of how a person with absolutely no computer The first step in any data base application is programming training or experience has been able to develop designing the file structure for storing the data. What and sell vertical market and custom applications using Magic information do I want to keep? With Magic Software, a Software and Btrieve. I make my living writing applications developer builds table called a data dictionary that defines with Magic Software. These include complete business what information he wants stored in what format (string, date, packages including inventory control, general ledger integer, etc.). Magic supports a variety of different data types accounting, accounts receivable, accounts payable, invoicing if you need to share data with other applications. If it is a and sales orders, retail point-of-sale, job cost, and payroll stand-alone application the developer does not need to know plus a variety of custom applications. anything about data storage, just accept the defaults when “Create applications without writing code.” That’s defining then record structure. The developer then picks what the advertisement said when I first read about Magic which fields are to be maintained as Btrieve indexes or keys. Software (then known as Magic PC) in 1987. I don’t even remember what magazine I was reading when I first saw that ad, but it sure caught my attention. At the time I had just started to work selling a vertical market package for golf professionals at a small software company. I knew nothing at all about personal computers or the personal computer industry. I had been hired because I could sell, and because I did know something about the golf industry. I had no idea how application software was developed or programmed. I quickly learned that as I called on prospects, they asked for features or changes to the product I was selling. However, changes and customization were very expensive. Therefore the Magic PC ad that went on to talk about how fast custom applications and changes could be done certainly got my attention. The people at the company where I worked just laughed when I showed them the ad. They said it must be a gimmick and it can’t work for commercial applications. The ad did not mention Btrieve. I ordered the software package anyway, despite the FIELD D EFINITION S CREEN FOR M AGIC S OFTWARE professionals opinions that it could not possibly work as advertised. The price was $199.00. Since then, I’ve learned Magic Software says there are two kinds of that Magic PC was just being introduced at that time in the programs, those with user interaction, called “on-line” by United States. The product was developed and written in Magic, and those that do not require user interaction, called Israel and is today a leading data base development tool in “batch.” Sure makes sense to me. Magic further defines on- Europe and other parts of the world. Yet it remains a rather line programs to be either screen mode or line mode. Screen obscure product in the United States. It is the best $199.00 I mode means that one record takes up the entire screen and have ever spent. Of course there have been updates and my therefore the user can only see one record at a time. Line total investment in Magic Software is much greater than mode means the Magic programmer defines a row or rows $199.00. I believe the current price to develop multi-user across the screen that will hold a single record. In line mode applications is around $1500.00. the user can see more than one record on the screen even After receiving the product I took it to the office to though only one record at a time is the active record. With show the programmers. When they saw Btrieve mentioned it this method you can create an editable, scrollable grid in a got a little of their attention. I had not known it, but the matter of seconds. Yes, I said seconds. With either mode the software I was selling was written in Microsoft Quick Basic process is the same except for screen design. The developer using the Btrieve record manager. Even though they simply completes a table, choosing the fields from the expressed some curiosity, there was no interest in looking predefined data dictionary that he wishes to participate in the closely at the product to see if it could be used to speed up user inter-active program. The screen design then places the adding features or customization of the product I was selling. fields on the screen for the user to edit. That is why I decided to learn to use the product myself. See Magic on page 11...

8 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Those areas where a problem might exist normally have to do with one or another of the flavors of Btrieve completely enforcing a documented restriction where other Inside Btrieve versions do not. For instance, in recent versions of Sharing and Working Together: BREQUEST.EXE (6.10d and later), it has been critical that the length parameter passed on a call to the Multi-User Btrieve GET_VERSION operation be properly set. In previous By Douglas J. Reilly, Access Microsystems requester versions and in BTRIEVE.EXE 5.10a, this appears not to have been required. One of the things that attracted people to PCs, Using Btrieve, you can implement two distinct especially in the early years, was that unlike the models to ensure that changes take place properly when minicomputer and mainframe world, PCs made you the multiple users are accessing the same record in a file. The captain of your own ship. You could expect that the entire first (and easiest to support) is called “passive universe that was your computer was completely under concurrency.” “Passive,” because there is no explicit your control. This led to some habits that can make the locking of records to ensure that updates by multiple users transition to the networked PC difficult. The focus of this do not step on each other. column is: what can we do with Btrieve based applications Imagine this scenario: User A gets Doug Reilly’s to make them multi-user friendly? employee record to edit. User B also gets Doug Reilly’s The first question is: What software and equipment employee record to edit. In many systems, the rule would do you need to share Btrieve files among several users? be “He (or She) who saves last, saves best.” For example, Since Btrieve 5.10, the only version of DOS User B changes the first name to “Douglas” and saves the BTRIEVE.EXE or Windows local Btrieve has been multi- record. User A changes the date for the next salary review, user (what had previously been called Btrieve/N). If you but does not touch the first name field, and then saves the have an older version of Btrieve, make sure that it reports record after User B had saved changes to the record. In many systems, where no allowance for locking the records has taken place, the name will revert back to “Doug” and the change to the salary review will be saved. Using Btrieve for the exact same scenario, User B will save the record properly, but User A will get a status 80 (Conflict) when the update is attempted. This can be used to let User A know that the changes made were not saved, since the record had changed between the time the record was originally read and the time that the update was attempted. This is why it is always a good idea to check the status code returned for any operation, even those you “know” can’t fail. Passive concurrency can be appropriate for some situations. For example, some systems have a natural key that makes such conflicts unlikely to occur. In a computerized employment selection testing system, the social security number is used to identify applicants. Since an applicant can only reasonably be expected to be using

PROPER U SE OF B TRIEVE R ECORD L OCKING WILL K EEP Y OUR one workstation at a time, locking the applicant record WORKGROUPS H APPY during a test session is not likely to be needed. Another case where passive concurrency might be adequate is that it is Btrieve/N upon start-up. If not, you must upgrade where records are quite small. The only real downside to before creating multi-user applications. Btrieve supports passive concurrency (assuming that status codes are always any network that conforms to the DOS 3.1 Network checked) is that a lot of work might be wasted each time a conventions, with special support for NetWare networks using BREQUEST.EXE on the workstation and Doug Reilly is the owner of Access Microsystems Inc., a software BTRIEVE.NLM on the server in place of BTRIEVE.EXE development house specializing in C/C++ software development, often using Btrieve as a file manager. He has had articles on Btrieve published in on the workstation. From the programmer’s standpoint, DR Dobbs Journal and is also the author of BTFILER and BTVIEWER there is little difference between an application running Btrieve file utilities available on CompuServe. Doug’s CompuServe address using BTRIEVE.EXE and an application running on is 74040,607 and can be contacted at 404 Midstreams Road, Brick, NJ 08724 or at (908) 892-2683. NetWare and using BREQUEST.EXE and the NLM.

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 9 user goes to save a record only to find someone else has WAIT lock. If this were not the case, a single locked changed the record in the meantime. If a record (or the application could hold up all applications multitasking on part of the record being edited) is small (say, one or two the Windows PC. An exception to the WAIT lock not fields), it might be reasonable to simply have the user returning control to your application exists in the server getting the conflict error reenter the changes. Other based environment (using BREQUEST.EXE and examples of where passive concurrency is not appropriate BTRIEVE.NLM in NetWare), if the server detects a is when there is an automated batch process using the deadlock, that is, a request that cannot be fulfilled because records. each of two or more applications are waiting for resources Resolving the conflict error might require human being locked by one of the other applications. In this case, intervention. Another concern when using BTRIEVE.EXE a status 78 (Deadlock Detected) is returned. version 5.x is that the conflict support is limited to the page A reasonable alternative to the WAIT lock is using level. Btrieve organizes data in “pages” that are blocks of the NO WAIT lock and retrying the operation. In many a Btrieve file between 512 bytes and 4096 bytes and evenly cases, the record will become available by itself (a user divisible by 512 (for details, see my article on Btrieve will save and exit, a batch process only holds the lock Pages, in BDJ Vol. I Number 1). A usage counter is temporarily), and for other cases, displaying a message to recorded for each record read that is specific to the page. If the user indicating that the record is locked will allow the another record on the page is updated, the page usage user to determine who is using the record. Allowing the counter changes, causing the next update on any record on user to abandon retries is also a good idea, since sometimes the page where the record was read with the old usage it is just easier to try the operation again later. A useful count to return a status 81. For instance, if two records are feature, not implemented as part of the Btrieve API, and located on a page, and both are read, after one of the not easy to do outside the Btrieve API, would be an records are saved, any attempt to save the second record indication of what user has a lock on the record. Using the will result in a conflict error. In Btrieve 6.x (all versions) server based Btrieve, the only way to determine who has the conflict checking is done on the record level. the lock is to use BCONSOLE (or BTRMON in 6.x). Thankfully, there is another way to ensure multiple Using BTRIEVE.EXE on another network, you must use users have clean access to records in the file. Btrieve whatever monitoring utility the network provides to see provides several lock “bias” codes. By a “bias,” I mean a who is holding the lock. code that gets added to other codes (for instance, The other decision to make when locking records is GET_FIRST or GET_EQUAL) to allow explicit locking to the MULTIPLE LOCKS vs. SINGLE LOCKS. If one of take place. To perform a “single record, no wait lock” on a the SINGLE LOCK biases are used, only a single record at record you wish to get using GET_EQUAL (operation code a time can be locked. If the single record being locked is 5), you would use an operation code of 205 (5 for the deleted or updated, or another single record lock is GET_EQUAL and +200 for the SINGLE RECORD/NO requested, the lock is released. You can also use the WAIT bias). A record that is “locked” by one workstation UNLOCK operation (operation code 27) to explicitly can be read by another. The lock simple disallows any release the single record lock. The advantage to this type other workstation from getting its own lock on the record. of lock is convenience. You do not need to track which There are two variables that are taken into account when record you are locking, since you can unlock it without choosing which of the lock bias codes to use: WAIT vs. knowing anything about the record currently locked with NO WAIT and MULTIPLE LOCKS vs. SINGLE LOCKS. the single record lock. In fact, this single lock can be used We will handle the easiest choice first: WAIT vs. NO even in cases where many records need to be controlled. WAIT. For instance, imagine a purchase order system that contains A WAIT lock, much like you would expect, waits a PO Header file, and a PO Line file. The PO Line records if the call to get a record finds that the record is locked by are related to the PO Header. If you have total control of another workstation. The NO WAIT lock immediately the applications that will use this system, you can, by returns a status 84 (Record Locked) or 85 (File Locked). agreement, state that any access to any of the PO Line While the WAIT lock might seem easier to implement (if records will require that you first obtain a lock on the PO you assume your application MUST have a particular Header associated with the PO Line. By using a single record to continue), but there are several problems. First, if lock, you can ensure that no two processes are updating the you use a WAIT lock and the record is not available, same PO. When the PO is no longer being operated on, control is not returned to your application until it is simply unlock the PO Header (or if an update to the PO available, which could be the next day, if Fred in Header is done as part of normal processing, do nothing accounting left a record sitting on his screen when he went further) and you can be sure your applications will not try home last night. A second potentially bigger problem is and step on each other's updates. that in Windows, the WAIT lock is not supported. Using a The MULTIPLE LOCK biases are used when you WAIT lock gives you exactly the same result as a NO need to lock multiple records in the same file at the same

10 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 time. The only complication to this is that if you wish Continued from page 8 to unlock only some of the records at a particular time, Magic... you need to have the four-byte position information All editing functions are pre-defined. That is TAB returned by the GET_POSITION operation (operation moves to the next field, SHIFT TAB moves to the previous code 22), for each record to be unlocked. This can be a field, PAGE DOWN moves the display to the next record, bit of an annoyance in practice. Another complication is PAGE UP moves to the previous record using the Btrieve that, if you use MULTIPLE LOCKS on a file, you index path defined for this particular program. However, cannot have SINGLE LOCKS on the same file at the Magic includes a complete keyboard re-mapping function that allows the developer to substitute any keystroke he wants same time. Attempting to do so will result in a status 93 for a particular action. For example, the ENTER key can be (Incompatible Lock Type). mapped to go to the next field. You must be aware of several parameters that may have to be adjusted when locking is added to an application. Using BTRIEVE.NLM, the maximum number of locks is specified on the server. Using BTRIEVE.EXE, the /L:n parameter specifies the number of MULTIPLE LOCKS that can be active simultaneously at a workstation (20 is the default). Transactions in Btrieve version 6.x can be concurrent transactions rather than exclusive transactions. That is, the entire file is not locked on concurrent transactions. One thing to look out for with concurrent transactions is that when a record is modified during a concurrent transaction, the page that contains the data, and any pages that contain key values for the modified records, will be locked until the transaction is ended or aborted. An issue that is specific to peer-to peer networks and using Btrieve as a multi-user file manager has MAGIC D EVELOPMENT I NVOLVES C REATING A G RID SELECTING T HIRTEEN O PERATIONS caused a great deal of confusion. Unlike Netware, and Batch programs loop through a data file in a other server based networks that provide emulation of programmer-defined sequence. The sequence can be an existing the features of SHARE.EXE, peer to peer networks rely index, or by using a Magic Software sort function, Magic will upon SHARE.EXE to provide information on locked build a Btrieve temporary key for this program. This sort files and records. For instance, load Artisoft’s process takes some time depending on how many records there LANtastic without SHARE.EXE loaded anywhere, and are in the file, just as it takes time to build a new index on an workstations will get no feedback when a file is locked, existing Btrieve file using conventional programming. Magic leading to (at best) updates that do not take place allows the developer to execute additional tasks: one time before correctly. (Note that LANtastic 6.0 has a SHARE.EXE and after the program begins, before and after each record is replacement integrated into the server software, so this read, and before and after defined groups of records are read. Just as in user interactive programs, the developer chooses the scenario cannot occur with 6.0). On the other hand, fields to participate in the program, he just does not do the load SHARE on both workstations and on the server, screen design. These types of programs can do batch processing, and much the same results will occur: file corruption, print reports, etc. and no status return codes to let you know about locked This is just a brief overview of how this developer’s records. The option is to use SHARE.EXE on the server tool works. It allows the developer to quickly and easily design and to NOT load SHARE anywhere else. This can be a the front end portion of data base applications, and it uses the problem, if not all files are located on a single peer Btrieve record manager and the Magic runtime engine to acting as a server, or if other applications on the perform all the back end processing while isolating the workstations require SHARE.EXE to be loaded. developer from the complicated calls to Btrieve. The entire One last hint for testing network functions when process has only thirteen commands. There is no programming required. More importantly, the only limits to what the product you do not have access to a network. Open two can do are Btrieve limits because Btrieve does all the work of instances of the program you are testing (this works in storing and retrieving data. Magic Software offers products that most cases for DOS Btrieve applications as well). If work exactly the same but use other database record managers you are not on a network, but you do have SHARE.EXE for the back end processing such as dBase, Clipper, Paradox, loaded (or possibly VSHARE.386 that is included in AS400, InformixSQL, C-ISAM, Microsoft SQL, and others. I Windows for Workgroups 3.11), you should be able to have not seen or used these versions of Magic Software and can test for network compatibility. ² not comment on them. ² (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 11 programmers are familiar with. Developers that are moving to Visual Basic from DOS Basic need to be aware of a few changes. The function you’re calling Feature Article is a C function, so you need to be aware of the way Btrieve Windows Development in which DLL functions are declared and data types are passed to functions in Visual Basic. By Steven A. Mook, Smithware, Inc. The advantage to using this approach to Btrieve are performance and familiarity. The disadvantages are familiar also. Anyone who has Windows Btrieve Access developed Btrieve applications in DOS can tell you that getting all your ducks in a row for a call to the Back when DOS was still pronounced dee-oh- API is tedious work, and the resulting code is neither ess and 512K of RAM was considered to be more particularly concise nor particularly readable. than anyone could ever use, developers worked What’s more, the Windows environment is not at all pretty much strictly with the timber, bricks, and forgiving if you inadvertently overlook a parameter. mortar of the trade - third-generation programming Most of us, who have worked in DOS for any length languages, a few commercial libraries, and a of time, developed or bought some sort of a Btrieve wonderful indexed filing system called Btrieve. The library to encapsulate the interface, handle errors in challenge for most of us then was office a standard way, reduce the number of lines of code construction. Building neat, isolated systems which we had to write and maintain, and hide the specialized in doing one thing well. Keeping the complexity of that cumbersome API call. For those mailing list up to date. Managing the books. of you who want a similar structured approach to Processing orders or tracking phone calls. your database in Windows, there are several Well, DOS has become an acronym, because possibilities. nobody has time to spell it out anymore. And with It’s also important to understand, when the capabilities of networked systems and of considering these options, what Btrieve is and is not. Windows, both DOS and the notion of third- Btrieve is lowest level interface in Btrieve generation languages are fast becoming Technologies’ Microkernel Database Architecture. It anachronisms. Developers now face the challenge of is the direct navigational interface to the microkernel bridge building — both between applications and, indexed record manager. This means that the more importantly, between users and the information application layer has the direct responsibility for stored as data by those applications. “navigating” through the database, and interpreting Choosing the appropriate tools for a the data returned. Btrieve is not a database, since it particular job can be a job in itself. Developers is not responsible for imposing a structure on the considering writing a Btrieve database application data, nor is it aware of the structure imposed. I’ve for Windows, or porting an existing application to fielded several questions from people who wanted to the Windows environment, face a bewildering convert data they had “from Btrieve format” to number of options. This article attempts to sort something else, with the response that there is no through the clutter on the workbench and give you a such thing as “Btrieve format” data. Btrieve data is broad-brush overview of the available Windows/ application format data. Btrieve merely does with it Btrieve options. what it’s told to do. Most of the higher level options for Btrieve access in Windows require that the Btrieve data be defined in DDF files, which are the Windows Programming Languages definition files used by Xtrieve, XQL, and the Scalable SQL products, the relational model First, it’s important to understand that any interface to the microkernel database engine. Windows programming language capable of calling a VBX controls and class libraries which dynamic link library function can interface to Btrieve provide a “native” interface to Btrieve are available in exactly the same way that programming languages commercially from Smithware and from Classic did in DOS. The Btrieve API in windows is Software. These tools can significantly cut the implemented as a dynamic link library. That means amount of effort required to write applications which that Microsoft Visual Basic, Visual C/C++, Borland access Btrieve files, but because they are designed to C++, and many other programming languages can work exclusively with Btrieve, and to use all of the declare and call the BTRV API function. The C API features of the API, they do not significantly curtail is essentially identical to the one that DOS a developer’s creativity, and the resulting program

12 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 performance is comparable to the performance of types such as arrays or variant values are not programs which call the API directly. supported. Tables are related by keys, such that the Microsoft Visual Basic also shares a common only complex collection of data in a relational driver with Microsoft Access, which has been database is the relation itself. The term “normal” or incorporated as part of the language. Referred to as “normalized” is often used to describe this model for the Jet engine or Data Access engine, this driver will data storage. If one considers a table to be support a number of different database back-ends, synonymous with a Btrieve file, then in this model, one of which is Btrieve. For programmers working in each record in the Btrieve file could be represented Visual Basic, the advantage to using the Jet engine is as a row of data, and each row would be uniquely immediate compatibility with a wide range of “bound identified by a primary key. The Btrieve file would controls” available from different tool vendors. contain a fixed number of fields. Each field in the These tools respond to system messages from the file would represent an atomic data value, and these Visual Basic Data control, making programming a values would be consistent across all records in the database application an almost trivial exercise. The file. These field values would comprise the columns average third grader could write a spectacular Visual of the table. Relationships would be established by Basic database application in less time than it takes links to other files via a primary key in one file, and most C\C++ programs to compile. There is, of a foreign key in the related file. course, a trade involved. In the case of the Access The relational model formed the basis for the engine, the most depressing is its unbearably slow development of SQL, or Structured Query Language. performance when accessing Btrieve files of any The relational model is actually a data storage size. Of course, like any generic database front-end, model, whereas SQL is a language for defining, the Access engine requires a data definition in order storing, and accessing data. Btrieve Technologies has to access Btrieve data, and like most other generic a line of SQL database products called Scalable SQL, database front-ends, it relies on DDF files to provide formerly NetWare SQL, which use the microkernel that definition. For this reason, it is not an option for database engine to provide low-level data some Btrieve data, as the rules which dictate file management services. structure in Xtrieve, XQL, and Scalable SQL are not enforced by the Btrieve API, and it is possible to use the API to create perfectly legitimate application data structures which one simply could not create using one of the SQL products.

The Relational Database Model

Many of you probably didn’t know we’d been programming in the navigational model all this time. I didn’t find out myself until last Tuesday. So I thought a little background on the relational model might be helpful before we begin the discussion of one of the more powerful tools in the Windows development set, ODBC. The relational model for database management traces its history to a scholarly paper presented in 1970 by Dr. Edgar F. Codd, then a researcher at the IBM Research Laboratory in San Jose, California. The model enforces a rectangular matrix representation of data, consisting of tables, rows, and columns. A relational database is a collection of tables, which are simple, two- dimensional structures analogous to common spreadsheet representations. Records are represented by rows, fields by columns. All data elements in a relational database must be atomic. Complex data

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 13 Btrieve data access using ODBC for nearly ten years, and has been involved with ODBC for about a year and a half. He has built a portable C++ class library for ODBC, odbc/ClassLib, Microsoft used SQL as the basis for its Open which was released commercially in April. His Database Connectivity specification, known as company also developed Btrvgen++, the class library ODBC. This specification details a common set of code generator for Btrieve licensed on an OEM basis API’s, and provides compatibility standards for to Classic Software. When I asked him for his device drivers, implemented as dynamic link assessment of the currently available Btrieve ODBC libraries, which link the API’s with different drivers, his review was not favorable. database engines. In theory, at least, the ODBC “Both currently available drivers for Btrieve driver layer would allow a common SQL interface to are a disservice to the Btrieve developer community both relational and non-relational databases. Two and to the ODBC movement as well.” He said, “They vendors currently provide ODBC drivers for Btrieve, leave two false impressions in the mind of anyone Microsoft and Q+E/INTERSOLV, and Q+E also who uses them: first, they give developers provides an ODBC driver for Scalable SQL. unaccustomed to Btrieve the feeling that Btrieve is Since ODBC provides a common API, with slow. Second, they give long-time Btrieve developers installable drivers for many different databases, this unaccustomed to ODBC the impression that ODBC is standard was quickly adopted by end-user database slow. Now, anyone used to using Btrieve to get front ends, fifth-generation Windows application things done knows Btrieve is not inherently slow. development languages, decision support software, And anyone who has used a top-quality ODBC and report writers. This exciting development has driver, such as the Watcom SQL driver, knows that sparked something of a revolution. This revolution ODBC is not inherently slow. It’s the quality of the has taken place to an extent within the developer drivers that is the problem, not Btrieve or ODBC. As community, where a common API to access any a developer and consultant with a foot in both worlds database immediately makes code more portable and and a long-term proponent of Btrieve, it is painful to easier to maintain. But a much more important see Watcom SQL outperform Btrieve in the ODBC revolution is taking place among end-users, who now arena, knowing that Btrieve is inherently faster.” enjoy an unprecedented level of access to application Dale went on to say that he had spoken with data, and an ever-increasing variety of tools for BTI product manager, Carol Rylander, and chief accessing, maintaining, analyzing, and presenting technology officer, Doug Woodward at length about that data. ODBC, and that he was convinced that Btrieve There are currently two primary Technologies was aware of the problems and disadvantages to using ODBC tools to access Btrieve working to find the best solution. “I think you will files. Because it is a standardized API, it completely see some action in the short term, but building a dictates the ways in which applications which use world-class ODBC driver is a non-trivial effort,” he that API can access their data. The particular said. features of any given database must fall within the Sources at BTI and at Q+E/INTERSOLV scope of the ODBC specification in order for those confirmed that senior engineers from Q+E had been features to be useful to ODBC-compliant programs. to Austin in July, working jointly with Btrieve In saying this, I do not mean to detract from the Technologies engineers to improve the interaction advantages of the ODBC philosophy, which are, in between Btrieve and the Q+E driver. The new ODBC my opinion, quite compelling. The second driver update, scheduled for a September release, disadvantage to using ODBC tools for Btrieve access will include improvements worked out in the is that, given the level of optimization of the current meetings. commercially available ODBC drivers, you’re better Our evaluation of the Microsoft ODBC driver off with a shoe box and a set of index cards. You’ll indicated that it turned in similar performance when spend a lot of time at the water cooler if you try to working with Btrieve files and with comma- use them with even moderately large files, and hell delimited text files, for the simple reason that no will freeze over before a query on a 4 million record optimization was performed at all. The driver simply table comes back. read all of the records in a file, and returned those which matched the search criteria of a query. Expert Advice Microsoft is working on a new set of drivers which will use the Access/Visual Basic Jet 2.0 engine as its Dale Hunscher, president and CEO of South query processor. The Jet 2.0 engine appears to have a Wind Design, Inc., has been working with Btrieve limited capacity for optimizing queries to Btrieve

14 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 files using Btrieve indexes, so this step should provide a considerable performance gain. Even with improvements in ODBC drivers, Hitting the Books however, ODBC is not necessarily the tool for every job. As Dale Hunscher told me, “The true beauty of C. J. Date: A Guide to the SQL Standard (Addison- Btrieve is its model independence, and that means its Wesley Publishing Company, 1987) capacity to handle things like variable record types, overlapping fields, and so on. Because ODBC is E. F. Codd: The Relational Model for Database based on the relational database model, it excludes Management: Version II (Addison-Wesley these constructs axiomatically, because relational Publishing Company, 1990) algebra does not tolerate such ambiguities.” “This kind of constraint chafes Btrieve J. Harvey Trimble, Jr. and David Chappel: A Visual addicts even within NetWare SQL,” Dale added, Introduction to SQL (John Wiley and Sons, 1989) “which is undoubtedly the best SQL database for Btrieve access at the present time. These limitations Harry Katzan, Jr: Computer Data Management and are already built into DDF, and even if DDF evolves Database Technology (Van Nostrand Reinhold, as it inevitably will, the limitations can’t be 1975) abandoned totally without violating the relational model, which for better or worse is the R. G. G. Cattel: Object Database Standard: ODMG interoperability standard for DBMS in the - 93 (Morgan Kaufmann, 1994) foreseeable future.” Colleen Lambert: “ODBC: Architecture, Perfomance, and Tuning” (Microsoft, 1994) Conclusion Richard Schwartz: “Writing Interoperable The basic premise behind good database Applications With ODBC” (Microsoft, 1993) programming has always been to provide users with information. In the past, this often meant a costly choice between developing information systems completely from scratch, or modifying existing applications every time a new procedure or report was required. Today, there are more options for plug-and-play programming than I could even name in four pages of very small print, not to mention the options now available to end-users for customizing reports and processes. Btrieve developers, just like everybody else, today face a market-driven imperative. Provide customers with independent access to their information, or loose customers. This is an especially difficult problem for Btrieve developers, given the quality of the current crop of available ODBC drivers. With an estimated 5 million customers maintaining important business data in Btrieve files, it’s a sure bet that the ODBC driver situation will improve. In the interim, developers should certainly consider interoperability issues when creating new applications or revisions. Since the relational model is, for better or worse, the interoperability standard for the foreseeable future, it’s a good one to consider at present. Whether that means moving to an RDBMS like Scalable SQL, or simply making sure that your application data is normalized and supplying your customers with DDF definitions, it’s important to bear in mind that you don’t need an ODBC driver to create an open database.

STORED PROCEDURES,REPLICATION ,ARRAY KEYS, NT SUPPORT, ODBC DRIVER. AMEN.

16 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 BTRIEVE TECHNOLOGIES TECHNICAL CORNER

JULY-SEPTEMBER, 1994 SUPPLEMENT TO BTRIEVE DEVELOPER'S JOURNAL MAD'S COLUMN TECHNICAL Q&A Hello, and welcome to the first issue Microkernel Database included a tremendous overhaul of Btrieve Technologies Technical of the product — we converted Corner! Architecture from 16-bit to 32-bit, we converted from assembly So much has happened since the last language to C, and so on. In What is “Data Model- issue of Bullets that it’s hard to know Q conjunction with that, we also re- Independence,” and why is it where to begin. I am pleased to be a architected Btrieve so that the important to BTI? part of this new regular supplement model-independent database to Btrieve Developer’s Journal, which Our strategy to position will continue to provide you with the A functions became a separate technical support and information ourselves as a premier database microkernel database engine, you used to get in Bullets. Working in engine supplier hinges on our independent from the full Btrieve conjunction with the staff of BDJ, we ability to create a database product itself. will present in these pages timely engine that is independent of a and thorough technical material specific database model. about Btrieve Technologies’ database Q What is the function of your Microkernel Database Engine? products. Over time, various data models have gone in and out of vogue as The microkernel database In this issue we’re introducing our A new Microkernel Database the “best” solution. The engine is the technology which Architecture. See the Technical Q&A Relational Model is certainly the handles database functions section and the section on Scalable most predominant data model common to the database SQL for details on how this used today. But earlier, people implementation of any data architecture will provide a powerful, depended on Hierarchical and model. The engine handles platform-independent base for Network Models, and many concurrent transaction developing a variety of data models, people today are talking about processing, advanced caching for including Scalable SQL. Object-Oriented models for the higher performance, and data future. security requirements such as A lot has changed here in the past few months, but one thing hasn’t. automatic recovery after a system We’re still committed to keeping you While we were a part of Novell, failure, logging and roll-forward, informed, and listening to your we began redesigning our and referential integrity. These feedback. How are we doing? You can technology in parallel with the are functions that are common to fax me your comments at (512) 794- Btrieve 6 project. We realized that different database models, and 1778 , or reach me by phone at (512) we had the opportunity to create need to be managed at the core 794-1501. an engine for database level so that all access to the functionality that would be database in regard to these Happy Programming! independent of those models, functions is coordinated. and could underlie an Mad Poarch How do you implement implementation for any database Q Vice President, Customer Service different Data Models? Btrieve Technologies, Inc. model. This would not only position us to provide the best A The data model-specific full-featured engines for the “modules” are implemented IN THIS ISSUE industry, but would also give us above our microkernel. In this the flexibility to move with the architecture, Btrieve is positioned Technical Q&A...... 17 industry as customer as the "Navigational Model” — requirements changed. that piece, in conjunction with Product Focus: Scalable SQL...... 19 our microkernel database engine So we began the process of re- is what comprises our Btrieve Technical Insights...... 22 architecting Btrieve v6, which database product today. Btrieve

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 17 provides a navigational access method for their microkernel from one platform to application programming requirements but still access a another, it is very easy to bring interface (API), designed common database engine. across a diverse set of modules specifically for programmers to support the different data using third- and fourth- It also provides a strong models. generation programming migration strategy for customers languages. The Btrieve API who feel the need to move from Some of our desire to re-architect provides the maximum amount of one data model to another. Now, this technology came about as a programmatic control from an they can leave their existing result of our experience with application over the database. applications in place and begin to NetWare SQL — a relational incorporate applications with engine that we had been shipping The "Scalable SQL Relational new data models that can operate for some time before we Model” is another simultaneously with their underwent this effort. That implementation of a different previous applications. This lets experience gave us a good idea of data model. Scalable SQL is a full- the user leverage the strength of what we needed in a model- featured implementation of the the model — whatever makes the independent engine which could Relational database model using most sense for their application support a model-specific module Structured Query Language (SQL), or situation. such as the Scalable SQL product. and uses the core database for How does this microkernel the common functions that are The technology is also designed Q architecture impact Scalable SQL? implemented in the microkernel. to support an open development More database models will platform — that’s been our A This microkernel design is the continue to emerge in the history here, first at SoftCraft, cornerstone of our technology industry. We can’t necessarily then Novell, and now Btrieve strategy. With this architecture, predict today what will come Technologies. We’ve always had we can move more efficiently and next, but this architecture leaves close ties to the developer more productively in the us well positioned to implement community and provide a very directions that our target market those new models. well-established, compatible set will demand of us. As a supplier of development APIs. This to the middle market, we have a The type of logic that is managed architecture is designed to demand for our products on by those “data model-specific support a variety of APIs. Btrieve additional platforms beyond modules” is specific to their represents a record-level NetWare, so we have recently database model. For example, in navigational API. Scalable SQL announced the Scalable SQL the case of the Relational Model, supports the standard SQL API, as relational database engines for the data definition techniques well as ODBC through the drivers DOS and Windows workstations, that define the database schema provided by Q+E and others. And both of which are based upon our are specific to the relational as time goes on, additional APIs microkernel foundation. We will database model and are could be implemented via other proceed to make Scalable SQL implemented through Structured models. This architecture lets us available in new environments Query Language. A “join” is also a take our proven database such as NetWare as a NetWare specific relational database technology and use it as a Loadable Module (NLM) within the function, implemented as a foundation to quickly next sixty days. WHERE clause in a SQL statement. accommodate new models as Does this “layered” approach requirements in the marketplace Q What are the benefits of a of Scalable SQL over a Q change. microkernel database microkernel engine add overhead architecture for the user? Q What are the benefits of a or decrease functionality? microkernel database It means you can have Of course, a “layer” of any A architecture for BTI? A multiple access methods kind adds some measure of concurrently sharing the same A This type of architecture lets “overhead.” All major RDBMS database. The microkernel us move quickly to support new vendors have within their database engine will ensure that data models, making us more products some concept of a any integrity constraints required competitive in the marketplace. It kernel-based architecture, where or security constraints enforced also makes our porting between the kernel manages physical data by one model cannot be violated new platforms more efficient, and isolates platform by another. This allows various since most of the platform- dependencies. So, all RDBMSs will data models to coexist specific logic is going to be in the spend some clock cycles simultaneously and access microkernel and not in the translating from a logical schema common data. Now, multiple model-specific modules. accessed via a highly abstracted applications can choose the best Therefore, as we port the language like SQL to an ISAM or

18 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 other navigational method of BTI microkernel is the industry- model — concurrent transaction accessing the physical data. The standard Btrieve API. Btrieve processing, advanced caching for goal of any RDBMS vendor is to provides a navigational higher performance, and data minimize any overhead, but the application programming security requirements such as real challange is to complement it interface (API), designed automatic recovery after a system with increased (not decreased) specifically for programmers failure, logging and roll-forward, functionality. Scalable SQL meets using third- and fourth- and referential integrity. As these that challange far better than any generation programming two technologies diverge, it is comparable product. languages. The Btrieve API possible that the microkernel provides the maximum amount of may eventually need to surface Scalable SQL differs from similar programmatic control from an an independent API. RDBMS products because its application over the database. microkernel technology exposes Q If the name BTRIEVE.NLM the direct navigational API. In the past, the “Btrieve API” and changes to something like Scalable SQL doesn’t hide this the “Btrieve Engine” that DBKERNEL.NLM, what affect will valuable access point, but instead supported that API have been that have on applications that relies on the microkernel engine thought of as synonymous. look for BTRIEVE? to enforce relational definitions However, now that the As we roll-out products that and constraints across many data microkernel database engine is a A reflect this architecture, we will models. The increased separate entity from the Btrieve ensure that all existing Btrieve- functionality comes from the API the two technologies can based applications continue to availability of this low-level API, potentially have separate futures. function normally. It is worth plus the ability to coexist with The role of the Btrieve API is to noting that applications written new or existing non-relational provide the best programmatic to Btrieve v1 over ten years ago applications. control over navigating data in a still run normally with today’s record-oriented, key-indexed data Can developers write to the Btrieve Engines. Q model. The microkernel handles microkernel? database functions common to A Yes. The most direct API to the the implementation of any data PRODUCT FOCUS Requester, depending on your configuration and the location Scalable SQL and the of your database. Microkernel Database ® Windows Communications Requester (WBTICOMM.DLL) Engine that passes requests to the server-based engine. The Microkernel Database Engine ® Local relational database handles the following tasks for engine (WXQLLOCL.DLL and all database files: WXQL32.DLL) that provides relational database services to ® Performs all disk I/O applications. ® Ensures data integrity ® Ensures referential integrity In addition, Scalable SQL for ® Controls simultaneous data Windows includes the following access by multiple Examples of Scalable SQL components: applications ® Logs all requests that result in System Configurations ® Loader and Requester Interface (WBTRCALL.DLL) changes to a file (if logging is The following Scalable SQL for enabled for the file) that either loads the local Windows components provide Microkernel Database Engine access to Scalable SQL databases: Because Btrieve v6.x also makes or passes requests to the Btrieve DOS Requester, use of the Microkernel Database ® Loader and Requester Engine, you can run Scalable SQL depending on your Interface (WXQLCALL.DLL) configuration and the location and Scalable SQL applications that either loads the local without conflicting with any of your data files. engine or passes requests to ® Local Microkernel Database existing Btrieve v6.x applications the Windows Communications on your workstation or network. Engine (WBTRLOCL.DLL and

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 19 WBTR32.EXE) thatprovides data management services to ® Server-basedMicrokernel applications. Database Engine (BTRIEVE.NLM) You can configure your Scalable ® Server-based SPX SQL for Windows system in the communications module following ways: (BSPXCOM.NLM) that provides communication to the local ® Local Scalable SQL with the Btrieve Requesters local Microkernel Database ® Local DOS Requester Engine, as described in “Using (BREQUEST.EXE) that provides Scalable SQL for Windows and communication to server- the Local Microkernel” on based Microkernel Database page 12. Engine ® Local Scalable SQL with a local or server-based Microkernel To use Scalable SQL for Windows Database Engine. Note: If you and either a local or a server- enable RI on your database, FIGURE 1 based Microkernel Database you cannot use local Scalable Engine, install the Scalable SQL SQL with a server-based for Windows components and the Microkernel Database Engine. Using Scalable SQL for server-based Microkernel However, you can use local Windows and Either the Database Engine components as Scalable SQL with the local shown in Figure 2. Microkernel. Local or Server-Based ® Local or server-based Scalable Microkernel SQL with a local or server- based Microkernel Database If you have access to a server Engine. Note: If you enable RI running the NetWare v3.11 or on your database, you cannot later network operating system use local Scalable SQL with a and the server-based Microkernel server-based Microkernel Database Engine for NetWare, you Database Engine. However, can configure your system as a you can use server-based client/server system that Scalable SQL with a server- performs Scalable SQL operations based Microkernel. Similarly, on the workstation and performs you can use local Scalable SQL Btrieve operations on a server with the local Microkernel. running a Microkernel Database FIGURE 2 Engine. The Microkernel Database Engine Using Scalable SQL for This configuration can improve must be loaded at any location where you intend for physical Windows and the Local performance in a Novell network environment because all data data processing to occur. Microkernel management is performed by a single Microkernel Database When your Windows application You can configure Scalable SQL Engine. However, if you enable RI makes a database service request, for Windows as a single-user on your database, you cannot use Scalable SQL for Windows system that accesses databases this configuration. If you enable processes the relational portion stored on your workstation or on RI on your database, you cannot and passes the data management a mapped network drive. To do use local Scalable SQL with a portion to the Microkernel so, install the Scalable SQL for server-based Microkernel Database Engine. If the request Windows and Microkernel Database Engine. However, you involves a server-based database, Database Engine components as can use server-based Scalable the Btrieve Requester Interface shown in Figure 1. SQL with a server-based passes the request to the DOS Microkernel. Similarly, you can Requester, which passes the In this case, all processing and all use local Scalable SQL with the request to the server-based interaction between Scalable SQL local Microkernel. Microkernel Database Engine for and the Microkernel Database processing. Engine occurs on the workstation. The following components provide access to server-based Btrieve-compatible data files:

20 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Using Scalable SQL for SQL for Windows components, capability is limited on a server-based Scalable SQL particular workstation or server. Windows and Server-Based components, and server-based However, individual database Scalable SQL Microkernel Database Engine operations on a single components as shown in Figure workstation or server are usually If you have access to a server 3. faster than operations split running NetWare v3.11 or later between the workstation and the and server-based Scalable SQL, server. In most cases, you will you can configure your system as achieve the best performance by a client/server system that storing as many of an performs Scalable SQL operations application’s data files as on the workstation or the server possible on the workstation where the database is stored. running Scalable SQL for If you enable RI on your Windows or on the server database, you cannot use local running server-based Scalable Scalable SQL with a server-based SQL. Microkernel Database Engine. However, you can use server- FIGURE 3 You can use RI only on databases based Scalable SQL with a server- stored entirely on a single based Microkernel. Similarly, you workstation or server. can use local Scalable SQL with When your Windows application Therefore, databases split the local Microkernel. makes a database service request between a workstation and a involving a local database, server cannot use RI. The following server-based Scalable SQL for Windows passes Scalable SQL components provide the request to the local Scalable SQL-Based Microkernel Database Engine. access to server-based Scalable Applications Making Direct SQL databases: When your application makes a database service request Btrieve API Calls ® Server-based relational involving a server-based database engine (SSQL.NLM) database, the Scalable SQL for If your Scalable SQL for Windows ® Server-based SPX Windows Requester passes the application makes direct Btrieve communications module request to server-based Scalable API calls (that is, it includes (SSPXCOM.NLM) that provides SQL for processing. Btrieve operations, such as Get communication to the local Next), you must also load the Windows Communications If duplicate database names exist local Microkernel Database Requester both at the workstation and at the Engine and the Btrieve DOS ® Local Windows server, Scalable SQL uses the Requester on the workstation, as Communications Requester database at the server. shown in Figure 5. (WBTICOMM.DLL) that provides SPX communication Storage of Database Files to the server-based Scalable SQL engine You can also use the local and server-based Scalable SQL Server-based Scalable SQL for configuration to access a Scalable NetWare requires a server-based SQL database that has some of its Microkernel Database Engine. files stored on the workstation Btrieve for NetWare (bundled with and some on a server, as shown NetWare) includes a server-based in Figure 4. engine that provides the functionality of the Microkernel Database Engine. Scalable SQL also includes the Microkernel. You should install the copy of the FIGURE 5 server-based Microkernel that is provided with Scalable SQL You must load the Btrieve DOS unless the version provided with Requester before loading Btrieve for NetWare is newer. FIGURE 4 Windows.

To use local or server-based This capability is useful when The Microkernel Database Engine Scalable SQL, install the Scalable either disk space or processing must be loaded at any location

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 21 where you intend for physical When your application makes a NetWare SQL 3.00 data processing to occur. data management request NetWare SQL v3.0x does not support fake When your Windows application involving a server-based roots for file locations. If a user maps a drive makes a data management database, the request is passed to in the following manner: request involving a local the Btrieve DOS Requester, which map root k:=sys:\database database, the request is passed to passes the request to the server- the local Microkernel Database based Microkernel Database and then gives k:\data\myfile.btr as the Engine for processing. Engine for processing. location for the Btrieve file, NetWare SQL will return a status 11 for the file. Consequently, fake roots cannot be used to TECHNICAL INSIGHTS specify file (location) names in the dictionary or as the Data Path on the XQLLogin or xLogin. Btrieve Indexing Performance a maximum size of 576 bytes (including overhead), compression is not used. History of INI files with Btrieve Btrieve v 6.1x However, if you are working with large Btrieve for Windows, All Versions When adding an index to a Btrieve file using variable-length records, or if you are Btrieve.NLM v6.10c or client Btrieve v6.15, retrieving multiple records with Extended What Windows INI files are used for the one of two methods will be used. When Get or Step operations, there may be an various Btrieve and NetWare SQL products? Btrieve uses the “slow” method, it inserts advantage to using it. Btrieve for Windows (client) version 5.10 each index value onto the appropriate index NOTE: This is an option that can be uses WIN.INI page and writes the page out to disk. When specified with Brequest v6.10 and above. To Btrieve for Windows (req) version 5.x uses Btrieve uses the “fast” method, it builds use Real Time Data Compression, load WIN.INI index pages for all the values in memory Brequest with the /O switch. Currently, this using a merge sort algorithm before writing option is only available in the Windows and NetWareSQL for Windows (req) version the finished pages out to the Btrieve file. DOS environments. Inclusion in the OS/2 3.0x uses NOVDB.INI This method may also utilize temporary files and UnixWare requesters is not scheduled at Btrieve for Windows (req) version 6.x for multiple passes of the merge sort. The this time. uses NOVDB.INI fast indexing can only be done if there is Btrieve for Windows (client) version 6.15 enough memory available. The amount of Dropping/Adding Specific Key uses BTI.INI memory required will vary depending on the Numbers Btrieve for Windows (req) version 6.15 key length, key flags, and number of records uses BTI.INI in the file. Btrieve v6.15 Btrieve for Windows Toolbox v5.10 Memory used for the fast sort is not Btrieve The new BUTIL.EXE for DOS v6.15 supports (BTRTOOLS.EXE) uses WIN.INI cache; reducing Btrieve’s cache will make dropping and adding specific key numbers Btrieve for Windows File Manager v6.15 more memory available for the indexing. without renumbering in 6.x format files. To uses BTI.INI drop a specific key number without Btrieve tries to allocate memory from the Btrieve for Windows Function Executor renumbering, add 128 (hex 80) to the key heap for the fast sort purposes; it does not v6.15 uses BTI.INI use the memory allocated for Btrieve cache number parameter. For example, the SQLScope (for NetWare SQL 3.0) (“-m” parameter). Naturally, Btrieve has a following command will drop key number 2 uses NOVDB.INI better chance to get the memory for the without renumbering subsequent keys: indexing if you reduce the cache size. There BUTIL -DROP file.btr 130 All future Btrieve Technologies Windows is no guarantee to get it though, due to the products will use the BTI.INI file for product The BUTIL.NLM v6.10a, and the Btrieve for initialization. multi-tasking environment and memory Windows v6.15 File Manager also support fragmentation. At this time, NetWare does this functionality, as well as an application BTRMON Statistics for Cache and not provide an API to tell Btrieve the size of using the Drop Index operation. the largest contiguous memory block that is Disk Accesses available. As a result, if not enough memory To add an index with a specific key number NetWare Btrieve v6.1x is available when Btrieve asks for it, a using BUTIL.EXE for DOS v6.15, the new message “cache memory allocator is out of keywords “usekeynumber” and “keynum” The User Information option of available memory” will be displayed on the must be added to the description file. For BTRMON.NLM displays statistics for “Disk server, and then Btrieve will index using the example, Accesses” and “Cache Accesses”. These slow method. values are calculated in the following usekeynumber=y keynum=3 position=40 manner: Real Time Data Compression length=5 duplicates=y modifiable=y type=Lstring alternate=n nullkey=n For every Btrieve operation that accesses a NetWare Btrieve NLM 6.10 segment=n file, when Btrieve needs to access a page from that file, it performs a “ReadPage”. If Brequest’s Real Time Data Compression Using the command: BUTIL -SINDEX file.btr the requested page is already in Btrieve option is useful when sending multiple file.dsc will add the specified index number cache, the “Cache Accesses” value is packets for one request across a network. to the Btrieve file. This functionality is also incremented. If not, the “Disk Accesses” Compression is not performed from the available in the Btrieve for Windows v6.15 value is incremented, and Btrieve makes a workstation side via the requester; it is only File Manager, as well as an application using NetWare request for that page. This done by BSPXCOM when sending data back the Create Index operation, but not with the NetWare request may be satisfied by to the workstation. If the reply from BUTIL.NLM v6.10a. NetWare cache, if the requested data is BSPXCOM fits in one SPX packet, which has Fake Roots and NetWare SQL already in NetWare cache, or NetWare may

22 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 have to do a physical disk I/O for the page. in uppercase. In a NetWare SQL application, it may be BTRMON does not distinguish between possible to use multiple cursors to these two, since it does not know where Xtrieve 4.11e & Empty Strings with accomplish this update with optimization. NetWare is getting the page. However, for SDF For this to work, the table being updated performance reasons, a NetWare cache must contain a unique key that is not being Xtrieve PLUS 4.1x, DOS access will certainly be faster than a updated. Consider the following steps: NetWare disk I/O, but a Btrieve cache If SDF format is used to translate in empty -> Call XQLCursor to allocate access will be faster than either of these. strings with Xtrieve 4.11e, the strings will be CursorID1; stored in the Btrieve file as binary zeroes Only “ReadPage” accesses are counted in -> Call XQLCursor to allocate instead of blanks. This will have an effect on the BTRMON statistics. However, almost CursorID2 sorting, joins, and anything that assumes that every Btrieve operation will produce calls to -> Call XQLCompile on CursorID1 with the string is being stored as blanks. “ReadPage”. For example, a Btrieve insert the statement: SELECT * FROM will cause Btrieve to read the FCR (file If the UNF (unformatted) option is used Patients WHERE Zip = ‘78730’ control record), one or more PAT (page instead of SDF, this problem does not occur. -> Call XQLCompile on CursorID2 with allocation table) pages, a data page, one or Also, when translating from view to view, the statement: UPDATE Patients SET more variable pages (for variable length or the problem does not occur. If the SDF file Zip = ‘78799’ WHERE ID = @IdValue compressed records), and one or more pages has at least one blank between the double -> Begin Loop per index in the file. A Btrieve GetEqual quotes, i.e. “ “, it will translate properly. -> Call XQLFetch (option 1) on operation will cause Btrieve to read the FCR, CursorID1 to fetch 1 record; one or more PAT pages, one or more index This problem exists only in Xtrieve PLUS -> IF Fetch is successful: pages to find the requested key value, a data 4.11e. -> Call XQLSubst on CursorID2, page, and possibly, one or more variable Memory error on Btrieve Install sending in the Patient ID pages. All Btrieve file access operations will returned by the Fetch on need to access one or more pages from the Btrieve for DOS VERSION: 6.15 CursorID1 for the @IdValue file; modifications and writes of those pages substitution variable. The Btrieve for DOS 6.15 Installation are not tracked. -> Call XQLExec on CursorID2 to program requires 440K of conventional execute the UPDATE; Once a file is closed, any pages from that memory to install. This information is -> Otherwise file that may have been in cache are no presented on the initial INSTALL screen as -> call XQLStatus (option 0) on longer “available”. If the file is reopened, well as in the README file on the CusorID2 to retrieve the and a page is requested, it will always Installation Disk. If there is not enough number of records that were produce a disk access (i.e., a NetWare cache memory to run the installation program, the updated. or I/O access), even if the page is still in a following message appears: -> End Loop when Fetch status <> 0. Btrieve cache buffer. Therefore, frequently FATAL ERROR: Out of memory in closing and reopening Btrieve files will EMemCalloc xxxx: xxxx n Press any key The fetches on CursorID1 will be optimized produce more Disk Accesses than Cache to continue. on the Zip key. The update on CursorID2 Accesses. will be optimized on the ID key (which is Depending on how much memory is LOAD BUTIL -STAT Info Scrolls not being updated). This optimation would available the xxxx:xxx n part will change. not be possible without a way to uniquely Off Screen This was reproduced with 371248 bytes of identify the record without using the field(s) conventional memory free. With this NetWare Btrieve NLM 6.10 being updated. configuration the initial install screen does When using the BUTIL.NLM, issuing the not appear, it is possible to get the initial This method works correctly with NetWare command “LOAD BUTIL -STAT filename” at install screen without enough conventional SQL v3.00e. A bug in previous revisions of a NetWare 3.x or 4.x file server may cause memory for the installation process. NetWare SQL caused the Update on the file statistics information to scroll off the CursorID2 to reposition CursorID1, resulting screen before it can be read. Using Multiple Cursors for Updates in some of the records not getting updated. The STAT information scrolls off the screen NetWare SQL 3.00 Errors Loading Btrieve in because many Btrieve v6.x files contain a Multiple cursors can be used to improve Windows large number of key specifications. performance of updates with NetWare SQL. Therefore, all of the file specifications cannot Consider the following UPDATE statement: Btrieve for Windows v 6.15 fit onto a single screen. The overflow If a Btrieve Windows application is able to automatically forces the screen to scroll and UPDATE Patients Set Zip = ‘78799’ locate and load the Loader and Requester the first information displayed is no longer WHERE Zip = ‘78730’ Interface (WBTRCALL.DLL), but cannot find visible. This statement attempts to update any record the Btrieve Interface module It is possible to redirect server console with a zip code of 78730 to have a new zip (WBTRLOCL.DLL), the application will screen output to a NetWare file using a code of 78799. Even if the Patients table has receive a status 2003 “No Local Access CLIB.NLM function. The following syntax an index defined on the Zip field, NetWare Allowed” when trying to access a file on a demonstrates how to redirect the screen SQL cannot use that index to find the local drive. This will happen even if the ouput to a file that later can be printed or records with 78730 since this field is also configuration specifies Local=Yes and viewed using an editor. being modified. NetWare SQL cannot Requester=No in the [Btrieve] section of the optimize its searching on an index if any BTI.INI file. LOAD BUTIL -STAT vol:\path\filename field in that index is being modified by the (CLIB_OPT)/>vol:\path\filename update statement. As a result, NetWare SQL Similarly, if WBTRCALL.DLL and WBTRLOCL.DLL are found, but The CLIB function ‘CLIB_OPT’ must be typed will scan the entire file looking for records with the correct zip code to update. WBTR32.EXE is not, then a status 20 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 23 “Record Manager is Inactive” will be and any record with a positive integer value for returned. the Code field will be returned. CURRENT VERSIONS All Btrieve for Windows files should be located Another possible workaround is to add a in a directory in the workstation’s path. By separate index on only the Name field. Then, the default, these files are installed in the original query with just the Name restriction BTRIEVE DATA MANAGEMENT SYSTEM optimizes on the new index instead of the C:\BTI\WIN\BIN directory, so adding this to the segmented index, and the correct data is Client/Server Database Engines path environment variable will resolve the returned. problem. Btrieve Engine for NetWare...... 6.10c NetWare SQL Does Not Utilize Workstation Database Engines NetWare SQL Tables and Btrieve Milliseconds in the Time Field Btrieve Engine for DOS...... 6.15 Unsigned Keys NetWare SQL 3.00x Btrieve Engine for Windows...... 6.15 NetWare SQL 3.00 When inserting the current time into a field with Btrieve Engine for OS/2...... 5.10a NetWare SQL does not support the unsigned a type of time, the values in milliseconds only binary key type that is available in Btrieve. display 0s. This is what the example code looks Btrieve Developer Kits like: Some applications use Btrieve files with keys of Btrieve Developer Kit for DOS...... 6.15 INSERT INTO VALUES (CURTIME) type “unsigned binary”. Unsigned binary data is Btrieve Developer Kit for Windows..6.15 sorted by Btrieve as unsigned integers. Since This is a limitation in NetWare SQL. NetWare NetWare SQL does not support the unsigned SQL cannot retrieve the milliseconds value Btrieve Developer Kit for NLM’s...... 1.1 because seconds are the smallest granularity of binary type, users generally declare those fields Querey and Report Writer System in the dictionary as NetWare SQL integers, time that is returned through CLIB functions. Xtrieve PLUS for DOS...... 4.11 which are signed integers. However, doing this Therefore, NetWare SQL always returns zero for the milliseconds. causes a problem if the key in the Btrieve file has Xtrieve PLUS for OS/2...... 4.11 the unsigned binary field as anything but the first Problem with Blank Padded Paths on Report Executive for DOS...... 4.11 segment in the key. XQLLogin Report Executive for OS/2...... 4.11 For example, suppose a Btrieve file is set up with NetWare SQL 3.00 Key 0 defined as: If the sDataPath parameter (that is sent to Key Pos Len Dup Mod Type Null NetWare SQL on the XQLLogin call) is blank- SCALABLE SQL DATA MANAGEMENT ======padded instead of null-terminated, subsequent SYSTEM queries will fail with a status 12. However, the 0 3 12 Yes No String _ Client/Server Database Engines 0 15 2 Yes No Unsigned _ XQLLogin call is successful. Always terminate the path in the sDataPath NetWare SQL...... 3.0 And the corresponding dictionary definition is: parameter with a binary zero without any blank- Workstation Database Engines padding. This is required, as described in the CREATE TABLE Test using “TEST.DAT” (ID Scalable SQL for Windows...... 3.01 int(2), Name char(12), Code int(2)) documentation for the XQLLogin function. Early revisions of NetWare SQL (up to v3.0a) worked with index (Name SEG, Code) XQL for DOS...... 2.11 even if this parameter was blank-padded, but Attempting to execute a NetWare SQL query later revisions (up to and XQL for OS/2...... 2.11 such as: SELECT * FROM Test WHERE Name = including v3.0e) require the null-terminated path. SQL Developer Kits “Smith” may not return data even if there are records with Name = “Smith”. NetWare SQL NetWare SQL Status 849 Scalabele SQL Developer Kit for Windows...... 3.01 will optimize the searching on Key 0, and issue a Documentation Btrieve GetGreaterOrEqual call on Key 0 with a NetWare SQL 3.00 NetWare SQL Developer Kit...... 3.0 14-byte Key Buffer of: In the NetWare SQL 3.0 documentation for 53 6D 69 74 68 20 20 20 20 20 20 20 00 80 (hex) status 849 it states: “If the problem persists, S m i t h . . (ASCII) contact Novell by phone, fax, or NetWire on OW TO EACH CompuServe (as instructed in “Where to Get H R BTI The first 12 bytes are the blank padded name, Help” in “About This Manual”) regarding a and the next two bytes are the lowest integer possible patch to increase the size of the buffer. Btrieve Technologies, Inc. value from which to start searching (in this case, This is incorrect. This instruction was for the 5918 West Courtyard Drive 0x8000, which is decimal value -32768). Due to previous version NetWare SQL 2.11. the differences in sorting unsigned vs. signed Suite 400 integers, this Key Buffer value will not be able to Btrieve Returns Status 88 Austin, TX 78730 find records that have a Code such as 1, which NetWare Btrieve NLM 6.10 would be stored internally as 01 00. If the Phone: (800) 287-4383 Under NetWare Btrieve v6.10c, if a number unsigned binary data in the Btrieve file is actually (512) 794-1719 integer data, it may be possible to issue NetWare other than 0 is used for a normal mode Btrieve Open operation, when a second attempt to open SQL queries to find the data. For example, the Night: (512) 794-1731 the file is made, a status 88 (Incompatible Open query: SELECT * FROM Test WHERE Name = Mode) may be returned. Fax: (512) 794-1778 “Smith” AND Code >= 0 Btrieve 5.x would open the file in normal mode CompuServe: GO BTRIEVE will cause NetWare SQL to issue a Btrieve provided “any other number” was used besides GetGreaterOrEqual call on Key 0 with a 14-byte Note: The BTRIEVE forum on the numbers reserved for accelerated (-1), read- Compuserve will be active by the end of Key Buffer of: only (-2), verify (-3), and exclusive (-4). Always September, 1994. Until then, use GO use 0 as the key number on an Open for 53 6D 69 74 68 20 20 20 20 20 20 20 00 00 (hex) NDEVSUP for CompuServe technical S m i t h . . (ASCII) normal mode. support and information. 24 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 As you can see, all pertinent information about the call is displayed in the top section of the window with data buffer, key buffer, and position block information Guest Review displayed in the bottom section. Important information to review before passing control to Btrieve is the operation Banalyze: The Btrieve Debugging code, key number, and key buffer. Tool for DOS By Richard Bogard, Information Architects

Have you ever lost sleep (or hair) about an elusive program “bug” that you just can’t find? Ever needed to “hack” (reverse engineer) a commercial product to solve a problem? Ever had a programmer take a permanent leave of absence with the source code to one of your mission- critical applications? If you regretfully answered “yes” to any of these questions, the following article may interest you. We’ll review a product called Banalyze, a Btrieve application debugger, and discuss how to debug or analyze an application. Banalyze is a TSR (Terminate-and-Stay-Resident) program that intercepts calls from an application program to the Btrieve record manager. It loads after Btrieve, but Figure 2 - Data Buffer After a Get Previous Btrieve Call before the application program: After Btrieve has performed the operation, the important information items are now the status code, buffer length and data buffer. To eliminate the need for a manual, the operation and status code descriptions are displayed. Application Program

Banalyze Btrieve Microkernal Database Engine

DOS

Figure 1 - Banalyze is Loaded After Btrieve and Before the Application Program

Since it works like Btrieve, it has the same attribute of being language-independent and requires no INFO ARCHITECTS application modification for debugging. No special hardware or other software is required. Simply load AD Banalyze after Btrieve and start your application. You may even debug applications which use XQL for relational database management. When a call is made to Btrieve, a window will “pop-up” over the application screen and all the Btrieve call parameters are displayed before and after the call to Btrieve (Figure 2).

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 25 Looking at all the Btrieve calls in an application can ® Poor handling of returned error codes be time consuming and tedious. So Banalyze has three ® Buffer size errors features which can dramatically speed up the debugging ® Debug or Reverse Engineer third-party process. applications without source code First, you may simply deactivate the Banalyze ® Improve performance by checking the duration of display until you reach the point in the program where the call operations is made. A hot-key can then be used to activate the display and begin tracing the Btrieve calls. Banalyze uses relatively few system resources. It Secondly, operations can be “trapped” or filtered by needs less than 20K of memory and works with Btrieve for file name and/or operation. For instance, you may have a Get DOS. Support for Btrieve 6.x and a Windows version are Equal call against a Customer Master file that is not finding under development. ² the desired customer record. To trap an operation, build a parameter file with any ASCII text editor and indicate the Btrieve file name and flag the operations to be traced. Then indicate the parameter file name on the command line when loading Banalyze. The filter feature allows restricting the trace to calls before and/or after the call to Btrieve or only calls which return an error status code. Finally, if your too busy to look at any Btrieve calls right away, Banalyze can be set up to log the screen information to a disk file which can be viewed at a later time. The information is stored as ASCII text which allows the use of any text editor to view the data and search for the problem. This also allows you to debug batch mode applications or track down those intermittent problems. Banalyze can log information to a file while a user is busy entering data. A simple menu of the options just described can be brought up by pressing a user defined hot-key combination Figure 4 - Data Buffer in Ruler Mode (Figure 3). You may also specify all options on the command line when loading Banalyze to operate it completely in batch mode.

Figure 5 - Position Block Information

Rich Bogard, President of Information Architects, Figure 3 - Banalyze Configuration Menu Inc., is the author of many Btrieve/Scalable SQL utilities under the Bsupport and Xsupport Typical problems which can be solved using Banalyze are: trademarks. He can be reached at (517) 887-8000 , CompuServe 76317,1056, or the Bhive BBS at ® Errors in program logic flow (517) 887-8018. ® Incorrect data in the key buffer

26 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Editors Note: If you have an interesting experience to report for this Btrieve In Action column, then we would like to hear from you. Please send a brief description of your proposed topic for this column to BDJ - Btrieve in Action, 2416 Btrieve Applied Hillsboro Road, Suite 201,Nashville, TN 37212 or send it to How to Break Btrieve's 4GB Barrier CompuServe address 73173,2731.

Without a Hammer This allows much faster updating of files because By Steve Troxell, Eagle Systems all the I/O involved with the pre-image file is skipped. However, that means there is no automatic file recovery, Did you know that Btrieve files were limited to 4 and when the system crashes, you will be unable to write to GB in size? Well, the vast majority of applications may the file again. Attempts to open the file as anything other not have to worry about that limitation, but for the than “read-only” will result in an “Incomplete Accelerated occasional few that are brushing the size threshold, Access” status. In our case, when this happens we have to consider the following attempt at a solution. go to the backup copy and start the process over again The company I work for, Eagle Direct, keeps (hopefully after eliminating the cause of the crash). This is databases of cable TV subscribers and their viewing history a very time consuming process when 3.5 GB’s are to provide market trend analysis reporting and involved. telemarketing/direct-mail lists for the cable industry. In order to get an accurate image of the cable viewing trends, A “Virtual” Btrieve File we track a sampling of the cable TV households across the country and store the particular channels they are being The solution we came up with revolved around the billed for each month over several years. Just one of our fact that the records in the database are all grouped by city, databases can have as many as 20 million records, and and each record has a “city ID” field that is a unique since the data is recorded in snapshots at monthly identifier for the city in which that subscriber lives. Since intervals over years, the size can pile up rather quickly. all of our reports are selectable by the city, each key in our The historical data can not be easily “archived” off-line Btrieve file includes the “city ID” as one of its segments. since it is actively and routinely used to perform various With this in mind, we elected to store all of the subscriber retention studies. When we observed the lone Btrieve file records for each city in separate Btrieve files, one file for in one of our database systems approach the 3.5 each city, using the city ID as the filename. GB mark, we realized we could be in trouble. In fact, A separate file for each city may be an obvious when Novell tech support learned of what we had, their solution, but we were greedy, at least as far as how we response was, “You have a Btrieve file how big? And it wrote programs to handle this system. We wanted to be works?” able to add or delete an entire city at will; we didn’t want to Other issues come into play related to the size of hassle with figuring out which file to open for any given I/ our huge file. For one thing, if even one of those 20 O operation; and since all our existing software had all the million records gets changed, our network backup system right calls in all the right places for the “all-in-one-file” gets bogged down that night backing up the whole 20 method, we were lazy and didn’t want to do any more million record file. Also, because of the nature of the retooling than was necessary. update data we receive, most of those 20 million records To satisfy our greediness, we wrote a programming are “touched” each month, which means we have a interface around the native Btrieve calls to completely tremendous amount of data to pump into our system each manage the “multi-file” system transparently to us and every month. programmers. All of the regular Btrieve routines were Because of the huge volume of updates, we use available, but those that accessed the actual file all had Btrieve’s “accelerated” mode rather than “normal” mode been enhanced such that if the call referenced a record that when updating our file. When updating a file in normal did not belong to the currently opened file, the routine mode, Btrieve stores a copy of the page that’s about to be would close the current file and open the appropriate file updated to a pre-image file, then updates the data page on before performing the native Btrieve operation (remember, disk. In the event of a system failure before the update is the city ID is in all keys). By using this API, programs completed, Btrieve uses the pre-image file to restore the could be completely unaware that anything but a single incomplete data page to its original state the next time the Btrieve file was in use. We dubbed this a “virtual Btrieve file is opened. The cost of this safety feature is that it file.” Any single piece of the “file” still could not exceed 4 slows down updates due to the extra writing of data pages GB, but within that constraint, the “file” could be as large to disk. When a file is opened in accelerated mode, the as all available disk space. pre-images of the updated pages are not written to disk.

28 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Making a Transparent File Manager Listing 2 shows two of the GET operations. The Get1st operation must return the first record of the first file Staff programmer Gary Suydam developed the in the file list. It does this through the OpenFile routine. application programming interface that allowed us to treat Once the correct file is opened, it simply calls the native the collection of city files as one single entity. The heart of GET_FIRST operation inherited from the TBtrieve object. the API is in the filenames and the fact that the filename is GetNext is handled similarly. Only in this case, a a segment of all keys. A sorted list of city filenames is call to the native GET_NEXT operation is done first using maintained inside the API. A GET_FIRST call would the currently opened file. If that call is successful, then involve the file at the top of the list; a GET_LAST call that's all there is to it. However, when the end of the would involve the file at the bottom of the list; a current file is reached, then we must make the seamless GET_NEXT call that hit the end of the current file would bridge into the next city file. We again use OpenFile to cause the next file in the list to be opened. Since the city open the next file in the file list and then call the native ID field is stored in each record, the INSERT and GET1ST operation for the new file. In the event that there UPDATE calls know which file to use. INSERTs of is no “next city” in the filenames list, then we truly have hit records with previously unknown city IDs would create a the end of our “virtual” file and only then do we return a new file for that city and add the appropriate entry in the status 9 (end-of-file). filename list. In a like fashion, DELETEs that removed the All the other GET routines, GET_EQUALS, last record for a city would physically delete the city file GET_GREATER_THAN, GET_LESS_THAN, etc., from the disk and remove the appropriate entry from the perform in a similar fashion. Since the city ID is a segment filename list. of every key, examining the requested key will tell us In Turbo Pascal, the filename list can be created which city file to open to perform the read. using the FINDFIRST/ FINDNEXT procedures. These The OpenFile routine is the crux of the system, and routines can scan a directory and return all existing files it is surprisingly simple. Each of the Btrieve operations matching a given wildcard mask. In our implementation, decide when to switch files and call OpenFile to do it. all of the files have an extension of SUB (subscribers). OpenFile simply closes the currently opened file (Done The sample code provided with this article shows from the TBtrieve object), and opens the new file (Init how a few of the critical Btrieve routines are implemented. from the TBtrieve object). Our regular Btrieve library is an object-oriented wrapper Writing to the file follows a similar methodology. around the native BTRV function (the TBtrieve object in Since the city ID is stored within the record, the INSERT/ the sample code). We provide a separate routine for each UPDATE routines simply examine that field to determine Btrieve function call and let the object handle the trouble of which file to write the record to. Listing 3 shows an setting up and interpreting the BTRV parameters. The example of the INSERT routine. INSERT attempts to open TBtrieve object is referenced but not shown in the sample the file for the given city (OpenFile will do nothing if the code. For the virtual Btrieve file, we make a descendant of correct file is already open). If no file exists for the city, the regular Btrieve object (called TVirtBtrv) and override then it creates a new one. In either case, once it has the the I/O routines to handle the switching between files as correct file, then it calls the native INSERT operation to needed. add the record. Listing 1 is a Turbo Pascal example of the In the case of the UPDATE operation, no TVirtBtrv object declaration and its constructor and modification of the UPDATE routine is necessary unless destructor. Not all of the I/O routines are shown. the city ID field itself has been changed. In that case, the TVirtBtrv is descendant from the TBtrieve object, which record is deleted from the current file and INSERT is contains all the fields and routines needed for regular called to place the updated record in the correct file. Btrieve access. TVirtBtrv contains the additional fields and Benefits of the System routines needed for the virtual Btrieve file. CurrentFile So, that’s the system. What do you gain from all contains the filename of the currently opened file. FileList of this? The most obvious gain, and the motivation for the contains the sorted list of all existing files. FileOpen is true entire concept, is that a Btrieve database can go beyond the or false depending on whether one of the component files 4 GB limitation to occupy up to all available disk space is currently open or not. NumFiles contains the number of (although there is still a 4 GB cap on any one component component files in FileList. The Init routine takes the file). But after accomplishing the principle goal, we place of the Btrieve OPEN call. This opens the database by noticed some beneficial side effects of the system: setting up all the necessary fields and populating FileList, but no physical files are actually opened until the first I/O In the “all-in-one-file” method, a system crash attempt is made. The Done routine takes the place of the during updates gave us an “incomplete accelerated access” Btrieve CLOSE call.

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 29 error, and the entire 20 million record file was out of Listing 1, continued from previous column commission until it was repaired. This almost always procedure Get1st( var Rec ); involved restoring the behemoth file from backup tapes and procedure GetNext( var Rec ); starting over. Now, only one small part of the overall procedure Insert( var Rec; Key : Integer ); database (whichever city was being updated at the time) is procedure OpenFile( Filename : String ); end; knocked out due to a system crash. The rest of the database remains unharmed and completely usable while { "Open" the virtual Btrieve file; note that no physical files are the damaged piece gets repaired (which in itself is also actually opened until the first I/O attempt. } much less of an ordeal). constructor TVirtBtrv.Init( Mode : Integer ); Our backup system no longer backs-up the entire var database when only a few records have been updated. Just DirEntry : SearchRec; the city files that have been changed get backed up; the ones that were untouched do not unnecessarily clog up the begin FileMode := Mode; { Access mode inherited from TBtrieve } backup process every night. FileOpen := False; When processing all of the records for a given city CurrentFile := ''; regardless of sequence or selection, as many of our NumFiles := 0; applications do, we can now use the STEP operations to { Scan the directory to compile list of all component files } read the records. Since the STEPs read records directly FindFirst('*.SUB',AnyFile,DirEntry); while DosError = 0 do without going through the index pages, I/O is noticeably begin faster. We couldn't do this in the “all-in-one-file” method NumFiles := NumFiles + 1; because the records for any one city could not be { Strip off file extension and store root name only } guaranteed to be contiguous within the file. ² FileList[NumFiles] := Copy(DirEntry.Name,1,Pos('.',DirEntry.Name) - 1); FindNext(DirEntry); end;

{ Your favorite sort algorithm goes here to sort FileList } Steve Troxell is the Chief Programmer of Software Development for Eagle Direct, Denver, end; CO, and can be reached on CompuServe at { "Close" the virtual file } 74071,2207. destructor TVirtBtrv.Done; begin if FileOpen then begin inherited Done; FileOpen := False; end; end; const MaxNumFiles = 1000; Listing 1, Continued type SubRecType = record CityId : array[1..5] of char; { Return the first record on a given access path } Account : array[1..10] of char; Name : array[1..30] of char; procedure TVirtBtrv.Get1st( var Rec : SubRecType; Key : Integer ); Address : array[1..40] of char; City : array[1..20] of char; begin CurrentKey := Key; { CurrentKey inherited from TBtrieve } State : array[1..2] of char; FilePtr := 1; Zip : array[1..9] of char; OpenFile(FileList[FilePtr]); { Open the file at the top of FileList } Phone : array[1..10] of char; if Status = 0 then { Status is inherited from TBtrieve } end; inherited Get1st(Rec,CurrentKey); { Call the native GET_FIRST } end; TVirtBtrv = object(TBtrieve) CurrentFile : String; { Return the next record on the current access path } FileList : array[1..MaxNumFiles] of String[8]; FileOpen : Boolean; procedure TVirtBtrv.GetNext( var Rec : SubRecType ); NumFiles : Integer; begin inherited GetNext(Rec); constructor Init( Mode : Integer ); destructor Done; if Status = 9 then { If we've hit the end of the current file } Continued top of next column... Continued on page 32, column 1...

Listing 1 Listing 2

30 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 begin Listing 3, continued from previous column if FilePtr < NumFiles then { If there are more files } begin FilePtr := FilePtr + 1; Create(Description,Rec.CityId + '.SUB',True); OpenFile(FileList[FilePtr]); { Open the next sequential file } if Status = 0 then inherited Get1st(Rec,CurrentKey); { Call the native GET_FIRST } OpenFile(Rec.CityId); end; end; end; end; if Status = 0 then begin { Handles "switching" between component files } inherited Insert(Rec,CurrentKey); if Status = 0 then procedure TVirtBtrv.OpenFile( Filename : string );

begin { Insert the new filename into the sorted list and if CurrentFile <> Filename then return it's list position. } begin if FileOpen then FilePtr := InsertFilename(Rec.CityId); begin inherited Done; end; FileOpen := False; end; CurrentFile := ''; end; Listing 3, Continued inherited Init(Filename + '.SUB',OwnerName,FileMode);

if Status = 0 then begin CurrentFile := Filename; FileOpen := True; end; end; end; Listing 2, Continued

{ Add a new record to the database }

procedure TVirtBtrv.Insert( var Rec : SubRecType; Key : Integer );

var

{ Btrieve file description packet for creating new files }

Description : record RecordLength : word; PageSize : word; NumKeys : word; Reserved1 : longint; FileFlags : word; Reserved2 : word; Allocation : word; Keys : array[0..23] of record Position : word; Length : word; Flags : word; Reserved1 : longint; Extended : byte; NullValue : char; Reserved2 : longint; end; end; Get your message out to the begin CurrentKey := Key; { CurrentKey inherited from TBtrieve } OpenFile(Rec.CityId); Btrieve Community! if Status = 12 then { file not found } begin Call Carolyn Lighty, Advertising Manager,

{ Set all the file parameters in the Description packet and at (800) 685-2403 or (201) 712-0044 for create a new file. Call Create routine inherited from TBtrieve to create a Btrieve file (performs a Btrieve operation 14) }. more information on advertising in Btrieve Developer’s Journal and The Continued top of next column... SourceBook catalog. Listing 3

32 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 What’s Being Said About Btrieve...

The New Btrieve: Novell departs the database business and gives Btrieve and NetWare SQL a new lease on life FromDBMS April 1994, Volume 7 Number 4, Page 42 Abstract Btrieve Technologies Inc Chairperson Nancy Woodward, Pres and CEO Ron Harris and Chief Technical Officer Doug Woodward discuss their company's products and plans. Btrieve Technologies is a spin-off from Novell Inc, which has transferred ownership of the Btrieve record management system to the new company. Novell thereby exits the database business, although it retains a 15 percent ownership in Btrieve Technologies and continues to bundle the product with the NetWare network operating system. About 60 employees from Novell Austin will staff the new company. Btrieve Technologies plans to enter several original equipment manufacturer (OEM) agreements and will continue to maintain relationships with companies providing middleware support. There are over 35,000 developers currently using Btrieve.

DBMS autonomy on tap for NetWare: Novell offering third-party database hooks. From PC Week May 16, 1994, Volume 11 Number 19, Page 1 Abstract Novell Inc gives up all rights to the central database technology within its NetWare network operating system and announces a database strategy that involves the Open Database Connectivity (ODBC) standard. Users will be able to choose among commercial databases on which to run their network's NetWare Distributed Management Services repository, the Novell Groupware message store and the core NetWare database engine, as well as the NetWare Loadable Module-based applications. Novell will design hooks for a variety of third-party NetWare based services into NetWare. Btrieve was often seen as a weak link in Novell's product line, and Novell managers claim the move will give the company a more up-to-date database approach. The company could officially announce its database strategy by summer of 1994. Sequential Read 1,000 Records Special Assignment Minutes:SecondsÆ 0:00 1:00 2:00 3:00 4:00 Btrieve Benchmarks DOS 5.10 0:02 DOS 6.15 0:04 By Steve Mook

No single issue has sparked more response and WIN 5.10 0:03 questions from our readers over the past few months, with WIN 6.15 0:03 the possible exception of ODBC, than Btrieve benchmarks. Seems like some of you need reassurance that you made NLM 6.10 0:05 the right choice, or others need a compelling reason to take the upgrade plunge. Well, the problem with any benchmark BEST WORST test is, as the automobile ads used to say back when anybody cared, “Your mileage may vary.” We compared Btrieve for DOS version 5.10 and Random Read 1,000 Records 6.15, Btrieve for Windows version 5.10 and 6.15, and NetWare Btrieve NLM version 6.10. The version 6 Minutes:SecondsÆ 0:00 1:00 2:00 3:00 4:00 comparisons were run on a version 6 format test file, the version 5 tests on a version 5 format test file with the same DOS 5.10 0:05 file specifications. Both files were optimized for their respective versions, but otherwise identical in key DOS 6.15 0:05 structure, record length, etc. The test file contained fixed WIN 5.10 0:03 length records of 512 bytes, one duplicate integer key of two bytes, and a page size of 1024. The same benchmark WIN 6.15 0:03 source code was compiled for the test on the DOS and Windows platforms, and the same EXE files were used for NLM 6.10 0:06 all tests on each platform. On each platform, we inserted 1000 records into an empty file. Then we read the records BEST WORST sequentially, and then randomly using the index path. Finally, we read each record sequentially and updated it. We repeated this test several times, allowing the file to Sequential Read and Update1,000 Records grow, and the number of duplicate key values to increase. The numbers shown are average times, but they generally Minutes:SecondsÆ 0:00 1:00 2:00 3:00 4:00 did not vary a great deal from one pass to the next. Here DOS 5.10 3:01 are the results: DOS 6.15 0:32

Insert 1,000 Records WIN 5.10 3:50

Minutes:SecondsÆ 0:00 1:00 2:00 3:00 4:00 WIN 6.15 0:22

DOS 5.10 4:15 NLM 6.10 0:18

DOS 6.15 0:30 BEST WORST WIN 5.10 4:28 The sequential read and random read results we obtained using this method looked suspect. So we WIN 6.15 0:18 decided to try again with a different database: one with NLM 6.10 0:15 a convoluted key structure, and one that was a too big to fit in a cache buffer. Rather than just make one up, we used our customer data base. It's about 35MB in size, BEST WORST 34 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 with a record length of 360 bytes, and an index structure Btrieve and Scalable SQL, was kind enough to provide that does about everything one can possibly do in a me with some numbers they had collected from Byte version 5 file. We also decided that we needed to magazine’s “1993 Price Waterhouse Report on High- expand the test from one thousand recrods to ten End LAN Accounting Systems.” The article compared thousand, to get a more representative sample. The the performance of their Solomon III for Btrieve results were interesting: product with the previous version, Solomon III version 8.0c, which used another database engine. The Sequential Read 10,000 Records improvement with the switch to NetWare Btrieve 6.10 was significant - processes ran in one half to one quarter Minutes:SecondsÆ 0:00 1:00 2:00 3:00 4:00 the time across the board. Solomon also recently upgraded their single- DOS 5.10 0:26 user package from Btrieve for DOS version 5.10 to DOS 6.15 1:35 version 6.15, with even more astonishing results. “It’s really unusual in this business to have people call and WIN 5.10 0:31 tell you they’re happy with a new release,” Mark said, “I’m keeping those comments on my voice mail so I can WIN 6.15 1:17 listen to them again when the other kind come in.” As a case in point, he told me that the company keeps its NLM 6.10 1:06 payroll module on a single-user machine for security reasons. “In the previous Btrieve version 5.10 release, BEST WORST the monthly posting process took over sixty hours to run. Switching to Btrieve version 6.15 cut that to Random Read 10,000 Records exactly seven hours. Needless to say, the accountant was pleased, and she’s an important person to please. Minutes:SecondsÆ 0:00 1:00 2:00 3:00 4:00 She has a really nice smile and she prints my paycheck.” ² DOS 5.10 0:30

DOS 6.15 1:54

WIN 5.10 0:53

WIN 6.15 1:42

NLM 6.10 1:11

BEST WORST

Btrieve performance varies for a number of reasons, some related to hardware, some related to database design. The sorts of factors one would expect generally effect performance. Slower machines with less available memory will be slower. Huge files will take longer to read than tiny ones. Files with a lot of keys and long records take longer than files with a few keys and short records. Poorly designed access paths take longer than well-designed access paths. All of which makes it difficult to design a meaningful test. So the first thing we did was to call people who had upgraded to get a general feel for what was really going In theBtrieve Developer's Journal Product Testing Laboratories, products undergo rigorous scientific on out there. testing and analysis using our state of the art Mark Granville with Solomon Software, a equipment and methods. company which manufactures accounting software using

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 35 YT: I founded AG-Tech Corp. in 1984. We have now fifteen people on staff. Four of them are working for technical support, and three people are working for development. We have three people in technical support and development who have over six International Btrieve years of Btrieve experience. We are located in Nagoya which is in between Tokyo and Osaka. Nagoya is about the sixth largest Yoshio Tanahashi, AG-Tech Corp city in Japan, and the population is about 1.8 million. Of course, many of our customers are in Tokyo, about 40 percent. AG-Tech Nagoya, Japan Corp. is privately owned, and our annual revenue is about $3 By Scott A. Smith million. At present, we distribute products from Crystal Services, Wilson WindowWare, Opt-Tech Data Processing, and Object Resource Corp. We are also working on a few other If you have ever scanned through the volume of companies, and will release their products in the future. messages in the Btrieve forums on CompuServe, then you have certainly seen the name Yoshio Tanahashi. Yoshio is SS: What does the future of Btrieve in Japan look like now that the president of AG-Tech Corporation in Nagoya, Japan, the products have been transferred to Btrieve Technologies? located between Tokyo and Osaka, and has been primarily YT: For the future, we are discussing several issues with Btrieve responsible for the enormous popularity of Btrieve in Technologies now. Many things have not been decided for the Japan. future yet. For these you should ask Ron Harris or Nancy Before Novell purchased SoftCraft, AG-Tech Woodward at BTI. However, at least, Novell Japan never did a Corp. remanufactured Btrieve in a Japanese version with good job marketing the Btrieve products. So I think things will be going better now if the BTI people try to understand the translated documentation and utilities. After the transfer of Japanese market well. Btrieve to Novell, they became Japanese distributors of Btrieve as manufactured by Novell Japan. AG-Tech Corp. has sold Btrieve to over 4,000 Japanese customers and offers support services for Btrieve on an annual service contract basis. Ag-Tech Corp. and Btrieve Technologies are currently in negotiations about the future of Btrieve in Japan. Whatever the results, we can be sure the Yoshio and AG-Tech Corp. will play a vital role with Btrieve in Japan. We had the opportunity to meet with Yoshio during our trip to BTI headquarters in Austin last April. The following is a partial text of the conversations we had there and also from our on-going correspondence via CompuServe.

Scott Smith: When did you first become involved with Btrieve? In Austin, Texas, pictured from left to right: Ron Harris, Scott Smith, Yoshio Tanahashi: The first time we used Btrieve was for our Nancy Woodward, Steve Mook, Yoshio Tanahashi, and Doug own internal use at AG-Tech Corp., in 1985. By 1986, we had Woodward entered into a distribution agreement with SoftCraft to translate SS: What, specifically, has BTI done to better understand the the Btrieve engine, utilities, and documentation into Japanese, Japanese market? and to begin marketing Btrieve to the Japanese market. We YT: I think they are doing a good job at looking seriously at the completed the translation early in 1987, and until 1992, we sold Japanese market now. BTI President and CEO, Ron Harris, almost 4,000 copies of Btrieve. When Novell Japan started came to Japan in June, and he stayed here for a week. Since we manufacturing Btrieve in Japan in 1992, we were one of the are still in discussion on several issues, I should not make major distributors of Novell Japan for Btrieve products. Also, further comments at this time. we offered our technical support services even if the customers did not buy Btrieve from us. That product is called, “Btrieve SS: What do you think about the size of the Btrieve market in Program Service” which includes some DOS and Windows Japan? utilities that assist in Btrieve development, additional DOS/Win/ YT: I estimate that there are about 10,000 developers who are OS2 language interfaces (most of them are for the languages using Btrieve now. I estimate that currently, about 50 percent of available in Japan only), and one year of technical support for business application packages (Accounting, Payroll, etc.) use one person. The cost for the first year is 50,000 yen, and 30,000 Btrieve as the record manager. yen for renewal. SS: Tell me more about AG-Tech Corp. SS: What has been your impression of the people who run BTI?

36 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 YT: It is difficult to say objectively, because I have known most SS: Having now met you, I might say that you do not appear to of them for a long time. Their strength would be what they have be a “typical” Japanese businessman. Do you consider yourself been doing with Btrieve over the years. The only weakness and your business different from the “norm” for Japan? would be what they did under Novell for a few years when they YT: I agree! I don’t do Golf, Karaoke, or Mah-jongg game at did not have to compete with other products directly. all! ² SS: If you could improve Btrieve, what would you change? YT: I would like to see Array Key support in Btrieve. Array keys are the opposite of Duplicate keys. Duplicate keys are when one key has several duplicate records. Array keys are when several keys point to one record. It would be very useful for keyword searches, for example. I hope it will be supported in the near future. I also would like to see 2-byte Alternate Collating Sequences. In the Japanese language, we use the Alphabet Hiragana, and also Katakana and Kanji. All characters in Alphabet and Katakana have both single-byte and double- byte characters. In some cases, the user wants to sort them as the same character. But since many Kanji have different pronunciations, even for the same characters, the one-byte ACS would not be the correct sequence for them. That is my personal opinion. SS: What do you do in your spare time? YT: Since computers are my business and my hobby, it is very difficult to divide my time into business and personal. But I do like Caribbean Music. I have about 4,000 old single records (45’s), 1,500 LP’s, 300 SP’s (78’s), and 1,500 CD’s.

(800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135 Vol. II, No. 3 July-September 1994 Btrieve Developer's Journal 37 Please let us hear from you! We want to make Btrieve Developer’s Journal just right for you. Send us any news, information, comments, suggestions, or anything else to Letters and Comments BDJ, 2416 Hillsboro Road, Suite 201, Nashville, TN 37212

Dear Btrieve Developer’s Journal, Enclosed find a recent column from the Rochester Business Journal talking about the wonderful world of Btrieve (and mentioning you too!) I appreciate your help in keeping up with Btrieve-related products for upcoming work. Thank you for your continued assistance. Eric E. Cohen Rochester, New York Dear Btrieve Developer’s Journal, We are interested in moving towards ODBC support, but we are concerned about it too. We have about 20,000 installations all running on Btrieve and the reliability and speed have been second to none! With this kind of track record and out experiences with other database formats, e.g. CTree, FoxPro, dBase, etc., the thought of support these ‘lesser’ database formats/engines with ODBC is concerning. I was wondering if there are any good articles regarding ODBC, addressing the issue of speed, reliability, broadness of the ODBC spec, etc. or if you had any other advice? James L. D. Naylor Lomita, California James, See this issue's article on Windows development using Btrieve beginning on page 12 for complete analysis of the current status of ODBC and other issues that you raise. Editor Dear Btrieve Developer’s Journal, I have one comment about the Product Review on Microsoft Access 2.0 from the APR-JUN ‘94 issue. You mentioned a problem that you ran across using MS Access with Btrieve v6.x. This is the “Unexpected error from external database (7)” message. It turns out that this is a problem with Microsoft’s Btrieve driver. We have been working with Microsoft on this, and they have resolved the problem. Users should contact Microsoft’s Product Support Services (206-882-8080) for an upgrade to the Btrieve driver. Doris Eldridge, Software Engineering Manager, Btrieve Technologies, Inc. Editor's Note: The patched version of this driver is available on the CompuServe MSACCESS forum library in the file BTR200.EXE. Dear Btrieve Developer’s Journal, My needs are rather primitive. I would like to find a set of wrapper/packaging functions to ease the use of Btrieve 5.x with QuickBasic version 4.5. Have you got such a set of functions (gathering dust on your shelves?) that you would be willing to sell me? If not, do you know of anyone who does (freeware, shareware, commercial)? Thanks! I am also interested in interfacing Btrieve 5.x with Smalltalk/V for Windows and am looking for a wrapper/package to assist in that too. Phil Engle Latrobe, Pennsylvania

Phil, You would not believe how many Btrieve-based products we do have on our shelves! We have samples from just about every company that sells anything to do with Btrieve. Most of the older materials from more that three years back have been discarded, however, because of space considerations. I remember a product called “ProTrieve” from a company in Little Rock, Arkansas, but I cannot remember the company name. Perhaps our readers can help you. Contact Phil at his CompuServe account: 71756,411 with any hints or suggestions. You may also want to check out the NOVLIB or other Novell CompuServe forums for anything there. As far as Smalltalk/V is concerned, I am familiar with the PARTS Workbench from Digitalk (714-513-3000) that helps to build components with Smalltalk, COBOL, CICS, or C. I hope that helps. Editor Dear Btrieve Developer’s Journal, Our company has offices in New Zealand and I am currently working as the lone programmer (soon to change) at our UK office. Our New Zealand office already receives your fine journal and we think it’s great. I must admit we were waiting for the report on Btrieve’s performance in the NetWare environment compared with the DOS, but maybe that will still appear in a later issue. Mark Cranness Parkshot, Richmond United Kingdom Mark, Thank you for your comments about BDJ. We are presenting a short Benchmark of overall Btrieve version 6.x performance in this issue. I can tell you now, from experience, that the speed increases of NetWare Btrieve over Btrieve for DOS are substantial, especially if you utilize extended operations (see Doug Reilly's Inside Btrieve article on Extended Operations in the APR-JUN ’94 issue). Editor Dear Btrieve Developer’s Journal, You said in your last issue that BDJ will replace the PDS Bullets publication. Does it mean that we will get no technical information about Btrieve if we do not subscribe to BDJ? Frank Heinrich Hemer, Germany Frank, Yes. The best place to get up-to-date technical information on Btrieve and Scalable SQL is right here in the pages of Btrieve Developer's Journal. Information will, of course, still be available from BTI via CompuServe, FAX, and telephone.

38 Btrieve Developer's Journal Vol. II, No. 3 July-September 1994 (800) 828-7438 or (615) 386-3100 FAX: (615) 386-3135