Winter 1996 • Vol. IV No. 4 Pervasive Launches …So let’s have fun while we do it. Call Marjean Jones at 615-386-3100 x27 (or e-mail [email protected]) and sched-ule a video-conference

THE INDEPENDENT SOURCE OF NEWS AND INFORMATION ABOUT BTRIEVE AND SCALABLE SQL

Winter 1996 • Vol. IV No. 4

By Jim BarberCrystal LinenE-mail: [email protected]

In the Autumn 1996 issue of BtrieveDeveloper’s Journal, Smithware announcedtheir Internet Data Server, or IDS. After hav-ing soap-boxed furiously for years for justsuch a product, I found myself suddenlystricken with “stage fright.” What about secu-rity? Would it actually work over sometimesslow and cranky routes? Would it work acrossmy subnets? Somany ques-tions...

Step one was to download the demo application from Smithware’s serverhttp://www.smithware.com/activex/internetand take it for a spin. I did, and it worked! Iwas running a real client-server application,accessing Btrieve data from a server that wasrumored to be somewhere in Tennessee. I

Enter the Internet —Smithware’s InternetData ServerBy Steve Mook

Smithware, Inc.E-mail: [email protected]

Austin, Texas — Pervasive Software hasbegun launch of it’s next generation relationaldatabase, Scalable SQL 4. The company plansto introduce the product to current customersover the next severalweeks with direct mail,direct response promo-tions, and informationon a new web site,http://www9.scalablesql.com.. The promo-tional web site is sched-uled to go live in Feb-ruary 1997.

Scalable SQL 4 isdescribed by the com-pany as “a comprehen-sive client/server data-base solution that pro-vides developers anduser organizations withcross-platform flexibili-ty, rich functionalityand a long-termupgrade path.” With this release Pervasivehas plans to position Scalable SQL to becomethe leading relational database for small tomid-sized companies. The company hopes toleverage their position as a leader in embed-ded databases for packaged applications

Pervasive Launches ScalableSQL 4

developed for small to mid-sized companies.Pervasive is counting on the product’s highperformance, ease of installation and mainte-nance-free operation, small memory footprint,and scalability in a fully relational database,to entice commercial application developersto bundle Scalable SQL 4 with their products.

According to Paul Antosh, product man-ager at Pervasive,Scalable SQL 4 repre-sents a completelyrevised code base, sig-nificantly different,architecturally, from itspredecessors ScalableSQL 3 and NetWareSQL. Like the compa-ny’s recentlyannounced BtrieveClient/Server DatabaseEngine for IBM WarpServer, the backbone ofScalable SQL 4 will bea new version 7.0MicroKernelDatabase Engine(MKDE). According toAntosh, MKDE version

7 represents the first total rewrite of theMicroKernel since the technology was acquiredfrom Novell, and the updated MKDE willoffer higher performance and more featureswhile maintaining a relatively small memory

See IDS, page 20See SQL, page 8

Book ReviewPage 29

Inside Btrieve — A Request For

HelpPage 21

Database HistoryPage 5

NN

aavviiggaattiioonnaall

RReellaattiioonnaall

OObbjjeeccttObject

Relational

N

avigational

i hate reporting... i hate reporting...i hate reporting... how

can i get it done fast ?

how will i finish

these reports by next week?

especially when i haven’t even

started ?

how on earth can i

create reports that do justice

to my apps ??

Crystal Reports

is the #1 award

winning report writer

for a simple reason:

it reduces reporting

drudgery while creat-

ing reports that make

you and your app look

great. That’s thanks to

powerful features like

ActiveX controls, sub-

reporting, and multi

database access. Call

us to get your copy

today (30 day money-

back guarantee). And

find out what thou-

sands of Btrieve devel-

opers already know.

y o u g o t t a k n o w ®

Smithware, Inc.2416 Hillsboro Road, Suite 201

Nashville, TN 37212 615-386-3100 800-828-7438

FAX: 615-386-3135 E-mail: [email protected]://www.smithware.com

Smithware C

rystal

Reports for B

trieve 5

.0

now available!

©1996-1997 Seagate Software, Inc. Seagate Crystal Reports, Seagate Software and the Seagate logo are trademarks of SeagateTechnology, Inc. or one of its subsidiaries. All other trademarks are the property of their respective owners. Outside the US & Canada,call 1-604-681-3435. “You gotta know” is a trademark of Ziff-Davis Publishing Company and is used by Seagate Software under license.

BDJ editor KathyJones recently cameinto my office to dis-cuss what I would betalking about in my “Fromthe Cockpit” column for theWinter issue. She happened to makethe comment, “You know, people really do read what you saythere.”

I don’t know...Was she just trying to make me feel good, orwas it a ploy to get me to actually get the piece in by her loomingdeadline? Or perhaps she just trying to make brownie points withthe boss. I seriously doubt it was that one! But it actually didmake me think...

One of the goals I have had since the first issue of BDJ fouryears ago, was to build an active working collaboration with all of the folks who use Btrieve. Wehave done this to a large degree. We’ve brought in some really talented writers, editors, anddevelopers to bring you what I think are timely, rich, well thought out articles about our Btrieveworld. We are building better relationships with other Btrieve tool vendors seeking out partner-ship opportunities. We have worked hard with Pervasive Software to make sure we get the mostcorrect and latest news from Austin.

But the one area of active collaboration that I don’t feel that I really have is with YOU, thereader. I want to tell you that I am very interested in hearing from our readership about what youthink about our publication. I also want to know what you think about our company, Smithware,and what you think about Pervasive as a company. What are we doing right, in your opinion?What can we do to make things better for you? Give us ideas on article topics that we can devel-op for you.

I really do want to hear about what’s up in your Btrieve world. So let’s have fun while wedo it. Call Marjean Jones at 615-386-3100 x27 (or e-mail [email protected]) and sched-ule a video-conference (6153860087:6153860165) with me. If you have access to a Picture-Tel orIntel-Proshare (or any other h.320 compli-ant) video system, then you’re all set.Otherwise, go to your local Kinko’s and setup a time that we can chat via ISDN. And ifyou’re not up to the video thing, please sendme e-mail at [email protected] to tellme what’s up in your Btrieve world!

From the Cockpit...Btrieve Developer’sJournal

Winter 1996: Volume IV, Issue 4

Staf fPublisher: Scott SmithEditor: Steve MookManaging Editor: Kathy JonesContributors: Jim Barber, Doug Reilly, JimKyle, Dale HunscherTechnical Corner: Linda Anderson, MichaelBeris, Kevin Brown, Doris Eldridge, VicEllisor, Mary Halbleib, David Hill, Bo Holland,Nancy Gore, Stephanie Lain, Craig Lakey,Chris Ojeda, Lance WolfeArt Director: Trudy MookPhotographers: Steve Lowry, Scott SmithIllustrators: Will Owen, Joyce RevoirAdministrative Assistant: Jane Carter

SubscriptionsAnnual subscriptions are for four issues peryear at $49/year for delivery inside the United States and Canada.Back Issues: Back issues are available for $20per issue. Contact Btrieve Developer’s Journalat 615-386-3100 for additional information.

Adver tis ingFor information about advertising your productor service in Btrieve Developer’s Journal, callKathy Jones, managing editor, at 800-828-7438 or 615-386-3100, ext. 17.

How to Contact BDJBtrieve Developer’s Journal2416 Hillsboro Road, Suite 201Nashville, Tennessee 37212Telephone: 615-386-3100Facsimile: 615-386-3135CompuServe: 73173,2731Email: [email protected]: http://www.smithware.com/bdj

Btrieve Developer’s Journal (ISSN 1071-7463) is publishedquarterly by Smithware, Inc. 2416 Hillsboro Rd., Suite 201,Nashville, TN, 37212-5318. Subscriptions are $49 per year fordelivery in the US and Canada.

PostmasterSend address changes to: Btrieve Developer’sJournal, 2416 Hillsboro Rd., Suite 201,Nashville, TN, 37212-5318.

Copyright© 1997 by Smithware, Inc. All rightsreserved. With the exception of the “TechnicalCorner” section, this publication is producedindependently of Pervasive Software. No part ofthis publication may be reproduced in any form,by any means without permission in writingfrom the publisher. Smithware is a trademark ofSmithware, Inc. Btrieve and XQL are registeredtrademarks and Scalable SQL, Xtrieve Plus andMicrokernel Database Engine are trademarks ofPervasive Software. All other names are thetrademark of their respective manufacturers.

Btrieve Developer’s Journal

Contents...

3Winter 1996

Publisher, Scott Smith

Stev

e Lo

wry

Letters..................................................4

DataBase HistoryJim Kyle defines what constitutes a data-base, and discusses the most significantorganizational models.............................5

Data Recovery — The Easy WayHow do you recover data from a damagedBtrieve file? What if Btrieve won’t open thedamaged file? Jim Kyle has answers.........9

Technical CornerPervasive Software offers Technical Insightsand Information................................13-19

Inside Btrieve — A Request ForHelpDoug Reilly discusses using Btrieve in clientand client/server development................21

Configure? Go Figure!!!Dale Hunscher of Southwind Design dis-cusses configuration problems.................27

Book ReviewA look at Doug Reilly’s book, Win32

Client/Server Developer’s Guide.............29

Smithware Tech TalkSmithware products news and technicaltips.......................................................30

Smithware, Inc.

Providing the following specialist Btrieveservices in the U.K.

• Technical Support • Consultancy• Analysis • Installation• Optimisation • Training

Authorized distributors for

A U T H O R I Z E D

SOLUTION PARTNER

Tel: (01306) 877998 Fax: (01306) 887755

Internet: [email protected] CIS: 100102,145Web: www.sthdown.demon.co.uk

Southdown House Software Ltd., Southdown House,Guildford Road,Westcott, Dorking, Surrey, RH4 3NR, U.K.

Southdown House Software LimitedSouthdown House Software Limited

Formerly Btrieve Technologies

Btrieve Developer’s Journal4 Winter 1996

Send your comments to: Letters, BtrieveDeveloper’s Journal, 2416 Hillsboro Road,Suite 201, Nashville, TN, 37212, FAX:615-386-3135 or E-mail: [email protected].

Dear Editor:We were surprised to see the

Performance Comparison Test in the Autumn1996 issue of BDJ. No one at Smithware ever men-

tioned a performance comparison test even though we hadbeen speaking to you about a review of our product, the Data

Control for Btrieve.We were even more surprised by the results cited in the article as we were

seeing much better results ourselves. When we spoke with the author of the arti-cle about the results of the performance test he said that he really did not knowhow to use our control effectively! Yet, we never received a phone call from any-one at Smithware to ask even simple questions.

The Smithware-BDJ test is a series of batch operations. By default, the DataControl for Btrieve has property settings configured for best performance whenbound to data aware controls. For batch type operations the unused features canbe disabled by simply changing a property value in the design environment. Forsome database operations, like simple key searches, certain recordset types willprovide better performance.

There are several flaws with the Smithware-BDJ test:1) The people who designed and executed the comparison test

have a financial stake in the outcome. Any objective test should be performed by someone without this conflict of interest.

2) The Smithware-BDJ test performs just some simple batch oper-ations. It does nothing to measure the amount or complexity of code for user interface activity.

3) Our control was not configured for optimal performance for the tests that were performed. We were not consulted about the test beforehand, and therefore, were unable to correct even the obvi-ous flaws in the property settings. On the other hand, the Smithware people performing the test were able to freely consult the developers of their controls to produce the best results.

We received a copy of the Smithware test after the results were published.The property settings on our control were set to produce the worst possible per-formance for the operations that were executed. We then modified the Smith-ware-BDJ test by removing code and simply changing some property values.The results we then obtained on our own machines improved dramatically andwere on the order of the Smithware controls. The results of our test can befound on our web site at http://www.classicsoftware.com. Anyone can downloadthe modified performance test and run it for themselves.

In our opinion, Smithware was not interested in an objective comparisonor we would have at least received a phone call with some simple questions.Our control provides many features not found in the Smithware controls likesupport for data binding to ANY data aware control. We are not afraid of anyreal comparison of the Classic Data Control for Btrieve to the SmithwareActiveX Controls for Btrieve. Anyone can download a demo version of our con-trol from our website.

Ed MoranPresident

Classic [email protected]

Dear Editor:I always enjoy reading the technical articles in your journal, and hope you

continue to make them informative. They have helped me in creating my pro-gram, BtSearch, a Btrieve tool to search, edit, print, export/import and a numberof other things. Btrieve has never been too well documented, so I appreciate theinformation you continue to provide.

Gil NelsonNelson Software Solutions

[email protected]

Dear Readers:Btrieve Developer’s Journal experienced mailing problems that delayed

delivery of our Autumn 1996 Issue. We apologize for any inconvenience. If youdid not receive your copy or have a question about your subscription, please callus at 615-386-3100 or e-mail at [email protected].

Kathy JonesManaging Editor

Btrieve Developer’s Journal

Letters

Austin, Texas — Pervasive Software has announced TCP/IPrequester support for both Btrieve and Scalable SQL onWindows NT and OS/2 Warp Server platforms. Upgrades forexisting installations are now available on CompuServe,(Btrieve Tech Forum) or directly from Pervasive. These newcomponents are “dual-mode,” supporting both SPX and IP.This gives existing users the option of using either protocol,and offers additional flexibility when planning new installa-tions.

Client support is provided for Windows, Windows 95,Windows NT, and OS/2. According to Pervasive, cross-plat-form operation is possible, allowing an OS/2 client to accessBtrieve on a Windows NT server, for example. This offering isbeing accepted gladly in the field, particularly by Windows NTusers who have no other need to support SPX on their localand wide-area networks. Developers will be able to targetlarge corporate TCP/IP networks that were previously“closed,” due to Btrieve’s reliance on SPX for communica-tions.

In keeping with Btrieve’s tradition of “scalability,” thesenew requester components can be used interchangeably withthe workstation MKDE, without changes to application pro-gramming. This will allow self-supporting or “shrinkwrap”application users to install and use the new requesters withoutfear of disabling their critical Btrieve applications.

TCP/IP

Btrieve Developer’s Journal 5Winter 1996

Just what constitutes a database? It seemsthat the word “database” means many differentthings to different people, so before we canmake reasonable decisions about the approachor specific tools to use when attacking a dataproblem, we need to establish some commonground and define what we’re discussing.

Much of this material appeared (in some-what different and more detailed form) in mybook Btrieve Complete, but the definitions gofar beyond any specific tool such as Btrieve orScalable SQL.

A good starting point might be to definejust what we mean by a database. The originalname, back in the 60s, was “data bank” ratherthan “database.” One definition of a “databank” is that it’s a “file of data” taken froma variety of sources and stored for readyaccess by a range of possible users.

As time passed, the term “database”replaced the more pretentious “databank.” Notice especially that this defini-tion for a database makes no mention atall of the technique by which the contentis managed, nor does it even necessarilyimply that any management at all exists.

In his tutorial book, C DatabaseDevelopment, Al Stevens presented a some-what more restrictive definition of a database.He defined it as being an integrated collectionof data files related to each other in support of acommon purpose. This definition adds theextremely important qualification that all thedata in the database be related (somehow) insupport of a common purpose. Let’s acceptStevens’ definition as being adequate if notexhaustive.

A database can be organized along manydifferent lines. Let’s look now at some of themost significant organization models, in histori-cal sequence, to see how they compare in termsof advantages and disadvantages. We’ll exam-ine, quite briefly, characteristics of five differ-ent data models. They’re called hierarchical,network, navigational, relational, and objectmodels. A sixth model, “object-relational,” isstill in the process of being defined and at pre-sent seems to mean whatever a speaker wants itto mean (in the time - honored tradition ofLewis Carroll’s Humpty Dumpty).

The Hierarchical Model

One of the earliest organizational modelswas to store data as a hierarchy of relatedrecords in a format closely resembling the tradi-tional organization chart. This level-basedapproach imposed serious constraints on free-dom to establish relations between specific

A short History of Database Technologyitems of information: each record type can haveonly one relation to a parent, but even morerestrictive is the fact that any two record typescan have only one relation linking them.

That’s the major problem with the hierar-chical model for database organization. Nomatter how the levels are initially arranged,some critical needs are almost certain to bemade difficult to achieve simply because of theorganization layers themselves. The restrictionto a single relation between different recordtypes, necessary in order to define the hierar-chy, makes the problem inescapable.

A secondary problem is nearly as serious(and may in some cases even be worse): Such adatabase becomes all but impossible to expandor modify, except after total redesign from thetop down. This total redesign requirement oftenproves too costly to even be considered. Thedatabase then remains static while the businesschanges. Eventually the database becomescompletely outdated. This is a major reasonwhy “legacy systems” and “problems” are oftenconsidered identical in meaning.

The Network Model

Another early organization method places

essentially no restrictions upon the number ofrelations in which a record type may partici-pate. In this “network” model, a single recordmay be, all at the same time, related to two ormore different “parent” records while having anumber of “siblings” and even “children.” Thefamily-based terms that describe the levelsinvolved reflect the metaphor from which thismodel came.

To a large degree the network modelembodies concepts first popularized in theearly days of computer research. The linkedlist, first described in 1951, provided a degreeof generality that appealed to researchers.Language developers came up with IPL-V andLISP based on the list structure. Systems theo-rists developed processor architectures usingthe idea of list linkage, and most of our modernCPU designs descend from these. And those

folk most concerned with “data processing”applied the idea to help organize their col-lections of data items.

One of the most influential of thesenetwork-model systems was the IntegratedData Store (IDS). Charles Bachmandeveloped IDS at the General ElectricCompany’s computer division in Phoenix,AZ, during the late 1950s, making it pub-

lic in 1961. In this design (which eventuallybecame a major part of the COBOL stan-

dards), records of the database are linked into“chains.” Links can be “masters,” “slaves,” or“details,” and the only limit to the number oflinks allowed for any single record is the recordsize itself.

To retrieve information from an IDS data-base, one first traverses the master chain to findthe record type involved in the search. With thetype’s master record located, tracing out itsslave and detail chains leads to the desired spe-cific record. While this process may soundcumbersome, it took full advantage of the capa-bilities of then new disk storage devices.Consequently, a well-designed IDS system’sperformance usually surpassed that of compet-ing data organizations.

The Navigational Model

According to some authorities, the naviga-tional model includes both the Hierarchical andNetwork models within its bounds. I use thephrase to refer specifically to the flat-file, card-index-oriented type of database most widelyknown in the desktop computer industry.

The industry uses a number of other termsbesides “navigational model” to describe thisstructure and technique. General Electric andHoneywell Bull labeled it the “IndexSequential Processor” (ISP). IBM calls it“Indexed Sequential Access Method” or

By Jim KyleAutomation Resources, Inc.E-mail: [email protected]

NN

aavviiggaattiioonnaall

RReellaattiioonnaall

OObbjjeeccttObject

Relational

N

avigational


ISAM, as do some Microsoft products.Examples of commercial products based

on the navigational model include xBase(including dBase, FoxPro, Clipper, Phase3,and a number of others using the DBF file for-mat), and Vulcan/EB. Several other popularproducts, including Access, Paradox, andClarion, can be used as navigational struc-tures, although their architecture is not neces-sarily that of the flat file.

The only product that emphasizes its nav-igational aspect, though, is Btrieve itself. Forthe original version, and all subsequent releas-es, the built-in application programming inter-face (API) is totally navigational in nature.

How does a navigational record managerwork? To describe the characteristics of thenavigational model, let’s start with the firstpopular desktop program built on this model,dBASE. In the March 1991 issue of DataBased Advisor magazine, this program’s origi-nator, C. Wayne Ratliff, told how the packagecame into existence.

Ratliff first became interested in creatingan English-like interpretive language in 1975,for extracting statistics from data sets. Thiswas not a part of his job on the Viking Mars-lander project at the Jet Propulsion Labora-tory. Instead, it originated from his participa-tion in office football pools. Within a fewdays, however, his emphasis shifted from foot-ball to the possibilities inherent in the lan-guage itself.

By November 1976, Ratliff had acquiredan IMSAI computer, and during the next 15months, he brought it up to full operationalcapability. During this time, he came acrossthe JPLDIS (JPL’s internal database system)manuals in the lab’s library. In January 1978,he began writing a program to interpret a sim-plified subset of the JPLDIS commands.

According to Ratliff’s account, the DBFfile format common to all the xBase languagescame into existence on January 29, 1978,“probably around midnight.” With a file for-mat established, Ratliff went on to implementthe commands CREATE, DISPLAY STRUC-TURE, DISPLAY, APPEND, and EDIT. In themonths that followed, he added additionalcommands, mostly modeled on the keywordspresent in BASIC.

Ratliff called his original programVulcan. The name changed to dBASE in 1980when Ratliff joined forces with George Tate.Tate formed a firm named Ashton-Tate(Ashton was the company mascot, a parrot) todistribute dBASE as a commercial product. Itsfeatures have constituted a benchmark for“compatibility” in the desktop database indus-try ever since.

These features, present in virtually allnavigational-model approaches, include thestandard Create-Retrieve-Update-Delete(CRUD) functions. Multiple indexes are notonly permitted but are encouraged. All dataitems within a specific file share the samerecord format, and the only relations estab-

lished are those implied by the appearance ofdifferent fields within the record. This single-format restriction gives the model its commonname, “flat file.”

Navigation from one record to anotherwithin the file uses the current index to estab-lish which records are first, last, previous,next, and current. Changing the index in usethus changes the effective sort order of the filealthough no physical data movement occurs.

Applications using this data modelinclude the whole dBase family, Btrieve, manymainframe applications built with COBOL,many legacy desktop applications originallydone in MBASIC, and most “flat file” data-bases. Despite the popularity of the newerrelational approaches that we’ll examine next,the navigational model probably still accountsfor a significant portion—if not the majority—of all data applications in existence.

The navigational model is unsurpassedfor such sequential tasks as repetitive dataentry, and its machine-level primitives are vir-tually required for implementation of all otherdata models. That is, any other data model canbe constructed on top of the foundation thatthe navigational primitives provide. This sim-ple fact is the heart of Btrieve’s microkernelapproach: the microkernel provides the primi-tives while a higher-level layer provides anappropriate model implementation.

The Relational Model

While most discussions of database man-agement systems (including this one) view therelational model as an entity totally distinctfrom all other data models, at least one expertsees it as a special case of the network model.Ben Shneiderman has written that a relationaldatabase is a network database in which therelations between data types are handled in aquite specific manner.

The apparent distinction, inShneiderman’s view, stems from the terminol-ogy used to describe relational databases,which is quite different from that in everydayuse for all other models. For example, theeveryday “relation” between data typesbecomes, in the RDBMS vocabulary, an“interrelational dependency.” The word “rela-tion” itself then refers to the record type.

The relational theory of database organi-zation made its first public appearance in a1969 IBM Research Report by E. F. Codd,titled “Derivability, Redundancy, andConsistency of Relations Stored in Large DataBanks.” The actual model was described byCodd the following year in theCommunications of the ACM, and quicklyattracted interest from many parts of theindustry. A major reason for the model’s rapidacceptance was its solid base in mathematicaltheory; nearly all previous database modelshad simply evolved pragmatically based onempirical experience.

Because of the theoretical underpinnings,

Codd felt it essential to use the mathematicalvocabulary rather than the existing databasejargon. Thus instead of files of records witheach record composed of fields, a relationaldatabase contains tables, organized into rowsand columns. The metaphor is that of a matrixor a multi-dimensional array. Each data itemmay be (and usually is) spread across severaltables, as one row of each table. The collec-tion of rows composing a single data item thenbecomes a relation, since it’s expressed interms of interrelational dependencies betweenthe tables which identify which row (or rows)of table A is related to a specific row of tableB.

Relationships, in other words, are repre-sented by including certain data items in morethan one table. These specific matching dataitems, or keys (not to be confused with thekeys, more properly termed indices, used inBtrieve), take values from a shared domain ofpossible values. All rows with matching val-ues in such key fields participate in the samerelationship.

In practice, one column in the rows ofeach table (known as the “primary key” forthe table) uniquely identifies each row withinthat table. This primary key establishes thedomain of possible values for dependencies inwhich it participates. Other columns withineach table establish any dependencies. Thesecolumns contain values that are in domainsestablished by other tables within the data-base, and are called “foreign” keys.

In 1985, Codd published a set of 12 ruleshe said must be met before a system could beconsidered fully relational. Paraphrased from aMay 1986 report written by Codd (and reviseda year later), these rules are:

1. All information in the database must be represented explicitly by values in relational tables, and in no other way.

2. Every atomic value of information in the database must be logically acces-sible through a combination of table name, primary key value, and col-umn name.

3. Indicators for “missing” information, distinct from blank or empty space, must be supported and must be inde-pendent of data type; the DBMS must also be capable of dealing with these indicators as if they were actualdata.

4. The database must be fully described in a data dictionary, which must be represented in the same manner as all other data so that users can deal with it in the same way.

5. At least one language must be provided for dealing with the database, and this language must support


data definition, definition of views, manipulation of data both interac-tively and by program, integrity of information, security of the data, and establishment of transaction bound-aries.

6. An algorithm to determine (when a view is defined) whether that view is capable of modifying data both at therow level and for each column withinthe view, must be provided; results ofthis determination must be recorded in the data dictionary (rule 4) entries for the view.

7. The DBMS must be able to deal withboth base relations and derived rela-tions as a single operand during retrieval, insertion, update, and dele-tion operations.

8. Changes made to either storage for-mats or access methods must have nological impact on application pro-grams.

9. Any kind of changes to the base tables that are capable of preserving information unimpaired must do so without affecting application pro-grams.

10. Any applicable integrity constraints must be capable of definition in the data language (rule 5) and must be stored in the data dictionary (rule 4). Two such constraints that apply to every DBMS are that no component of a primary key may have a missing value, and each non-missing for-eign key’s value must match the value of an existing primary key in the same domain. These are known as “entity integrity” and “referential integrity” respectively.

11. The database must preserve all appli-cations without impairment if data distribution is introduced, or if data is re-distributed.

12. If the database can be accessed by a low level language, that low level must not be able to bypass or subvert the integrity constraints of Rule 10.

Few, if any, commercially available sys-tems completely meet more than 11 of theserequirements. The stumbling block, in mostcases, is Rule 12, since any data can be modi-fied by machine-language intervention. Thisfailure, however, has not prevented anyonefrom claiming full RDBMS functionality for aproduct.

Among products based primarily on therelational model we find IBM’s DB2, Oracle,

Paradox, Access, and many others. The mostwidely used data query language, StructuredQuery Language or SQL, presumes the rela-tional organization and meets the requirementsof Rule 5. Little doubt exists that the RDBMSis, today, the standard for information technol-ogy.

Btrieve now includes features to supportits relational-model relative, Scalable SQL.Scalable SQL provides an effective RDBMSinterface to underlying data and provides fullyrelational organization. The microkernel thatforms the foundation of both Btrieve andSSQL in their most recent versions providesfull relational integrity of data (one of themost difficult of the 12 rules to deal with) atthe engine level.

The major advantage of the relationalmodel is its ability to improve data integrityand to assure consistency in representation.The price paid for this advantage is a signifi-cant increase in complexity of the databasedesign, and possibly somewhat poorer perfor-mance. The performance issue is still hotlydebated, but with modern systems and propersystem design appears to be more mythicalthan real.

How does SQL relate to the relationalmodel?

Shortly after Dr. Codd published his rela-tional database theories, IBM’s research centerput together something called StructuredQuery Language (SQL, often pronounced“sequel”) to comply with Rule 5 of the 12rules. Thus the RDBMS model significantlyinfluenced the structure and syntax of SQL.As a result, SQL and RDBMS became almostsynonymous to most computer users.However, even though SQL is built upon therelational model, a database need not be rela-tional in itself to use SQL.

As the relational model grew in populari-ty, SQL advanced right alongside. Originallyconfined to IBM’s mainframe databases, itbecame more generic when Oracle introducedits version in 1979. By 1986, the languagebecame an ANSI standard (revised in 1989and again in 1992). At least 140 different data-base products with SQL capability had beencounted by 1993, according to MartinGruber’s SQL Instant Reference book.

SQL differs significantly from conven-tional programming languages. Possibly themost striking difference is its non-proceduralapproach. Where programming languagesspecify, step by step, every action required tosolve a problem, SQL merely states whatresult is required and leaves the rest up to theDBMS.

Because of this generality, SQL is proba-bly the most widely known information-retrieval method in use today. The 1992 ver-sion of the standard is five times as long as the

original 1986 document.

The Object Model

Most of today’s pundits seem to considerobject orientation the next “silver bullet” forsolution of all software problems. When writ-ing Btrieve Complete, I asked Rud Merriam, aHouston consultant who was working on theo-retical justification for object data base man-agement systems at that time, to explain forme just how an ODBMS differs from the moreconventional variety.

“Data management research didn’t stopwith the advent of the relational model, “heexplained.” A specific area of continuing inter-est involves complex objects. To deal withthese, several workers have extended the rela-tional model, by relaxing its implied normal-ization requirements while maintaining a rig-orous mathematical foundation. This led to thedevelopment of Object Database ManagementSystems (ODBMS).

“Currently, ODBMS are used primarilyas application—specific data managementtools. In the applications where ODBMS arebeing used, they are of great value.”

“One area of common use is for storageof graphic information such as that in CAD,CAM, and CASE tools. Such an applicationcontains well-defined object classes and well-defined relationships between those objects. Inthese applications, too, retrieving one objectnormally draws upon relationships to bring inmany other objects.”

“In a CAD drawing, bringing in a Widgetalso brings in a multitude of lines, arcs, fig-ures and notations. Using other database formsto access all these other objects by indexes ishorribly time consuming.”

The jury is still out as to the advantagesof the ODBMS for general use, however. Onlya few commercial products yet exist, and userreaction to them has been mixed at best.

The Bottom Line

As we enter 1997, only three of the datamodels discussed here remain significant.They are the navigational model, the relationalmodel, and the object model. Of the three, thenavigational model remains central to anyactual implementation since it provides thefunctions to manipulate the stored data at thehardware level. However, at the applicationlevel, presence of the navigational model mayeasily be hidden by a relational or object-ori-ented layer that mediates between the applica-tion and the underlying data managementengine.

A successful database developer mustknow the characteristics of all three data mod-els, in order to choose which will be best suit-ed to the task at hand. Using the wrong toolfor any job will guarantee less than optimumresults.


FotoFlood Brings Catalog Salesto the WebLachine, Quebec — FotoFlood, a customizable and secure web-hosted

multimedia database, allows companies to build product catalogs for

marketing and distribution of products and services on the Internet.

According to Epicad, the makers of FotoFlood, the product is Built-on-

Btrieve and dramatically reduces the time and effort involved in getting

data from databases and presenting it on the web.

FotoFlood is a repository for merchants who have thousands of

image files. Conventional authoring for such large volumes of images

and product information becomes impractical and server performance

becomes a key issue. FotoFlood is designed for building and publishing

cataloging applications with high volume images and includes a database

where customers can perform searches. It also offers features to imple-

ment on-line catalog sales.

Epicad is distributing FotoFlood through “Value Added” Internet

service providers, web site developers, imaging service bureaus, system

integrators and consultants.

The price is $2,295 US, and the Single Server Client Application

Licenses start at $1,195 US. For more information, visit

http://www.epicad.com or contact Epicad Design Inc. at 514-634-0638

or fax 514-637-1506.

New Titan Versions Now Available for Delphi ReggattaSystems Outlines Plans for 1997

Oakland, California — Reggatta Systems has announced that several newreleases of their Titan product line are now available. Titan is a series of productsthat offer additional database options to developers who use Borland’s Delphidevelopment environment. Current Titan products include Titan Btrieve, whichgives Delphi native access to Btrieve, and Titan Btrieve SQL which uses ScalableSQL to support SQL queries in Delphi.

Titan Btrieve currently ships in two versions. Titan Btrieve version 1.50supports 16-bit Delphi 1.x while Titan Btrieve version 2.01 supports 32-bitDelphi 2.x. One of the primary benefits of developing with Titan Btrieve is thatDelphi developers can use standard Delphi components to build Btrieve appli-cations. (See Jim Barber’s review of Titan Btrieve in BDJ Vol. III, Issue 3,Autumn 1995).

Titan Btrieve SQL 1.5 uses Scalable SQL to fully integrate Delphi withSQL. Titan SQL is compatible with Delphi’s TQuery component so that resultsof Scalable SQL statements can be displayed in all of the Borland data-awarecomponents at design and run-time.

All Titan products support all of the Delphi visual development tools suchas Database Form Expert, Field Editor, and Master/Detail Relationshipsbetween tables. Titan products also support most of the Smithware extendeddata types via DDF Builder extensions. New features of Titan include the abili-ty to compile DDFs and include table definitions as part of a compiled project.Titan is also compatible with 3rd party add-ons like Orpheus and InfoPower.

According to Peter Blair, president of Reggatta Systems, “We are in theprocess of building releases of Titan that will support the upcoming releases ofDelphi 97, and also Borland’s new C++ Builder. C++ Builder is an excitingdevelopment for us because brings Delphi’s ease of development to C++.”Reggatta is also developing a version of Titan for Sybase SQL Anywhere, andwill soon complete Titan for Access which gives Delphi native access to MSAccess .mdb files.

Free trial versions of Titan, as well as complete product and orderinginformation, are available at http://www.reggatta.com or contact Reggatta at800-873-0569 or fax 605-845-7627.

SQL ...continued from page 1

footprint.The new version includes features that many long-time

Pervasive customers have been waiting for. Scalable 4 has beenenhanced to more closely conform to Microsoft ODBC, ANSISQL and IBM SAA standards. According to a source at Pervasive,the version 2.0 ODBC interface implements “about 99 percent” ofthe ODBC to specification, and Scalable SQL for provides imple-mentation for all but three rarely-used SQL operations.

The company maintains that Scalable SQL 4 will be com-pletely compatible with existing applications and databases writ-ten with Scalable SQL 3. Compatibility with Btrieve applicationsand data will also provide the ability to convert existing Btrievenavigational data and applications to the relational SQL format orto add Scalable SQL 4 functionality to existing Btrieve databases.

Scalable SQL 4 also implements SQL triggers and stored pro-cedures. Triggers can be declared for a database to run a storedprocedure if certain operations are performed, or if certain condi-tions are met in the data, and can be useful in enforcing businessrules at the database level. Stored procedures can also be calleddirectly by an application. Scalable SQL 4 represents the firstcommercial deployment of the company’s new Inscribe scriptingtool for creating and editing stored procedures. Inscribe allowsdevelopers to create stored procedures using a syntax compatiblewith Microsoft Visual Basic.

Though SQL rules specify the syntax for queries and stipulatewhat the results of a particular query should be, they say nothingabout how the data is to be gathered. Cost-based optimization, anew feature in Scalable SQL 4, uses statistical analysis algorithmsand new MKDE features to optimize the data gathering process.

Other enhancements in the new MKDE which Scalable SQL4 takes advantage of include automatic index balancing, the abilityto perform nested transactions, and transactional logging, whichlogs each transaction and allows the data to be rolled back to thelast accurate point in a nested transaction in case of system failure.The new MKDE supports individual data file sizes up to 64GB, asubstantial increase over the 4GB limit imposed by previous ver-sions.

Scalable SQL 4 also adds three new data types: time stamp,unsigned, and currency, bringing the total number of field typessupported by the database to 21. The unsigned data type adds sup-port for unsigned integer and long integer values which previousversions of Pervasive’s relational database products have lacked, acurious omission considering the fact that they are supported byseveral programming languages, and were one of only two keytypes supported by Btrieve prior to Btrieve version 3. Both thetime stamp and currency data types can be masked to store anddisplay international values for dates, times, and monetaryamounts. The new currency data type is a large-capacity storagetype with a configurable number of fixed decimal places designedto handle international currency values and very precise financialdata such as interest rate calculations.

Scalable SQL 4 database engine pricing will vary dependingupon user count, with ten-user client/server stations priced at$995.00 with increments of ten users available. The company alsoplans deployment license pricing for commercial software devel-opers.

the easy way


We’ve all been there at one time or another. You’ve just delivereda finished custom system. Your customer is extremely happy with it.You’re sitting back, taking pride in a job well done. Then the phonerings.

Your customer is on the other end of the line. Her voice has anote of panic: “We just lost power over here for an hour. It’s back onnow, but we can’t find any of the stuff that we spent all morning typ-ing into the system! Can you help us?”

This doesn’t happen nearly as often as it once did, since the intro-duction of shadow imaging at Btrieve’s version 6.1, but occasionally itstill does. One of Btrieve’s strongest points is its ability to protect datain cases like this, but not even Btrieve can work miracles.

When you need to recover data from a damaged Btrieve file, youcan choose from a wide selection of tools. They include the Save andRestore options in BUTIL. Alternatively you can use a third-party edit-ing/maintenance package. Both Doug Reilly (Access Microsystems,BTFILER) and André Larmet (C-Soft, BTEdit) offer these. Such toolscan usually bring back most of the data after a serious database crash.

Sometimes, though, Btrieve just won’t open the damaged file atall. Since all the usual data recovery tools require the Btrieve enginefor getting the records out of the file, they’re unusable when this hap-pens.

Fortunately, a method exists for recovering most if not all the datafrom a damaged Btrieve file, that doesn’t require the Btrieve engine toeven be loaded. While it won’t recover information from an encryptedfile, it does get almost everything else. To work this magic, you need aprogram that uses undocumented knowledge of the Btrieve file format.

I came up with just such a program while writing BtrieveComplete, and it’s one of the samples in the book. I learned the valueof DATADUMP.EXE a year ago, when a power failure crashed a just-loaded Btrieve database at a customer site, before they had created anybackup files for the data. Btrieve wouldn’t even recognize the dam-aged data file as being a valid Btrieve file. DATADUMP, however, hadno problems with it, and recovered every record. This saved the cus-tomer many hours of re-keying effort and convinced me that the tech-nique should be more widely known.

However, the original DATADUMP.EXE file that’s in the bookand on its accompanying diskette has a serious (though not fatal) errorthat can drive you to distraction should your data bring it out of hiding.

The bug affects only compressed files with variable-lengthrecords. However, any time you need to recover such a file there’s agood chance that the program will go quietly crazy and attempt touncompress the next four gigabytes of data from your memory buffer!Never mind that you don’t have that much available; the program willtry anyway.

Fortunately files of this sort are rare enough that I’ve had onlythree reports of the problem, and all three came from the same organi-zation over an 18-month period. With a sample file that could triggerthe bug every time, it still took me several weeks to track it down andapply fixes; it’s just that obscure.

The bug is now laid to rest, and a bit later in these columns I’llexplain it in detail. To avoid confusion with the original buggy version,I’ve changed the program’s name to DATASAVE.EXE. You don’t needto know all the technical details, though, to use DATASAVE. Just fol-

low the bouncing ball. That is, the procedure I’m about to describe.

Getting the File Package

The very first step, of course, is to have your own copy ofDATASAVE.EXE available to use. You can download the ZipFile con-taining both the full program source and the executable file, fromBDJ’s Web site at http://www.smithware.com/bdj/datasave.html.

Once you’ve downloaded the file onto your own system, usePKUnZip, WinZip, or the other unzip program of your preference toextract the EXE file from the package. Copy DATASAVE.EXE onto afloppy diskette so that you can easily take it to your customer siteswhen need be. Note that the program runs under MS-DOS, not underWindows. You may want to format the floppy as a bootable systemdiskette, just in case the customer hasn’t made the DOS interfaceavailable at all workstations.

The ZipFile also includes everything you need to recompile theEXE, using either Borland or Microsoft 16-bit C compilers. This letsyou use the modules within the source file as parts of your own cus-tom package should you want to do so. If you don’t need the sourcefiles or change log, you don’t need to extract them from the ZipFile.Only DATASAVE.EXE is necessary for data recovery.

Recover the Data First

The first step in using DATASAVE to recover data from a dam-aged file is to change the working directory to the one that contains thedamaged file. Then at the command prompt type A:DATASAVEFileName, where “FileName” is the name and extension of the fileyou’re trying to recover. If you copy DATASAVE.EXE into the samedirectory, the “A:” prefix to the command isn’t necessary.

You’ll then see a banner and copyright notice from the book,which still lists the original name DUMPDATA rather than the newone. It’ll be followed by two lines like these (although the values maydiffer and should match those of the file you’re trying to recover):

File TEST.DAT is in new format; pagesize = 3072, has 25 pagesRecord count = 126 (Compressed variable-length).

The screen will also show the following prompt:

Write SAVE file, or VIEW data on CRT (S or V)?

The proper response here, for recovering data, is S. When you pressany key the program takes off without waiting for another keystroke,but if the key is anything other than S or V, it merely repeats theprompt. When you press S, you get a prompt for the name of the filein which to write the recovered data (the filename in italics was myresponse to this prompt):

Save to filename: mysave.asc

DATASAVE then goes through the file, recovering every record that itcan locate and writing each record to the file you told it to use. The pro-gram writes each record in the format that BUTIL -LOAD expects, so

data recoveryBy Jim Kyle Automation Resources, Inc.E-mail: [email protected]


that the final file can provide direct input to the standard tool in a subse-quent step.

When the recovery operation completes, DATASAVE returns to thecommand prompt with no additional messages.

You can use the V option if you want to view the file in a combina-tion hex-value and ASCII format. This can be helpful if you need torebuild DDF files or do some similar operation requiring knowledge ofthe record layout, but is seldom useful for data recovery. Next, Create aNew File.

Once you’ve written a recovery file with all the records possible,the next step is to create a new, empty data file with the same recordlayout. One way to do this is with the BUTIL -CLONE option, whichsometimes works even though BUTIL cannot recover any data from theoriginal. If you have DDF files for the package you can rename the orig-inal damaged file, then use the DDF files to create a new empty version.Finally, if you have an older backup copy of the file (even though itsdata is no longer valid) you can restore that copy to obtain an undam-aged version that has the proper format, then CLONE that one to pro-vide an empty copy.

Other methods, also, may occur to you. It doesn’t really matter howyou get there; the goal is to obtain a totally empty file with the nameand record structure of the one you’re recovering. Once you've gottenthis far, the rest is easy.

Finally, Restore the Recovered Data

The final step in this data recovery technique is to use the recoveryfile you created with DATASAVE as input to the BUTIL -LOAD option,to put all recovered records into your replacement copy of the file. Thisassures that Btrieve itself does all needed indexing.It’s possible that you may fail to recover every record from the damagedfile. If the original crash made an entire data page unreadable, for exam-ple, then every record on that page will vanish. Nevertheless when youwork with large volumes of data, it’s much less painful to lose a page ofdata than it is to lose the entire file. Once the recovery process com-pletes, you need to print a full report of all records so that the users canverify that all records have been restored, or identify the lost ones if thisisn’t the case.

With Version 6 format files, it’s also possible (though unlikely) thatyou may recover invalid records. That is, you may recover both the pre-change and post-change copies of one or more records. This can happenif the Page Allocation Tables (PAT pages) themselves were damaged.However, I’ve never heard of this happening; it’s possible, but not worthworrying overmuch about. Again, careful proofreading after recoverycan catch such things.

How DATASAVE Works

If you’re curious about the way this approach works, here’s anabbreviated explanation. The complete details take up a full chapter inBtrieve Complete, and obviously we don’t have room for that here.Any Btrieve file, as you probably know, consists of a sequence of fixed-size pages that can be any multiple of 512 bytes up to 4,096. Each pagecan be one of several “page types” but for our purposes we can classifythem into just four types: header pages, data pages, PAT pages, and allother kinds (including index pages). PAT pages didn’t exist beforeVersion 6.0.

Except for the header page or pages (Version 6 formatted files havetwo header pages while older formats have only one) every Btrieve pagebegins with a 32-bit page-ID area followed by a 16-bit “usage count.”

Every data page has the most significant bit of its usage-count fieldset to “1.” Thus, if the usage count field for any page has an unsignedvalue less than 32,768, that page cannot be a data page. However, if thevalue is 32,768 or greater, it DOES hold data. Each data page containsanother field that tells how many of the possible records on that page arevalid.

DATASAVE’s algorithm simply starts with the first page of the file,which is always a header page. After extracting essential information

such as the page size itself, the file’s format, the data storage type (fixedor variable length, compressed or uncompressed) and the number ofrecords to expect from the header page, the program then begins cyclingthrough the pages from front to back looking for those pages with usagecount fields greater than 32,768.

Each time it finds a data page, the program sets up a record counterand cycles through the records on that page, processing each in turn.

The details of processing vary, depending on the record’s storageformat. Variable length records, for instance, contain linkage to otherpage types that contain the variable parts of the records. Compressedrecords require internal processing to reverse the compression. Thechoice of which processing to apply takes place as each record appears,and all the processing routines come back together at the end of eachrecord’s actions.

The Elusive Insect

The rare bug that afflicts the original DUMPDATA programsneaked in because it’s possible to have several unused pointer positionswithin an internal table that’s part of the variable-length record process-ing. Such unused positions contain a key value of 0xFFFF to tell theBtrieve engine to skip over them during data recovery.

My original DUMPDATA program detected the first such unusedpointer and ignored it. Unfortunately, having skipped over the first0xFFFF value, it then quit looking for any more. Consequently whentwo or more consecutive pointer positions held values of 0xFFFF, theprogram skipped over the first one but accepted the second as beingvalid.

Accepting an invalid pointer as “good” was bad enough, but theproblem was even worse. At this point, the program calculates the num-ber of bytes to process by subtracting one pointer value from another.When the second pointer is 0xFFFF and the first cannot be greater than0x0FFF (the maximum size of a Btrieve page, minus 1), this guaranteesthat the most significant four bits of the difference will all be “1.”During the calculation, these bits force sign extension of the result, andcreate a final length value in the neighborhood of four billion! The pro-gram outruns its memory limits immediately.

To fix the problem, I added an additional variable (named “skip-per”) within the record-processing module, and created an additionalsearch loop at the point where the unused pointers are detected, so thatall of the unused pointers get passed over instead of just the first one.While I was at it, I made a number of cosmetic changes, and quadrupledthe size of the work buffer to allow for expansion of records up to a sizeof 16K bytes.

Summing Up

The revised program has proved its worth in many situations.While I’ve copyrighted the source code, you can use the executable as atool for diagnosis and data recovery with no restriction. The purpose ofthe copyright is primarily to prevent anyone from re-selling DUMPDA-TA or DATASAVE intact as a product (a secondary purpose is to protectpublication rights, of course).

Download a copy today from http://www.smithware.com/bdj/datasave.html, and try it with some sample files. When the time comesthat everything else fails, you’ll be glad you did.

DUMPDATA — from Btrieve Complete by Jim KyleCopyright 1995 by Jim Kyle — All Rights ReservedCommercial distribution prohibited.

File TEST.DAT is in new format; pagesize = 3072, has 25 pagesRecord count = 126 (Compressed variable—length).

Write SAVE file, or VIEW data on CRT (S or V)?


Nashville, Tennessee — Four months after the general release ofCrystal Reports 5.0 from Seagate Software, Smithware hasannounced that version 5.0 of Smithware Crystal Reports forBtrieve is now available.

Seagate Software, the manufacturers of Crystal Reports, hasprovided a number of new features in version 5, includingfree-form report design, greater control over report ele-ments using formulas, the ability to create sub-reports, and the capability to export reports to anumber of new formats, including HTML. Inaddition to the report writer enhancements,Smithware’s version adds the capability to useapplications developed in Magic 7, the rapidapplication development system from MagicSoftware Enterprises, as data sources forreports.

Smithware President Scott Smith indicatedthat the delay in shippng Smithware’s versionwas the result of the company’s efforts to makesure that the product would work well with Btrievedata. “There were some real pesky little bugs that wehad to iron out with Seagate before we could put our stamp ofapproval on Smithware Crystal Reports 5.0 for Btrieve,” saidSmith. “We did not want to ship the product until we knew that itwas ready to deal perfectly with the variety of Btrieve data outthere.”

Because Smithware Crystal Reports 5.0 for Btrieve requiresalmost 100 megabytes for a full install, Smithware is making theproduct available only on CD-ROM. The CD-ROM includes boththe 16-bit and 32-bit editions of Smithware Crystal Reports 5.0 forBtrieve. It also includes a demonstration of the Crystal 5.0

Interactive Learning CD, a four hour computer-based train-ing program developed by Seagate Software to intro-

duce users to the features and capabilities of thereport writer and train them in using it effectively.

The suggested retail price of Smithware CrystalReports 5.0 for Btrieve is $495.95 and includesthe complete Crystal Reports 5.0 ProfessionalEdition, Smithware DDF Builder and DDFSniffer, and Smithware’s High PerformanceBtrieve drivers for Crystal Reports. Registeredusers of Smithware Crystal Reports version 4.5

for Btrieve can upgrade for $229.The Crystal Reports 5.0 Interactive Learning

CD is also now available from Smithware. TheInteractive Learning CD normally sells for $99, but

through April 30, 1997, Smithware is making it availableto Smithware Crystal Reports 5.0 for Btrieve customers at the

special price of $69.See http://www.smithware.com/products/scrwb.html for com-

plete information, or contact Smithware by phone 800-828-7438 or615-386-3100, fax 615-386-3135, or e-mail [email protected].

Smithware Crystal Reports for Btrieve Available

Smithware, Inc.2416 Hillsboro Road, Suite 201, Nashville, TN 37212

615-386-3100 FAX: 615-386-3135E-mail: [email protected]://www.smithware.com

Version 5.0

Instructions: Run d:\setup (where d is the drive letter for your CD-ROM drive)

©Co

pyrig

ht19

88, 1

997

bySm

ithw

are,

Inc.

All

right

sres

erve

d.

Smithware


2416 Hillsboro Road, Suite 201Nashville, Tennessee 37212Phone: 615.386.3100 Fax: 615.386.3135E-mail: [email protected]://www.smithware.com

Please send me a one-year, four-issue subscription to Btrieve Developer’s Journal($49) for delivery within the US & Canada, $79 elsewhere). I am:

A new subscriberRenewing my subscription for another year (4 more issues)

Please send me Btrieve Complete for only $24.95Please send me The Illustrated Guide to Netware Btrieve for only $24.95

Name _______________________________________________________Address _______________________________________________________

_____________________________________________________________________________________________________________________________________________________________________

Please charge my: Visa MasterCard American ExpressCard# _____________________________________ Expires_______________Signature ________________________________________________________

Start Your Subscription or Renew Todayand Get Special Subscriber Discounts!

Take advantage of special subscriber discounts on BtrieveComplete and The Illustrated Guide to Netware Btrieve.These two great reference books should be part of everyBtrieve and Scalable SQL developer’s library. They containa wealth of up-to-date information, including tips forunderstanding, configuring, and programming the Btrieverecord manager. For a limited time, you can save up to $30when you begin or renew your subscription to BtrieveDeveloper’s Journal. Both books retail for $39.95, but withyour paid subscription to BDJ, get either book for $24.95,a $15 savings off the cover price. Buy both, and save $30!

Offer good only in conjuction with new subscriptions and renewals. Book will beshipped when payment is received. Limit one copy of each book per subscriber.

Save$30

Access Microsystems, Inc.

404 Midstream Road • Brick, NJ 08724908-892-2683 FAX: 908-892-3737

CIS: 74040,607

Services for Btrieve Users:• Programming/Consulting• File Recovery/Utilities BTFILER & BTVIEWER

• Training

TOP GUNS FOR HIRE• ODBC-Related Consulting & Product Engineering• Fast Assistance Resolving Btrieve & Scalable SQL

Configuration Issues

When you need the best in ODBC consulting or help with tough config-uration problems, it makes sense to talk directly to the engineersbehind the Pervasive Software ODBC Interfaces and the SupportAbilityproduct line!

Call South Wind Design, Inc. @ 800-897-9463International call +1-313-213-0118 FAX +1-313-213-0155

Post Your Messageon the BDJ

Bulletin Board!For more information, contact Kathy Jones,

Managing Editor, Btrieve Developer’s Journal,

800-828-7438 or 615-386-3100 ext. 17

WINTER 1996 SUPPLEMENT TO BTRIEVE DEVELOPER’S JOURNAL

SUPPORT FOR BTRIEVE APPLICATIONS IN A NOVELL DIRECTORY (NDS) ENVIRONMENT

Formerly Btrieve Technologies TECHNICAL CORNER


Pervasive Software supports the useof Btrieve applications in a NovellDirectory Services (NDS) environmentwhen Btrieve file pathnames are speci-fied using the NetWare bindery namingconvention or the Universal NamingConvention (UNC). This allows users ofBtrieve applications to log into Net-Ware through NDS. Support for filepathnames specified using NDS path-names will be included in future releas-es.

The NetWare bindery naming con-vention or UNC must also be usedwhen defining drive letter mappingsused in Btrieve file pathnames. Supportfor this configuration requires the use ofthe Btrieve requester componentsincluded in the December 1996 Btrievev6.15 for NetWare product update andthe Novell client software. Specificconfiguration information for the use ofdrive letter mappings is describedbelow.

NetWare 4.x offers network admin-istrators new levels of flexibilty andsecurity when managing a NetWarenetwork through the use of NetWareDirectory Services (NDS). DOS,Windows, Windows NT, and Windows95 workstations can all utilize NDS tologin to a NetWare 4.x server. However,the implementation of NDS in each ofthese environments varies and maycause conflicts with the Btrieverequesters provided with the Btrieve forNetWare v6.15 product.

Btrieve requesters require informa-tion from the NetWare Bindery in orderto establish a connection to the serveras well as authenticate the user’s rightsto access a specified Btrieve data file.Btrieve requesters do not currently useNDS calls to accomplish these tasks.

DOS and Windows 3.x worksta-tions, using the 16-bit Novell ODI dri-vers, provide the functionality neededfor the DOS Btrieve requester (BRE-QUEST.EXE) and the Windows Btrieverequester (WBTRCALL.DLL & WBTI-COMM.DLL) to function properly in anNDS environment. However, there areseveral different configuration optionsavailable when using Windows 95 andWindows NT workstations using the32-bit Btrieve requester (WBTRV32.DLL & W32BTICM.DLL), and not all ofthese function properly with NDS.Novell and Microsoft each offer prod-ucts that allow these types of worksta-tions to login to a NetWare environ-ment using NDS. For Windows 95,Novell’s product is NetWare Client 32,and Microsoft’s is the Microsoft Servicefor NetWare Directory Service. ForWindows NT, Novell has the NetWareClient for Windows NT, and Microsoftincorporates NDS support within itsGateway Server for NetWare andClient Service for NetWare onWindows NT 4.0. Microsoft does notsupport NDS on versions of WindowsNT prior to 4.0.

The Btrieve v6.15 requesters func-tion within an NDS environment byusing Bindery Emulation to parse filenames sent by an application into aNetWare server and volume name, inorder to obtain the target server’s SPXaddress. The Btrieve requesters do notuse NDS APIs to parse file names. In aWindows 95 or Windows NT environ-ment, this is not a problem for filenames specified with a full NetWare(\\server\vol:dir\dir\file.btr) orUniversal Naming Convention (\\serv-er\vol\dir\dir\file.btr) pathname.However, when file names are speci-

fied with a drive letter (F:\dir\dir\file.btr), different configurations producedifferent results, including: successfullyopening a file, status 20 “Btrieve NotLoaded”, status 94 “Permission Error”,or other errors.

In order for Btrieve requesters tofunction properly with file names spec-ified with a drive letter on a Windows95 or Windows NT workstation in anNDS environment, the followingrequirements must be followed:

1. The latest Novell client softwaremust be used; the Microsoft client software does not support the necessary APIs.

2. The drive mapping must be established via the bindery (i.e., using the MAP command), and not the NDS tree or the NetworkNeighborhood.

3. If you are running a 16-bit application, you must have the Thunk=Yes setting in the [Btrieve] section of the BTI.INI file in the Windows directory.

4. The 6.15.435 or later versions ofthe requester must be used (see component list below).

As mentioned above, the Btrieverequesters support file names specifiedwith the NetWare and UNC format inan NDS environment. The followingtable shows the supported configura-tions for Btrieve requesters in an NDSenvironment, where the file name isspecified with a drive letter:


Troubleshooting

1. Verify that your configuration meets the four requirements specified above.

2. Login to the server via Bindery Emulation instead of NDS to verify that Btrieve can suc-cessfully open a file, and any conflicts result only from interaction with NDS.

3. Verify that the following registry entry either does not exist, or is set to 1 on your Windows 95 or Windows NT workstations:

HKEY_LOCAL_MACHINE\SOFTWARE\Btrieve Technologies\Microkernel Workstation Engine\Version 6.15\Microkernel Interface\Settings\Requester

The following table shows the requester components that must be used in conjunction withNDS. These components are included in the Btrieve for NetWare v6.15.435 update.

Client Platform Application Component Name Version Date File Size

DOS 16-bit BREQUEST.EXE 6.16.431 08/27/96 63788BREQNT.EXE 6.16.431 08/27/96 85746

Windows 16-bit WBTRCALL.DLL 6.15.6.3 10/21/96 43280WBTICOMM.DLL 1.20 10/25/96 39292WBTRVRES.DLL 6.15.3 04/19/95 4192

Windows 95 32-bit WBTRV32.DLL 6.15.435 11/07/96 65536W32BTICM.DLL 6.15.435 10/25/96 38400

Windows 95 16-bit ** WBTRCALL.DLL 6.15.6.3 10/21/96 43280WBTRVRES.DLL 6.15.3 04/19/95 4192WBTRTHNK.DLL 6.15 07/15/96 5824WBTRV32.DLL 6.15.435 11/07/96 65536W32BTICM.DLL 6.15.435 10/25/96 38400W16NR.DLL -- -- -- 10/12/95 10784W32NR.DLL -- -- -- 10/12/95 18944

Windows NT 32-bit WBTRV32.DLL 6.15.435 11/07/96 65536W32BTICM.DLL 6.15.435 10/25/96 38400

Windows NT 16-bit ** WBTRCALL.DLL 6.15.6.3 10/21/96 43280WBTRVRES.DLL 6.15.3 04/19/95 4192WBTRTHNK.DLL 6.15 07/15/96 5824WBTRV32.DLL 6.15.435 11/07/96 65536W32BTICM.DLL 6.15.435 10/25/96 38400

** For these configurations, you must have the following settings in your BTI.INI file in your Windows directory: [Btrieve]

local=norequester=nothunk=yes

If this entry does not exist, you do not have to create it; the default value is Requester=1.

4. When logged in via NDS, use a Btrieve utility instead of your appli-cation to attempt to open a Btrieve file. BTRTOOLS.EXE is a 16-bit Windows utility, which is included in BTOOLS.EXE. A 32-bit utility is also available as BSAMP32.EXE. Both of these files can be downloaded from Pervasive’s FTP site (ftp.pervasivesw.com). Use the utilitythat is comparable to your applica-tion, and attempt to open a file usingthe same path specification that yourapplication is using. You may need to contact your application vendor to find out how the application spec-ifies the file name.

5. Using a utility (from Step 3), attempt to open a Btrieve data file with dif-ferent path specifications: NetWare format, UNC format, Drive letter for-mat, and note the results of each.

6. If possible, re-install Windows NT orWindows 95 in a different directory on your workstation. Also, re-install the Novell Client software. This should eliminate any inconsistenciesdue to workstations that had various configurations installed prior to the current configuration.

7. Contact Pervasive Software TechnicalSupport for assistance. Be prepared to provide information on your trou-bleshooting of steps 1-4, as well as:

• A description of your NDS tree (from NWAdmin)

• List of DLLs in memory at the time of failure, including size, date, and location of each.

Summary

Although Btrieve requesters utilize theNetWare bindery for connection andauthentication information, they can beused in an NDS environment. Most conflictswith NDS are seen in conjunction with 16-bit and 32-bit Windows applications run-ning on Windows 95 and Windows NTworkstations. These can be resolved byusing the Novell Client software in theseenvironments, the latest Btrieve requesters,and bindery drive mappings. PervasiveSoftware now supports the coexistence ofBtrieve for NetWare v6.15 and NetWareDirectory Services.

Client Platform Client Software Btrieve Application Bindery mapping

DOS Novell Client 16 DOS Supported

Windows Novell Client 16 16-bit Win SupportedWindows Novell Client 16 DOS Supported

Windows 95 Novell Client 32 16-bit Win, 32-bit Win SupportedWindows 95 Novell Client 32 DOS Supported

Windows NT 3.51 Novell Client for NT 16-bit Win, 32-bit Win SupportedWindows NT 3.51 Novell Client for NT DOS Supported

Windows NT 4.0 Novell Client for NT 16-bit Win, 32-bit Win SupportedWindows NT 4.0 Novell Client for NT DOS Supported

■

BTRIEVE FOR NETWARE UPDATE v6.15.435 RELEASED

TECHNICAL INSIGHTS


In November of 1996, PervasiveSoftware released an update to Btrieve forWindows NT Server v6.15.435. The mainaddition was the support for the TCP/IPcommunications protocol. A correspondingupdate for Btrieve for NetWare v6.15.435 isnow available which includes some of thesame updates.

The 16-bit and 32-bit Windowsrequesters in the v6.15.435 Windows NTupdate are dual mode requesters, meaningthey can talk to Btrieve for NetWare orBtrieve for NT or both at the same time.They include several fixes that apply to theNetWare environment, as well as the newTCP/IP support for the NT environment.TCP/IP access for Btrieve for NetWare is notavailable. Some of the updates related to

Status 88 Using BUTIL -STARTBU and -ENDBUBtrieve for NetWare, Btrieve for NT Serverv6.1x

ISSUE: You cannot do a BUTIL -ENDBU toremove files from continuous operation afterBtrieve has been unloaded and reloaded. Theinformation Btrieve needs regarding files inContinuous Operations mode is in memory,and therefore, this information is no longeravailable after Btrieve has been unloaded.

SOLUTION: If delta files exist after such anevent, the user should just attempt to use thefiles normally (open, read, write, etc.) andthe delta files should be deleted. When a fileis opened, Btrieve will detect the presence ofthe delta file, roll in the changes, if there areany, and proceed normally. If the user wantsto verify this, they may use BSIM/WBExec orthe utility of choice to open the file, do aGetFirst, Update, and then close the file. Thedelta file should then disappear.

Status 94 From Window 95 in a NDSEnvironmentBtrieve for NetWare, v6.15

ISSUE: A status 94 “Permission Error” may bereturned when using the Windows 32-bitBtrieve requester on a Windows 95 worksta-tion trying to access files on a NetWare 4.1xserver. The user was logged in to theNetWare server via NDS. The following trou-bleshooting steps were completed:

• verified the latest Btrieve update (6.15.435) was in use

• verified the user has the appropriate

rights to the file• verified the username and password

on Windows 95 is the same as the user’s NetWare username and password

• verified that the bindery context is set correctly

SOLUTION: There seems to be a problemwith some versions of Microsoft’s NetWareredirector (NWNP32.DLL) under Windows95, in that it logs into NDS, even though it(the Microsoft NetWare redirector) does notsupport NDS. To verify this problem, go to aDOS prompt, change drives to the 4.1 server,and type in the command: “cx <return>.” Iftyping in the cx command returns NDS infor-mation, the user is logged in via NDS, andBtrieve cannot get the proper permissionsreturned to allow access to the file.

In some circumstances, the problem canbe solved by copying a differentNWNP32.DLL from a machine that does notreturn the error. In the event copying a newNWNP32.DLL does not work, you will needto call Microsoft Technical Support in orderto solve the problem, or reinstall Windows 95into a different directory.

Status 559 Using Create ProcedureStatement in SQLScopeScalable SQL, v4

ISSUE: The CREATE PROCEDURE statementin Scalable SQL 4 requires the use of thesemi-colon (;) within the statement syntax.The semi-colon is also the default SQLStatement seperator when executing a scriptwith multiple statements in the SQLScopeutility. If the statement seperator is set to thesemi-colon default and you try and run a

NetWare are listed below. These updates aresignificant enough that the requesters arenow available to NetWare users as well asNT users.

Some of the fixes related to NetWareinclude:

• UNC pathname support (along with NetWare pathnames and drive letters) in the 32-bit requester

• NDS support with the Novell client software on Windows NT and Windows 95 workstations

• Re-architected 16-bit requester (it no longer uses the TLI interface)

This product update has been testedusing the Novell Client 32 for Windows 95and the Novell Client for Windows NT in

conjunction with Microsoft’s NDIS drivers.Testing was performed with the DOS,Win16, and Win32 requester components.We have not qualified this release using theNovell Client 32 for Windows 95 or theNovell Client for Windows NT in conjunc-tion with the Novell ODI drivers and do notcurrently recommend use of that configura-tion. Windows NT workstations must bev3.51 or later.

The patch file (BTRNW615.EXE) andthe README file (BTRNW615.TXT) can befound in the following locations:

• CompuServe, GO BTRIEVE, Library 3 (Patch Upgrades)

• ftp://ftp.pervasive-sw.com/bin/patches ■

CREATE PROCEDURE statement inSQLScope, you receive status 559 (TheSyntax in the Stored Procedure or Trigger isInvalid).

SOLUTION: Change the SQLScope state-ment seperator from the semi-colon to anyother valid character. Select the SETTINGSmenu option, then ENVIRONMENT; thestatement seperator option is in the lowerright hand corner. Your current statementseparator is displayed at the top of the SQLText box on the main SQLScope dialog. Youcan choose to save this configuration on thesettings menu so that you do not have toreset it each time you run SQLScope.

NOTE: If you change your statementseparator, any previously created SQL state-ment scripts need to be modified to containthe new statement separator character whenrunning them under this configuration.

Programming With Visual Basic 4.0Btrieve and Scalable SQL

ISSUE: 32-bit applications are receivingincorrect data when using Visual Basic v4.0with Btrieve and Scalable SQL. This is due tothe fact that Visual Basic v4.0 aligns numerictypes of fields in data structures on a double-word boundary, which adds extra bytes intothe structure and changes positions of thedata fields. Btrieve and Scalable SQL are notexpecting these extra bytes, and interpretthem as part of the data.

SOLUTION: When declaring your TYPEbuffers in Visual Basic, only use string fields.This will not cause additional bytes to beincluded in your databuffer that you pass toBtrieve or Scalable SQL. Your application


will have to convert numeric types of datafrom string to the appropriate VB type. Forexample, the following portion of code readsa 4-byte integer into a databuffer definedwith only string fields, and then uses twointermediary type buffers to convert the stringvalue into the appropriate integer value anddisplay it.

TYPE DataRecordfld1 AS STRING * 20

...LongIntField AS STRING * 4...

END TYPE

TYPE String4Typevalue AS STRING * 4

END TYPE

TYPE LongTypevalue AS LONG

END TYPE

Global DataBuffer AS DataRecordGlobal String4Buffer AS String4TypeGlobal LongBuffer AS LongTypeRem --- use Btrieve or Scalable SQL APIs toread data into DataBuffer

String4Buffer.values =DataBuffer.LongIntFieldLSet LongBuffer = String4BufferMsg$ = “Long Integer Value is =” + CStr(LongBuffer.value)MsgBox Msg$

Btrieve and Netware SFT III ServerBtrieve for NetWare, v6.15.430

ISSUE: There is a documentation error in theBtrieve for NetWare v6.15 Installation andOperation manual on page 3-29. It states thatyou should load BTRIEVE.NLM and BSPX-COM.NLM in the MS Engine of an SFT IIIserver, and you should load AFTER311.NLMin the IO engine.

SOLUTION: The SFT server has 2 CPUs: theMS engine and the IO engine. You must issuethe following commands at the console inthe MS Engine:

: LOAD AFTER311 (which loads both AFTER311.NLM and A3112.NLM)

: BSTART (which loads BTRIEVE.NLM and BSPXCOM.NLM with configured parameters)

If you have an application (usually ahardware driver) that needs to run in the IOEngine and also needs access to Btrieve, youmust issue the following command at theconsole in the IO Engine after the MS Enginesteps were performed:

:LOAD BTRIEVE

You should not use the BSTART com-mand in the IO engine, and you do not needto specify any parameters on the LOAD

BTRIEVE line. This command loads a routingstub that will accept Btrieve calls in the IOEngine and route them to the Btrieve enginerunning in the MS Engine.

You do not need to load Btrieve in theIO Engine to support Btrieve applicationsrunning on a workstation.

Updating with ODBC and Visual Basic 4.0 orMS AccessODBC Interface, v1.0.x

ISSUE: When attempting to perform anupdate to a Btrieve database using MicrosoftVisual Basic v4.0 or Microsoft Access (7.0 or2.0) with Pervasive Software’s ODBCInterface, Visual Basic will return an error3147 and MS Access will display an ‘Unableto perform update’ message. If an applicationusing direct Btrieve calls (i.e., not usingODBC) is able to successfully update thesame data, the Visual Basic or MicrosoftAccess symptom indicates that a status 849 isbeing returned to the ODBC Interface by thedatabase engine. This happens when theinternal buffer size of the SQL engine isexceeded.

SOLUTION: The v2.0 release of the ODBCInterface has a larger internal engine buffersize and should resolve most of these cases.

Status 62 On GetDirect/Chunk UsingIndirect Random OptionBtrieve, v6.15

ISSUE: When attempting a GetDirect/Chunkoperation (opcode 23), a status 62 “InvalidDescriptor” may be returned. The applicationis specifying the Indirect Random option(SubFunction 0x80000001), but with theBtrieve trace enabled, it can be seen that theBtrieve engine is actually receiving a DirectRandom option (SubFunction 0x80000000).Also, the trace shows that the DatabufferLength parameter is not what the applicationsent, but instead is the value in the“Maximum Communications Buffer” settingin the registry.

SOLUTION: The indirect chunk optionallows an application to specify a pointer toa data address in the application’s memoryblock where the data should be stored after itis retrieved, rather than having the datareturned in the actual databuffer parameter ofthe Btrieve call. However, if the applicationis running in an environment where theBtrieve Microkernel Database Engine (MKDE)does not have direct access to the applica-tion’s memory, the Btrieve requester interfacemust convert indirect chunk requests intodirect chunk requests before sending therequest to the Btrieve engine. This is requiredwhen InterProcess Communication (IPC) isused to communicate between the applica-tion and the MKDE. Following are someexamples of environments where IPC is used:

1) The application is running on a remote workstation utilizing SPX or TCP to communicate to a server run-ning a Btrieve Server Engine.

2) The application is running on the same physical machine as the Btrieve for NT Server Engine, utilizing named pipes and the OS’s shared memory forcommunication.

3) The application is running on a Windows NT or Windows 95 workstation using the Btrieve for Windows NT/Windows 95 Workstation Engine, utilizing the OS’s shared memory to communicate data between the appli-cation and the MKDE.

Anytime IPC is required, the MKDE hasno access to the application’s memory, so therequester must allocate a single contiguousblock of memory and adjust all data pointersto point into that memory block. On returnfrom the engine, the requester converts thedata buffer back into the appropriate formatfor the indirect option and moves thereturned data chunk into the designated (indi-rect) address in the application’s memoryblock.

The size of the contiguous memoryblock used in the converted direct call is con-strained by the configuration parameter“Maximum Communications Buffer.” The sta-tus 62 was a result of not having enoughmemory to convert the indirect into a directcall based on this parameter’s setting. Thesolution to this problem is to increase thisparameter to accommodate the descriptorand the data chunk.

NOTE: The application does not have tobe modified; only the buffer size needs to beadjusted. This is a design issue forced on therequesters by client/server needs and NTarchitecture needs, and is not considered tobe a bug.

Direct access to the application’s memo-ry is possible (i.e., IPC is not used) in theWindows 3.x environment and on a NetWareserver with an NLM making direct calls to theBTRIEVE.NLM, making the indirect to directchunk conversion unneccessary.

IDE Emulation of SCSI Disk Slows ODBCInterface v2.0 Performance32-bit ODBC Interface, v2.0

ISSUE: The 32-bit ODBC Interface runs veryslowly on Windows 95 systems with SCSI dri-ves using IDE Emulation. This is not an opti-mal Windows 95 configuration, and the 32-bit ODBC Interface components (namely,WSSQL32.EXE) suffer noticeably in this envi-ronment.

SOLUTION: Do not use IDE Emulation onSCSI drives in a Windows 95 environment.This configuration can be set/verified under


Control Panel/System/Performance.

Redirecting Workstation Engine Lock FilesBtrieve for Windows NT/Windows 95, v6.15

ISSUE: The Btrieve for Windows NT/Windows95 Workstation Engine setup utility does notprovide an option to redirect lock files to adifferent drive. This option is necessary whenaccessing a read-only device (such as a CD-ROM drive) in a MultiEngine File Sharingmode.

SOLUTION: The Btrieve for WindowsNT/Windows 95 workstation engine supportsthe redirection of lock files even though thiscan not be configured through the setup utili-ty. To redirect lock files, you must manuallyload the engine as follows:

w32mkde /i:<drive>

This should be done before starting anapplication. The <drive> specification shouldbe a drive letter, such as /i:c

In order to properly redirect lock files,the drive specified with the /i: parametermust have the exact same directory structureas the path to the Btrieve data files beingopened.

ODBC Interface Will Not Work With BtrieveDeveloper KitODBC Interface

ISSUE: When attempting to use the ODBCInterface with the Btrieve components includ-ed in a Btrieve Developer Kit, the followingerror will be returned:

“This product requires a fully-functionalBtrieve product”

SOLUTION: In order to use the ODBCInterface, you must have the appropriateBtrieve v6.15 engine. Btrieve Developer Kitsdo not contain a Btrieve engine which can beused in a production environment. TheODBC Interface for Windows requires theBtrieve Workstation Engine for Windows, orthe 16-bit Btrieve Windows requester config-uration. The ODBC Interface for Windows 95requires the Btrieve Workstation Engine forWindows NT/Windows 95, or the 32-bitBtrieve Windows requester. The requesterconfigurations can be used in conjunctionwith either Btrieve for NetWare v6.15 orBtrieve for Windows NT Server v6.15.

Using ODBC Interface with MicrosoftAccess and the NOT NULL OperatorODBC Interface

ISSUE: When using Pervasive Software’sODBC Interface with Microsoft Access, thefollowing results can be expected when usingthe IS NULL and IS NOT NULL operators:

The following statement returns the cor-rect data:

SELECT <fieldname> FROM <tablename> WHERE <fieldname> IS NULLThe following statement returns Status

847 “Syntax in the WHERE clause is invalid”:

SELECT <fieldname> FROM <tablename>WHERE <fieldname> IS NOT NULL

SOLUTION: Modify the failing query inAccess to:

SELECT <fieldname> As [NOT NULL]FROM <tablename>

The brackets around “Not Null” arerequired. This will return the records where<fieldname> is not null.

Status 46 With 32-bit ODBC Interface onPeer-to-Peer Network32-bit ODBC Interface for Windows 95

ISSUE: A Status 46 (Access Denied) may bereturned while trying to add a data sourceusing the 32-bit ODBC administrator. Thiswill happen when the shared resource is notlocated on the machine where the applica-tion is running. But rather, is located onanother machine connected using Windows95’s peer-to-peer networking support wherethe shared resource is read-only.

SOLUTION: The DDF files must be locatedin a shared resource that the user can writeto in order to access the files via ODBCInterface. This can be accomplished by grant-ing write access to the shared resource, ormoving the files to a local directory.

Workstation Lock When Running BREQNT inWindows 95 DOS BoxBtrieve For NT Server Edition, v6.15

ISSUE: A DOS application running in aWindows 95 DOS Box locks up when read-ing data from a Windows NT 3.51 Serverrunning Btrieve for NT Server Edition v6.15.BREQNT.EXE v6.16.430 is loaded in the DOSBox. The problem does not occur if Btrievefor DOS v6.15 Workstation Engine(BTRIEVE.EXE) is used instead of therequester.

SOLUTION: This problem occurs when read-ing large records. When the IPX/SPXMaxPktSize in the Windows NT Registry ischanged to 576 (240 Hex) the problem isresolved.

To change the MaxPktSize, runREGEDT32 and take the following path:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ NwlnklPX\NetConfig\ <LANDriver Name>\ MaxPktSize

■

You can find more information aboutmodifying MaxPktSize in the document NETWORK.WRI on the Windows NT v3.51 CD.

Btrieve Requester for OS/2 Faults (Stack orMemory)Btrieve for OS/2, 6.15

ISSUE: Older applications and legacy appli-cations written with Btrieve for OS/2 v5.1xmay produce a fault when running with theOS/2 Btrieve requester included in the Btrievefor NetWare v6.15 package because of thesmaller stack size used by the older applica-tions (typically 4K). When these older appli-cations are recompiled and relinked usingBtrieve for OS/2 v6.15 without increasing thestack size they may fault in the requestercomponent OS2NWBRQ.DLL.

SOLUTION: OS2NWBRQ.DLL in the OS/2Btrieve 6.15 product requires an 8K stacksize. Older applications must be recompiledand relinked with at least an 8K stack. This isdocumented in the README that is includedwith the Btrieve for OS/2 v6.15 DeveloperKit.

Key Index Number ParameterDocumentation ErrorBtrieve Developer Kit, v6.15

ISSUE: When developing an application usingthe Btrieve navigational interface, there aretimes when Btrieve needs to be called using -1 as the Key Index (Key Number). However,the 32-bit interface uses Byte rather thanSmall Integer for this parameter. You cannotsend -1 (FFFF hex) in a byte parameter.

SOLUTION: Early revisions of the Programmer’sManual did not document the parameterscorrectly. The KeyNumber was documentedas a BTI_SINT when using the BTRV() func-tion, and under the BTRCALL() function, itsaid the parameters were the same as forBTRV(). However, the BTRAPI.H declares thekeynumber as BTI_CHAR for the BTRCALL()prototype, which does allow a -1 value. Thisis correctly documented in the current revi-sion (April 1995) of the Btrieve Programmer’sManual.

The correct BTRCALL() function proto-type (from btrapi.h) is:

BTI_API BTRCALL(BTI_WORD operation,BTI_VOID_PTR posBlock,BTI_VOID_PTR dataBuffer,BTI_ULONG_PTR dataLength,BTI_VOID_PTR keyBuffer,BTI_BYTE keyLength,BTI_CHAR ckeynum );

ckeynum has type BTI_CHAR (which isdefined as char in BTITYPES.H) is essentiallya signed 1-byte integer. Passing -1 (0xFF) inckeynum works correctly.


Q & ANew Support for TCP/IP with Btrieve for NTServer

Q: How will the support for TCP/IP changeBtrieve?

A: TCP/IP support will give users on MicrosoftNT networks the flexibility of choosingbetween two transport protocols: SPX andTCP/IP. It is not going to change theMicrokernel Engine’s function in any way; itis basically providing the option of usingTCP/IP over SPX. The TCP/IP requester isavailable for 16-bit and 32-bit Windowsrequesters. TCP/IP support for DOS is notavaiable.

Using ClientIDs in Btrieve ApplicationsBtrieve for Windows NT/Windows 95v6.15

Q: What is the maximum number of uniqueClientIDs that can be used in a single appli-cation running on Windows NT or Windows95, and how is this affected by the ActiveClients configuration parameter?

A: When developing an application using theBTRVID function rather than BTRV, you mustspecify an extra parameter called a ClientID.This allows an application to assign itselfmore than one client identity to Btrieve, andexecute operations for one client withoutaffecting the state of the other clients. Anapplication can have a maximum of 64active ClientIDs at any one time.

The Active Clients parameter in theSystem Resources/Directories category of theBtrieve for Windows NT/Windows 95 Setuputility (W32MKSET.EXE) is used to configurethe total number of ìclientsî that can beactive in all applications accessing theMicroKernel simultaneously. This setupoption corresponds to the “Max Clients” reg-istry entry under:

HKEY_LOCAL_MACHINE\Software\Btrieve Technologies\Microkernel Workstation Engine\Version 6.15\Settings

Following are several examples demon-strating how ClientIDs are “counted” in vari-ous configurations.

Example 1: Two 32-bit applications are running onWindows NT or Windows 95, and each uti-lizes three different ClientIDs. This will countas six active clients. It does not matter if thisis two instances of the same application (andthe same ClientID values in each instance) ortwo different applications. Btrieve will distin-guish between each of the six ClientIDs.

Example 2: Five 16-bit applications are either running onWindows 95 or running each in a separate

address space on Windows NT, and each uti-lizes four distinct ClientIDs. The BTI.INI isconfigured with Thunk=Yes in the [Btrieve]section, which specifies that the Btrieve forWindows NT/Windows 95 workstationengine handles the requests. This will countas 20 Active Clients. Again, It does not matterif any of the applications happen to use theexact same ClientID; Btrieve will distinguishbetween each of the 20 Active Clients.

Example 3: Two different 16-bit applications are runningon Windows 95 or in the same address spaceon Windows NT, and each utilizes two dis-tinct ClientIDs. In this example, all fourClientIDs are unique. The BTI.INI is config-ured with Thunk=Yes in the [Btrieve] section,which specifies that the Btrieve for WindowsNT/Windows 95 workstation engine handlesthe requests. This will count as four ActiveClients.

Example 4: Two instances of the same 16-bit applicationare running in the same address space, andeach utilizes two ClientIDs; the same twoClientIDs are used in each instance. TheBTI.INI is configured with Thunk=Yes in the[Btrieve] section, which specifies that theBtrieve for Windows NT/Windows 95 work-station engine handles the requests. On aWindows 95 workstation, this will count asfour Active Clients. On a Windows NT work-station, this will only count as two ActiveClients.

The difference in behavior on WindowsNT vs. Windows 95 in Example 4 is currentlybeing investigated by Pervasive Software. It isrecommended at this time that you run each16-bit application in a separate address spaceon Windows NT.

The Active Clients parameter can beconfigured to a maximum of 64,000.However, any individual application can cur-rently have a maximum of 64 activeClientIDs.

Performance of BREQNT in a Windows NT4.0 DOS Box

Q: Are there any performance problems withDOS-based applications running under aWindows NT v4.0 Workstation using BRE-QNT.EXE to communicate to a Btrieve for NTv6.15 Server Engine running on Windows NTv4.0?

A: Running a DOS-based SPX applicationfrom a Windows NT DOS box is known torun slow. This is due to the emulation codethe application goes through which causesthe performance degradation (this is really adesign issue with Windows NT).

Pervasive has discussed this issue with

Microsoft. Microsoft did confirm they knowperformance is not optimal, however,Microsoft indicated performance could notbe further improved.

Wait Locks and No-Wait LocksBtrieve for Windows & Windows 95, v6.15

Q: How are wait locks implemented in theWindows 95/Windows NT environment?

A: Due to the non-preemptive nature ofWindows 3.x, a wait lock never relinquishescontrol, and can result in a deadlock situa-tion. Therefore, when a 16-bit application isrunning on Windows 3.x, wait locks are“converted” by the Btrieve for Windowsworkstation engine to no-wait locks.

Multiple 16-bit Windows applicationswill execute in the same Virtual DOSMachine (VDM) under Windows NT (bydefault), and under Windows 95 always.Applications that are running in the sameVDM are not preemptive with regard to eachother.

If a 16-bit Windows application usesthunking to get to the 32-bit engine onWindows NT or Windows 95, Btrieve isaware of the fact that the request was madefrom the 16-bit subsystem and converts thewait lock to a no-wait lock just as if theapplication was running on Windows 3.x.

Native Windows 32-bit applications areall running as separate processes onWindows NT and Windows 95. They fullysupport the preemptive nature of the 32-bitoperating systems. A wait lock originated bya Win32 application is handled as it is,namely the application will not get controlback until the lock is granted or a deadlockoccurs.

Installing Btrieve for Windows NT/Windows 95Btrieve for Windows NT/Windows 95 ClientEngine, v6.15

Q: Many customers, when they receive theUnlimited Distribution License for Btrieve forWindows NT/Windows 95 v6.15 ask whatfiles they need to re-distribute as part of theirinstallation?

A: The workstation will need the followingfiles in the Windows\System directory for a32-bit application: WBTRV32.DLL W32MKDE.EXE W32MKRC.DLL

For a 16-bit application, the following fileswill also be used:WBTRCALL.DLLWBTRVRES.DLLWBTRTHNK.DLL


The first time Btrieve runs, it createsentries in the registry. These entries can bemodified using the Setup Utility(W32MKSET.EXE and W32MKSET.HLP),which can also be distributed with an appli-cation. If the customer does not want to shipthe setup utility, and/or wants to initializethe registry entries to the values required bythe application, the customer’s installationprogram can make the necessary changes. Acheck should be made before the installa-tion attempts to make any modifications andverify whether or not entries already existfrom another application. The installationprogram can then open a Btrieve file (afterinstalling the required files and DLLs); thiswill create the default registry entries. Then,the installation program can modify theentries to the values needed by the applica-tion.

Also, 16-bit applications running onWindows NT or Windows 95 require thesetting Thunk=Yes in the [Btrieve] section ofBTI.INI, which must be located in theWindows directory.

In the case where multiple Btrieveapplications are installed in a single envi-ronment, the settings required by each appli-cation must be merged. For more informa-tion on this issue, refer to the paper titled“Configuring Btrieve for Multiple Applications”available on the Pervasive Software web site(www.pervasive-sw.com) or the BTRIEVEforum on CompuServe (LIB 4,BTRPARMS.TXT).

16-bit Applications and Btrieve forWindows NT/Windows 95

Q: Can you develop 16-bit windows appli-cation with the Btrieve Developer Kit forWindows NT/Windows 95?

A: Yes. The application will link to WBTR-CALL.DLL, just as it would when developingwith the Btrieve for Windows Developer Kit.However, development needs to occur on aWindows NT or Windows 95 workstation,since the Btrieve for Windows NT/Windows95 Workstation Engine included with theDeveloper Kit will not run on a Windowsworkstation. Once the 16-bit application isdeveloped, the application can run onWindows NT or Windows 95, using Btrievefor WindowsNT/Windows 95, or it can berun on Windows 3.1 using Btrieve forWindows.

32-bit Applications & Scalable SQL

Q: Can a customer use the Scalable SQL forWindows Developer kit to develop a 32-bitWindows 95 application?

A: The Scalable SQL for WindowsDeveloper Kit v3.01 only supports 16-bitapplication development. There is no 32-bitScalable SQL development environment.

SOLUTION NETWORKPARTNER TRAINING

SCHEDULE

FAQ

Targeted Date City

Feb. 4 Washington, D.C.Feb. 6 Atlanta, GAFeb. 11 Memphis, TNFeb. 18 San Francisco, CAFeb. 20 Los Angeles, CAFeb. 25 Chicago, ILFeb. 27 St. Louis, MOMar. 6 Las Vegas, NVMar. 18 Kansas City, MOMar. 20 Dallas, TXMar. 25 Pittsburg, PAMar. 27 Orlando, FLApr. 1 Boston, MAApr. 3 New York, NYApr.10 Montreal, QBApr. 15 Portland, ORApr. 17 Vancouver, BCApr. 22 Salt Lake City, UTApr. 24 Denver, COApr. 29 Cleveland, OHMay 1 Cincinnati, OHMay 13 DetroitMay 15 Raleigh, NCMay 20 Seattle, WAMay 22 Phoenix, AZMay 29 Philadelphia, PAJune 5 Houston, TXJune 10 Miami, FLJune 12 New Orleans, LAJune 17 Minneapolis, MN

*These dates and locations of Solution Networktraining sessions are subject to change. Please con-tact the number above for specific informationregarding the training session in your area.

Btrieve Status 95NetWare Btrieve, v6.x

Q: What causes a status 95? What can be doneto prevent it?

A: A status 95 (session no longer valid) indicatesthat an SPX session has been established, but dueto network delays and/or network communica-tion problems, the SPX session has been termi-nated. If the problem is due to delays in receiv-ing a response from the server, it may be advis-able to increase the SPX TIMEOUT parameters inthe workstation’s NET.CFG file or in the SPX-CONFG.NLM at a NetWare server. These para-meters are shown below with their default val-ues:

SPX VERIFY TIMEOUT=54SPX LISTEN TIMEOUT=108SPX ABORT TIMEOUT=540

These three parameters (in the order listedabove) have values in a 1:2:10 ratio. If the val-ues are changed from the default settings, theyshould be kept in this ratio. It is a good idea tojust double, or at most triple them all. If the sta-tus 95s persist, the problem is probably not relat-ed to a timing issue. SPX timing issues are com-mon in WAN environments or large LAN seg-ments, and are usually resolved by increasingthese parameters. (Refer to the NetWare worksta-tion documentation for more information aboutthese parameters.)

Other causes of status 95s are related tocommunication problems on the network. Thiscan be due to old workstation drivers for the net-work, old LAN card drivers at the workstation orserver, bad hardware (usually the LAN cards atthe workstations or server), or routing configura-tion problems in routers and/or bridges. It isoften difficult to diagnose exactly what is causingthe problem, but there are some actions that canbe taken to help prevent it.

First, make sure your system is equippedwith the latest workstation drivers from Novell, aswell as the latest LAN card drivers from yourLAN card manufacturer. Also, make sure thatyour LAN cards and drivers are certified byNovell to run on the version of NetWare that youare using.

Next, try to isolate the problem. Is it hap-pening on all workstations, or only some ofthem? Check with workstations on different seg-ments on the LAN. You may want to try swap-ping hardware components at the server or atworkstations to see if different LAN cards make adifference.

It is often a good idea to try other SPXapplications. RCONSOLE is a good test for DOSworkstation applications that use SPX. If havingproblems with a DOS Btrieve application:

1) Run RCONSOLE on a workstation,2) Let it run the length of time it takes

for the Btrieve application to get the status 95, and

3) See if RCONSOLE reports any errors.

Try running RCONSOLE from DOS and ina Windows or OS/2 DOS box if the problem isWindows- or OS/2- related.

In an SFT III environment, when the prima-ry server goes down and re-synchronization istaking place, Btrieve users can get status 95.

To avoid this, increase the IPX Retry Countparameter in NET.CFG. The recommended valueis 40 or more.

However, a 16-bit application can be runwith the Scalable SQL for Windows engineon Windows 95. You must also have theBtrieve for Windows NT/Windows 95Workstation Engine or requester for this con-figuration.

Scalable SQL 4 will support 32-bitapplication development for Windows 95and Windows NT.

NT Server Setting for SPX Watchdog

Q: Is there a setting on the Windows NTServer registry to setup the SPX watchdog?

A: Yes. Run REGEDIT and follow the “path”HKey_Local_Machine\System\

CurrentControlSet\Services\NWLinkSPX\Parameters:

KeepAliveTimeout: 1 to 65535 half-seconds.Default is 12 (6 seconds).

You may want to adjust this value if youare experiencing problems using SPX withBtrieve for Windows NT, and seeing sessionsbeing dropped and/or Btrieve status 95s(Session No Longer Valid). Refer to pages515-520 of the Windows NT Resource KitNetworking Guide for further details. ■

decided to stop right there, swallow my enthusiasm, and think this onethrough.

During the next couple of days, I tried the demo many times, bothduring peak hours and not. I measured the response time to retrieverecords, (impressive, generally under a half-second) and even calculat-ed the great-circle distance between my office and the Nashville air-port (1,873 miles or 3,013 kilometers). It still worked. I decided to letmyself be ‘cautiously optimistic,’ and to install the IDS, a WindowsNT service, on “Darth Vader,” my pride-and-joy NT server at my com-pany’s main site.

Braving ice, snow, and scheduling problems, Smithware’s Ken White,the lead developer on the IDS project, flew into Yakima on a recentSaturday morning. After a quick breakfast, we arrived at the officearound 10 AM, and Ken started work. Within 30 minutes, he had theIDS running, and was busily writing the sample application includedwith this article, using my workstation. In spite of my endless ques-tions, (and occasional tirades of opinion) by 6 PM he had not only fin-ished the sample app, but we had tested it on different subnets, andinstalled Remote Access Server on Darth Vader for further testing.Quite an amazing day. We then drove out to my home, and tested theapp.via Remote Access, (Windows NT ‘Dialup Networking’) thenbroke for dinner. The next morning, he (barely) made his plane, aftersurviving a warp nine trip to the airport. True to form, I was late, soI’m afraid his last view of our fair city was something of a blur.

The after-action report - Operation

I learned quite a bit about both Smithware and the IDS duringthis process, and I’ll get down to tacks here. At my company, CrystalLinen, we have a fairly complex network, with multiple servers, trans-ports, protocols, and physical topologies. The Smithware IDS ranwithout a glitch. During Ken’s visit, we tested it across subnets, andvia “dial-up.” I’ve since tested it across our frame relay and direct-dig-ital (DDS) WANs. It works, and the speed over the low-bandwidthnetworks still surprises me. The (selectable) data compression providesboth speed and data security, should you decide to use a public net-work, such as the Internet.

Security

The Smithware IDS fully supports ‘native’ Windows NT domainsecurity. This means that you can (optionally) allow either users orgroups of users access to your data, restricting public access.Additionally, you can place files in “read-only,” “write-only,” and“full-access” directories. The combination of these features is a power-ful tool, giving both robust security and flexibility; a combination thatis often difficult to achieve.


These Things Are FastGet blinding performance and nativeaccess to Btrieve databases without writ-ing code! Our advanced data bindingtechnology outperforms the VB DataControl, other data bound controls,ODBC, Jet and other access methods.

Control Freaks Pay AttentionSmithware ActiveX Controls give you total control over your datawith these features: seamless integration of Btrieve’s client/serverextended operations, extended joined record sets, bound controls andjoined tables across multiple forms in VB (try that trick with a VB datacontrol), advanced debugging and more! Build a complete data browserwithout writing code just by dropping a text box, list box, and scrollbar on a form and setting a few properties!

Activate Your Favorite Development EnvironmentUse our ActiveX Controls in VB, Delphi, Visual C++, Internet Exploreror any environment that supports the ActiveX standard. SmithwareActiveX Controls let you build true client/server applications and caneven enable your Btrieve based applicationover the web. Includes DDF Builder,the #1 Btrieve data definition toolused by Btrieve developersworld wide. Access yourBtrieve data fast and easytoday!

2416 Hillsboro Road, Suite 201, Nashville, TN 37212Phone: 615-386-3100 or 800-837-6315

E-mail: [email protected] http://www.smithware.com

Btrieve Database Access& Easy !

Smithware, Inc.Power Tools For Btrieve

Fast

Client support

The “client side” of the IDS is an ActiveX control (32-bit OCX)that can be used from any ActiveX control container, such as VisualBasic, Visual C++, Borland Delphi, or MS Internet Explorer. The con-trol shares a common interface with Smithware’s ActiveX Controls forBtrieve, with additional properties to specify the host’s IP address,whether to use compression, etc. DDF (Data Dictionary) files are fullysupported.

Applications

This is the exciting part! Obvious applications will be remoteorder entry, and customer information. How about a ‘mixed’ applica-tion, using both web publishing and Btrieve data? Hypertext docu-ments and graphics can be handled by your web server, (that comeswith NT 4.0) and live, client-server data from IDS. Scientific andindustrial applications abound as well. Seismic data, process control,management reports, shoe sales, or mango futures. Anything you canimagine.

Wrapping it up

Given all that’s happened, I’ve decided to upgrade my attitudefrom ‘cautiously optimistic’ to ‘Let’s do it.’ Having thoroughly tor-tured Ken, Smithware, and the IDS, I feel that the corporate managerfinally has the tools to make an Internet presence pay off. As a devel-oper, (different hat) I see opportunity, and a platform to launch from.The rest is up to us.

For more information on the Smithware Internet Data Server, seehttp://www.smithware.com/ids or contact Smithware at 615-386-3100x16 or Fax: 615-386-3135.

A sample Btrieve application created in minutesusing the IDS client.

IDS ...continued from page 1


Inside BtrieveA Request for HelpBy Douglas J. Reilly Access Microsystems, Inc.E-mail: [email protected]

I am a die-hard fan of Btrieve, using it even for projects where itmight be easier to use something else (Delphi is a perfect example of theless than perfect environment for developing Btrieve applications). Thatsaid, I have to admit there are some things about Btrieve that take a whilefor new users to get used to. The first is the fact that Btrieve is a recordmanager, not a database program in the mold of dBase or Paradox. I con-sider this a feature of Btrieve. Developers are not constrained by whatPervasive Software thinks we want to store in a Btrieve file, but rather wecan store whatever we need to store, however it suits us. This has causedsome problems when people use really non-standard data types, but on bal-ance, it is a good thing.

Once people understand the record manager concept, the next confus-ing point is the use of the standalone, “client only” version of Btrieve orthe “client/server” version. To this day, perhaps 20 percent of my supportcalls on BTFILER and BTVIEWER relate to confusion over which “fla-vor” of Btrieve is being used: client only or client/server. Generating evenmore confusion is the fact that you can, quite reasonably, use the clientonly version to access files that are on a file server. And, by the way, whatis a requester, anyway?

Client/Server 101

Some introduction of terms is in order. To understand Btrieve’s twousage models, you need to understand a little about client/server comput-ing. The main thing to remember about client/server computing is that it isall about two or more processes, often on two or more processors, cooper-ating using a pre-defined protocol, to perform some task. The confusionover client/server computing is due, in no small part, to the marketingmachines at many major software firms hawking client/server solutions.Listening to them, you would think that client/server computing is a binarychoice, true or false, yes or no. This is far from the case. Any time twocomputers (or any two devices with even the least amount of intelligence)are communicating and cooperating to perform some task, client/servercomputing is taking place.

The true array of client/server choices is represented in figure 1.Near one extreme you have a smart terminal that communicates with amainframe computer. This is the thinnest possible of the “thin clients” thatare currently in demand. In this case, the client does little more thanprocess keystrokes and some presentation management. Currently in thenews are Network Computers, or NC’s. These represent only a minor stepup the client/server balance from smart terminals. NC’s will handle only alittle bit more of the presentation to the user than the average smart termi-nal.

Near the other end of the spectrum is a PC connected to a networkand using only the barest of the server’s capacity, using server solely for

file and print services. This is the fattest of the “fat clients.” This can bean appropriate choice, but might not make the best possible use of theserver.

Somewhere in the middle is a system where the client handles thepresentation of data and the acquisition of information from the user. Itbuilds a query (using SQL, or in the case of client/server Btrieve, an APIcall) and passes that information to the server where the data resides. Thisrequest for information is where the Btrieve requester gets its name. Theserver processes the request, managing the details required to find the data,and returns just the data requested, or a status code indicating why therequest failed. The scenario is neither a very thin client nor a very fatclient, though it is closer to a fat client, since it is likely that more than justpresentation of information is handled by the client (for instance, businessrules are probably embedded in the client).

A requester to call our own...

A good way to understand what the requester is doing is to create ourown, simple requester. Why would you want to do this? Several scenar-ios come to mind beyond the simple thrill of the intellectual exercise.Suppose you were writing a very simple e-mail system and you wanted touse the Btrieve file manager. You wanted to have a notification systemthat would allow you to know about incoming mail as soon as it arrived.Suppose further that the client workstations were already overburdened,and that the use of the Btrieve engine on each workstation was overkill. Itcould be that the workstations were running Windows 95 and only had 8meg of RAM, and the Windows 95 workstation engine requires 16 meg(yes, I know that Windows 95 in 8 meg is ugly, but some folks do havethis working). Another possibility is that there was another mission-criti-cal Btrieve application already on the workstation, and it was not possibleto tweak the Btrieve settings in any way. Yet another possibility exists. Ifthis system needs to work over a wide area network, and the client is con-nected via an ISDN line, it is possible that the periodic “I’m alive” signalssent between the client and the server in a normal Btrieve session willcause the ISDN network to stay up constantly. This can result in anincrease in the cost of maintaining the ISDN link (which is commonlybilled by the minute). The mini-requester that we will design works with-out network activity between operations.

What does a requester do? As far as the programmers interface, call-ing the local engine or the requester requires identical steps. Under thecovers, an awful lot is happening. When you call BTRV or BTRVID, theBtrieve engine first must determine if the file in question is even on a fileserver where the Btrieve server engine is running, and further, whether theclient workstation is set up to use the requester. Once it is determined thatthe request is for a file residing on a server that is running the Btrieveserver, the next step is to establish a communications session with theBtrieve server. Once this is done, the client must move all of the parame-ters across the network to the server. This is a little trickier than it mayappear. For instance, suppose on a NetWare workstation, you execute thefollowing command:

MAP ROOT G:=FS1/SYS:APPS\DATA

Now suppose you call BTRV with an OPEN op code for a fileG:\OTHER\MYFILE.BTR. The server knows nothing of your drive map-pings, and so part of the process of marshalling parameters to the BTRVcall (transporting across machine boundaries) must include setting up thefilename parameter (in this case, passed in the key buffer) so that the serv-er understands the true file location (in the example above, SYS:APPS\DATA\OTHER\MYFILE.BTR). Further, the requester must have an ideaabout what file server is involved, so that the request is sent to the serveron FS1 and not some other server. For our example requester, we willtake the cowards way out, assuming that the file name passed to an opencall is a full path name to the C drive on the server machine, and that thereis only a single server. In a production environment, you would want therequester to examine each file open request and determine from the driveletter what server the share name refers to. In addition, it is not possible todirectly send pointers across processor boundaries. For instance, a char*data on the client machine looses meaning when transported to the servermachine. As we will see, the solution is to determine the size of the array


the character pointer points to and allocate a buffer that size and send theactual buffer across the network to the server.

Once the packaging of parameters is done, the client needs to wait forthe server to respond. What to do while waiting is a bigger question thancan be covered in this article, but suffice it to say that these days, with theadvent of multithreaded applications, dealing with the problem of waitingis a lot less difficult than it used to be.

Once the request is sent to the server, it is up to the server to handlethe request and send the information back to the user. In the case of tradi-tional server-based Btrieve (the NetWare BTRIEVE.NLM or the NTBtrieve Server), the server itself handles the communication with theclient. In our example requester, we will write a server module that com-municates with the Btrieve Micro-Kernel Database Engine (MKDE) on themachine where the file resides. The server module will be responsible forconverting the parameters back to a format useful for calls to BTRVID(),calling the MKDE just like any other application program, and then send-ing the information back to the client, after of course converting the para-meters back to a data structure that can be transported beyond machineboundaries.

Can we talk?

Not just an academic question, the ability to talk is critical to theoperation of a client/server system. Just how to talk is a topic that couldfill many books. I have written such a book that deals primarily with justthis issue (figure 1 and some of the example code is derived from mybook), but for our purposes, let us assume that there are three options.

1. IPX/SPX, a communications protocol favored by NetWare servers.

2. Named Pipes, a holdover from OS/2.3. TCP/IP, the communications protocol of the Internet.

Given these three options, it is obvious that TCP/IP is the winner, sinceanything having anything to do with the Internet seems to be compellingreading, but this is one case where the hype does not outweigh the actualbenefits. TCP/IP is an efficient way to send large chunks of informationfrom machine to machine, and the machines need not all be Intel/Windowsboxes (though for our example, we will use Win32 machines as the clientand the server). IPX/SPX is included on Win32 systems primarily forcompatibility with NetWare servers, and there is no compelling reason toimplement the requester using this protocol. Named Pipes is a protocol Irather like (if you know how to read and write to files, you know how touse Named Pipes) but it has of late fallen out of favor, and Windows 95can act only as a Named Pipes client, not as a server. Windows 95 andWindows NT can each act as client and server for TCP/IP connections.

That said, how do we communicate with TCP/IP on a Win32machine? If you do a directory on any Windows machine that is capableof TCP/IP communications, you will find a file called WINSOCK.DLL.This is the Dynamic Link Library that implements the Windows SocketAPI. Windows Sockets is an extension of the standard Unix BerkleySockets. There are several Windows specific extensions to the WindowsSockets API, but for the most part, using the WinSock is like using socketson any machine. The current version of WinSock supported on my homeWindows 95 machines is 1.1, and version 2.0 is shipped with NT 4.0. Adetailed discussion of WinSock is beyond the scope of this article, but seethe references at the end of the article for sources of more information.For practical purposes, version 2.0 works as you would expect version 1.1to work if called from a program using only 1.1 functionality. One oddnote is that the system status string returned by WinSock 2.0 when youcheck the status after a call to WSAStartup() is “Running (duh).” Youcan’t make this stuff up.

Anatomy of a server

Though it seems somewhat backwards, looking at the server first isoften useful. Creating a server is a reasonable task these days, given thenature of the operating systems we have to work with. There are two pos-sible options for partitioning the work of a server: One thread per client orn clients per thread. From a standpoint of ease of understanding, the one

thread per client is preferred. If a thread is required to split its timebetween multiple clients, the details of interacting with the client switchesoverwhelms the basic flow of the program. While one thread per client isconvenient, it can often be too consumptive of system resources for a serv-er handling many dozens or hundreds of clients. Since I do not envisionour server handling high activity for many clients, the one thread per clientmodel is reasonable, as well as easy to understand. Each thread acts like aseparate program, going out and doing the tasks required without anyawareness that it is part of a larger system.

About (inter)face!

When you create a server application, you have to determine how theclient should interact with the server. In our example, we have a perfectmodel: The BTRVID() API. It is not difficult to allow the server to takeinformation essentially like the parameters to a BTRVID() call and packthem into a structure and send them over the wire, have the server react tothem, and send them back over the wire to the client, with whateverchanges to the parameters made by the MKDE on the server passed rightalong.

Listing 1 presents the primary structure used to communicatebetween the client and the server. This mostly mimics the parameters to astandard BTRVID() call. Several differences are worthy of note. First, theorder is changed from the BTRVID parameter order. This is done so thatwe can have a structure where the last parameter is likely to be shorterthan the allocated space, so that we can transmit a partial structure acrossthe wire. KeyBuf is declared as a 255-character buffer, large enough toensure that the entire key will be sent.

As I prepared this, I was quite pleased with myself, having created areasonable server application in a limited amount of code. The initial passtook just about 50 lines of code, with the balance of the code “borrowed”from the generic WinSock client from Win32 Client/Server Developer’sGuide. The code from the book is described in detail there, as well as incomments in the source code, and so I will go no further to describe ithere.

Unfortunately, I was not finished. Listing 2 presents the final versionof the doChat() function, the function that actually does the work of takingthe parameters structure from the client and passing it on to the server’sMKDE. Some things are related to my last column covering multitaskingBtrieve. For instance, the code:

//critical section!EnterCriticalSection(&CriticalSection);thisClient=curClient;curClient++;LeaveCriticalSection(&CriticalSection);// Leave critical section.

Is an example of the use of Critical Sections to ensure that a globalvariable is not touched by two threads at the same time. If two requestscome in from a two different workstations at the same time, we need tomake sure that each one is assigned a client code that is unique. This isrequired because we have arrays that are set up to allow a client to indexinto various arrays that are global without interfering with other clients.This scheme works for trusted threads that all work the same way and willnot peek in array elements other than those they should have access to.

Just after we exit the critical section, we enter a loop that will runFOREVER (FOREVER is #define’d as while ( TRUE )). This is the pro-cessing loop for the Btrieve handler for a single client. Initially, I correctlyhandled the two obvious special cases, OPEN and CLOSE operations. Inthese cases, buffers had to be allocated or de-allocated as the open andclose, respectfully, occurred. Less obvious was the need to do somethingabout the STOP and RESET calls. Though other calls can simply bepassed off to the Server’s MKDE, doing so with the STOP or RESET com-mand would have dire consequences, closing files for ALL the clientsusing our simple requester and server, which is probably not what we hadin mind.

A solution was obviously to intercept the call to STOP or RESET.But then what? To preserve the existing syntax and semantics, these callshad to close all files open for that client. But how? If we simply stored


local copies of each position block, we would need to match each one upbefore we called BTRVID(), and then be sure to copy the data back intothe server’s buffer before we sent the data on. Could two position blocksever be identical? Who knows.

My solution takes advantage of the fact that most well-behaved pro-grams simply treat the position block like a black box, assuming that if thecall returns a zero status code on an open call, all is well. Taking this fur-ther, why do we even have to tell the client what the position block reallyis? This results in the unusual code seen in the final B_OPEN case:

for ( thisHandle=0 ; thisHandle<MAX_CLIENT_FILES && posBlocks[thisClient][thisHandle].pb!=NULL ;

){

thisHandle++;}if ( thisHandle>=MAX_CLIENT_FILES ){

status=87; //handle table fullÖ}else{

posBlocks[thisClient][thisHandle].pb=malloc(128);status=BTRVID(btrvParms->opCode,

posBlocks[thisClient][thisHandle].pb,btrvParms->dataBuf,&btrvParms->dataLen,btrvParms->keyBuf,btrvParms->keyNum,btrvParms->clientID);

}if ( status!=0 ) //Error opening?{

if ( thisHandle<MAX_CLIENT_HANDLES ){

free(posBlocks[thisClient][thisHandle].pb);posBlocks[thisClient][thisHandle].pb=NULL;

}

}else{

// this is to allow us to send back fictitious // position blocks and get back to the real block.// This is needed so that we can reset all files// when STOP or RESET is called.wsprintf(btrvParms->posBlk,”%d”,thisHandle);

}break;

First, we look through the position block structures that belong to thisclient to find one that is available. If we do not find one, we “spoof,”passing back our own error code indicating the server’s handle table is full.If we find a position block structure that we can use, we allocate the space,try the open, and finally check the status again. If the status is non-zero(indicating a failure), the memory allocated is freed and the pointer reset toNULL. If the file is opened correctly, we use wsprintf() to set the positionblock equal to the ASCII representation of the number of this file for thisclient. This is what we pass back to the client for a position block. I couldhave simply used an int to represent the value, taking only 4 bytes ratherthan whatever the printed representation would take up, but we have 128bytes to fool with, and the text version is easier to look at in a debugger...

This allows us to have access to all open position blocks wheneverSTOP or RESET is called, because the server has all the position blocks,and the client has only handles into our table, which allow other operationsto work. For instance, the default case statement shows how to get back tothe REAL position block:

default:status=BTRVID(btrvParms->opCode,

posBlocks[thisClient][atoi(btrvParms->posBlock)].pb,btrvParms->dataBuf,&btrvParms->dataLen,btrvParms->keyBuf,btrvParms->keyNum,btrvParms->clientID);

break;

Here we see that we use the atoi() return to get at the index into theposBlocks array.

Where will this scheme fail? If we have a program that does some-thing too clever, and depends upon some values in the position block, theywill fail. This is not too heavy a burden, since mucking with the positionblock is pretty much assured to break in newer versions of Btrieve anyway.

The Client Side

The client side of our Btrieve requester is fairly straightforward.First, the client application cannot be compiled with the normal BtrieveAPI, since we will take over that API. Calls to BTRVID() will not go tothe Btrieve interface code and then on to the Btrieve DLL, but rather willgo directly to OUR BTRVID() function. Our function will first determineif it needs to establish a session. It will need to establish a session if this isthe first call or if the last call was a call to RESET. On first calls, and oncalls after a RESET or STOP, the BTRV function will start with the staticcliSocket set to INVALID HANDLE, and it will re-establish contact withthe server (which in this example defaults to “pentium”).

Stepping back a bit from this initial call to our special BTRVID()call, we require a call to take place before the first call to BTRVID(). Thiscall to WSAStartup() is in the main() routine in our example, but could beplaced wherever it makes sense in a non-demo application, as long as it isassured that it will be called before any call to BTRVID(). WSAStartup()is one of those function calls for WinSock that are special Windows relatedcalls with no similar call in the Berkley Sockets specification.

In BTRVID(), (listing 3) we initialize a structure to allow “binding”to the socket, then we call a function that gets host information requiredfor a TCP/IP session given the name of the host. This is much more con-venient than using the standard “dotted notation,” for example,128.4.56.22. While these addresses are required for TCP/IP to function, itis easier to remember the server name (in our example, “pentium”). Thisassumes that you have a way for the system to resolve names to addresses.This is often done using a HOSTS or LMHOSTS file, which is simply anASCII file that contains addresses and names of hosts you have access to.Other name resolution systems exist, but again, these are beyond the scopeof this discussion.

If we cannot get the host information, we return status 20, indicatingrecord manager not loaded. Otherwise we send an initial message to theserver to establish the connection, and then proceed to send the parameterssent to our BTRVID() on to the server. In both the server and the client,we use the functions csSend() and csReceive() respectfully to send andreceive data across the network. These functions serve to isolate us fromthe details of how the data is sent. A more complete implementationwould allow you to have a client that can, with changes to INI files or reg-istry entries, convert from using WinSock to Named Pipes without changesto the application level code.

Finally, our BTRVID() call either sends back the status code returnedfrom the client or our “spoofed” code 20, and converts the data in thestructure passed from the server back into the parameters sent to ourBTRVID().

Conclusions

How useful is this example? As presented, not too terribly useful, butperhaps reasonable for some of the examples mentioned earlier in the arti-cle, notably for simple clients that might require minimal interaction withthe database, or for situations where the current requesters need to commu-nicate constantly thwart a networking scheme using a metered transport


media, such as ISDN. The example serves to remind us of the detailsthat have to be remembered when designing a client/server system, espe-cially when you have compatibility with an existing non-client/serversystem in mind.

The example code is used in a Win32 console mode application.The server is quite properly a console mode application. Unless there issome user interface required of the server, using Win32’s console modecan be quite useful, as you can concentrate on the application itself,without the need to concern yourself with the details of the Windowsframework. The example client simply calls our copy of BTRVID() thatis linked in statically.

A useful change to the client side would be encapsulation of theclient’s functionality in a stand-alone DLL. Add to the DLL functionali-ty to handle the file name resolution and include all ten exports exportedin the real Btrieve DLL, and you can have a system where your modi-fied DLL can act as a stand-in interface for ANY Btrieve application.This is useful for more than just the case of writing your own simplerequester. Imagine that you needed to place a security layer on Btrieve,more exotic than that allowed by use of owner names. Call your DLLWBTRV32.DLL, and any Btrieve application can use it. It is even pos-sible to have your “WBTRV32.DLL” call the REAL WBTRV32.DLL(assuming it is renamed or placed in a directory where it will not befound before your DLL) and provide a different type of security than ispossible with the plain vanilla Btrieve installation. While this is oneproject that should have one of those “We are professionals ñ Don’t trythis at home” messages in from of it, I will explore this as a possibilityin the next BDJ. In addition, some of the details of the WinSock usagein these examples should fit in the next issue as well.

One detail in the example code reminds me of a controversy cur-rently raging on the Pervasive Software’s CompuServe Forum. One useris VERY upset at the 64-client ID limit. Just like some of the limits thathave found their way into this code (50 files per client, 100 clients),there is no hard and fast rational for this particular limit, but there needsto be SOME limit, and this developer decided these were reasonablelimits. However, often some seemingly reasonable limits imposed bydevelopers have implications beyond the vision of the developer. Forthis reason, I am becoming conscious of things that I do in code thatimpose a restriction on the user of the code and documenting theserestrictions. The butt saved by having these restrictions documentedcould be your own, since limitations not made explicit are as likely tobite the developer of the code as others.

References

Microsoft Developers Network Library CD — Contains a completedescription of the WinSock API. Essential if you are ready to get intothis stuff at a lower level, and really valuable even for the VB or MSOffice developer.

Win32 Client/Server Developer’s Guide (by Doug Reilly, Addison-Wesley, ISBN 0-201-40762-0). I am a bit biased (since I wrote thebook), but I believe it provides a reasonable introduction toClient/Server development. Some code from the article derived from thebook, with neater examples of protocol independent API’s presented.NetWare code is weaker than the pure Win32 stuff because the NetWare32-bit development kit was not functional when the book was written.

Modern Operating Systems (by Andrew S. Tanenbaum, Prentice-Hall, ISBN 0-13-588187-0). I don’t get a nickel if you buy this one, butI still recommend it for anyone doing serious multitask programming.There are no Win32 references (not even Windows references), but it isa very good volume to get you started thinking about these issues at amuch deeper level than you might normally do.

Listing 1 — Structure definitions to support the Btrieve client/servercommunication.

#ifndef CHAT_H#define CHAT_H

#include “btrapi.h”

#define CS_REQ_CHAT 1000

struct BTRIEVE_PARM_INFOBTI_WORD opCode;BTI_BYTE posBlk[128];BTI_WORD dataLen;BTI_BYTE keyBuf[255];BTI_SINT keyNum;BTI_BYTE clientID[16];// Reasonable default buffer length...Increase if you need larger.BTI_CHAR dataBuf[32000];

};

struct BTI_POS_BLK {BTI_BYTE *pb;

};

#endif

Listing 2 — doChat() function that passes requests to the Server’sMKDE.

void DoChat(DATA_PACKET *p,WORD commHandle){

CHAR buffer[1152];CHAR who[100];CHAR chRequest[MAX_DATA_SIZE];BTI_WORD status;

DWORD bytesRead,bytesReplied;BOOL fSuccess;BTRIEVE_PARM_INFO *btrvParms;int thisClient=0;int thisHandle=0;

//critical section!EnterCriticalSection(&CriticalSection);thisClient=curClient;curClient++;LeaveCriticalSection(&CriticalSection);// Leave critical section.

FOREVER{

memset(chRequest,’\0’,MAX_DATA_SIZE);fSuccess=csRecv(commHandle,chRequest,bytesRead);memcpy((char *)p,&chRequest[0],MAX_DATA_SIZE);btrvParms=&p->data[0];if ( p->serviceCode==CS_ABANDON_REQUEST ){

csDisconnect(commHandle);break;

}

if ( fSuccess==FALSE || bytesRead==0 ){

showError(“csRecv”);break;


}else{

switch ( btrvParms->opCode ){case B_OPEN:

for ( thisHandle=0 ; thisHandle<MAX_CLIENT_FILES && posBlocks[thisClient][thisHandle].pb!=NULL ;

){

thisHandle++;}posBlocks[thisClient][thisHandle].pb=malloc(128);status=BTRVID(btrvParms->opCode,

posBlocks[thisClient][thisHandle].pb,btrvParms->dataBuf,&btrvParms->dataLen,btrvParms->keyBuf,btrvParms->keyNum,btrvParms->clientID);

if ( status!=0 ) //Error opening?{


}else{

// this is to allow us to send back fictitious // position blocks and get back to the real block.// This is needed so that we can reset all files// when STOP or RESET is called.wsprintf(btrvParms->posBlk,”%d”,thisHandle);

}

break;

case B_CLOSE:status=BTRVID(B_CLOSE,


free(posBlocks[thisClient][atoi(btrvParms->posBlock)].pb);posBlocks[thisClient][atoi(btrvParms->posBlock)].pb=NULL;break;

case B_RESET:case B_STOP:

for ( thisHandle=0, status=0 ; thisHandle<MAX_CLIENT_FILES && status==0 ; thisHandle++ )

{if ( posBlocks[thisClient][thisHandle].pb!=NULL ){

status=BTRVID(B_CLOSE,posBlocks[thisClient][thisHandle].pb,

btrvParms->dataBuf,&btrvParms->dataLen,btrvParms->keyBuf,btrvParms->keyNum,btrvParms->clientID);


}}csDisconnect(commHandle);break;

continued on page 26

default:status=BTRVID(btrvParms->opCode,


break;

}

p->returnCode=status;memcpy(chRequest,(char *)p,MAX_DATA_SIZE);// although the structure has a 32000 byte buffer, // send only what is needed.bytesReplied=(sizeof(struct BTRIEVE_PARM_INFO)-

(32000-btrvParms-dataLen))+12;

fSuccess=csSend(commHandle,chRequest,bytesReplied);}

}

}

Listing 3

BTI_API BTRVID(BTI_WORD operation,BTI_VOID_PTR posBlock,BTI_VOID_PTR dataBuffer,BTI_WORD_PTR dataLength,BTI_VOID_PTR keyBuffer,BTI_SINT keyNumber,BTI_BUFFER_PTR clientID )

{static SOCKET cliSocket=INVALID_SOCKET;struct sockaddr_in cliSocketAddr;struct sockaddr_in srvSocketAddr;struct hostent *host;LPVOID lpvBuffer=NULL;CHAR chBuffer[MAX_DATA_SIZE];CHAR gotSock=0;BOOL fSuccess=FALSE;DWORD bytesRead;DWORD bytesWritten;DWORD dwMode;BTI_WORD status;int error;CHAR serverName[255];CHAR who[100];DATA_PACKET p;BTRIEVE_PARM_INFO *btrvParms;

status=0; // default to success...// this is the server I am attempting to get to...

strcpy(serverName,”Pentium”);

// do this the first time through or if RESET was last called...if ( cliSocket==INVALID_SOCKET ){

cliSocket=socket(PF_INET,SOCK_STREAM,0);gotSock=1;

}if ( cliSocket==INVALID_SOCKET ){

/* Report that Windows Sockets did not respond to the WSAStartup() call */printf(“\nCLIENT error - Invalid socket returned from socket().”);

WSACleanup();exit(0);

}

if ( gotSock ){

cliSocketAddr.sin_family=AF_INET;cliSocketAddr.sin_addr.s_addr=INADDR_ANY;cliSocketAddr.sin_port=0;if ( (bind(cliSocket,(LPSOCKADDR)&cliSocketAddr,

sizeof(cliSocketAddr)))==SOCKET_ERROR ){

printf(“\nCLIENT error %d - socket can’t be bound.”,WSAGetLastError());WSACleanup();

exit(0);

}

host=gethostbyname(serverName);

if ( host==NULL ){

status=20; // record manager not found...}else{

srvSocketAddr.sin_family=AF_INET;srvSocketAddr.sin_addr.s_addr=INADDR_ANY;memcpy(&srvSocketAddr.sin_addr.s_addr,*host->h_addr_list,4);srvSocketAddr.sin_port=5001;

if ( connect(cliSocket,(LPSOCKADDR)&srvSocketAddr,sizeof(srvSocketAddr))==SOCKET_ERROR )

{printf(“\nCLIENT error %d - socket can’t connect.”,

WSAGetLastError());WSACleanup();exit(0);

}// initial send to establish communications...p.serviceCode=CS_REQ_CHAT;p.returnCode=0;bytesWritten=strlen(p.data)+12;fSuccess=csSend(0,(LPVOID)&p,bytesWritten);if ( !fSuccess ){

showError(“WriteFile”);}else{

printf(“\nCONNECTED to server, awaiting a response!\n”);}

}}// Use handle 0, just for a consistant approach. Change the connect code above, and the // csSend and csRecv code, and this can be used for a different protocol.commHandles[0].flag=1;commHandles[0].cliSocket=cliSocket;

btrvParms=(struct BTRIEVE_PARM_INFO *)&p.data[0];btrvParms->opCode=operation;btrvParms->keyNum=keyNumber;btrvParms->dataLen=*dataLength;memcpy(btrvParms->posBlk,posBlock,128);memcpy(btrvParms->dataBuf,dataBuffer,*dataLength);memcpy(btrvParms->keyBuf,keyBuffer,255);if ( status=0 ){

fSuccess=csSend(0,(LPVOID)&p,bytesWritten);// default to failure...p.returnCode=9999;fSuccess=csRecv(0,(LPVOID)&p,bytesRead);if ( fSuccess )


continued from page 25

continued on page 28

Configure? Go Figure!!!By Dale HunscherSouth Wind Design, Inc.E-Mail: [email protected]

Btrieve has been a part of the savvy PC programmer’s tool setsince the dawn of life as we know it. One of the principal engineershere at South Wind Design, Inc. had the honor of buying the firstcopy of Btrieve ever sold, soon after buying a very early IBM PC.Btieve was likely the first (and certainly the most popular) sharedsoftware component available on the IBM PC.

While this dominance in the marketplace is a powerful indica-tor of Btrieve’s speed, reliability, and flexibility, it has also led tooccasional configuration conflicts, as different versions of Btrieveworkstation engines and requesters abound on end user machines.This problem was not too serious for DOS applications, but hasbecome more apparent with the advent of Microsoft’s Windowsfamily of operating systems. The problem has three roots:

• A huge number of applications redistribute Btrieve compo-nents, or rely on their availability as part of NetWare client software.

• Until very recently, there was no standard for how to install shared components on IBM PCs. Windows 95 and Windows NT 4.0 now have a standard, but it is neither widely publi-cized nor well documented.

• The architectures for sharing components in existing versionsof Windows have serious design flaws.

If you sell, re-sell, or distribute Btrieve-based applications orserver products, you’ve encountered these kinds of configurationproblems. We’re not here to save the world (that happens in a laterissue!), so this brief article just describes the top configuration prob-lems we’ve seen in Btrieve installations, how to fix them, andstrategies for diagnosing other configuration-related problems.

1. App Won’t Start (Ever)Common causes:a) Older version of WBTRCALL.DLL in the search path.b) Newer version of WBTRCALL.DLL than expected found in

the path, and app doesn’t assume it will be backward com-patible.

c) Broken version of WBTRCALL.DLL in the search path (i.e., one that does not correctly support Btrieve function calls).

d) WBTRCALL.DLL, support DLLs, or workstation engine components not found on the search path.

The search order for finding a DLL or other supporting compo-nents varies a bit from one Windows version to another, but alwaysincludes the application program’s executable directory and workingdirectory, the Windows and Windows SYSTEM sub-directory, theSYSTEM32 sub-directory under Windows NT, and the directorieslisted in the current value of the PATH environment variable, andany mapped network drives.

If the version of Btrieve components required by the applica-tion is not found, it cannot be loaded into memory, so the app won’tstart. Some apps incorrectly assume a newer version is not back-ward compatible, and stop themselves without trying to use a newerversion of Btrieve than expected.

2. App Won’t Start (Sometimes)Common Cause:Older version of Btrieve found in a legacy app’s home directory

is loaded into memory when an app that requires a newer version istrying to start up. This is a problem for 16-bit Btrieve only. Under32-bit, apps don’t share components in the same way, so two ver-sions of Btrieve can be operating in memory simultaneously.

3. App Can’t Connect To Server (or Workstation) Engine Common Causes:a) Wrong version of requester (see 1, above).b) BTI.INI settings are wrong (16-bit apps only).c) Registry settings are wrong (all 32-bit apps, and 16-bit apps

thunking into Btrieve for Windows 95).

See the documentation that comes with your workstation orserver engine for the correct settings. The general rules are:

• Find the settings for local and requester (BTI.INI for 16-bit apps, the registry for 32-bit apps).

• If using a 16-bit app with 16-bit Btrieve, set the BTI.INI entries to local=yes (or no) to enable (or disable) access to thelocal engine, and requester=yes (or no) to enable (or disable) access to remote engines.

• If using a 16-bit app with the 32-bit Btrieve For Windows 95/Windows NT, set the BTI.INI entries as follows: local=no, requester=no, thunk=yes. This will cause your app to thunk into 32-bit Btrieve. Then follow the instructions for 32-bit apps, below.

• If using a 32-bit app, or thunking into 32-bit Btrieve from a 16-bit app, set the registry entries to local=1 (or 0) to enable (or disable) access to the local engine, and requester=1 (or 0) to enable (or disable) access to remote engines.

4. App Causes Many Status 2 ErrorsCommon Causes:a) (NetWare 4.10 only) NetWare TurboFAT Bug. A beta fix for

NetWare 4.10, available from Pervasive Software technical support or from Novell, can eliminate the cause of intermit-tent status 2 problems occurring in variable-load multi-user Btrieve apps.

b) Bad disk controller or network card. Use only Novell-certi-fied hardware; substitute known-good equipment for suspect equipment and see if the problem goes away.

Unfortunately diagnosing configuration-related problems isn’talways so simple. Sometimes users have multiple Btrieve apps ontheir machines, and often these apps require different, and sometimesincompatible, versions of Btrieve or other Pervasive Software prod-ucts. Throwing a new app into the mix while keeping all the otherapps up and running can sometimes be a frustrating and time-con-suming affair.


Dale Hunscher is the author of Smithware’s SupportAbilityfor Btrieve (http://www.smithware.com/products/supportability.com). SupportAbility is a Btrieve configuration diag-nostic tool designed to help developers and support person-nel resolve software configuration problems.


Dumb terminal attached to Mainframe

PC acting as Robot User on Mainframe

PC using RPC

PC using server based SQL

PC on LAN

Standalone PC

Smart Terminal

Client

Server

Figure 1 — The Client/Server Continuum

{btrvParms=(struct BTRIEVE_PARM_INFO *)&p.data[0];dataLength=btrvParms->dataLen;memcpy(posBlock,btrvParms->posBlk,128);memcpy(dataBuffer,btrvParms->dataBuf,btrvParms->dataLen);memcpy(keyBuffer,btrvParms->keyBuf,255);

}if ( operation==B_STOP || operation==B_RESET ){

WSACleanup();cliSocket=INVALID_SOCKET;

}}else{

p.returnCode=status;}return(p.returnCode);}

Orem, Utah — TradeMark Software has just announced a new versionof its flagship product SoftPort, a solution for processing on-line creditcard authorization, address verification and automatic transaction set-tlement. SoftPort is Built-on-Btrieve and is designed to integrate intoany other Btrieve-based application.

Mail-order companies rely heavily on information systems toexpedite the acquisition and processing of orders and retail and mail-order credit card transactions.

Capitalizing on his experience in building corporate order-entrysystems, Mark Russon, president of TradeMark Software, saw theneed for a product that filled a niche in the area of electronic creditcard processing. According to Russon, SoftPort is the “most powerfuland easy-to-use credit card authorization software available,”

To process a credit card transaction using SoftPort, an applicationinserts a record into the SoftPort transaction queue (a Btrieve file) withthe necessary fields filled, such as credit card number, expiration dateand purchase amount. Then, the application polls the inserted record tosee if its status has changed to “completed.” Within four to eight sec-onds, SoftPort processes the transaction record and updates its status,as well as returning such fields as Approval Code and AddressVerification Result Code.

SoftPort runs under Windows 3.1, 95 or NT. It can be used byany application which can access regardless of the OS on which theapplication is runnging.

TradeMark Software worked with Visa Corporation in develop-ing SoftPort technology for electronic credit card verification and set-tlement. The company plans to introduce version 2.0 to support asyn-chronous leased-line authorization and draft capture directly withVisaNet.

For more information, contact TradeMark at 801-223-9404, orvia E-mail at [email protected], or visit TradeMarks’s web siteat http://www.idworks.com/softport.

Credit Card Authorization Systemis Built-on-Btrieve

Fresno, California — Yosemite Technologies recently released version 5.0 ofTapeWare, the company’s data archival storage program designed to back-upand restore network data. The upgrade from Version 4.2 is designed to fit anyconfiguration, from a single PC to NetWare network. TapeWare provides a fileserver-based tape rotation manager, unattended job scheduling, integratedlibrary and quick file access. Of particular interest to Btrieve and Scalable SQLusers is that the product integrates with the Micro Kernel Database Engine onthe NetWare server to backup open and active Btrieve files.

Version 5.0 adds a new MicrosoftWindows 95 and Windows NT work-station client user interface, whichallows backup and restoration ofMicrosoft Windows 95 and MicrosoftWindows NT registry databases. Theproduct supports long files names, andincludes Windows 95 and WindowsNT file system agents which allowserver-based backup of files residingon network client workstations.

Other version 5.0 enhancementsinclude added support for NetWare4.10, NetWare 4.11 and 4.11 SFT-III,drivers for ADIC VLS Dual DriveAutoloader, Quantum DLT 2000XT,and Tandberg MLR1 mass storagedevices, and automatic detection ofASPI controllers.

TapeWare/LAN-NLM is available in NetWare user levels from 5 to 1000,and offers remote backup and restore for OS/2, Unix(NFS), DOS, Windows 95,Windows NT, and NetWare 4.x, 3.x and 2.x. The manufacturer’s suggested listprice is $199 to $1,399. For more information, visit the Yosemite Technologiesweb site at http://www.tapeware.com. The company can be reached by phone at209-292-8888, or by fax at 209-292-8908.

TapeWare 5.0 Releasedcontinued from page 28


Win32 Client/ServerDeveloper’s GuideBy Jim Kyle Automation Resources, Inc.E-mail: [email protected]

Want a quick introduction to what client/server computing is allabout? Or maybe you need a way to set up applications for client/serveruse that will be able to survive almost unchanged when your customersconvert from using NetWare to using Windows NT as their network? Oris all you want a simple way to explain the differences between the vari-ous available solutions, when a prospect asks for more detail?

If you answered “yes” to any of those, then you’ll find DougReilly’s Win32 Client/Server Developer’s Guide (ISBN 0-201-40762-0,1996, $39.95, from Addison-Wesley) a worthwhile investment. Even ifyou answered “no” to all three questions, you still ought to at least takea look at Doug’s work in your friendly neighborhood bookstore, since“client/server” is the buzzword of the year. Even Pervasive Software,the makers of Btrieve, have adopted “Client/Server In a Box” as one oftheir trademarks.

The Basic Premise

Covering the entire scope of client/server computing is a task farbeyond any single book, so Doug has quite wisely limited his premiseto the use of client/server techniques with 32-bit Windows systems. Thistranslates, in practice, to Windows 95 and Windows NT workstations,on networks running one of the four major versions of NetWare or run-ning Windows NT Advanced Server.

He begins with simple yet clear illustrations of the differencesbetween local database access, file-server access, and client/serveraccess. The examples he gives here make it easy for you to explain thedifferences to your non-technical customers, and to select the bestapproach for any specific application task. That’s not always a trueclient/server approach, either, although uninformed customers mayinsist that this is what they want.

From that beginning, he moves on to cover many aspects ofclient/server development. They range from the use of screen-scrapingtechniques when the “server” happens to be a minicomputer or main-frame such as the AS/400, through the creation of custom NLM mod-ules, to the use of Named Pipes, the WinSock library, and RemoteProcedure Call technologies.

Throughout all, this book maintains a totally realistic attitude. The“Conclusion” section for Chapter 8 sums things up quite nicely: “Thebottom line for any programmer is getting the job done. ... Althoughsome of the methods presented ... are Stone Age in comparison to ...methods presented elsewhere, if at the end of the day the job is done inan ugly way or a pretty way, it is still done. And when the only option is

ugly, ugly will have to do.”

What’s the Btrieve Connection?

“Okay,” you may be asking about now, “but what does all this haveto do with Btrieve, anyway?” The answer is that throughout the book,Doug uses Btrieve as the example whenever an example is needed andthere’s any way at all of fitting Btrieve into the solution.

As early as Chapter 4, he introduces Btrieve as his primary exam-ple, to bring out the differences between using it in a standalone situa-tion, on a network with file servers but not taking advantage of theclient/server capability, and finally using the package in true client/serv-er fashion.

In one benchmark, comparing a number of typical actions betweenfile-server usage and the client/server approach, Btrieve took almosttwice as long to insert 7,865 records into an existing file when runningin server-only mode. While this is impressive enough, another testinvolving selection of 608 records from the same file based on a non-indexed field took more than seven times as long to do in server-onlymode. While the task required only six seconds in client/server configu-ration, it took 44 seconds otherwise.

Although the primary focus of the book is upon creation of a net-work-intermediary layer API to insulate client and server from eachother, most of the examples that involve database dealings use Btrieveas the specific instance.

A Universal API

That network-intermediary API is the core of the book. In manyways, the first two thirds of the book serves as preparation and sets thestage for full comprehension of what the author accomplishes in Chapter13, when he presents the complete network intermediary layer API.

The great advantage of adding such a layer is that using it givesyou the opportunity to change to a totally different network architecturewith no change in your client applications. Simply replacing the serverside of the API layer takes care of all the differences.

The downside, of course, is that the API must necessarily reflectthe lowest common denominator of all functions provided by the net-works involved. Anything that’s missing from even just one server net-work has to be left out of the API in order to achieve the goal of plat-form independence. Fortunately, the API that Doug has developed andprovides on the included 3.5-inch diskette does an excellent job of mini-mizing this effect. For most enterprises it should never appear.

Who is This Guy Anyway?

Doug Reilly needs no introduction to regular readers of BtrieveDeveloper’s Journal. His regular column here brings out many of thehidden or not well known aspects of Btrieve development. Those of uswho know him primarily as one of the leading Btrieve gurus, however,may be somewhat amazed when reading this book to learn that he’sequally expert in many other database systems as well.

His company, Access Microsystems Inc., provides custom softwareand support to a number of health care institutions in the northeasternU.S., and publishes a series of Btrieve development tools that are dis-tributed as shareware. It’s a family business, with both his son and hisdaughter taking part (to which he alludes in his introduction to thebook).

The Bottom Line

I can’t claim to be totally objective in this review, since I’veworked closely with Doug for several years now (he served as technicalreviewer for Btrieve Complete, at my recommendation). However, Ifound it so valuable at several levels that I think I would have bought iteven had I never heard of him.

In other words, I like it. Take a look at it and see if you agree withme.


ContactUs

CompanyInfo

BDJMagazineSupportHow to

OrderProductsWhat’sHot

HomePage

Smithware Tech Talk is a regular supplementto Btrieve Developer’s Journal, providing thelatest information about Smithware products.

http://www.smithware.com

Be sure to check out the new features of the Tech Support webpage like the new Btrieve Matrix of Configurations for Btrieve.

Smithware Year 2000 Compliance

You hear panicked talk about this everywhere from the local bankto the British House of Commons on C-SPAN2 but ...

“All software that Smithware distributes is Year 2000 compli-ant. We support both short dates (mm-dd-yy) and long dates (mm-dd-yyyy) in all products. It is up to the developer who usesSmithware products to choose which type of date implementationto support.”

Help on choosing a date implementation...For a date data types to be “Year 2000 Compliant” it must be able

to store information about the century. The following data types support-ed by Smithware store information about the century. Ergo, they can beYear 2000 Compliant.

Btrieve DateMagic Int Date-0001Magic Int Date-1901TAS DateVB Date-TimeYYYYMMDD 8-Byte DateYYYYMMDD Long Int Date

The following data types supported by Smithware do not storeinformation about the century. Thus, by their own nature, are not Year2000 Compliant.

YMD 3-Byte DateYYMMDD 6-Byte Date

To guarantee that data entered on a platform is Year 2000Compliant, you can change the short date format in the operating sys-tem settings from MMDDYY to MMDDYYYY. This makes it necessaryfor a four digit year to be entered.

Tech Tips

Cannot convert ANSI to OEM characters with the decimal value 32 -126, and 160 - 255 and vice versa.

In Smithware Crystal Reports, ANSI conversion can be toggled onand off by using the DosString = Yes/No option in the CRW.INI file. InDDF Builder, this effect can be achieved by using the OemConvertcheck box or the OemConvert setting in the WINDDF.INI file. In the VBXControls and ActiveX Controls, this option can be found in the propertieswindow for the VAccess Control.

In Delphi ( version 2.01 none of the samples that were providedoperate, the class names are invalid.

Delphi (assigns default class names to the ActiveX Controls.Smithware has no determination options over that default assignment. Insome builds of Delphi, these default class names change (to somethingdifferent than our builds assign) resulting in the halting of the sampleprograms from operating at all. The class names can either be changedto your build’s default names in our samples or, in Delphi, by removing

the controls and re registering them with the names of choice.

Compobj.dll is out of date An error message pops up during the installation with the above

information. The resolution for this is to rename the version of com-pobj.dll that is currently in \windows\system and reinstall our product.The current shipping version of this file is dated 08/15/95 12:00AM and107KB in size. A version dated after the shipping version can also beused.

Tech Tip of the Issue

Question: I made an application with Microsoft Visual Basic™Application Setup Wizard using the ActiveX Controls, but when I distrib-ute them I can’t get the controls to register, what can I do?

Answer: The first thing to be aware of is that for the ActiveX Controls toregister a working installation of Btrieve must be on the machine prior tothe distribution of the application. (N.B., You must be licensed to distrib-ute Btrieve program files. See ActiveX Help | Distributing Files withApplications | Important Copyright Information)

The next thing to be aware of is that there are four redistributablefiles that either must be present on the target platform or distributedduring the installation. They are:

For 16-bit applications: File Location Registrationacbtrv16.ocx SYSTEM Must be registered.acctrl16.ocx SYSTEM Must be registered.sedtconv.dll SYSTEM No registration needed.vamngr16.dll SYSTEM No registration needed.

For 32-bit applications:File Location Registrationacbtrv32.ocx SYSTEM Must be registered.acctrl32.ocx SYSTEM Must be registered.s2dtconv.dll SYSTEM No registration needed.vamngr32.dll SYSTEM No registration needed.

The file wbtrcall.dll is also needed to allow for the controls to self-regis-ter for 16-bit applications and wbtrv32.dll for 32-bit applications (see thenote above about licensing).

With these conditions met you should ensure that these lines ofcode are in the file swdepend.ini used by the VB Setup Wizard

[ACCTRL16.OCX] [ACBTRV16.OCX]Register=$(DLLSelfRegister) Register=$(DLLSelfRegister) Dest=$(WinSysPath) Dest=$(WinSysPath) Uses1=OCX Runtime Support Uses1=OCX Runtime Support Uses2=VAMNGR16.DLL Uses2=VAMNGR16.DLLUses3= Uses3=SEDTCONV.DLL

Uses4=


DDF Builderddfsvc.zip (257K)Patch for DDF Builder 2.50a and 2.50.003 only. (PKZIP format). winddf.zip (237K)Contains the DDF Builder version 2.51.012 patch update. Fixes printingproblem, runtime 380 error when copying a table definition. Note: thisfile patches 2.51 versions of DDF Builder ONLY. If you have an earlierversion of DDF Builder, contact Smithware for upgrade information.Note: Also contains patch update files for VCBTRV.VBX andWINDDFUI.DLL. (PKZIP format).

DDF Snifferddfsniff.zip (62K)DDF Sniffer version 1.50.003 patch update. Fixes program lock up prob-lem on files with certain index characteristics. Note: This patch alsorequires the winddf.zip (237K) patch update. Note: this file patches 1.50versions of DDF Sniffer ONLY. If you have an earlier version of DDFSniffer, contact Smithware for upgrade information. (PKZIP format).

Miscellaneous Filess2dtconv.zip (32K)Contains the latest version of S2DTCONV.DLL. Do not install unlessadvised to do so by Smithware Technical Support. (PKZIP format). sedtconv.zip (31K)Contains the latest version of SEDTCONV.DLL. Do not install unlessadvised to do so by Smithware Technical Support. (PKZIP format).

SupportAbility for Btrievesuscript.zip (38K)Contains the latest configuration scripts for SupportAbility for BtrieveStandard Edition. This file is password protected. Registered users maycontact Smithware Technical Support with their registration informationfor the password. (PKZIP format).

VBX Controls for Btrieveexbtrv.zip (85K)VBX Controls for Btrieve 2.50 patch to the Extended Operations VBX.Applies to version 2.5 only. Fixes problem with the GotData event notfiring. (PKZIP format). vcbtrv.zip (77K)VBX Controls for Btrieve 2.50 patch to the latest version. Applies to ver-sion 2.5 only. DDF Builder will not work with this version, so be sure tokeep your unpatched copy of vcbtrv.vbx in the same directory aswinddf.exe. (PKZIP format).

From the Tech Support Blotter

In Tech Support, there are many questions that come in that are inno way associated with our software like the message, “I installed yoursoftware and now my computer will not turn off.” But a reoccurring mes-sage — the latest received in the wee hours of the night on January 13,1997 — goes something like this...

“Ah, yeah, this is Peter at Country Lock and Key of Idaho and I gotme a safe, Sentry number 3140, that I need to break into down at theWal-Mart. If you could tell me the drill points that would be just greatcause I gotta run down there in a few hours and get in it. Thanks.”

My initial thoughts ran towards an acetylene torch. But thanks tomy days at the University, I learned how to pick locks so something thatbulky and messy is not necessary. Then, I thought that giving out thisinformation would probably be breaking some kind of interstate felonylaw that would go onto my permanent record.

Actually the Smithware’s 800 number is one digit off of a safe com-pany that keeps this kind of information on hand. So, Tech Supportreceives about three of these misdirected calls a month and enjoysplaying the messages over for their co-workers enjoyment.

Contacting Smithware Tech Support

Internet: [email protected] Web Site: http://www.smithware.com/supportCompuServe: 75470,546Voice: 615.386.3100x14Fax: 615.386.3135

Btrieve

Developer’s

FIXED

[ACCTRL32.OCX] [ACBTRV32.OCX] Register=$(DLLSelfRegister) Register=$(DLLSelfRegister) Dest=$(WinSysPath) Dest=$(WinSysPath) Uses1=OCX Runtime Support Uses1=OCX Runtime Support Uses2=VAMNGR32.DLL Uses2=VAMNGR32.DLLUses3= Uses3=S2DTCONV.DLL

Uses4=

[ACINET32.OCX] Register=$(DLLSelfRegister) Dest=$(WinSysPath) Uses1=OCX Runtime Support Uses2=VAMNGR32.DLLUses3=S2DTCONV.DLLUses4=SWCOMP32.DLLUses5=

Save the changes and run the Setup Wizard with these new set-tings. If all of the above is true, then during the installation of theapplication the ActiveX Controls OCX’s will register themselves.

To Be Fixed: Known Issues with Patches in Development

Magic Integer Date-1901In DDF Builder and ActiveX Controls, the date data type is

viewed/stored as one day earlier than the date expected in the applica-tion.

10-byte IEEE FloatUnfortunately Microsoft dropped support for this data type, and

our initial patch provides a work around for most numbers (the oneswe used to test) but not all.

Patches and Updates - A file listing for each component of thepatches can be found at the Smithware Tech Support Site www.smith-ware.com\support\

ActiveX Controls for Btrieveac3102.zip (323K)Contains the latest versions of ActiveX OCX files. Compatible onlywith version 3.0 of ActiveX Controls for Btrieve. Issues resolved:Erroneous User Counts, 255 byte length limit of text boxes, Clearmethod issues, International settings issues, NT Server issues, CZSting/Text Box issues, unsigned integer issues, any issues of previ-ous patches. Rename the old files in the acbtrv30 directory and placethese in that directory. (PKZIP format).

oc25dll.zip (247K)Place this file in \WINDOWS\SYSTEM if it is not there and DDFBuilder will not run because it cannot find the file. (PKZIP format). setuplib.zip (133K)Place this file on disk 1 when having installation problems onWindows 3.1. (PKZIP format). win31hlp.zip (118K)Windows 3.1 compatible help file. The help file included on the instal-lation disks will not run on Windows 3.1. (PKZIP format).

Class Library for Btrievebtkvlen.zip (11K)Smithware Class Library for Btrieve 4.0 patch. Corrects a bug in theKEYTYPES library encountered when compiling these files for usewith Microsoft MFC string classes. (PKZIP format).

Crystal Reports for Btrievedrivers.zip (61K)Smithware Crystal Reports for Btrieve 16-bit driver update. Passwordprotected. Contact Smithware Technical Support with your registrationinformation to receive the password if you need this patch. (PKZIPformat). driver32.zip (91K)Smithware Crystal Reports for Btrieve 32-bit driver update. Passwordprotected. Contact Smithware Technical Support with your registrationinformation to receive the password if you need this patch. (PKZIPformat).

Documents

Winter 1996 • Vol. IV No. 4 Pervasive Launches …So let’s have fun while we do it. Call Marjean Jones at 615-386-3100 x27 (or e-mail [email protected]) and sched-ule a video-conference