Btrieve Programmer s Reference

Transcription

1 Btrieve Programmer s Reference Copyright 1998 Pervasive Softare Inc. All rights reserved orldide. Reprodction, photocopying, or transmittal of this pblication, or portions of this pblication, is prohibited ithot the express prior ritten consent of the pblisher, nless sch reprodction, photocopying, or transmittal is part of a Derivative Softare Prodct as defined in the licenses granted in conjnction ith the prchase of this pblication and associated softare. This prodct incldes softare developed by Poerdog Indstries Poerdog Indstries. All rights reserved. Pervasive Softare Inc Capital of Texas Highay Astin, Texas USA

2 disclaimer trademarks PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN "AS IS" BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT. PERVASIVE SOFTWARE INC. MAKES NO OTHER WARRANTIES WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE OR THE CONTENT OF THE DOCUMENTATION; PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR YOUR COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT MAKE ANY WARRANTIES, INCLUDING, FOR EXAMPLE, WITH RESPECT TO MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE OR ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, AMONG OTHERS. Btrieve and XQL are registered trademarks of Pervasive Softare Inc. Bilt on Btrieve, Bilt on Scalable SQL, Client/Server in a Box, DDF Ease InstallScot, MicroKernel Database Engine, MicroKernel Database Architectre, Navigational Client/Server, Pervasive.SQL, Scalable SQL, Smart Components, Smart Component Management, Smart Naming, SmartScot, and Xtrieve PLUS are trademarks of Pervasive Softare Inc. Microsoft, MS-DOS, Windos, Windos NT, Win32, Win32s, and Visal Basic are registered trademarks of Microsoft Corporation. Windos 95 is a trademark of Microsoft Corporation. NetWare and Novell are registered trademarks of Novell, Inc. NetWare Loadable Modle, NLM, Novell DOS, Transaction Tracking System, and TTS are trademarks of Novell, Inc. All company and prodct names are the trademarks or registered trademarks of their respective companies. Btrieve Programmer s Reference Febrary 1998

3 Contents Abot This Manal Who Shold Read This Manal Organization Conventions Introdction to Btrieve APIs Btrieve Fnctions BTRV Fnction BTRVID Fnction BTRCALL Fnction BTRCALL32 Fnction BTRCALLID Fnction BTRCALLID32 Fnction Obsolete Fnctions Btrieve Fnction Parameters Operation Code Stats Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Client ID Key Length Smmary of Btrieve Operations Session-Specific Operations File-Specific Operations Btrieve Programmer s Reference 3 Contents

4 Seqence of Events in Performing a Btrieve Operation Btrieve Operations Abort Transaction (21) Begin Transaction (19 or 1019) Clear Oner (30) Close (1) Continos Operation (42) Create (14) Create Index (31) Delete (4) Drop Index (32) End Transaction (20) Find Percentage (45) Get By Percentage (44) Get Direct/Chnk (23) Get Direct/Record (23) Get Directory (18) Get Eqal (5) Get First (12) Get Greater (8) Get Greater Than or Eqal (9) Get Key (+50) Get Last (13) Get Less Than (10) Get Less Than or Eqal (11) Get Next (6) Get Next Extended (36) Get Position (22) Get Previos (7) Get Previos Extended (37) Insert (2) Insert Extended (40) Open (0) Btrieve Programmer s Reference 4 Contents

5 Reset (28) Set Directory (17) Set Oner (29) Stat (15) Stat Extended (65) Step First (33) Step Last (34) Step Next (24) Step Next Extended (38) Step Previos (35) Step Previos Extended (39) Stop (25) Unlock (27) Update (3) Update Chnk (53) Version (26) A Langage Interfaces C/C Interface Modles Programming Reqirements Program Example Creating Applications ith the Tenberry DOS/4G Extender Compiling, Linking, and Rnning the Program Example Compiling C++ Bilder Applications Cobol Program Example Delphi Program Example Compiling, Linking, and Rnning the Program Example Pascal Sorce Modles Compiling and Linking Using the Interface Program Example Btrieve Programmer s Reference 5 Contents

6 Programming Notes Visal Basic Program Example Compiling, Linking, and Rnning the Program Example Creating 32-Bit Applications B Data Types C Qick Reference of Btrieve Operations Btrieve Programmer s Reference 6 Contents

7 Tables 1-1 Btrieve Fnctions Client ID Strctre Session-Specific Operations File Access and Information Operations Data Retrieval Operations Data Maniplation Operations Data Bffer Strctre for Create Operation File Flag Vales Key Flag Vales Extended Data Types Data Bffer for Creating a User-Defined ACS Data Bffer for Specifying a Locale-Specific ACS Data Bffer for Specifying an ISR ACS ACS Name Formats Data Bffer Size Limitations by Environment Data Bffer for Random Chnk Operations Data Bffer for Rectangle Chnks Inpt Data Bffer Strctre for Extended Get and Step Operations Retrned Data Bffer Strctre for Extended Get and Step Operations Data Bffer Strctre for the Insert Extended Operation Open Modes Open Mode Combinations for Local Clients Using SEFS Btrieve Programmer s Reference 7 Tables

8 2-17 Open Mode Combinations for Local Clients Using MEFS Open Mode Combinations for Remote Clients Access and Encryption Codes Data Bffer Exclding File Version Information Data Bffer Inclding File Version Information Extended Files Descriptor System Data Descriptor Extended Files Retrn Bffer System Data Retrn Bffer Random Chnk Descriptor Strctre Rectangle Chnk Descriptor Strctre Trncate Descriptor Strctre Version Block A-1 Langage Interface Sorce Modles A-2 Common Data Types Used in the Btrieve Data Bffer A-3 Operating System Sitches B-1 Extended Key Types and Codes B-2 Rightmost Digit ith Embedded Sign C-1 Qick Reference of Btrieve Operations Btrieve Programmer s Reference 8 Tables

9 Abot This Manal This manal contains information abot ho to develop applications that se the Btrieve navigational data management system. Btrieve is designed for high-performance data handling and improved programming prodctivity. The fnctions described in this manal are available in the modles installed by the Programming Interfaces installation option. Yo may also parchase the Programmer s Site. The Programmer s Site prodct provides: all of the interfaces described in this manal a 5-ser version of both the NetWare and Windos NT server engines licensed for development and testing se only the complete set of Pervasive docmentation in hardcopy Who Shold Read This Manal This manal provides information for developers ho are sing Btrieve to develop applications for the OS/2, NetWare, Windos, Windos NT, and Windos 95 operating environments. Pervasive Softare old appreciate yor comments and sggestions abot this manal. Please complete the User Comments form that appears at the end of this manal, and fax or mail it to Pervasive Softare, or send to [email protected]. Btrieve Programmer s Reference 9 Abot This Manal

10 Organization Chapter 1 Introdction to Btrieve APIs This chapter provides a brief overvie of the Btrieve fnctions and their parameters. This chapter also smmarizes the Btrieve operations. Chapter 2 Btrieve Operations This chapter docments the Btrieve operations. Appendix A Langage Interfaces This appendix provides specific information abot the langage interfaces. Appendix B Data Types This appendix provides information abot the data types Btrieve spports for keys. Appendix C Qick Reference of Btrieve Operations This appendix smmarizes the Btrieve operations in order of operation nmber. Btrieve Programmer s Reference 10 Abot This Manal

11 Conventions Unless otherise noted, command syntax, code, and code examples se the folloing conventions: Case Commands and reserved ords typically appear in ppercase letters. Unless the manal states otherise, yo can enter these items sing ppercase, loercase, or both. For example, yo can type MYPROG, myprog, or MYprog. [ ] Sqare brackets enclose optional information, as in [log_name]. If information is not enclosed in sqare brackets, it is reqired. A vertical bar indicates a choice of information to enter, as in [file name]. < > Angle brackets enclose mltiple choices for a reqired item, as in /D=<5 6 7>. variable Words appearing in italics are variables that yo mst replace ith appropriate vales, as in file name.... An ellipsis folloing information indicates yo can repeat the information more than one time, as in [parameter...]. ::= The symbol ::= means one item is defined in terms of another. For example, a::=b means the item a is defined in terms of b. Btrieve Programmer s Reference 11 Abot This Manal

12 chapter 1 Introdction to Btrieve APIs The Btrieve navigational database management system is designed for highperformance data handling and improved programming prodctivity. Btrieve operations allo yor application to retrieve, insert, pdate, or delete records either by key vale, or by seqential or random access methods. The Programming Interfaces provide compatibility ith the folloing programming langages and development environments: Borland C/C++ Borland Delphi Micro Focs COBOL Microsoft Access Microsoft Visal Basic Microsoft Visal C++ Watcom C/C++ This chapter discsses the folloing topics: Btrieve Fnctions Btrieve Fnction Parameters Smmary of Btrieve Operations Seqence of Events in Performing a Btrieve Operation Btrieve Programmer s Reference 12 Introdction to Btrieve APIs

13 Btrieve Fnctions Btrieve offers a single-fnction API, in hich most program actions are determined by an operation code parameter, rather than a fnction name. Yo shold choose the API for yor application based on hether yo are most interested in cross-platform portability of code or the best possible performance on a particlar platform. Yor Btrieve application shold never perform any standard I/O against a data file. Yor application shold perform all file I/O sing a Btrieve fnction. Folloing are the Btrieve fnctions. Table 1-1 Btrieve Fnctions Fnction Operating Systems Description BTRV BTRVID BTRCALL BTRCALLID BTRCALL32 BTRCALLID32 All OS/2, Windos 3.x, Windos NT, and Windos 95 only For 32-bit OS/2 applications only Use for complete code portability beteen operating systems. For most developers, this advantage offsets a very slight performance decrease. Use these fnctions to achieve a slight performance increase or backard compatibility ith existing sorce code. To find the langage-specific syntax reqired hen calling a Btrieve fnction, refer to Appendix A, Langage Interfaces. Btrieve Programmer s Reference 13 Introdction to Btrieve APIs

14 BTRV Fnction BTRV allos an application to make Btrieve calls. All the langage interface modles provided ith the Programming Interfaces installation option spport the BTRV fnction. In OS/2, Windos 3.x, Windos NT, and Windos 95, the BTRV fnction actally calls the BTRCALL fnction. Hoever, BTRV is the preferred fnction becase of the platform independence it provides. BTRVID Fnction BTRVID allos an application to make a single Btrieve call that contains a clientid parameter, hich the application can control. An application can se BTRVID to assign itself more than one client identity to Btrieve and to execte operations for one client ithot affecting the state of the other clients. For more information, refer to Client ID. In OS/2, Windos 3.x, Windos NT, and Windos 95, the BTRVID fnction actally calls another fnction. In 16-bit applications, it calls the BTRCALLID fnction. In 32-bit applications, it calls the BTRCALLID32 fnction (OS/2) or the BTRCALLID fnction (Windos NT and Windos 95). Hoever, in both cases, BTRVID is the preferred fnction becase of the platform independence it provides. In DOS applications, yo mst load the DOS Reqester ith the appropriate /T vale. Set /T to eqal the nmber of client IDs yo se in the application. For more information abot the DOS Reqester, refer to Getting Started. BTRCALL Fnction BTRCALL is the preferred fnction if yor application accesses only local files and ses only the OS/2 or Win32 orkstation engines. For OS/2, the BTRCALL fnction is a 16-bit fnction. For Windos NT and Windos 95, the BTRCALL fnction is a 32-bit fnction. Btrieve Programmer s Reference 14 Introdction to Btrieve APIs

15 BTRCALL32 Fnction The BTRCALL32 fnction is the same as BTRCALL fnction, except that BTRCALL32 is a 32-bit fnction. BTRCALLID Fnction Use the BTRCALLID fnction if yo need client-level control and yor application operates only in the OS/2, Windos 3.x, Windos NT and Windos 95 environments. This fnction is similar to the BTRVID fnction, except that it does not call an intermediate fnction. For Windos NT and Windos 95, BTRCALLID is a 32-bit fnction. BTRCALLID32 Fnction The BTRCALLID32 fnction is the same as the BTRCALLID fnction, except that the BTRCALLID32 is a 32-bit fnction. Obsolete Fnctions The folloing historical fnctions are spported to maintain compatibility ith applications ritten for previos Btrieve releases: BTRCALLBACK BTRVINIT BTRVSTOP Btrieve Programmer s Reference 15 Introdction to Btrieve APIs

16 RQSHELLINIT WBRQSHELLINIT WBTRVINIT WBTRVSTOP BRQSHELLINIT While these fnctions are no obsolete, older applications that call these fnctions ill still rn ith 6.15 and later MicroKernels. (No additional fnctions have been made obsolete in Btrieve 7.0.) Btrieve Fnction Parameters Yo mst provide all parameters on every call; hoever, the MicroKernel does not se every parameter on every operation. In some cases, the MicroKernel ignores their vale. In general, different parameters can be sent and retrned for each operation. Chapter 2, Btrieve Operations provides a detailed description of the parameters that are relevant for each Btrieve operation. Note C developers: Refer to BTITYPES.H for a description of the platform-independent data types and pointers sed in the C langage interface. The parameters to the Btrieve fnctions are as follos: Operation Code Stats Code (BASIC and COBOL only) Btrieve Programmer s Reference 16 Introdction to Btrieve APIs

17 Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Client ID (BTRVID and BTRCALLID fnctions only) Key Length (BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 fnctions only) Operation Code The Operation Code parameter determines hat action is performed by the Btrieve fnction. For example, the operation may read, rite, delete, or pdate one or more records. Yor application mst specify a valid Operation Code on every Btrieve call. The MicroKernel never changes the Operation Code. The vale of the variable yo specify can be any one of the legal Btrieve Operation Codes described in Chapter 2, Btrieve Operations. Note C developers: The variable yo specify mst be BTI_WORD (an nsigned short integer). Stats Code Btrieve retrns stats codes as signed integers. In most programming environments, the stats code is the retrn vale of the Btrieve fnction call. Hoever, some BASIC and Btrieve Programmer s Reference 17 Introdction to Btrieve APIs

18 COBOL langage interfaces reqire a Stats Code parameter. This parameter is a 2-byte integer containing a coded vale that indicates hether any errors occrred dring the operation. After a Btrieve call, the application mst alays check the vale of the stats variable to determine if the call as sccessfl. Pervasive.SQL components retrn stats codes from calls to their APIs. When yo rite to these APIs, yo shold provide handling for three conditions: API Sccess Anticipated API failre Unanticipated API failre Folloing is a C code example that handles all three conditions. stats = BTRVID(B_VERSION, posblock1, &versionbffer, &datalen, keybf1, keynm, (BTI_BUFFER_PTR) &clientid); if (stats == B_NO_ERROR) { /* contine normal operation */ stats = BTRVID(...); } else if (stats == B_RECORD_MANAGER_INACTIVE) { /* handle knon error */ printf("btrieve Get Version() retrned B_RECORD_MANAGER_INACTIVE\n"); } else { /* nanticipated error */ printf("btrieve Get Version() retrned %d\n", stats); } /* end if-else */ Btrieve Programmer s Reference 18 Introdction to Btrieve APIs

19 By folloing this method of stats code handling, yo can help Pervasive Softare ensre yor application s ftre stability. Pervasive Softare encorages and incorporates developer feedback in order to continosly improve or prodcts. For example, in Pervasive.SQL 7, Stats Code 20 has been differentiated into several additional stats codes. Applications that handle stats information as demonstrated here can accept sch enhancements graceflly. (For more information abot the differentiation of stats codes, refer to Stats Codes and Messages.) Position Block The Position Block parameter is the address of a 128-byte array that the MicroKernel ses to store file I/O strctres and the positioning information associated ith an Open (0) operation. Each time yor application opens a file, it mst allocate a niqe Position Block. Btrieve initializes the Position Block hen yor application performs the Open operation, then references and pdates it dring file operations. Therefore, yor application mst specify the same Position Block on all sbseqent Btrieve operations for the file. Note Do not rite to the Position Block. Doing so cold reslt in a lost position error, other errors, or damage to the file. When yo open more than one file at a time, the MicroKernel ses the Position Block to determine hich file a particlar call is for. Similarly, hen yo open the same file more than once, the MicroKernel ses a different Position Block for each separate Open operation. Likeise, the MicroKernel ses a different Position Block for each separate client that opens the same file. Mltiple clients cannot share position blocks. Btrieve Programmer s Reference 19 Introdction to Btrieve APIs

20 Data Bffer Yor application transfers data to and from a file sing the Data Bffer. The information passed to or from the MicroKernel in the Data Bffer depends on hich Btrieve operation is being performed. Freqently, the Data Bffer contains one or more records that yor application is transferring to or from a file. Hoever, depending on the Btrieve operation, the Data Bffer can contain other information, sch as file or key specifications, MicroKernel version information, and so on. Be sre to allocate a large enogh Data Bffer to accommodate the longest record in yor file. If yor Data Bffer Length parameter specifies a vale smaller than the size of yor Data Bffer, Btrieve modification operations may destroy data folloing the Data Bffer. Data Bffer Length For any operation that reqires a Data Bffer, yor application mst pass a variable that indicates the size (in bytes) of the Data Bffer, hich shold be large enogh to contain data that the operation retrns. Note BASIC developers: Yor application mst pass the Data Bffer Length parameter ByRef as an integer. C, COBOL, and Pascal developers: Yor application mst pass the Data Bffer Length parameter as a pointer to a 2-byte nsigned integer. When yo are inserting records into or pdating a file ith variable-length records, the Data Bffer Length shold eqal the record length specified hen yo first created the file, pls the nmber of characters inclded beyond the fixed-length portion. When yo are retrieving variable-length records, the Data Bffer Length shold be large enogh to Btrieve Programmer s Reference 20 Introdction to Btrieve APIs

21 accommodate the longest record in the file. If a record is longer than 64 KB, yo mst se a chnk operation to operate on a portion of the record. The MicroKernel ses the Data Bffer Length parameter to determine ho mch space is available in the Data Bffer. If yo pass a Data Bffer Length that is longer than the Data Bffer yo have allocated, yo may case the MicroKernel to overrite memory. The Data Bffer Length shold alays represent the size of the allocated Data Bffer. Key Bffer Yor application mst pass the Key Bffer parameter on every Btrieve operation, even if that operation does not se a Key Bffer. Depending on the operation, yor application may set the data in the Key Bffer, or the Btrieve fnction may retrn it. Note BASIC developers: Yor application mst pass the Key Bffer as a string. If the key vale is an integer, yor application shold convert it to a string sing the MKI$ statement before calling the Btrieve fnction. If a key consists of to or more segments, yo mst concatenate them into a single string variable and pass the variable as the Key Bffer. The MicroKernel retrns an error if the string variable passed as the Key Bffer is shorter than the key s defined length. If yor application s first call does not reqire initialization of the Key Bffer, assign the string variable the vale SPACE$(x), here x represents the key s defined length. Until yor application assigns some vale in BASIC to the string variable, it has a length of 0. C developers: Yor application mst pass the Key Bffer as the address of a variable containing the key vale. The file BTITYPES.H defines the Key Bffer as a VOID pointer (BTI_VOID_PTR). Yor application can then define the Key Bffer type as needed. Btrieve Programmer s Reference 21 Introdction to Btrieve APIs

22 COBOL developers: Yor application mst pass the Key Bffer as a record variable. If the key consists of to or more segments, list them in the correct order as individal fields nder an 01 level record. Then yo can pass the entire record as the Key Bffer. Pascal developers: Yor application mst pass the Key Bffer as a variable containing a key vale. If a key consists of to or more segments, se a record strctre to define the individal fields in the key. In most environments, the MicroKernel cannot determine the Key Bffer length hen an application makes a Btrieve call. Therefore, yo mst ensre that the bffer is at least as long as the key length yo specified hen yo first created the key. Otherise, Btrieve operations may destroy data stored in memory folloing the Key Bffer. It is best to alays have a 256-byte Key Bffer. Key Nmber The information passed in the Key Nmber parameter depends on hich operation is being performed. Most often, the Key Nmber contains a vale that indicates hich of p to 119 key (access) paths to follo for a particlar operation. Hoever, other information can be sent or retrned in the Key Nmber parameter, sch as a vale indicating in hat mode a file is to be opened. For BTRV and BTRVID fnctions, the Key Nmber parameter is a 2-byte integer. For BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 fnctions, the Key Nmber parameter is a 1-byte signed CHARACTER (BTI_CHAR). In all fnctions, the Key Nmber parameter has a vale range of 0 throgh 118. A Btrieve fnction never alters the Key Nmber parameter. Btrieve Programmer s Reference 22 Introdction to Btrieve APIs

23 Client ID The Client ID parameter is sed only in the BTRVID and BTRCALLID fnctions. The Client ID parameter is the address of a 16-byte strctre that allos the MicroKernel to differentiate among the clients on a compter. Use the folloing strctre for the Client ID. Table 1-2 Client ID Strctre Element Length (bytes) Description Filler 12 Initialize to 0. Service Agent ID 2 Identifies each instance of yor application to the MicroKernel. This is a 2-character ASCII vale. The vale of this identifier mst be greater than or eqal to the ASCII vale AA (0x41 0x41). The MicroKernel assmes special meaning for the folloing vales: 0x4140 (@A) 0xFFFF 0x4952 (RI) 0x4553 (SE) 0x4353 (SC) 0x4544 (DC) 0x4544 (DE) 0x5544 (DU) 0x5257 (WR) Used internally. Used internally. Used internally. Used to identify clients originated by Scalable SQL. Used by Btrieve Reqesters. Btrieve Programmer s Reference 23 Introdction to Btrieve APIs

24 Table 1-2 Client ID Strctre contined Element Length (bytes) Description Client Identifier 2 Establishes a client s identity ithin the crrent instance of yor application. The MicroKernel ses this niqe identifier for concrrency and transaction-processing prposes. Key Length The Key Length parameter is sed only in the BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 fnctions and is specific to the OS/2 and Windos 3.x operating systems. While the Key Length parameter is crrently reserved for internal se by the MicroKernel, if yor application calls BTRCALL, BTRCALLID, BTRCALL32, or BTRCALLID32, it mst pass the Key Length parameter as an nsigned char (BTI_BYTE), ith a vale of 255 (the maximm length of any key). Btrieve Programmer s Reference 24 Introdction to Btrieve APIs

25 Smmary of Btrieve Operations Btrieve provides over 40 operations that yo can call from yor application program. The folloing tables smmarize these operations. Refer to Chapter 2, Btrieve Operations for complete descriptions of the Btrieve operations. Refer to Appendix C, Qick Reference of Btrieve Operations for a smmary of Btrieve operations ordered by operation code. Session-Specific Operations The folloing operations allo yo to set or retrieve the crrent directory, sht don a orkstation MicroKernel, retrieve the MicroKernel version nmber, terminate a client connection ith the server MicroKernel, and begin, end, or abort a transaction. In applications that handle mltiple clients, these operations are specific to the calling client. Table 1-3 Session-Specific Operations Operation Code Description Set Directory 17 Changes the crrent directory. Get Directory 18 Retrns the crrent directory. Stop 25 Terminates the orkstation MicroKernel (not available for serverbased MicroKernels). Version 26 Retrns the version nmber of the MicroKernel. Reset 28 Releases all resorces held by a client. Btrieve Programmer s Reference 25 Introdction to Btrieve APIs

26 Table 1-3 Session-Specific Operations contined Operation Code Description Begin Transaction Marks the beginning of a set of logically related operations. Operation 19 begins an exclsive transaction. Operation 1019 begins a concrrent transaction. End Transaction 20 Marks the end of a set of logically related operations. Abort Transaction 21 Removes operations performed dring an incomplete transaction. File-Specific Operations The folloing operations deal ith a specific file, and therefore se the position block parameter to identify the file on hich to operate. The file-specific operations are of three types: File access and information. These operations allo yo to create a file, open and close a file, retrieve file statistics, set and clear the file s oner name, start or stop continos operation mode on a file, nlock a file, and create and drop indexes on a file. Data retrieval. These operations allo yo to retrieve a single record or a set of records given specified criteria. Btrieve spports data retrieval either by logical location in an index path or by physical location. For more information, refer to Accessing Records in the Btrieve Programmer s Gide. In addition, yo can apply biases to the operation codes to control file and record locking in mlti-client sitations. For more information, refer to Spporting Mltiple Clients in the Btrieve Programmer s Gide. Data maniplation. These operations allo yo to insert, pdate, or delete data. Btrieve Programmer s Reference 26 Introdction to Btrieve APIs

27 Table 1-4 File Access and Information Operations Operation Code Description Open 0 Makes a file available for access. Close 1 Releases a file from availability. Create 14 Creates a file ith the specified characteristics. Stat 15 Retrns file and index characteristics, and nmber of records. Stat Extended 65 Retrns file names and paths of an extended file s components and reports hether a file is sing a system-defined log key. Set Oner 29 Assigns an oner name to a file. Clear Oner 30 Removes an oner name from a file. Continos Operation 42 Server-based MicroKernels only. Places the specified file in or removes the file from continos operation mode, for se in system backps. Unlock 27 Unlocks a record or records. Create Index 31 Creates an index. Drop Index 32 Removes an index. Btrieve Programmer s Reference 27 Introdction to Btrieve APIs

28 Table 1-5 Data Retrieval Operations Operation Code Description Index-Based (Logical) Data Retrieval Get Eqal 5 Retrns the first record in the specified index path hose key vale matches the specified key vale. Get Next 6 Retrns the record folloing the crrent record in the index path. Get Previos 7 Retrns the record preceding the crrent record in the index path. Get Greater Than 8 Retrns the first record in the specified index path hose key vale is greater than the specified key vale. Get Greater Than or Eqal 9 Retrns the first record in the specified index path hose key vale is eqal to or greater than the specified key vale. Get Less Than 10 Retrns the first record in the specified index path hose key vale is less than the specified key vale. Get Less Than or Eqal 11 Retrns the first record in the specified index path hose key vale is eqal to or less than the specified key vale. Get First 12 Retrns the first record in the specified index path. Get Last 13 Retrns the last record in the specified index path. Get Next Extended 36 Retrns one or more records that follo the crrent record in the index path. Filtering conditions can be applied. Get Previos Extended 37 Retrns one or more records that precede the crrent record in the index path. Filtering conditions can be applied. Btrieve Programmer s Reference 28 Introdction to Btrieve APIs

29 Table 1-5 Data Retrieval Operations contined Operation Code Description Get Key +50 Detects the presence of a key vale in a file, ithot retrning an actal record. Get By Percentage 44 Retrns the record located approximately at a position derived from the specified percentage vale. Find Percentage 45 Retrns a percentage figre based on the crrent record s position in the file. Non-Index-Based (Physical) Retrieval Get Position 22 Retrns the position of the crrent record. Get Direct/Chnk 23 Retrns data from the specified portions (chnks) of a record at a specified position. Get Direct/Record 23 Retrns the record at a specified position. Step Next 24 Retrns the record from the physical location folloing the crrent record. Step First 33 Retrns the record in the first physical location in the file. Step Last 34 Retrns the record in the last physical location in the file. Step Previos 35 Retrns the record in the physical location preceding the crrent record. Step Next Extended 38 Retrns one or more sccessive records from the location physically folloing the crrent record. Filtering conditions can be applied. Btrieve Programmer s Reference 29 Introdction to Btrieve APIs

30 Table 1-5 Data Retrieval Operations contined Operation Code Description Step Previos Extended 39 Retrns one or more preceding records from the location physically preceding the crrent record. Filtering conditions can be applied. Get By Percentage 44 Retrns the record located approximately at a position derived from the specified percentage vale. Find Percentage 45 Retrns a percentage figre based on the crrent record s position in the file. Concrrency Control Biases (Add to the Appropriate Operation Code) Single-record ait lock +100 Locks only one record at a time. If the record is already locked, the MicroKernel retries the operation. Single-record no-ait lock Mltiple-record ait lock Mltiple-record no-ait lock +200 Locks only one record at a time. If the record is already locked, the MicroKernel retrns an error stats code Locks several records concrrently in the same file. If the record is already locked, the MicroKernel retries the operation Locks several records concrrently in the same file. If the record is already locked, the MicroKernel retrns an error stats code. No-ait page lock +500 In a concrrent transaction, tells the MicroKernel not to ait if the page to be changed has already been changed by another active concrrent transaction. This bias can be combined ith any of the record locking biases (+100, +200, +300, or +400). Btrieve Programmer s Reference 30 Introdction to Btrieve APIs

31 Table 1-6 Data Maniplation Operations Operation Code Description Insert 2 Inserts a ne record into a file. Update 3 Updates the crrent record. Delete 4 Removes the crrent record from the file. Insert Extended 40 Inserts one or more records into a file. Update Chnk 53 Updates specified portions (chnks) of the crrent record. This operation can also append data to a record or trncate a record. Btrieve Programmer s Reference 31 Introdction to Btrieve APIs

32 Seqence of Events in Performing a Btrieve Operation To perform a Btrieve operation, yor application mst complete the folloing tasks: 1. Satisfy any prereqisites the operation reqires. For example, before yor application can perform any file I/O operations, it mst make the file available by performing an Open operation (0) on that file. 2. Initialize the parameters that the Btrieve operation reqires. The parameters are program variables or data strctres that correspond in type and size to the particlar vales that the MicroKernel expects for an operation. For ftre compatibility, initialize all parameters, hether or not they are sed. For parameters of type INTEGER, set the vale to binary 0. For character arrays, pass a pointer to a bffer. Initialize the first byte of the bffer to binary Call the appropriate Btrieve fnction. (Refer to Btrieve Fnctions.) 4. Evalate the reslts of the fnction call. Every Btrieve operation retrns a stats code. Yor application mst check the stats code and take the appropriate action. The operation also retrns data or other information to the individal parameters based on the prpose of the operation. Btrieve Programmer s Reference 32 Introdction to Btrieve APIs

33 chapter 2 Btrieve Operations This chapter describes the operations yor application can perform sing the Btrieve API. For each operation, this chapter presents the folloing information: Name, code, and description of the operation. Parameters a table indicating hich of the six parameter vales the operation expects from and retrns to yor application. A Sent parameter is sent from the application to the operation; a Retrned parameter is retrned from the operation to the application hen the operation is complete. Prereqisites the conditions yor application mst satisfy for the operation to be sccessfl. Procedre the steps for initializing the parameters that the operation reqires. Details additional information abot the operation. Reslt the reslts of both a sccessfl and an nsccessfl operation. Each operation retrns a stats code, informing yor application of the otcome of the operation. Stats Code 0 indicates the operation as sccessfl. A nonzero stats code sally indicates a failre. Hoever, some nonzero stats codes are informative and appear even hen the associated operation is sccessfl for example, Stats Code 60 means the specified reject cont has been reached. Positioning the effect the operation has on the logical and/or physical crrency of the records in a file. Btrieve Programmer s Reference 33 Btrieve Operations

34 This chapter incldes the folloing Btrieve operations, organized alphabetically: Abort Transaction (21) Begin Transaction (19 or 1019) Clear Oner (30) Close (1) Continos Operation (42) Create (14) Create Index (31) Delete (4) Drop Index (32) End Transaction (20) Find Percentage (45) Get By Percentage (44) Get Direct/Chnk (23) Get Direct/Record (23) Get Directory (18) Get Eqal (5) Get First (12) Get Greater (8) Get Key (+50) Get Last (13) Get Less Than (10) Get Next (6) Get Next Extended (36) Btrieve Programmer s Reference 34 Btrieve Operations

35 Get Position (22) Get Previos (7) Get Previos Extended (37) Insert (2) Insert Extended (40) Open (0) Reset (28) Set Directory (17) Set Oner (29) Stat (15) Stat Extended (65) Step First (33) Step Last (34) Step Next (24) Step Next Extended (38) Step Previos (35) Step Previos Extended (39) Stop (25) Unlock (27) Update (3) Update Chnk (53) Version (26) Btrieve Programmer s Reference 35 Btrieve Operations

36 Abort Transaction (21) The Abort Transaction operation terminates the crrent transaction and removes the reslts of all operations performed since the beginning of the transaction. It also nlocks all files and records locked by the transaction. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X Retrned Prereqisites Yo mst isse a sccessfl Begin Transaction operation (19 or 1019) before yo isse an Abort Transaction operation. Procedre Set the Operation Code to 21. The MicroKernel ignores all other parameters on an Abort Transaction call. Reslt If the Abort Transaction operation is sccessfl, the MicroKernel retrns Stats Code 0. The reslts of all Insert, Update, and Delete operations issed since the beginning of the transaction are removed from the files. Btrieve Programmer s Reference 36 Btrieve Operations

37 If the Abort Transaction operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 36 The application encontered a transaction error. 39 A Begin Transaction operation mst precede an End/Abort Transaction operation. Positioning The Abort Transaction operation has no effect on any file crrency information. Btrieve Programmer s Reference 37 Btrieve Operations

38 Begin Transaction (19 or 1019) The Begin Transaction operation defines the start of a transaction. Transactions are sefl hen yo need to perform mltiple Btrieve operations as a single event. For example, se a transaction if yor database old become logically inconsistent if some operations ere sccessfl, bt at least one operation failed to complete sccessflly. By enclosing a set of operations beteen Begin and End Transaction operations, yo can ensre that the MicroKernel does not permanently complete any operations in the set nless yo reqest the completion ith an explicit End Transaction operation (20). The MicroKernel prohibits certain operations dring transactions becase they have too great an effect on the file or on performance. These operations inclde Set Oner, Clear Oner, Create Index, Drop Index, and Close (for files pdated dring the transaction). Parameters Operation Code X Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent Retrned Prereqisites Yor application mst end or abort any previos transaction before issing a Begin Transaction operation. Btrieve Programmer s Reference 38 Btrieve Operations

39 Procedre Set the Operation Code to 19 to begin an exclsive transaction, or 1019 to begin a concrrent transaction. The MicroKernel ignores all parameters except the Operation Code on any Begin Transaction call. On any Begin Transaction operation, yo can specify defalt lock biases: +100 Single ait record lock Single no-ait record lock Mltiple ait record lock Mltiple no-ait record lock. On a Begin Concrrent Transaction operation, yo can add +500 to the Operation Code (1519), hich forces the MicroKernel not to retry the Insert, Update, and Delete operations ithin a transaction. In addition, yo can combine the +500 bias ith a defalt lock bias (+100, +200, +300, or +400). For example, sing (1719) begins a concrrent transaction, sppresses retries for Insert, Update, and Delete operations, and specifies single no-ait read locks at the same time. For more information abot transactions and locking, refer to the Btrieve Programmer s Gide. Reslt If the Begin Transaction operation is sccessfl, the MicroKernel retrns Stats Code 0. Btrieve Programmer s Reference 39 Btrieve Operations

40 If the Begin Transaction operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 36 The application encontered a transaction error. 37 Another transaction is active. Positioning The Begin Transaction operation has no effect on any file crrency information. Btrieve Programmer s Reference 40 Btrieve Operations

41 Clear Oner (30) The Clear Oner operation removes an oner name that yo have previosly assigned to a file ith the Set Oner operation. If the file as previosly encrypted, the MicroKernel decrypts the file dring a Clear Oner operation. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X Retrned X Prereqisites The file mst be open. No transactions can be active. Procedre 1. Set the Operation Code to Pass the Position Block that identifies the file to clear. Reslt After a Clear Oner operation, the MicroKernel no longer reqires the oner name to open or modify a file. If yo encrypted the data in the file hen yo assigned the oner, the MicroKernel decrypts the data dring a Clear Oner operation. The more data that as encrypted, the longer the Clear Oner operation takes. Btrieve Programmer s Reference 41 Btrieve Operations

42 If the Clear Oner operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 41 The MicroKernel does not allo the attempted operation. Positioning The Clear Oner operation has no effect on any file crrency information. Btrieve Programmer s Reference 42 Btrieve Operations

43 Close (1) The Close operation closes the file associated ith a specified Position Block and releases any locks yor application has exected for the file. Yor application shold alays perform a Close operation hen it has finished accessing a file. After a Close operation, yor application cannot access the file again ntil it isses another Open operation (0) for that file. Yo can close a file even hile inside a transaction. Hoever, the Close operation does not end the transaction; yo mst explicitly end or abort the transaction. If yo abort the transaction, changes made inside the transaction are aborted; if yo end the transaction, changes are committed. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X Retrned Prereqisites The file mst be open. Procedre 1. Set the Operation Code to Pass a valid Position Block for the file to close. Btrieve Programmer s Reference 43 Btrieve Operations

44 Reslt If the Close operation is sccessfl, the Position Block for the closed file is no longer valid. Yor application can se it for another file or se the data area for other prposes. If the Close operation fails, the file remains open and the MicroKernel retrns the folloing stats code: 3 The file is not open. Positioning The Close operation destroys both the physical and the logical crrency information of the file. Btrieve Programmer s Reference 44 Btrieve Operations

45 Continos Operation (42) The Continos Operation operation allos yo to perform system backps ithot closing active Btrieve files. Any changes yo make hile a file is being backed p are stored in a temporary file called a delta file. Except for changes ritten to the delta file, the system backp incldes the contents of all files placed in continos operation mode. The MicroKernel atomatically rolls the delta file changes into the backed p files hen those files are taken ot of continos operation mode. This operation also allos yo to copy a file hile that file is still active. Note This operation is available only to applications rnning local on a server machine. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Note Vales for the Data Bffer parameter and the Data Bffer Length parameter are reqired only if the vale of the Key Nmber parameter is 0 (hich starts continos operation mode) or 2 (hich ends continos operation mode). The folloing sections discss these Key Nmber vales. A Data Bffer Length of zero is reqired for a Key Nmber parameter of 1. Key Nmber Sent X X X X Retrned X X Btrieve Programmer s Reference 45 Btrieve Operations

46 Procedre To start continos operation mode, perform the folloing steps: 1. Define a file or a set of files for backp, or add a file to the set of files crrently defined for backp. a. Set the Operation Code to 42. b. Place the names of the files yo ant to place in continos operation mode into the Data Bffer parameter. Inclde the fll pathname, exclding only the server name. Separate the names ith commas and terminate the list of names ith a binary 0. The folloing example is for Windos NT servers: f:\acct\march.mkd,f:\acct\april.mkd The folloing example is for NetWare servers: sys:\acct\march.mkd,sys:\acct\april.mkd c. Place the length of the name (or names) in the Data Bffer Length parameter. This vale mst be eqal to or greater than the actal length of the names (inclding binary zeros) in the Data Bffer itself. For example, the preceding names reqire a Data Bffer Length of 40 or greater. d. Set the Key Nmber parameter to Perform the backp. 3. End continos operation mode. a. Set the Operation Code to 42. b. Set the Key Nmber parameter to 1. To end continos operation on one or more specific files, set the Key Nmber parameter to 2, and then place the filenames in the Data Bffer parameter as described in step 1b. Also, place the length of the name (or names) in the Data Bffer Length parameter as described in step 1c. Btrieve Programmer s Reference 46 Btrieve Operations

47 Details When defining the set of files to be backed p, keep in mind the folloing information: The MicroKernel does not consider the absence of filenames in the Data Bffer to be an error. If it finds no filenames, the MicroKernel takes no action on the Continos Operation operation. The presence of dplicate filenames in the Data Bffer does not affect ho the Continos Operation operation orks. The MKDE places the specified file in continos operation mode only once. No to files are alloed to share the same filename and differ only in their extension. This is becase the name of the delta file ses the corresponding file s name ith.^^^ for the extension. An application can iteratively call the Continos Operation operation to add more names to the list of files to be placed in continos operation mode. Hoever, this action can corrpt a backp hen referential integrity (RI) constraints are placed on any of the files by Scalable SQL. The MicroKernel retrns Stats Code 88 if a file is specified that is already in continos operation mode. When riting a server-based application that calls the Continos Operation operation, make sre yo call btrvid, and se a valid client ID so yo can begin and end continos operation nder the same client. Btrieve allos yo to define mltiple backp sets by specifying a different client ID for each backp set throgh the btrvid fnction. Hoever, to sets cannot contain the same files. While the MicroKernel rolls changes from the delta file into the data file, sers can contine to pdate, insert, and read the Btrieve file jst as they normally old. The Btrieve Programmer s Reference 47 Btrieve Operations

48 MicroKernel appends ne pages to the delta file hile rolling in changes, if an insert reqires sch an action. No changes are lost. Note Never delete a delta file manally. If yor application ses the btrv fnction, do not nload the application hile any file is in continos operation mode. If yo do, yo may be nable to remove the affected files from continos operation mode. This is becase the defalt client ID that the MicroKernel originally assigned as the oner of the affected files may have been reassigned to another application. Becase the MicroKernel no longer knos the proper oner of the affected files, it is nable to remove those files from continos operation mode. If the system crashes hile in continos operation mode or hile the MicroKernel is rolling the changes from a delta file into the file, then the MicroKernel rolls all changes into the file hen it is first opened after the system is rebooted. Reslt If the Continos Operation operation is sccessfl, the MicroKernel retrns Stats Code 0, bt it retrns no vales either in the Data Bffer or in the Data Bffer Length parameter. If the operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 11 The specified filename is invalid. 12 The MicroKernel cannot find the specified file. 41 The MicroKernel does not allo the attempted operation. 51 The oner name is invalid. Btrieve Programmer s Reference 48 Btrieve Operations

49 88 The application encontered an incompatible mode error. 91 The application encontered a server error. In addition to the preceding codes, yor application can retrn standard I/O error codes sch as Stats Code 18. If the MicroKernel retrns a nonzero stats code, the Continos Operation operation retrns in the Data Bffer the portion of the inpt string that generated the error. If no inpt string as sed, the Data Bffer contains the file names that cased the error. The Data Bffer Length reflects the length of the otpt string in the Data Bffer. At this point, the Data Bffer Length contains the length of that filename. Positioning The Continos Operation operation does not establish any crrency on the file. Btrieve Programmer s Reference 49 Btrieve Operations

50 Create (14) The Create operation lets yo generate a file from ithin yor application. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned Prereqisites If yo are creating an empty file over an existing file, ensre that the existing file is closed before execting the Create operation. Procedre 1. Set the Operation Code to Specify the file specifications, key specifications, and any alternate collating seqences in the Data Bffer as described in Details. (All the vales for the file specifications and key specifications yo store in the Data Bffer mst be in binary format.) 3. Specify the Data Bffer Length. This is the length of the bffer that contains the Create specifications, not the length of the records in the file. 4. Specify the pathname for the file in the Key Bffer. Be sre to terminate the pathname ith a blank or binary zero. The pathname can be p to 80 characters long, inclding the volme name and the terminator. Btrieve Programmer s Reference 50 Btrieve Operations

51 For more information abot path names Btrieve spports, refer to Getting Started. Note For yor application to be compatible ith Scalable SQL, limit the pathname to 64 characters. 5. If yo ant the MicroKernel to arn yo that a file of the same name already exists, set the Key Nmber parameter to 1. Otherise, set the Key Nmber parameter to 0. Btrieve Programmer s Reference 51 Btrieve Operations

52 Details Table 2-1 illstrates the order in hich the file and key specifications mst be stored. Table 2-1 Data Bffer Strctre for Create Operation Element Description Unsigned Data Type 1 Length (in Bytes) File Specification Logical Record Length short int 2 Page Size short int 2 Nmber of Indexes short int 2 Reserved char 4 File Flags short int 2 Nmber of Dplicate Pointers To Reserve char 1 Not Used char 1 Allocation short int 2 Key Specification Key Position short int 2 (repeated for each Key Length short int 2 key segment) Key Flags short int 2 Reserved char 4 Extended Data Type char 1 Nll Vale char 1 Not Used char 2 Manally Assigned Key Nmber char 1 ACS Nmber char 1 ACS Nmber 0 ACS char char 265 Btrieve Programmer s Reference 52 Btrieve Operations

53 Table 2-1 Data Bffer Strctre for Create Operation contined Unsigned Length Element Description Data Type 1 (in Bytes) ACS Nmber x ACS char For simplification, this table shos C langage data types only. Table A-2 lists the data types in other langages. Note Yo mst allocate the not sed and reserved areas of the Data Bffer, even thogh the MicroKernel does not se them for a Create operation. Initialize the reserved areas to zero to maintain compatibility ith ftre releases. File Specification Store the file specification in the first 16 bytes of the Data Bffer. The bytes are nmbered beginning ith 0. Store the information for the record length, page size, and nmber of indexes as integers. Logical Record Length. (Offset 0x00) The logical record length is the nmber of bytes of fixed-length data in the file. (Do not inclde variable-length data in the logical record length.) Page Size. (Offset 0x02) Yo can specify any mltiple of 512 p to 4,096. For more information abot choosing the optimal page size, refer to the Btrieve Programmer s Gide. Nmber of Indexes. (Offset 0x04) The nmber of indexes is the nmber of keys (not key segments) yo are defining for the file. To create a data-only file, set the nmber of indexes to 0. Btrieve Programmer s Reference 53 Btrieve Operations

54 File Flags. (Offset 0x0A) The bit settings in the File Flags ord specify file attribtes. Table 2-2 shos the binary, hexadecimal, and decimal representations of the file flag vales. Table 2-2 File Flag Vales Attribte Constant Binary Hex Decimal Variable Length Records VAR_RECS Blank Trncation BLANK_TRUNC Page Preallocation PRE_ALLOC Data Compression DATA_COMP Key-Only File KEY_ONLY Balanced Index BALANCED_KEYS % Free Space FREE_ % Free Space FREE_ % Free Space FREE_ C0 192 Reserve Dplicate Pointers DUP_PTRS Inclde System Data 1 INCLUDE_SYSTEM_DATA Do Not Inclde System NO_INCLUDE_SYSTEM_DATA ,608 Data* Key Nmber SPECIFY_KEY_NUMS ,024 Use VATs VATS_SUPPORT ,048 1 If yo do not explicitly specify hether to inclde system data in the file, Btrieve ses the crrent setting of the MicroKernel configration option Inclde System Data. Avoid sing incompatible flags; flags are incompatible if they se the same bit positions. Unsed bits are reserved for ftre se. Set them to 0. Btrieve Programmer s Reference 54 Btrieve Operations

55 To combine file attribtes, add their respective File Flag vales. For example, to specify a file that allos variable-length records and ses blank trncation, initialize the File Flags ord to 3 (2 + 1). The MicroKernel ignores the Blank Trncation and Free Space bits if the Variable Length Records bit is set to 0. If yo set the Page Preallocation bit, se the last 2 bytes in the file specification block (allocation) to store an integer vale that specifies the nmber of pages to preallocate to the file. If yo set the Data Compression bit, the MicroKernel ignores the Variable Length Records bit. If yo set the Key-only File bit, the MicroKernel ignores the System Data bits. Note The MicroKernel atomatically ses data compression on files that se system data and have a record length greater than 4,076 bytes. Set the Dplicate Pointers bit if yo anticipate adding an index sometime after creating a file, and if that index has many dplicate vales. Setting this bit cases the MicroKernel to reserve space in each record of the file for pointers that link the dplicate vales. By reserving this space, yo can possibly loer retrieval time and save disk space, especially if the keys are long and yo anticipate that many records ill have dplicate key vales. Note Yo can reserve dplicate pointer space only for indexes that are added after file creation. Therefore, hen reserving space for pointers to dplicate vales, do not inclde space for the indexes created dring this Create operation. Also, the MicroKernel does not reserve dplicate pointer space for any key yo specify as a repeating-dplicatable key. Set the Key Nmber bit if yo need to assign a specific nmber to a key, and place the desired key nmber in the Manally Assigned Key Nmber element (offset 0x0E) of the Key Specification block. The MicroKernel does not reqire consective key nmbers; Btrieve Programmer s Reference 55 Btrieve Operations

56 files can have gaps beteen key nmbers. When a key is created, by defalt the MicroKernel assigns the loest available key nmber to that index (beginning ith 0). Hoever, some applications may reqire a key nmber different from the defalt assignment. Set the Use VATs bit if the file ses Variable-tail Allocation Tables. To se VATs, a file mst se variable-length records. Nmber of Dplicate Pointers to Reserve. (Offset 0x0C) Yo can specify the nmber of dplicate pointers to reserve for each key. Use this element only if yo specified the Reserve Dplicate Pointers file flag. For more information abot dplicatable keys, refer to the Btrieve Programmer s Gide. Allocation. (Offset 0x0E) Yo can specify the nmber of pages to preallocate. Use this element only if yo specified the Page Preallocation file flag. For more information abot page preallocation, refer to the Btrieve Programmer s Gide. Key Specification Blocks Place the key specification blocks immediately after the file specification. Allocate a 16- byte key specification block for each key segment in the file. Store the information for the Key Position and the Key Length as integers. Btrieve Programmer s Reference 56 Btrieve Operations

57 The maximm nmber of key segments alloed depends on the file s page size. The folloing table shos these vales: Page Size Maximm Key Segments , 2560, 3072, or Key Position. (Offset 0x00) The key position is the byte offset at hich the key or key segment begins. Key Length. (Offset 0x02) The length of the key or key segment. The maximm length of a key, inclding all key segments, is 255 bytes. Key Flags. (Offset 0x04) The bit settings in the Key Flags ord specify key attribtes. Table 2-3 shos the binary, hexadecimal, and decimal representations of the Key Flags vales. Btrieve Programmer s Reference 57 Btrieve Operations

58 Table 2-3 Key Flag Vales Attribte Constant Binary Hex Decimal Linked Dplicates DUP Modifiable Key Vales MOD Use Old Style BINARY BIN Data Type Use Old Style STRING Data Type 1 Nll Key (All Segments) NUL Segmented Key SEG Use Defalt ACS ALT Use Nmbered ACS in File NUMBERED_ACS ,056 Use Named ACS NAMED_ACS C20 3,104 Descending Sort Order DESC_KEY Repeating Dplicates REPEAT_DUPS_KEY Use Extended Data Type EXTTYPE_KEY Nll Key (Any Segment) MANUAL_KEY Case Insensitive Key NOCASE_KEY ,024 1 Bit 2 and Bit 8 mst be 0. Avoid sing incompatible flags; flags are incompatible if they se the same bit positions. Unsed bits are reserved for ftre se. Set them to 0. Btrieve Programmer s Reference 58 Btrieve Operations

59 To combine key attribtes, add their respective Key Flags vales. For example, if the key is an extended type, part of a segmented key, and to be collated in descending order, initialize the Key Flags ord to 336 ( ). The Segmented Key attribte indicates that the next key specification block in the Data Bffer refers to the next segment of the same key. Follo these rles for segmented keys: All segments of the same key mst have the same Dplicate Key Vales, Repeating Dplicates, Modifiable Key Vales, and Nll Key vales. (If yo specify the Nll Key attribte, either All Segments or Any Segment, yo can assign different nll vales for individal segments.) All segments of the same key mst se the same ACS. Individal segments of the same key can have different Descending Sort Order and Extended Data Type vales. ACSs are applicable only to STRING, LSTRING, and ZSTRING keys. Yo cannot define a key that is both case-insensitive and ses an ACS. In a file in hich a key has an ACS designated for some segments bt not for others, the segments that designate an ACS are sorted by the specified ACS; the segments ith no ACSs are sorted according to their respective types. Btrieve Programmer s Reference 59 Btrieve Operations

60 Extended Data Type. (Offset 0x0A) Yo specify the Extended Data Type in byte 10 of the Key Specification block as a binary vale. Table 2-4 shos the codes for the extended data types. Table 2-4 Extended Data Types Type Code Type Code STRING 0 BFLOAT 9 INTEGER 1 LSTRING 10 FLOAT 2 ZSTRING 11 DATE 3 UNSIGNED BINARY 14 TIME 4 AUTOINCREMENT 15 DECIMAL 5 NUMERICSTS 17 MONEY 6 NUMERICSA 18 LOGICAL 7 CURRENCY 19 NUMERIC 8 TIMESTAMP 20 Extended data type codes 12, 13, and 16 are reserved for ftre se. Yo can define the STRING and UNSIGNED BINARY data types as either standard or extended types. This maintains compatibility ith applications that ere developed ith earlier versions of Btrieve, hile alloing neer applications to se extended data types exclsively. Regarding the data type yo assign to a key, Btrieve does not ensre that the records yo inpt adhere to the data types defined for the keys. For example, yo cold define a TIMESTAMP key in a file, bt store a character string there. Yor Btrieve application old ork fine, bt an ODBC application that tries to access the same data sing the ODBC TIMESTAMP format might fail, becase the byte format cold be different and the Btrieve Programmer s Reference 60 Btrieve Operations

61 algorithms sed to generate the timestamp vale cold be different. For complete descriptions of the data types, refer to Data Types. Nll Vale. (Offset 0x0B) of the Key Specification block represents an exclsion vale for the key. If yo have defined a key as a nll key, yo mst spply a vale for the MicroKernel to recognize as the nll vale for each key segment. Manally Assigned Key Nmber. (Offset 0x0E) The MicroKernel allos an application to assign specific key nmbers hen creating a file ith indexes. To manally assign key nmbers to each index for a file, specify each key s nmber as a binary vale in byte 14 of the key specification block, and set the Key Nmber bit (0x400) in the File Flags ord. Key nmbers mst be niqe to the file and mst be specified in ascending order, beginning ith key 0. They mst also be valid (less than the maximm nmber of keys for the file s page size). The ability to manally assign key nmbers complements to the ability to delete a key and not have the MicroKernel renmber all keys that have a key nmber greater than the deleted key. For example, if an application drops an index and instrcts the MicroKernel not to renmber higher-nmbered keys, and if a ser then clones the affected file ithot assigning specific key nmbers, the cloned file has different key nmbers than the original. ACS Nmber. (Offset 0x0F) For keys that se a specific ACS, offset 0x0F in the key specification block provides the ACS nmber by hich to collate the key. The ACS nmber is based on its position in the Data Bffer. The first ACS folloing the last key specification block is ACS nmber 0. Folloing ACS 0 is ACS 1, hich is folloed by ACS 2, and so on. Btrieve Programmer s Reference 61 Btrieve Operations

62 Alternate Collating Seqence Yor application specifies ACSs one after the other immediately folloing the last key specification block in the Data Bffer. User-Defined ACSs. To create an ACS that sorts string vales differently from the ASCII standard, yor application mst place 265 bytes directly into the Data Bffer, sing the folloing format: Table 2-5 Offset Length (in Bytes) Data Bffer for Creating a User-Defined ACS Description 0 1 Signatre byte. Specify 0xAC. 1 8 A niqe 8-byte name that identifies the ACS to the MicroKernel A 256-byte map. Each 1-byte position in the map corresponds to the code point having the same vale as the position s offset in the map. The vale of the byte at that position is the collating eight assigned to the code point. For example, to force code point 0x61 ( a ) to sort ith the same eight as code point 0x41 ( A ), place the same vales at offsets 0x61 and 0x41. For examples of ser-defined ACSs, refer to the Btrieve Programmer s Gide. Btrieve Programmer s Reference 62 Btrieve Operations

63 Locale-Specific ACSs. To specify an ACS that sorts string vales according to a localespecific collating seqence, yor application mst place 265 bytes directly into the Data Bffer, sing the folloing format: Table 2-6 Offset Length (in Bytes) Data Bffer for Specifying a Locale-Specific ACS Description 0 1 Signatre byte. Specify 0xAD. 1 2 Contry ID (Intel format). See yor operating system s docmentation for more information abot national langage spport. 3 2 Code page ID (Intel format). See yor operating system s docmentation for more information abot national langage spport Filler. To se the defalt locale-specific ACS, specify a vale of 0xFFFF for the Contry ID and the Code page ID. Note Windos NT clients and servers do not spport passing a locale s contry ID and code page nmber to Btrieve. If yo ant to se an ACS other than the one for the defalt locale, yo mst create a ser-defined ACS or specify an international sort rle (ISR). Btrieve Programmer s Reference 63 Btrieve Operations

64 International Sort Rles (ISRs). To specify an ISR, yor application mst place 265 bytes directly into the Data Bffer, sing the folloing format: Table 2-7 Data Bffer for Specifying an ISR ACS Offset Length (in Bytes) Description 0 1 Signatre byte. Specify 0xAE A niqe 16-byte name that identifies the ISR table to the MicroKernel. Refer to the Btrieve Programmer s Gide for a list of ISR table names Filler. Data Bffer Length The Data Bffer Length mst be long enogh to inclde the file specifications, the key specifications, and any ACSs that have been defined. Do not specify the file s record length in this parameter. For example, to create a file that has to keys of one segment each and an ACS, the Data Bffer for the Create operation shold be at least 313 bytes long, as follos: File Spec + Key1 Spec + Key2 Spec + ACS = 313 Key Nmber The Create operation s Key Nmber parameter is sed to determine if the MicroKernel arns yo hen a file of the same name already exists. Btrieve Programmer s Reference 64 Btrieve Operations

65 Reslt If the Create operation is sccessfl, the MicroKernel either arns yo of the existence of a file ith the same name or creates the ne file according to yor specifications. The ne file does not contain any records. The Create operation does not open the file. Yor application mst perform an Open operation before it can access the file. If the Create operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 2 The application encontered an I/O error. 11 The specified file name is invalid. 18 The disk is fll. 22 The data bffer length is too short. 24 The page size or data bffer size is invalid. 25 The application cannot create the specified file. 26 The nmber of keys specified is invalid. 27 The key position is invalid. 28 The record length is invalid. 29 The key length is invalid. 48 The alternate collating seqence definition is invalid. 49 The extended data type is invalid. 59 The specified file already exists. 104 The MicroKernel does not recognize the locale. 105 The file cannot be created ith Variable-tail Allocation Tables (VATs). Btrieve Programmer s Reference 65 Btrieve Operations

66 134 The MicroKernel cannot read the International Sorting Rle. 135 The specified International Sort Rle table is corrpt or otherise invalid. Positioning The Create operation establishes no crrency on the file. Btrieve Programmer s Reference 66 Btrieve Operations

67 Create Index (31) The Create Index operation adds a key to an existing file. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned Prereqisites The file mst be open. The nmber of existing key segments in the file mst be less than or eqal to maximm nmber of key segments alloed mins the nmber of key segments to be added. The maximm nmber of key segments alloed depends on the file s page size. The folloing table shos these vales: Page Size Maximm Key Segments , 2560, 3072, or Ensre that the key flags, position, and length of the ne key are appropriate for the file to hich yo are adding the key. No transactions can be active. Btrieve Programmer s Reference 67 Btrieve Operations

68 Procedre 1. Set the Operation Code to Pass the Position Block for the file to hich to add the key. 3. For each segment in the key, store a 16-byte key specification block in the Data Bffer. Use the same strctre as defined in Table 2-1. Store the information for the key position and the key length as integers. If yo are rebilding the systemdefined log key (also called system data), the Data Bffer mst be at least 16 bytes long and initialized to zeroes. 4. To define an ACS for the ne key, perform one of the folloing steps: To se the defalt ACS, hich is the first ACS already defined in the file, specify the Use Defalt ACS attribte in the Key Flags ord. To define a ne ACS, specify the Use Nmbered ACS attribte in the Key Flags ord and set the ACS Nmber field to zero (0). In addition, store the 265-byte ACS after the last key specification block in the Data Bffer. To specify an existing ACS by name, specify the Use Named ACS attribte in the Key Flags ord and set the ACS Nmber field to zero (0). In addition, store the name of the ACS at the beginning of the 265-byte block after the last key specification block in the Data Bffer. (The remainder of the ACS block after the name is ignored.) The name mst be in one of the folloing formats: Btrieve Programmer s Reference 68 Btrieve Operations

69 Table 2-8 ACS Name Formats ACS Type Length (in Bytes) Description User-defined ACS 1 Signatre 0xAC 8 ACS table name Locale-specific ACS 1 Signatre 0xAD 2 Contry ID 2 Code page ID ISR 1 Signatre 0xAE 16 ISR table name 5. Set the Data Bffer Length parameter to the nmber of bytes in the Data Bffer. For a ne key ith no ACS (or one that ses the defalt ACS), se the folloing formla to determine the correct Data Bffer Length: 16 * (# of segments) If the ne key specifies an ACS other than the defalt, se the folloing formla to determine the correct Data Bffer Length: 16 * (# of segments) To assign a specific Key Nmber to the key being created, add the desired key nmber to 0x80, and place the sm in the Key Nmber parameter. If yo are rebilding the system-defined log key (also called system data), specify 0xFD (that is, key nmber 125 pls 128). Btrieve Programmer s Reference 69 Btrieve Operations

70 Note Key nmbers mst be niqe to the file. They mst also be valid. (The vale of each key nmber mst be less than the maximm nmber of key segments alloed for the file s page size.) Details The MicroKernel allos yo to assign specific key nmbers hen creating a key. This capability complements the ability to delete a key and not have the MicroKernel renmber all keys that have a key nmber greater than that of the deleted key. If an application drops an index and instrcts the MicroKernel not to renmber higher-nmbered keys, and a ser then clones the affected file ithot assigning specific key nmbers, the cloned file has different key nmbers than the original. If yo define an ACS in the Data Bffer, the MicroKernel first checks for an existing ACS (sing the name yo specified) before adding it to the file. If the MicroKernel finds an existing ACS ith the name yo specified, the MicroKernel does not dplicate the ACS definition in the file, bt does associate the ACS ith the ne key. If yo specify the Use Named ACS attribte in the Key Flags ord, the MicroKernel ses the ACS name spplied in the Data Bffer to locate an ACS of the same name ithin the file, then assigns that ACS to the ne key. If a file is opened by more than one MicroKernel and a client initiates a Create Index process, remote clients can perform Get and Step operations on the same file hile the MicroKernel creates the key. If the key being created is not an AUTOINCREMENT key, the Get and Step operations of remote clients can have lock biases, and hen the Create Index process is completed, yo can pdate and delete the locked records ithot issing additional read operations. This is possible becase the MicroKernel does not have to change the images of the records in order to create the key. Btrieve Programmer s Reference 70 Btrieve Operations

71 Hoever, if the key being created is an AUTOINCREMENT key, the MicroKernel has to both bild the index and change every record ith a zero vale in the appropriate field. Remote clients that perform Get or Step operations ithot a lock bias before or dring the key creation can receive Stats Code 80 hen they execte an pdate or delete operation after the sccessfl completion of the key creation. Also, the MicroKernel retrns Stats Code 84 if a client attempts to create an AUTOINCREMENT key hile another client has locked a record. Similarly, the MicroKernel retrns Stats Code 85 if a client attempts to execte a Get or Step operation ith a lock bias dring index creation for an AUTOINCREMENT key by another client. Reslt The MicroKernel immediately adds the ne key to the file. The time reqired for this operation depends on the total nmber of records to be indexed, the size of the file, and the length of the ne index. If the Create Index operation is sccessfl, the nmber of the ne key is either the nmber yo specified or one of the folloing: For files that have no gaps beteen key nmbers, the key nmber is one higher than the previos highest key nmber. For files that have gaps beteen key nmbers, the key nmber is the loest missing key nmber. Yo can se the ne key to access yor data as soon as the operation completes. If the Create Index operation is nsccessfl, the MicroKernel drops hatever portion of the ne index it has already bilt. The file pages allocated to the ne index prior to the error are placed on a list of free space for the file and resed hen yo insert records or create another key. Btrieve Programmer s Reference 71 Btrieve Operations

72 If the operation fails dring the creation of an AUTOINCREMENT key, any vales that have already been altered remain altered. The MicroKernel can retrn the folloing stats codes: 22 The data bffer length is too short. 27 The key position is invalid. 41 The MicroKernel does not allo the attempted operation. 45 The specified key flags are invalid. 49 The extended data type is invalid. 56 An index is incomplete. 84 The record or page is locked. 85 The file is locked. 104 The MicroKernel does not recognize the locale. 134 The MicroKernel cannot read the International Sorting Rle. 135 The specified International Sort Rle table is corrpt or otherise invalid. 136 The MicroKernel cannot find the specified Alternate Collating Seqence in the file. If processing is interrpted dring the creation of a key, yo can access the data in the file throgh the file s other keys. Hoever, the MicroKernel retrns a nonzero stats code if yo try to access data by the incomplete index. To correct this problem, drop the incomplete index ith a Drop Index operation (32) and reisse the Create Index operation. Positioning The Create Index operation has no effect on any file crrency information. Btrieve Programmer s Reference 72 Btrieve Operations

73 Delete (4) The Delete operation removes an existing record from a file. The space that the deleted record occpied is then available for inserting ne records. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X Retrned X Prereqisites The file mst be open. Yo have established physical or logical crrency in the file. Operations that satisfy this reqirement are: Get (except extended Gets or Get Key), Step (except extended Steps), Insert, and Update. If yo ant to delete a record hile inside a transaction, the record mst have been retrieved hile inside the transaction. Procedre 1. Set the Operation Code to Pass the Position Block of the file that contains the record to be deleted. Details The Delete operation is not a valid operation if performed immediately after an extended Get or extended Step operation. Btrieve Programmer s Reference 73 Btrieve Operations

74 When performing a Delete operation immediately folloing a Get operation, do not change the Key Nmber that the Get operation retrns. If yo do, the MicroKernel deletes the record sccessflly; hoever, it retrns Stats Code 7 on the first Get operation performed after the deletion. The MicroKernel does not allo Delete operations after a Get Key operation (+50). Before the MicroKernel performs a Delete operation, it compares the crrent sage cont of the data page it intends to modify ith the sage cont of the data page hen the record as read. To obtain the sage cont, the MicroKernel mst read the data page. Becase the Get Key operation does not read the data page, no sage cont is available for comparison on the Delete. The Delete fails becase the MicroKernel cannot perform its passive concrrency conflict checking ithot the compare. When the Delete fails, the MicroKernel retrns Stats Code 8. Reslt If the Delete operation is sccessfl, the MicroKernel removes the record from the file, releases the record lock (if one existed for the deleted record), and adjsts all key indexes to reflect the deletion. If the Delete operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 8 The crrent positioning is invalid. 80 The MicroKernel encontered a record-level conflict. 83 The application encontered an incompatible mode error. Positioning The Delete operation destroys the complete physical location information and the logical crrent record position bt leaves the positions of the logical next record and logical previos record nchanged. Btrieve Programmer s Reference 74 Btrieve Operations

75 Drop Index (32) The Drop Index operation deletes a key from an existing file. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X Retrned Prereqisites The file mst be open. The key mst exist in the file. No transactions can be active. Procedre 1. Set the Operation Code to Pass the Position Block of the file that contains the key to drop. 3. Store the nmber of the key to drop in the Key Nmber parameter. To drop the system-defined log key (also called system data), specify 125. Details Yo may ant to drop the system-defined log key (also called system data) and rebild it if it becomes corrpted. After dropping the system-defined log key, rebild it sing the Create Index (31) operation. Btrieve Programmer s Reference 75 Btrieve Operations

76 When yo delete a key, the MicroKernel atomatically renmbers all higher-nmbered keys, nless yo specify otherise. The MicroKernel renmbers by decrementing the higher-nmbered keys by 1. For example, sppose yo have a file ith key nmbers 1, 4, and 7. If yo drop key 4, the MicroKernel renmbers the keys as 1 and 6. If yo do not ant the MicroKernel to atomatically renmber keys, add a bias of 128 to the vale yo spply for the Key Nmber parameter. This allos yo to leave gaps in the key nmbering; conseqently, yo can drop a damaged index and then rebild it ithot affecting the nmbering of other keys in the file. Yo rebild the index sing the Create Index operation (31), hich allos yo to specify a key nmber. Hoever, if yo delete a key and do not renmber higher-nmbered keys and a ser then clones the affected file ithot assigning specific key nmbers, the cloned file has different key nmbers than the original. (Users can clone files sing the Btrieve Maintenance tility. Cloning is the process of creating a ne, empty file ith the same statistics as an existing file.) Reslt If the Drop Index operation is sccessfl, the MicroKernel places the pages that ere allocated to that index on a list of free space for later se. Unless yo specify otherise, the MicroKernel renmbers the higher-nmbered keys. If the Drop Index operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 6 The key nmber parameter is invalid. 41 The MicroKernel does not allo the attempted operation. If processing is interrpted hile the MicroKernel is dropping an index, yo can access the data in the file by the file s other keys. The MicroKernel retrns Stats Code 56 if yo Btrieve Programmer s Reference 76 Btrieve Operations

77 try to access the file by an incomplete index. If processing is interrpted, reisse the Drop Index operation. Positioning The Drop Index operation has no effect on physical file crrency information. Hoever, dropping the key sed to establish the last logical crrency destroys the logical crrency. Btrieve Programmer s Reference 77 Btrieve Operations

78 End Transaction (20) The End Transaction operation completes a transaction and makes the appropriate changes to the data files. It also nlocks all files and records locked by the transaction. Parameters Sent Retrned Operation Code X Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Prereqisites Before issing an End Transaction operation, yor application mst isse a sccessfl Begin Transaction operation (19 or 1019). Procedre Set the Operation Code to 20. While the MicroKernel ignores all other parameters on an End Transaction call, yo shold initialize them to 0 to ensre compatibility ith ftre releases. Reslt If the End Transaction operation is sccessfl, all the operations ithin the transaction are recorded in yor file. Yor application cannot abort a transaction after an End Transaction operation. Btrieve Programmer s Reference 78 Btrieve Operations

79 If the End Transaction operation is nsccessfl, the MicroKernel retrns the folloing stats code: 38 The MicroKernel encontered a transaction control file I/O error. Positioning The End Transaction operation has no effect on any file crrency information. Btrieve Programmer s Reference 79 Btrieve Operations

80 Find Percentage (45) The Find Percentage operation is one of to Btrieve operations that indo-oriented applications can se to implement scroll bars. The other is the Get By Percentage operation (44). Find Percentage finds the position of a record either relative to a key path or as the record s physical location ithin the file. The position is expressed as a percentage vale. See the Reslt section for a definition of the range of percentage vales. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Note When seeking the percentage relative to a key path, Find Percentage does not reqire an inpt vale for the Data Bffer parameter. When seeking the percentage as relative to a record s physical location ithin the file, Find Percentage does not reqire an inpt vale for the Key Bffer parameter. Key Nmber Sent X X X X X X Retrned X X X Prereqisites The file mst be open. If yo are seeking the percentage relative to a key path, the file cannot be a dataonly file. When yo are seeking the percentage by a record s physical location in the file, yo mst provide the 4-byte physical location of the record. Yo can retrieve this location ith a Get Position operation (22). Btrieve Programmer s Reference 80 Btrieve Operations

81 Procedre Details 1. Set the Operation Code to Pass the Position Block for the file. 3. If yo are seeking the percentage relative to the record s physical location ithin the file, store the record s physical address in the Data Bffer parameter. Otherise, yo do not need to provide a vale for the Data Bffer parameter. 4. Set the Data Bffer Length to a minimm of 4 bytes. (This 4-byte minimm is a reqirement of the MicroKernel s internal implementation.) 5. If yo are seeking the percentage relative to a key path, set the Key Bffer parameter to the key vale. Otherise, yo do not need to provide a vale for the Key Bffer parameter. 6. Set the Key Nmber parameter as follos: a. If yo are seeking the percentage by a key path, set the Key Nmber parameter to the actal key nmber. b. If yo are seeking the percentage by the record s physical location, set the Key Nmber parameter to 1 (0xFF). The Find Percentage operation is provided specifically to spport scroll bar implementation. Becase many factors affect the accracy of this operation that is, hether the retrned percentage vale accrately reflects the position of the record or key vale yo shold not rely on the accracy of this operation for other prposes. To optimize the Find Percentage operation, the MicroKernel assmes that a file has an even distribtion of records among the data pages and keys among the index pages. Hoever, distribtion can be affected by the folloing sitations: The file is not index balanced, and a large nmber of records ithin the same range of keys has been deleted. Btrieve Programmer s Reference 81 Btrieve Operations

82 A large nmber of records ithin the same range of physical addresses has been deleted. The file contains nmeros dplicate key vales, and the key is a linkeddplicatable key. Reslt If the Find Percentage operation is sccessfl, the MicroKernel retrns the position of the specified key vale or record to the Data Bffer. This position is expressed as a percentage of the offset into the key path or file and is a vale in the range of 0 (0 percent) throgh 10,000 ( percent). The percentage vale is retrned as an integer in lo-byte, high-byte order. For example: Retrned Vale Hex Retrned Vale Dec Percentage in Key Path or File 88h 13h % The MicroKernel also retrns a Data Bffer Length of 4 if the operation is sccessfl. If the Find Percentage operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 7 The key nmber has changed. 8 The crrent positioning is invalid. 9 The operation encontered the end-of-file. Btrieve Programmer s Reference 82 Btrieve Operations

83 22 The data bffer parameter is too short. 41 The MicroKernel does not allo the attempted operation. 43 The specified record address is invalid. 82 The MicroKernel lost positioning. Positioning The Find Percentage operation does not change any crrency information. Btrieve Programmer s Reference 83 Btrieve Operations

84 Get By Percentage (44) The Get By Percentage operation is one of to Btrieve operations that can be sed by indo-oriented applications for implementing scroll bars. The other is the Find Percentage operation (45). Get By Percentage retrieves a record by that record s position in the file, here the position is based on a percentage vale yo spply hen yo call the operation. Yo mst also specify hether the position is relative to a specified key path or represents the record s actal physical location in the file. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Note The Get By Percentage operation, hen seeking the record by its physical location in the file, does not retrn any information in the Key Bffer parameter. Key Nmber Sent X X X X X Retrned X X X X Prereqisites The file mst be open. If yo are seeking the record relative to a key path, the file cannot be a data-only file. Btrieve Programmer s Reference 84 Btrieve Operations

85 Procedre 1. Set the Operation Code to 44. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. Details For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Store the percentage vale as a 16-bit integer in the Data Bffer. See the Details section for the acceptable range of percentage vales and related information. 4. Set the Data Bffer Length to a vale greater than or eqal to the length of the largest possible record that cold be retrned. (The MicroKernel s internal implementation reqires that yo set the Data Bffer Length vale to a minimm of 4 bytes.) 5. Set the Key Nmber parameter. a. If yo are seeking the record by a key path, set the Key Nmber parameter to the actal key nmber. To se the system-defined log key (also called system data), specify 125. b. If yo are seeking the record by the record s physical position in the file, set the Key Nmber parameter to 1 (0xFF). The range of acceptable percentage vales for the Data Bffer parameter is from 0 (indicating the beginning of the key path or file) throgh 10,000 (the end of the key path or file). Be sre to store the vale as an integer (in lo-byte, high-byte order). For Btrieve Programmer s Reference 85 Btrieve Operations

86 example, to seek to the 50 percent point in the file, se a vale of 5,000 (0x1388). After byte-sapping 0x1388, store 0x88 and 0x13 in the first to bytes of the Data Bffer parameter. The Get By Percentage operation is provided specifically to spport scroll bar implementation. Becase many factors affect the accracy of this operation that is, hether the retrned record is positioned at the actal percentage point yo specify in the file yo shold not rely on the accracy of this operation for other prposes. To optimize the Get By Percentage operation, the MicroKernel assmes that a file has an even distribtion of records among the data pages and keys among the index pages. Hoever, distribtion can be affected by the folloing sitations: The file is not index balanced, and a large nmber of records ithin the same range of keys has been deleted. A large nmber of records ithin the same range of physical addresses has been deleted. The file contains nmeros dplicate key vales, and the key is a linkeddplicatable key. Reslt If the Get By Percentage operation is sccessfl, the MicroKernel retrns to the Data Bffer a record that is either from the designated position relative to the specified key path or from the physical position in the file. The MicroKernel retrns the length of the record in bytes into the Data Bffer Length parameter. If the operation seeks the record by a key path, the MicroKernel retrns the key vale for the specified key path in the Key Bffer parameter. If the operation seeks the record by physical record order, the MicroKernel does not retrn any information in the Key Bffer parameter. Btrieve Programmer s Reference 86 Btrieve Operations

87 Note When Get By Percentage is seeking a record relative to a key path, and the key contains dplicate vales, the MicroKernel alays retrns the first record containing the dplicated vale. This implementation detail can affect the accracy of the operation. If the Get By Percentage operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 7 The key nmber has changed. 8 The crrent positioning is invalid. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. 41 The MicroKernel does not allo the attempted operation. 43 The specified record address is invalid. 82 The MicroKernel lost positioning. Positioning If sccessfl hen seeking a record relative to a specified key path, the Get By Percentage operation establishes the ne logical and physical crrencies based respectively on the specified Key Nmber and the retrieved record. Btrieve Programmer s Reference 87 Btrieve Operations

88 If sccessfl hen seeking a record based on the record s physical location ithin the file, the Get By Percentage operation establishes the ne physical crrency based on the retrieved record. If the Get By Percentage operation is nsccessfl, the MicroKernel changes no crrency. Btrieve Programmer s Reference 88 Btrieve Operations

89 Get Direct/Chnk (23) The Get Direct/Chnk operation can retrieve one or more portions, called chnks, of a record. This operation is especially sefl on files containing records longer than 65,535 bytes. Sch records are too long to be retrieved by the other Get and Step operations, de to restrictions on the length of the Data Bffer parameter. Yor application specifies the record from hich chnks are to be retrieved by spplying its physical address. The location of a chnk in a record is generally specified by its offset and length. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X Prereqisites The file mst be open. Yo mst provide the 4-byte physical location of the record. Yo can retrieve this location ith a Get Position operation (22). Yo mst provide a large enogh Data Bffer to contain all vales that a Get Direct/Chnk operation retrns. The Data Bffer mst also be able to contain the entire chnk descriptor (all the chnk definitions) hen the Get Direct/Chnk operation is performing an indirect chnk operation. The maximm size of the Data Bffer is limited as shon in Table 2-9. Btrieve Programmer s Reference 89 Btrieve Operations

90 Table 2-9 Data Bffer Size Limitations by Environment Environment Local calls to server or orkstation engine Remote calls via DOS Reqester (BREQNT) Remote calls via DOS Reqester (BREQUEST) Remote calls via Win16, Win32, or OS/2 Reqester Maximm Data Bffer Size 64,512 bytes 55,512 bytes 57,000 bytes 65,153 bytes Procedre 1. Set the Operation Code to 23. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Specify a Data Bffer, as described in Details. 4. Specify the Data Bffer Length as either the length of the inpt strctre (Table 2-10 or Table 2-11) or the nmber of bytes yo reqested for the MicroKernel to retrieve, hichever is larger. Some options for the Get Direct/Chnk operation retrieve chnks to locations other than the Data Bffer. See the Details section for more information abot calclating the Data Bffer Length. 5. Set the Key Nmber parameter to 2 (0xFE). Btrieve Programmer s Reference 90 Btrieve Operations

91 Details Use one of the folloing chnk descriptors in the Data Bffer: Random Chnk Descriptor To retrieve a single chnk per operation, or to retrieve mltiple chnks in a single operation hen the chnks are spaced randomly throghot the record. Rectangle Chnk Descriptor To retrieve mltiple chnks in an operation, hen each chnk is the same length and chnks are spaced eqidistantly in the record. Random Chnks The folloing example shos a record ith three randomly spaced chnks (shaded areas): chnk 0 (bytes 0x12 throgh 0x16), chnk 1 (bytes 0x2A throgh 0x31), and chnk 2 (bytes 0x41 throgh 0x4E) A 0B 0C 0D 0E 0F A 1B 1C 1D 1E 1F A 2B 2C 2D 2E 2F A 3B 3C 3D 3E 3F A 4B 4C 4D 4E 4F Btrieve Programmer s Reference 91 Btrieve Operations

92 To fetch random chnks, yo mst create a strctre in the Data Bffer, based on the folloing table. Table 2-10 Data Bffer for Random Chnk Operations Element Length (in Bytes) Description Record Address 4 The 4-byte physical location of the record. Yo can retrieve this location ith a Get Position operation (22). Random Chnk Descriptor Sbfnction 4 Type of chnk descriptor; one of the folloing: 0x (Direct random chnk descriptor) Retrieves chnks directly into the Data Bffer. The first chnk is retrieved and stored at offset 0 in the Data Bffer, the second chnk immediately follos the first, and so on. 0x (Indirect random chnk descriptor) Retrieves chnks into addresses specified by the Chnk Definitions. NmChnks 4 Nmber of chnks to retrieve. The vale mst be at least 1. Althogh no explicit maximm vale exists, the chnk descriptor mst fit in the Data Bffer, hich is limited in size as described in Table 2-9. Btrieve Programmer s Reference 92 Btrieve Operations

93 Table 2-10 Data Bffer for Random Chnk Operations contined Element Length (in Bytes) Description Chnk Definition (Repeat for each chnk) 12 Each Chnk Definition is a 4-byte Chnk Offset, folloed by a 4-byte Chnk Length, folloed by a 4-byte User Data, described as follos: Chnk Offset Indicates here the chnk begins as an offset in bytes from the beginning of the record. The minimm vale is 0, and the maximm vale is the offset of the last byte in the record. Chnk Length Indicates ho many bytes are in the chnk. The minimm vale is 0, and the maximm vale 65,535; hoever, the chnk descriptor mst fit in the Data Bffer, hich is limited in size as described in Table 2-9. User Data (Used only for indirect descriptors.) A 32-bit pointer to the actal chnk data. The format yo shold se depends on yor operating system. 1 The MicroKernel ignores this element for direct chnk descriptor sbfnctions. 1 For 16-bit applications, initialize User Data as a 16-bit offset and a 16-bit segment. User Data cannot address memory beyond the end of its segment. When Chnk Length is added to the offset portion of User Data, the reslt mst be ithin the segment that User Data defines. By defalt, the MicroKernel does not check for violations of this rle and does not properly handle sch violations. The folloing table shos a sample Data Bffer for a fetching direct random chnks. Element Sample Vale Length (in Bytes) Record Address 0x Sbfnction 0x NmChnks 3 4 Chnk 0 Btrieve Programmer s Reference 93 Btrieve Operations

94 Element Sample Vale Length (in Bytes) Chnk Offset 18 4 Chnk Length 5 4 User Data N/A 4 Chnk 1 Chnk Offset 42 4 Chnk Length 8 4 User Data N/A 4 Chnk 2 Chnk Offset 65 4 Chnk Length 14 4 User Data N/A 4 Btrieve Programmer s Reference 94 Btrieve Operations

95 Rectangle Chnk Descriptor Strctre When chnks of the same length are spaced eqidistantly throghot a record, yo can describe all the chnks to retrieve ith a rectangle chnk descriptor. For example, consider the folloing diagram, hich represents offset 0x00 throgh 0x4F in a record: A 0B 0C 0D 0E 0F A 1B 1C 1D 1E 1F A 2B 2C 2D 2E 2F A 3B 3C 3D 3E 3F A 4B 4C 4D 4E 4F The record contains three chnks (shaded areas): chnk 0 (bytes 0x19 throgh 0x1C), chnk 1 (bytes 0x29 throgh 0x2C), and chnk 2 (bytes 0x39 throgh 0x3C). Each chnk is for bytes long, and a total of 16 (0x10) bytes, calclated from the beginning of each chnk, separates the chnks from one another. Btrieve Programmer s Reference 95 Btrieve Operations

96 Yo can retrieve all three chnks sing a single rectangle descriptor. To fetch rectangle chnks, yo mst create a strctre in the Data Bffer based on the folloing table. Table 2-11 Element Data Bffer for Rectangle Chnks Length (in Bytes) Description Record Address 4 The 4-byte physical location of the record. Yo can retrieve this location ith a Get Position operation (22). Rectangle Chnk Descriptor Sbfnction 4 Type of chnk descriptor; one of the folloing: 0x (Direct rectangle chnk descriptor) Retrieves chnks directly into the Data Bffer. The first chnk is retrieved and stored at offset 0 in the Data Bffer, the second chnk immediately follos the first, and so on. 0x (Indirect rectangle chnk descriptor) Retrieves chnks into addresses specified by the User Data and Application Distance Beteen Ros elements. Nmber of Ros 4 Nmber of chnks on hich the rectangle chnk descriptor mst operate. The minimm vale is 1. No explicit maximm vale exists. Offset 4 Offset from the beginning of the record of the first byte to retrieve. The minimm vale is 0, and the maximm vale is the offset of the last byte in the record. If the record is vieed as a rectangle, this element refers to the offset of the first byte in the first ro to be retrieved. Bytes Per Ro 4 Nmber of bytes to retrieve in each chnk. The minimm vale is 0, and the maximm vale is 65,535; hoever, the chnk descriptor mst fit in the Data Bffer, hich is limited in size as described in Table 2-9. Btrieve Programmer s Reference 96 Btrieve Operations

97 Table 2-11 Element Distance Beteen Ros 4 Nmber of bytes beteen the beginning of each chnk. User Data 4 (Used only ith indirect descriptors.) A 32-bit pointer to the location into hich the MicroKernel stores bytes after retrieving them from each ro. The format yo shold se depends on yor operating system. 1 The MicroKernel ignores this element for direct rectangle descriptors; hoever, yo mst still allocate the element and initialize it to 0. Application Distance Beteen Ros Data Bffer for Rectangle Chnks contined Length (in Bytes) Description 4 (Used only ith indirect rectangle descriptors.) Nmber of bytes beteen the beginning of each chnk in the rectangle, as the rectangle is stored in yor application s memory, at the address specified by User Data. The MicroKernel ignores this element for direct rectangle descriptors; hoever, yo mst still allocate the element and initialize it to 0. 1 For 16-bit applications, express User Data as a 16-bit offset folloed by a 16-bit segment. When yo se an indirect descriptor, be sre that the User Data pointer is initialized so that the chnks retrieved do not overrite yor chnk descriptor. The MicroKernel ses the descriptor hen copying the retrned chnks to the locations that the User Data elements specify. In the event that yo overrite yor chnk descriptor, the MicroKernel retrns Stats Code 62. If the rectangle has the same nmber of bytes beteen ros hen it is in memory as hen it is stored as a record, set Application Distance Beteen Ros ith the same vale as Distance Beteen Ros. Hoever, if the rectangle is arranged in yor application s memory ith either more or feer bytes beteen ros, Application Distance Beteen Ros allos yo to pass that information to the MicroKernel. Btrieve Programmer s Reference 97 Btrieve Operations

98 When yo se an indirect rectangle descriptor, the MicroKernel ses both the User Data and the Application Distance Beteen Ros elements to determine the locations in hich to store the data after retrieving it. The MicroKernel stores data from the first ro in offset 0 of User Data. The MicroKernel stores the second ro s data to an address specified by User Data pls Application Distance Beteen Ros. The MicroKernel stores the third ro s data in the address specified by User Data pls (Application Distance Beteen Ros * 2), and so on. The folloing table shos a sample Data Bffer for fetching a direct rectangle chnk. Element Name Sample Vale Length (in Bytes) Record Address 0x Sbfnction 0x Nmber of Ros 3 4 Offset 25 4 Bytes Per Ro 4 4 Distance Beteen Ros 16 4 User Data 0 4 Application Distance Beteen Ros 0 4 Next-in-Record Sbfnction Bias If yo add a bias of 0x to any of the sbfnctions previosly listed, the MicroKernel calclates the sbfnction s Offset element vales based on yor physical intrarecord crrency (that is, yor crrent physical location ithin the record). When yo se the Next-in-Record sbfnction, the MicroKernel ignores the Offset element in the chnk descriptor. Btrieve Programmer s Reference 98 Btrieve Operations

99 Reslt If the Get Direct/Chnk operation is sccessfl and a direct chnk descriptor is sed, the MicroKernel retrns the chnks one after another in the Data Bffer. If yo sed an indirect random chnk descriptor, the MicroKernel retrns the data to the locations that each chnk s User Data element specifies. If yo sed an indirect rectangle descriptor, the MicroKernel retrns the data to locations it derives from the User Data and Application Distance Beteen Ros elements. The MicroKernel also stores the total length of the chnks retrieved in the Data Bffer Length parameter. (The retrned vale reflects all bytes retrieved, hether they ere retrieved and stored directly into the Data Bffer, or the indirect descriptor as sed to retrieve and store the bytes elsehere.) If the operation as partially sccessfl, yor application can se the vale retrned in the Data Bffer Length parameter to determine hich chnks cold not be retrieved and ho many bytes of the final chnk ere retrieved. The Get Direct/Chnk operation is only partially sccessfl if any chnk begins beyond the end of the record (reslting in the MicroKernel retrning Stats Code 103), or if any chnk s offset and length combine to exceed the length of the record. In the latter case, the MicroKernel retrns Stats Code 0 bt ceases processing sbseqent chnks, if any, in the operation. Note Only the Data Bffer Length parameter shos that not all of the chnks ere properly retrieved. For this reason, be sre that yo alays check the vale retrned in the Data Bffer Length parameter after a Get Direct/Chnk operation. The folloing stats codes indicate a partially sccessfl Get Direct/Chnk operation. When the MicroKernel retrns one of these stats codes, yor application shold check Btrieve Programmer s Reference 99 Btrieve Operations

100 the Data Bffer Length parameter s retrn vale to see ho mch data the MicroKernel actally retrned. 54 The variable-length portion of the record is corrpt. 103 The chnk offset is too big. If the MicroKernel retrns any of the folloing stats codes, it has retrned no data. 43 The specified record address is invalid. 58 The compression bffer length is too short. 62 The descriptor is incorrect. 97 The data bffer is too small. 106 The MicroKernel cannot perform a Get Next Chnk operation. Positioning The Get Direct/Chnk operation has no effect on logical crrency. In terms of physical crrency, Get Direct/Chnk makes the record from hich chnks are retrieved the physical crrent record. Btrieve Programmer s Reference 100 Btrieve Operations

101 Get Direct/Record (23) The Get Direct/Record operation retrieves a record sing its physical location in the file instead of sing one of the defined key paths. Use Get Direct/Record to accomplish the folloing: Retrieve a record faster sing its physical location instead of its key vale. Use the Get Position operation (22) to retrieve the 4-byte location of a record, save the location, and se Get Direct/Record to retrn directly to that location after performing other operations that affect crrency. Use the 4-byte location to retrieve a record in a chain of dplicates ithot rereading all the records from the beginning of the chain. Change the crrent key path. A Get Position operation, folloed by a Get Direct/ Record operation ith a different key nmber, establishes positioning for the crrent record in a different index path. A sbseqent Get Next retrns the next record in the file based on the ne key path. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Note The Key Nmber parameter is not needed hen performing a Get Direct/Record operation on a data-only file. Key Nmber Sent X X X X X Retrned X X X X Btrieve Programmer s Reference 101 Btrieve Operations

102 Prereqisites The file mst be open. Yo mst provide the 4-byte physical location of the record. Yo can retrieve this location ith a Get Position operation (22), hich retrns the physical address of the crrent record. Procedre 1. Set the Operation Code to 23. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Store the 4-byte position of the reqested record in the first 4 bytes of the Data Bffer. 4. Set the Data Bffer Length to a vale greater than or eqal to the length of the record to retrieve. 5. Set the Key Nmber to the key nmber of the path for hich yo ant the MicroKernel to establish logical crrency. Specify 1 if yo do not ant the MicroKernel to establish logical crrency. To se the system-defined log key (also called system data), specify 125. Btrieve Programmer s Reference 102 Btrieve Operations

103 Reslt If the Get Direct/Record operation is sccessfl, the MicroKernel retrns the reqested record in the Data Bffer, the length of the record in the Data Bffer Length parameter, and the key vale for the specified key path in the Key Bffer. If the Get Direct/Record operation is nsccessfl and the MicroKernel cannot retrn the reqested record, the MicroKernel retrns one of the folloing stats codes: 22 The data bffer parameter is too short. (Logical crrency is still established.) 43 The specified record address is invalid. (Logical crrency is not established.) 44 The specified key path is invalid. (Logical crrency is not established.) 82 The MicroKernel lost positioning. (Logical crrency is not established.) Positioning The Get Direct/Record operation erases any existing logical crrency information and establishes the ne logical crrency according to the Key Nmber specified. It has no effect on the physical crrency information. Btrieve Programmer s Reference 103 Btrieve Operations

104 Get Directory (18) The Get Directory operation retrns the crrent directory for a specified logical disk drive. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X Retrned X Prereqisites Yor application can isse a Get Directory operation at any time. The Key Bffer shold be at least 65 characters long. Procedre 1. Set the Operation Code to Store the logical disk drive nmber in the Key Nmber parameter. Specify the drive as 1 for A, 2 for B, and so on. To se the defalt drive, specify 0. Reslt The MicroKernel retrns the crrent directory, terminated by a binary 0, in the Key Bffer. Positioning The Get Directory operation has no effect on any file crrency information. Btrieve Programmer s Reference 104 Btrieve Operations

105 Get Eqal (5) The Get Eqal operation retrieves a record that has a key vale eqal to that specified in the Key Bffer. If the key allos dplicates, this operation retrieves the first record (chronologically) of a grop ith the same key vales. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X Prereqisites The file mst be open. The file cannot be a data-only file. Procedre 1. Set the Operation Code to 5. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. Btrieve Programmer s Reference 105 Btrieve Operations

106 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record to retrieve. 4. Specify the desired key vale in the Key Bffer. 5. Set the Key Nmber to the correct key path. To se the system-defined log key (also called system data), specify 125. Reslt If the Get Eqal operation is sccessfl, the MicroKernel retrns the reqested record in the Data Bffer and the length of the record in the Data Bffer Length parameter. If the Get Eqal operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 4 The application cannot find the key vale. 6 The key nmber parameter is invalid. 22 The data bffer parameter is too short. Positioning The Get Eqal operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. Btrieve Programmer s Reference 106 Btrieve Operations

107 Get First (12) The Get First operation retrieves the logical first record based on the specified key. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Procedre 1. Set the Operation Code to 12. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. Btrieve Programmer s Reference 107 Btrieve Operations

108 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record to retrieve. 4. Indicate the Key Nmber for the key path. To se the system-defined log key (also called system data), specify 125. Reslt If the Get First operation is sccessfl, the MicroKernel retrns the reqested record in the Data Bffer, stores the corresponding key vale in the Key Bffer, and retrns the length of the record in the Data Bffer Length parameter. If the Get First operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. Positioning The Get First operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. The logical previos position points beyond the beginning of the file. Btrieve Programmer s Reference 108 Btrieve Operations

109 Get Greater (8) The Get Greater operation retrieves a record in hich the field specified by the Key Nmber has the next greater vale than the one in the Key Bffer. If the key allos dplicates, this operation retrieves the first record (chronologically) of the grop ith the same key vales. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Note If yo are sing the Get Greater operation on descending keys, the next greater vale refers to a vale loer than the one specified in the Key Bffer. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Procedre 1. Set the Operation Code to 8. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. Btrieve Programmer s Reference 109 Btrieve Operations

110 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record yo ant to retrieve. 4. Specify the desired key vale in the Key Bffer parameter. 5. Set the Key Nmber parameter to correspond to the correct key path. To se the system-defined log key (also called system data), specify 125. Reslt If the Get Greater operation is sccessfl, the MicroKernel stores the record in the Data Bffer, the key vale in the Key Bffer, and the length of the record in the Data Bffer Length parameter. If the Get Greater operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 22 The data bffer parameter is too short. Positioning The Get Greater operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. Btrieve Programmer s Reference 110 Btrieve Operations

111 Get Greater Than or Eqal (9) The Get Greater Than or Eqal operation retrieves a record in hich the vale for the key specified by the Key Nmber is eqal to or greater than the vale yo spply in the Key Bffer. The MicroKernel first tries to satisfy the eqal reqirement. If the key allos dplicates, this operation retrieves the first record (chronologically) of the grop ith the same key vales. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Note If yo are sing the Get Greater Than or Eqal operation on descending keys, the next greater vale refers to a vale loer than the one specified in the Key Bffer. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Procedre 1. Set the Operation Code to 9. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. Btrieve Programmer s Reference 111 Btrieve Operations

112 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record yo ant to retrieve. 4. Specify the key vale in the Key Bffer parameter. 5. Set the Key Nmber parameter to correspond to the correct key path. To se the system-defined log key (also called system data), specify 125. Reslt If the Get Greater Than or Eqal operation is sccessfl, the MicroKernel stores the record in the Data Bffer, the key vale in the Key Bffer, and the length of the record in the Data Bffer Length parameter. If the Get Greater Than or Eqal operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 22 The data bffer parameter is too short. Positioning The Get Greater Than or Eqal operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. Btrieve Programmer s Reference 112 Btrieve Operations

113 Get Key (+50) The Get Key bias allos yo to perform a Get operation ithot actally retrieving a data record. Yo can se Get Key to detect the presence of a vale in a file. A Get Key operation is generally faster than its corresponding Get operation. Yo can se the Get Key operation ith any of the folloing Get operations: Get Eqal (5) Get Next (6) Get Previos (7) Get Greater (8) Get Greater Than or Eqal (9) Get Less Than (10) Get Less Than or Eqal (11) Get First (12) Get Last (13) Parameters The parameters are the same as those for the corresponding Get operation, except that the MicroKernel ignores the Data Bffer Length and does not retrn a record in the Data Bffer. Prereqisites The prereqisites for a Get Key operation are the same as those for the corresponding Get operation. Btrieve Programmer s Reference 113 Btrieve Operations

114 Procedre 1. Set the parameters as yo old for the corresponding Get operation. Yo do not need to initialize the Data Bffer Length. 2. Set the Operation Code to the Get operation yo ant to perform, pls 50. For example, to perform a Get Key (+50) ith the Get Eqal operation (5), set the Operation code to 55. The MicroKernel does not allo Delete or Update operations after a Get Key operation (+50). Before the MicroKernel performs Update or Delete operations, it compares the crrent sage cont of the data page it intends to modify ith the sage cont of the data page hen the record as read. To obtain the sage cont, the MicroKernel mst read the data page. Becase the Get Key operation does not read the data page, no sage cont is available for comparison on the Update or Delete. The Update or Delete fails becase the MicroKernel cannot perform its passive concrrency conflict checking ithot the compare. When the Update or Delete fails, the MicroKernel retrns Stats Code 8. Reslt If the MicroKernel finds the reqested key, it retrns the key vale in the Key Bffer and Stats Code 0. Otherise, the MicroKernel retrns a stats code indicating hy it cannot find the key vale. Positioning The Get Key operation establishes the crrent positioning in a similar manner to the corresponding Get operation. Hoever, hen a Get Key operation involves a key that allos dplicates, the MicroKernel ignores the dplicate instances of the crrent retrieved key vale. After a Get Key operation, the logical previos position points to the record Btrieve Programmer s Reference 114 Btrieve Operations

115 containing the previos lesser key vale. The logical next position points to the record ith the next greater key vale. For example, assme yo perform a Get Key/Get Eqal operation (55) on a last name key that contains eight occrrences of Smith and a single Smythe. The logical next position does not point to the next Smith, bt to Smythe. Becase a Get Key operation does not positively identify any one record, the MicroKernel does not allo an Update or Delete operation to follo a Get Key operation. Btrieve Programmer s Reference 115 Btrieve Operations

116 Get Last (13) The Get Last operation retrieves the logical last record based on the specified key. If dplicates exist for the last key vale, the record retrned is the last dplicate. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Procedre 1. Set the Operation Code to 13. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. Btrieve Programmer s Reference 116 Btrieve Operations

117 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record yo ant to retrieve. 4. Specify the Key Nmber for the key path. To se the system-defined log key (also called system data), specify 125. Reslt If the Get Last operation is sccessfl, the MicroKernel retrns the reqested record in the Data Bffer, stores the corresponding key vale in the Key Bffer, and retrns the length of the record in the Data Bffer Length parameter. If the Get Last operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. Positioning The Get Last operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. The logical next position points beyond the end of the file. Btrieve Programmer s Reference 117 Btrieve Operations

118 Get Less Than (10) The Get Less Than operation retrieves a record in hich the vale for the key specified by the Key Nmber has the previos lesser vale than the vale yo spply in the Key Bffer. If the key allos dplicate vales, this operation retrieves the last record (chronologically) of the grop ith the same key vales. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Note If yo are sing the Get Less Than operation on descending keys, the next lesser vale refers to a vale higher than the one specified in the Key Bffer. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Procedre 1. Set the Operation Code to 10. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. Btrieve Programmer s Reference 118 Btrieve Operations

119 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record yo ant to retrieve. 4. Specify the desired key vale in the Key Bffer parameter. 5. Set the Key Nmber parameter to the key path. To se the system-defined log key (also called system data), specify 125. Reslt If the Get Less Than operation is sccessfl, the MicroKernel retrns the record in the Data Bffer, the key vale for the record in the Key Bffer, and the length of the record in the Data Bffer Length parameter. If the Get Less Than operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 22 The data bffer parameter is too short. Positioning The Get Less Than operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. Btrieve Programmer s Reference 119 Btrieve Operations

120 Get Less Than or Eqal (11) The Get Less Than or Eqal operation retrieves a record in hich the vale for the key specified by the Key Nmber has an eqal or a previos lesser vale than the vale yo spply in the Key Bffer. The MicroKernel first tries to satisfy the eqal reqirement. If the key allos dplicate vales, this operation retrieves the last record (chronologically) of the grop ith the same key vales. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Note If yo are sing the Get Less Than or Eqal operation on descending keys, the next lesser vale refers to a vale higher than the one specified in the Key Bffer. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Procedre 1. Set the Operation Code to 11. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. Btrieve Programmer s Reference 120 Btrieve Operations

121 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record yo ant to retrieve. 4. Specify the key vale in the Key Bffer parameter. 5. Set the Key Nmber parameter to the key path. To se the system-defined log key (also called system data), specify 125. Reslt If the Get Less Than or Eqal operation is sccessfl, the MicroKernel retrns the record in the Data Bffer, the key vale for the record in the Key Bffer, and the length of the record in the Data Bffer Length parameter. If the Get Less Than or Eqal operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 22 The data bffer parameter is too short. Positioning The Get Less Than or Eqal operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. Btrieve Programmer s Reference 121 Btrieve Operations

122 Get Next (6) The Get Next operation retrieves the record in the logical next position (based on the specified key). Yo can se the Get Next operation to retrieve records ithin a grop of records that have dplicate key vales. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Yor application mst have an established logical next position based on the specified key. Procedre 1. Set the Operation Code to 6. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. Btrieve Programmer s Reference 122 Btrieve Operations

123 For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record yo ant to retrieve. 4. Specify the key vale from the previos operation in the Key Bffer. Pass the Key Bffer exactly as the MicroKernel retrned it on the previos call, becase the MicroKernel may need the information previosly stored there to determine its crrent position in the file. 5. Set the Key Nmber parameter to the key path sed on the previos call. Yo cannot change key paths sing a Get Next operation. Reslt If the Get Next operation is sccessfl, the MicroKernel retrns the record in the Data Bffer, the key vale for the record in the Key Bffer, and the length of the record in the Data Bffer Length parameter. If the Get Next operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 7 The key nmber has changed. 8 The crrent positioning is invalid. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. 82 The MicroKernel lost positioning. Btrieve Programmer s Reference 123 Btrieve Operations

124 The operation retrns Stats Code 9 if the logical next position points beyond the end of the file. Positioning The Get Next operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. Btrieve Programmer s Reference 124 Btrieve Operations

125 Get Next Extended (36) The Get Next Extended operation examines one or more records, starting at the logical next position and proceeding toard the end of the file, based on the specified key. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Get Next Extended can also extract specified portions from records and retrn only those portions to an application. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Yo mst have an established logical next position based on the specified key. Procedre 1. Set the Operation Code to 36. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. Btrieve Programmer s Reference 125 Btrieve Operations

126 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Specify a large enogh Data Bffer to accommodate either the inpt Data Bffer or the retrned Data Bffer, hichever is larger. Initialize the Data Bffer according to the strctre shon in Table Specify the Data Bffer Length as either the length of the inpt strctre (Table 2-12) or the length of the retrned strctre (Table 2-13), hichever is larger. The MicroKernel sets p a bffer as a orkspace for extended operations. Yo configre the size of this bffer sing the Extended Operation Bffer Size option. The sm of the Data Bffer strctre, pls the longest record to be retrieved, pls 355 bytes of reqester overhead, cannot exceed the configred bffer size. (Reqester overhead is not applicable for DOS orkstation engines.) 5. Specify the key vale from the previos operation in the Key Bffer. Pass the Key Bffer exactly as the MicroKernel retrned it on the previos call, becase the MicroKernel may need the information previosly stored there to determine its crrent position in the file. 6. Set the Key Nmber parameter to the key path sed on the previos call. Yo cannot change key paths sing a Get Next Extended operation. Btrieve Programmer s Reference 126 Btrieve Operations

127 Details The folloing table shos the strctre of the inpt data bffer. Table 2-12 Inpt Data Bffer Strctre for Extended Get and Step Operations Element Length (in Bytes) Description Header 2 Total length of the Data Bffer. 2 One of to non nll terminated string constant vales: EG Begin ith the record after the one at hich yo are positioned. UC Begin ith the record at hich yo are positioned. Filter (Fixed Portion) For Step Next Extended operations, alays set this vale to EG. 2 Maximm Reject Cont, hich is the nmber of records that the MicroKernel can skip hile searching for records that satisfy the filter condition. Yo can set the vale from 0 to 65,535. (0 means the MicroKernel ses the system-defined maximm reject cont, hich is 4,095.) 2 Nmber of Terms in the logic expression of the filter condition. (0 means the MicroKernel performs no filtering.) Btrieve Programmer s Reference 127 Btrieve Operations

128 Table 2-12 Element Filter (Repeating Portion one for each term of logic expression) Inpt Data Bffer Strctre for Extended Get and Step Operations contined Length (in Bytes) Description 1 Data Type of the field. Use one of the codes shon in Table Field Length. 2 Field Offset (zero relative). 1 Specifies a Comparison Code: 1 Eqal 2 Greater than 3 Less than 4 Not eqal 5 Greater than or eqal 6 Less than or eqal Add a +8 bias to compare strings sing one of the file s existing ACSs. 1 Add a +32 bias to compare strings sing the file s defalt ACS, hich is the first ACS defined in the file. Add a +64 bias if the second operand is another field of the record, rather than a constant. Add a +128 bias to compare strings ithot case sensitivity. Btrieve Programmer s Reference 128 Btrieve Operations

129 Table 2-12 Element Filter (Repeating Portion contined) Descriptor (Fixed Portion) Descriptor (Repeating Portion one for each extracted field) Inpt Data Bffer Strctre for Extended Get and Step Operations contined Length (in Bytes) Description 1 Indicates an AND/OR logic expression: 0 Identifies the last term 1 Next term is connected ith AND 2 Next term is connected ith OR 2 or n When comparing to fields: a 2-byte, zero-relative offset to the second field. (The second field mst be the same type and length.) or When comparing a field to a constant: the actal vale of the constant. The length of the constant (n) mst eqal the length of the field. 0, 5, 9, or When specifying an ACS by name (bias +8), the ACS identifier sing one 17 of the name formats shon in Table Nmber of Records to retrieve. To retrieve only one record instead of a set of records, specify 1. 2 Nmber of Fields to extract from each record. 2 Field Length to extract. 2 Field Offset (zero relative). 1 If yo se both a +8 bias and a +32 bias, the +32 bias is ignored. Btrieve Programmer s Reference 129 Btrieve Operations

130 The MicroKernel interprets the AND and OR operators sed in a filter ith the extended Get and Step operations in strict left-to-right order. The MicroKernel evalates an expression in the filter and proceeds as follos: If the expression is tre hen applied to the crrent record and the next operator is OR, the MicroKernel accepts this record as meeting the filter condition. If the expression is tre and the next operator is AND, the MicroKernel contines to evalate each expression ntil one of the folloing sitations occrs: The MicroKernel reaches an OR expression. One of the expressions evalates to false. The MicroKernel reaches the end of the filter. If the expression is false and the next operator is OR, the MicroKernel contines and evalates the next expression in the filter. If the expression is false and the next operator is AND, the MicroKernel rejects the record. The search for records stops if any one of the folloing conditions is met: The MicroKernel finds the reqested nmber of records that satisfy the filter. While the MicroKernel searches for records to satisfy the filter condition, the nmber of records it examines exceeds the Maximm Reject Cont yo specify. The crrent key path is sed as a filtering field and the MicroKernel reaches a rejected record after hich no records can satisfy the filtering condition in the rest of the file. The MicroKernel reaches the end of the file. Btrieve Programmer s Reference 130 Btrieve Operations

131 Examples To get the next entire record that satisfies the filtering condition, set the filter portion as desired and set the descriptor fields as follos: 1. Set the Nmber of Records to Set the Nmber of Fields to Set the Field Length to the length of the entire record to retrieve. 4. Set the Field Offset to 0. To retrieve the next 12 records ithot sing a filtering condition and extract 4 fields from each record, set the filter Nmber of Terms to 0 and set the descriptor fields as follos: 1. Set the Nmber of Records to Set the Nmber of Fields to Set the Field Length and Field Offset parameters for each of the 4 fields extracted. Retrieving Fields from Records When retrieving one or more fields (portions) of records ith an extended operation, yo mst ensre that the Data Bffer can accommodate the information that the operation retrns. Btrieve Programmer s Reference 131 Btrieve Operations

132 The folloing table illstrates the strctre of the Data Bffer that the MicroKernel retrns. Table 2-13 Retrned Data Bffer Strctre for Extended Get and Step Operations Element Length (in Bytes) Description Nmber of Records 2 Nmber of records retrned. Repeating portion (one for each record retrieved) Length 0 2 Length of the first record image (all fields combined). Position 0 4 Physical crrency (address) of the first record. Record 0 n Image of the first record (all fields combined).... Length x 2 Length in bytes of the last record image (all fields combined). Position x 4 Physical crrency (address) of the last record. Record x n Image of the last record (all fields combined). If all retrned records (or fields of records) are fixed length, yor application can easily calclate the location of data ithin the retrned Data Bffer. Hoever, yor application may need to perform extra steps to extract the variable-length portion of records from the Data Bffer that an extended operation retrns. The MicroKernel does not pad any record image in the retrned Data Bffer hen retrning the variable-length portion of a record. Conseqently, if yo allo room in the retrned Data Bffer for the maximm nmber of bytes that the variable-length portion of a record cold occpy, bt the actal data retrned is less than that maximm, the MicroKernel starts the field description for the next retrned field immediately folloing the data for the crrent field. For example, sppose yor fixed-record length is 100 bytes, yor variable-length portion is p to 300 bytes, and yo ant to retrn jst the variable-length portion of 5 records. Btrieve Programmer s Reference 132 Btrieve Operations

133 Yo old se the descriptor element of the inpt bffer to set a Field Length of 300 and a Field Offset of 100. For the retrned bffer, yo need 2 bytes for the Nmber of Records pls 306 bytes for each record (that is, 2 bytes for the length, 4 bytes for the address, and 300 bytes for the data), as shon in the folloing calclation: 2 + ((2 bytes + 4 bytes bytes) * 5) = 1532 bytes Hoever, sppose that the variable-length portion of the first record retrned contains only 50 bytes of data. This means the 2-byte length for the second record retrned is stored at offset 58 in the Data Bffer, immediately folloing the image of the first record s field. In sch a sitation, yor application mst parse the length, position, and data from the Data Bffer that the MicroKernel retrns. Reslt If the Get Next Extended operation is sccessfl, the MicroKernel retrns the folloing: In the Data Bffer, one or more fields from one or more records. (See Table 2-13.) In the Data Bffer Length, the total nmber of bytes received. In the Key Bffer, the key vale for the last data record received. If the Get Next Extended operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 7 The key nmber has changed. 8 The crrent positioning is invalid. 9 The operation encontered the end-of-file. Btrieve Programmer s Reference 133 Btrieve Operations

134 22 The data bffer parameter is too short. 60 The specified reject cont has been reached. 61 The ork space is too small. 62 The descriptor is incorrect. 64 The filter limit has been reached. 65 The field offset is incorrect. 82 The MicroKernel lost positioning. 134 The MicroKernel cannot read the International Sorting Rle. 135 The specified International Sort Rle table is corrpt or otherise invalid. 136 The MicroKernel cannot find the specified Alternate Collating Seqence in the file. It is possible for the MicroKernel to retrn a nonzero stats code and also retrn valid data in the Data Bffer. In this case, the last record retrned may be incomplete. If the Data Bffer Length parameter retrned is greater than 0, check the Data Bffer for extracted data. If a field can only be partially filled becase the record is too short, then the MicroKernel retrns hat it can of the record to and inclding the partial field. If the partial field is the last field to be extracted, then the MicroKernel contines the operation. Otherise, the MicroKernel aborts the operation and retrns a Stats Code 22. For example, consider a Get Next Extended operation that retrieves 3 fields from 2 variable-length records. The first record is 55 bytes long and the second is 50 bytes long. The 3 fields to be retrieved are defined as follos: Field 1 begins at offset 2 and is 2 bytes long. Field 2 begins at offset 45 and is 10 bytes long. Field 3 begins at offset 6 and is 2 bytes long. Btrieve Programmer s Reference 134 Btrieve Operations

135 When the MicroKernel performs the Get Next Extended operation, it retrns the first record ithot any problem. Hoever, hen attempting to extract field 2 s 10 bytes from the second record, the MicroKernel finds that only 5 bytes are available (beteen offset 45 and the end of the record, at offset 49). At this point, the MicroKernel does not pad the missing 5 bytes of field 2, and ths cannot extract field 3. Instead, the MicroKernel retrns Stats Code 22 and places all of field 1 and the first 5 bytes of field 2 in the retrn Data Bffer. Depending on the fields and the operators sed in the filtering condition, the MicroKernel may be able to optimize yor reqest. After reaching a certain rejected record, it retrns Stats Code 64, indicating that no records can satisfy the filtering conditions in the rest of the file. Positioning The Get Next Extended operation establishes the complete logical and physical crrencies. The last record examined becomes the crrent record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected. Note The MicroKernel does not allo Delete or Update operations after a Get Next Extended operation. Becase the crrent record is the last record examined, there is no ay to ensre that yor application old delete or pdate the intended record. Btrieve Programmer s Reference 135 Btrieve Operations

136 Get Position (22) The Get Position operation retrns the physical 4-byte position of the crrent record. Get Position fails if there is no established physical crrency hen yo isse the operation. Once yo determine a record s position (address), yo can se the Get Direct/Record operation (23) to retrieve that record directly by its physical location in the file. The MicroKernel does not perform any disk I/O to process a Get Position reqest. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X Retrned X X X Prereqisites The file mst be open. Yor application mst have established physical crrency. Procedre 1. Set the Operation Code to Pass the Position Block for the file. 3. Set the Data Bffer Length to at least 4 bytes. 4. Set the Key Nmber to 0. Btrieve Programmer s Reference 136 Btrieve Operations

137 Reslt If the Get Position operation is sccessfl, the MicroKernel retrns the position of the record in the Data Bffer. The position is a 4-byte binary vale (most significant ord first) that indicates the record s offset (in bytes) into the file. The MicroKernel also sets the Data Bffer Length to 4 bytes. If the Get Position operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 8 The crrent positioning is invalid. Positioning The Get Position operation has no effect on positioning. Btrieve Programmer s Reference 137 Btrieve Operations

138 Get Previos (7) The Get Previos operation retrieves the record in the logical previos position based on a specified key. Yo can se the Get Previos operation to retrieve a record ithin a grop of records that have dplicate key vales. Yo can se the Get Key (+50) bias to detect the presence of a vale in a file. A Get Key operation is generally faster. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Yor application mst have established a logical previos position based on the specified key. Procedre 1. Set the Operation Code to 7. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. Btrieve Programmer s Reference 138 Btrieve Operations

139 For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record yo ant to retrieve. 4. Specify the key vale from the previos operation in the Key Bffer. Pass the Key Bffer exactly as the MicroKernel retrned it on the previos call. The MicroKernel may need the information previosly stored in the Key Bffer to determine its crrent position in the file. 5. Set the Key Nmber parameter to the key path sed on the previos call. Yo cannot change key paths sing a Get Previos operation. Reslt If the Get Previos operation is sccessfl, the MicroKernel pdates the Key Bffer ith the key vale for the previos record, retrns the previos record in the Data Bffer, and retrns the length of the record in the Data Bffer Length parameter. If the Get Previos operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 6 The key nmber parameter is invalid. 7 The key nmber has changed. 8 The crrent positioning is invalid. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. 82 The MicroKernel lost positioning. Btrieve Programmer s Reference 139 Btrieve Operations

140 This operation retrns Stats Code 9 if the logical previos position points beyond the beginning of the file. Positioning The Get Previos operation establishes the complete logical and physical crrencies and makes the retrieved record the crrent one. Btrieve Programmer s Reference 140 Btrieve Operations

141 Get Previos Extended (37) The Get Previos Extended operation examines one or more records, starting at the logical previos position and proceeding toard the beginning of the file, based on the specified key. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Get Previos Extended can also extract specified portions of records and retrn only those portions to an application. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X X Retrned X X X X Prereqisites The file mst be open. The file cannot be a data-only file. Yo mst have an established logical previos position based on the specified key. Btrieve Programmer s Reference 141 Btrieve Operations

142 Procedre 1. Set the Operation Code to 37. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Specify a large enogh Data Bffer to accommodate either the inpt Data Bffer or the retrned Data Bffer, hichever is larger. Initialize the Data Bffer according to the strctre shon in Table Specify the Data Bffer Length as either the length of the inpt strctre (Table 2-12) or the length of the retrned strctre (Table 2-13), hichever is larger. The MicroKernel sets p a bffer as a orkspace for extended operations. Yo configre the size of this bffer sing the Extended Operation Bffer Size option. The sm of the Data Bffer strctre, pls the longest record to be retrieved, pls 355 bytes of reqester overhead, cannot exceed the configred bffer size. (Reqester overhead is not applicable in DOS orkstation engines.) 5. Specify the key vale from the previos operation in the Key Bffer. Pass the Key Bffer exactly as the MicroKernel retrned it on the previos call, becase the MicroKernel may need the information previosly stored there to determine its crrent position in the file. 6. Set the Key Nmber parameter to the key path sed on the previos call. Yo cannot change key paths sing a Get Previos Extended operation. Btrieve Programmer s Reference 142 Btrieve Operations

143 Details This operation ses the same inpt and retrned Data Bffers as the Get Next Extended operation. Refer to Details for more information. Reslt This operation retrns the same reslts as the Get Next Extended operation. Refer to Reslt for more information. Positioning The Get Previos Extended operation establishes the complete logical and physical crrencies. The last record examined becomes the crrent record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected. Note The MicroKernel does not allo Delete or Update operations after a Get Previos Extended operation. Becase the crrent record is the last record examined, there is no ay to ensre that yor application old delete or pdate the intended record. Btrieve Programmer s Reference 143 Btrieve Operations

144 Insert (2) The Insert operation inserts a record into a file. The MicroKernel adjsts the B-trees for the keys to reflect the key vales for the ne record. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X Prereqisites The file mst be open. The record to be inserted mst be the proper length, and the key vales mst conform to the keys defined for the file. Procedre 1. Set the Operation Code to Pass the Position Block for the file. 3. In the Data Bffer, store the record to be inserted. 4. Specify the Data Bffer Length. This vale mst be at least as long as the fixedlength portion of the record. 5. Specify the Key Nmber that the MicroKernel ses to establish positioning information (crrency). To se the NCC option, specify 1 (0xFF) for the Key Nmber. To se the system-defined log key (also called system data), specify 125. Btrieve Programmer s Reference 144 Btrieve Operations

145 Note When sing the no-crrency-change (NCC) option, the Insert operation does not pdate the vale of the Key Bffer parameter; it does not retrn any information in that parameter. Reslt If the Insert operation is sccessfl, the MicroKernel places the ne record in the file, pdates the B-trees for the keys to reflect the ne record, and retrns the vale of the specified key in the Key Bffer. If yo insert a record that contains an AUTOINCREMENT key vale initialized to binary 0, the MicroKernel also retrns the inserted record in the Data Bffer, inclding the AUTOINCREMENT vale assigned by the MicroKernel. An NCC Insert operation does not change the vale of the Key Bffer parameter. If the Insert operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 2 The application encontered an I/O error. 3 The file is not open. 5 The record has a key field containing a dplicate key vale. 18 The disk is fll. 21 The key bffer parameter is too short. 22 The data bffer parameter is too short. Btrieve Programmer s Reference 145 Btrieve Operations

146 Positioning An Insert operation that does not specify the NCC option establishes the complete logical and physical crrencies and makes the inserted record the crrent one. The logical crrency is based on the specified key. An NCC Insert operation establishes physical crrency ithot affecting logical crrency. This means that an application, having performed an NCC Insert operation, has the same logical position in the file as it had prior to the Insert operation. In sch a sitation, operations that follo an NCC Insert sch as Get Next (6), Get Next Extended (36), Get Previos (7), and Get Previos Extended (37) retrn vales based on the application s logical crrency prior to the NCC Insert. Note The MicroKernel does not retrn any information in the Key Bffer parameter as the reslt of an NCC Insert operation. Therefore, an application that mst maintain the logical crrency mst not change the vale of the Key Bffer folloing the NCC Insert operation. Otherise, the next Get operation has npredictable reslts. The MicroKernel establishes the physical crrency to a nely inserted record for both the standard Insert and the NCC Insert operations. Operations folloing an NCC Insert operation sch as Step Next (24), Step Next Extended (38), Step Previos (35), Step Previos Extended (39), Update (3), Delete (4), and Get Position (22) operate based on the ne physical crrency. Btrieve Programmer s Reference 146 Btrieve Operations

147 Insert Extended (40) The Insert Extended operation inserts one or more records into a file. The MicroKernel adjsts the B-trees for the keys to reflect the key vales for the ne records. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Note When sing the no-crrency-change (NCC) option, the Insert Extended operation does not pdate the vale of the Key Bffer parameter; it does not retrn any information in that parameter. Key Nmber Sent X X X X X Retrned X X X Prereqisites The file mst be open. The records to be inserted mst be the proper length, and the key vales mst conform to the keys defined for the file. Procedre 1. Set the Operation Code to Pass the Position Block for the file. 3. Specify the Data Bffer according to the strctre shon in Table Btrieve Programmer s Reference 147 Btrieve Operations

148 Details 4. Specify the Data Bffer Length. This vale mst be exactly the size of the Data Bffer strctre. 5. Specify the Key Nmber that the MicroKernel ses to establish crrency. To se the NCC option, specify 1 (0xFF) for the Key Nmber. To se the systemdefined log key (also called system data), specify 125. The folloing table shos the data bffer strctre. Table 2-14 Data Bffer Strctre for the Insert Extended Operation Element Length (in Bytes) Description Fixed portion 2 Nmber of records inserted. Repeating portion (one for each record) 2 Length of the record image. n Record image. Reslt If the Insert Extended operation is sccessfl, the MicroKernel places the ne records in the file, pdates all the B-trees to reflect the ne records that ere inserted, and (except for NCC Insert Extended operation) retrns in the Key Bffer the vale of the specified key from the last record inserted. In addition, in the first ord of the retrned Data Bffer, the MicroKernel places the nmber of records that ere sccessflly inserted into the file. Folloing the first ord of the Data Bffer, the MicroKernel stores the addresses of the inserted records. If the operation is only partially sccessfl and the MicroKernel retrns a nonzero stats code, the first ord of the Data Bffer eqals the nmber of records that ere Btrieve Programmer s Reference 148 Btrieve Operations

149 sccessflly inserted. The record that cased the error is the nmber of records that ere sccessflly inserted pls one. If the Insert Extended operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 2 The application encontered an I/O error. 3 The file is not open. 5 The record has a key field containing a dplicate key vale. 18 The disk is fll. 21 The key bffer parameter is too short. 22 The data bffer parameter is too short. Positioning An Insert Extended operation that does not specify the NCC option establishes the complete logical and physical crrencies and makes the last inserted record the crrent one (nless the inserted record s key vale is nll). The logical crrency is based on the specified key. An NCC Insert Extended operation establishes physical crrency ithot affecting logical crrency. This means that an application, having performed an NCC Insert Extended operation, has the same logical position in the file as it had prior to the operation. In sch a sitation, operations that follo an NCC Insert Extended operation sch as Get Next (6), Get Next Extended (36), Get Previos (7), and Get Previos Extended (37) retrn vales based on the application s logical crrency prior to the NCC Insert Extended operation. Btrieve Programmer s Reference 149 Btrieve Operations

150 Note The MicroKernel does not retrn any information in the Key Bffer parameter as the reslt of an NCC Insert Extended operation. Therefore, an application that mst maintain the logical crrency mst not change the vale of the Key Bffer folloing the NCC Insert Extended operation. Otherise, the next Get operation has npredictable reslts. The MicroKernel establishes the physical crrency to a nely inserted record for both the standard Insert Extended and the NCC Insert Extended operations. Therefore, operations folloing an NCC Insert Extended operation sch as Step Next (24), Step Next Extended (38), Step Previos (35), Step Previos Extended (39), Update (3), Delete (4), and Get Position (22) operate based on the ne physical crrency. An NCC Insert Extended operation is sefl hen an application mst save its logical position in the file prior to execting the Insert Extended operation in order to perform another operation based on the original logical crrency, sch as a Get Next operation (6). To achieve this effect ithot an NCC Insert Extended operation, yor application old have to execte the folloing steps: 1. Get Position (22) Obtains the 4-byte physical address for the logical crrent record. The application saves this vale and passes it back in Step Insert Extended (40) Inserts the ne records. This operation establishes ne logical and physical crrencies. 3. Get Direct/Record (23) Re-establishes logical and physical crrencies as they ere in Step 1. The NCC Insert Extended operation has the same effect in terms of logical crrency, bt can have a different effect in terms of physical crrency. For example, execting a Get Btrieve Programmer s Reference 150 Btrieve Operations

151 Next (6) operation after either procedre prodces the same reslt, bt execting a Step Next (24) might retrn different records. Btrieve Programmer s Reference 151 Btrieve Operations

152 Open (0) The Open operation makes a file available for access. To access a file, yor application mst first perform an Open operation. The file does not have to reside in the crrent directory as long as yo specify the fll or relative pathname. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X Prereqisites The file to be opened mst exist on an accessible logical disk drive. A file handle mst be available for the file. Procedre 1. Set the Operation Code to If the file has an oner, specify the oner name, terminated by a binary 0, in the Data Bffer parameter. 3. Specify the length of the oner name, inclding the binary 0, in the Data Bffer Length parameter. 4. Place the pathname of the file to open in the Key Bffer parameter. Terminate the pathname ith a blank or binary zero. The pathname can be p to 80 characters long, inclding the volme name and the terminator. Btrieve Programmer s Reference 152 Btrieve Operations

153 For more information abot path names Btrieve spports, refer to Getting Started. Note For yor application to be compatible ith Scalable SQL, limit the pathname to 64 characters. 5. In the Key Nmber parameter, specify one (or more) of the mode vales listed in Table Details In the Key Nmber parameter, yo can add a -32 or -64 bias to the open mode vales 0 throgh 4 to combine standard open modes ith file sharing modes. For example 2 pls 64 ( 66) tells the MicroKernel to open the file in Read-Only mode ith MEFS enabled on that file. Table 2-15 Open Modes Mode Description 0 Normal Btrieve Programmer s Reference 153 Btrieve Operations

154 Table 2-15 Open Modes contined Mode Description 1 Accelerated To improve performance on specific files, yo can open a file in Accelerated mode. (The 6.x MicroKernel accepted Accelerated mode opens, bt interpreted them as Normal opens.) When yo open a file in Accelerated mode, the MicroKernel does not perform transaction logging on the file. If yo open a file in Accelerated mode ith mlti-engine file sharing (MEFS), local clients can access the file only if they also open it in Accelerated mode and ith MEFS. No remote clients can access the file. If yo open a file in Accelerated mode ith single engine file sharing (SEFS), local clients can open the same file in SEFS mode combined ith any open mode except Exclsive. For more information abot MEFS and SEFS, refer to the Btrieve Programmer s Gide. NetWare developers: Opening a file in Accelerated mode cancels the effect of flagging a file as transactional. (On other platforms, the MicroKernel ignores the file s NetWare TTS flag.) 2 Read-Only When yo open a file in Read-Only mode, yo can only read the file; yo cannot perform pdates. This mode allos yo to open a file ith corrpt data that the MicroKernel cannot atomatically recover. If the data in the file s indexes has been corrpted, yo can retrieve the records by opening the file in Read-Only mode and then sing the Step Next (24) operation. 3 Verify This mode is ignored. If yo specify this mode, the MicroKernel opens the file in Normal mode. In previos versions of the MicroKernel, Verify mode verified that the data ritten to disk as correct. Btrieve Programmer s Reference 154 Btrieve Operations

155 Table 2-15 Open Modes contined Mode Description 4 Exclsive Exclsive mode gives an application exclsive access to a file. No other application can open that file ntil the application that has exclsive access to the file closes it. 32 Single Engine File Sharing Bias Use this open mode bias hen yo ant to open a file in SEFS mode and the defalt file sharing mode for the drive is MEFS. Note: This bias orks only if the MicroKernel s Enable Sharing Bias configration option is trned on. If the Enable Sharing Bias option is trned off, this bias has no effect. 64 Mlti-Engine File Sharing Bias Use this open mode bias hen yo ant to open a file in MEFS mode and the defalt file sharing mode for the drive is SEFS. Note: This bias orks only if the MicroKernel s Enable Sharing Bias configration option is trned on. If the Enable Sharing Bias option is trned off, this bias has no effect. For server MicroKernels, this mode maps to SEFS mode. The MicroKernel allos a maximm of 250 open files, bt yo might be nable to open that many files de to limitations on system resorces. A file is opened only once by the MicroKernel. (The MicroKernel recognizes and handles the sitation in hich more than one client at a time opens a file, or a single client has more than one Position Block in the file.) When yo open an extended file, the MicroKernel ses a single handle, and opens the base file and all extension files. Btrieve Programmer s Reference 155 Btrieve Operations

156 Note When the NetWare server MicroKernel opens an extended file, it enforces NetWare secrity on the base file, bt not on the extension files. In the rare event that a ser has NetWare rights to a base file, bt not the extension files, NetWare secrity can be violated. For orkstation engines, NetWare does enforce secrity; therefore, sch a ser old not have access to the extension files. Reslt If the Open operation is sccessfl, the MicroKernel assigns a file handle to the file, reserves the Position Block passed on the Open call for the nely opened file, and makes the file available for access. If the Open operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 2 The application encontered an I/O error. 11 The specified filename is invalid. 12 The MicroKernel cannot find the specified file. 20 The MicroKernel or Btrieve Reqester is inactive. 46 Access to the reqested file is denied. 84 The record or page is locked. 85 The file is locked. 86 The file table is fll. 87 The handle table is fll. 88 The application encontered an incompatible mode error. Btrieve Programmer s Reference 156 Btrieve Operations

157 The folloing tables sho the possible combinations for open modes involving local clients sing SEFS, local clients sing MEFS, and remote clients (implicitly sing MEFS). Table 2-16 shos open modes involving local clients sing SEFS. Table 2-16 Open Mode Combinations for Local Clients Using SEFS Open Mode for Local Client 1 Open Mode for Local Client 2 Reslt Normal Normal Sccessfl Read-Only Sccessfl Exclsive Stats Code 88 Accelerated Sccessfl Read-Only Normal Sccessfl Read-Only Sccessfl Exclsive Stats Code 88 Accelerated Sccessfl Exclsive Normal Stats Code 88 Read-Only Stats Code 88 Exclsive Stats Code 88 Accelerated Stats Code 88 Accelerated Normal Sccessfl Read-Only Sccessfl Exclsive Stats Code 88 Accelerated Sccessfl Btrieve Programmer s Reference 157 Btrieve Operations

158 Table 2-17 shos open modes involving local clients sing MEFS. Table 2-17 Open Mode for Local Client 1 Open Mode Combinations for Local Clients Using MEFS Open Mode for Local Client 2 Reslt Normal Normal Sccessfl Read-Only Sccessfl Exclsive Stats Code 88 Accelerated Stats Code 88 Read-Only Normal Sccessfl Read-Only Sccessfl Exclsive Stats Code 88 Accelerated Stats Code 88 Exclsive Normal Stats Code 88 Read-Only Stats Code 88 Exclsive Stats Code 88 Accelerated Stats Code 88 Accelerated Normal Stats Code 88 Read-Only Stats Code 88 Exclsive Stats Code 88 Accelerated Sccessfl Btrieve Programmer s Reference 158 Btrieve Operations

159 Table 2-18 shos open modes involving remote clients, hich implies the se of mltiengine file sharing. Table 2-18 Open Mode for Remote Client 1 Open Mode Combinations for Remote Clients Open Mode for Remote Client 2 Reslt Normal Normal Sccessfl Read-Only Sccessfl Exclsive Stats Code 88 Accelerated Stats Code 88 Read-Only Normal Sccessfl Read-Only Sccessfl Exclsive Stats Code 88 Accelerated Stats Code 88 Exclsive Normal Stats Code 88 Read-Only Stats Code 88 Exclsive Stats Code 88 Accelerated Stats Code 88 Accelerated Normal Stats Code 88 Read-Only Stats Code 88 Exclsive Stats Code 88 Accelerated Stats Code 88 Positioning Btrieve Programmer s Reference 159 Btrieve Operations

160 An Open operation does not establish any positioning except that the physical next record becomes the first physical record of the file. Btrieve Programmer s Reference 160 Btrieve Operations

161 Reset (28) The Reset operation releases all resorces held by a client. This operation aborts any transactions the client has pending, releases all locks, and closes all open files for the client. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X Retrned Prereqisites Yor application can isse a Reset operation at any time after the MicroKernel or Reqester is loaded, as long as the client issing the Reset call has established a connection ith the MicroKernel for example, by opening a file or by reqesting the stats of a file sing a Btrieve tility. Procedre 1. Set the Operation Code to Set the Key Nmber and Key Bffer to 0. Btrieve Programmer s Reference 161 Btrieve Operations

162 Reslt If the Reset operation is sccessfl, the MicroKernel performs the folloing actions for the specified client, indo, or session: 1. Aborts any active transactions. 2. Releases all locks held. 3. Closes all open files. If the Reset operation is nsccessfl, the MicroKernel retrns a nonzero stats code. Positioning The Reset operation destroys all crrencies becase it closes any open files. Btrieve Programmer s Reference 162 Btrieve Operations

163 Set Directory (17) The Set Directory operation sets the crrent directory to a specified pathname. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Sent X X Retrned Key Nmber Prereqisites The target logical disk drive and directory mst be accessible. Procedre 1. Set the Operation Code to Store the logical disk drive and directory path, terminated by a binary 0, in the Key Bffer. If yo omit the drive name, the MicroKernel ses the defalt drive. If yo do not specify the complete path for the directory, the MicroKernel appends the directory path specified in the Key Bffer to the crrent directory. For more information abot path names Btrieve spports, refer to Getting Started. Reslt If the Set Directory operation is sccessfl, the MicroKernel makes the directory specified in the Key Bffer the crrent directory. Btrieve Programmer s Reference 163 Btrieve Operations

164 If the Set Directory operation is nsccessfl, the MicroKernel leaves the crrent directory nchanged and retrns a nonzero stats code. Positioning The Set Directory operation has no effect on positioning. Btrieve Programmer s Reference 164 Btrieve Operations

165 Set Oner (29) The Set Oner operation assigns an oner name to a file, so that sers ho do not provide the name cannot access or modify the file. If an oner name has been set for a file, sers or applications mst specify the oner name each time they open the file. Yo can specify that an oner name be reqired for any access or jst for pdate privileges. When yo assign an oner name, yo can also direct the MicroKernel to encrypt the file s data on the disk. If yo specify data encryption, the MicroKernel encrypts all the data dring the Set Oner operation. Therefore, the longer the file, the longer Set Oner takes to complete. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X X Retrned X Prereqisites The file mst be open. No transactions can be active. The file cannot already have an oner name. Procedre 1. Set the Operation Code to Pass the Position Block that identifies the file to protect. Btrieve Programmer s Reference 165 Btrieve Operations

166 3. Store the oner name in both the Data Bffer and the Key Bffer. The MicroKernel reqires that the name be in both bffers to avoid accidentally specifying an incorrect vale. The oner name can be p to eight characters long and mst end ith a binary Specify the Data Bffer Length. 5. Set the Key Nmber to an integer that specifies the type of access restrictions and encryption for the file. (See Table 2-19.) Details Once yo specify an oner name, it remains in effect ntil yo isse a Clear Oner operation. The folloing table lists the access restriction codes yo can specify for the Key Nmber. Table 2-19 Access and Encryption Codes Code Description 0 Reqires an oner name for any access mode (no data encryption). 1 Permits read-only access ithot an oner name (no data encryption). 2 Reqires an oner name for any access mode (ith data encryption). 3 Permits read-only access ithot an oner name (ith data encryption). Reslt If the Set Oner operation is sccessfl, the MicroKernel prevents ftre operations from accessing or modifying the file nless those operations specify the correct oner name. The only exception is if read-only access is alloed ithot an oner name. In addition, Btrieve Programmer s Reference 166 Btrieve Operations

167 if the Set Oner operation is sccessfl, the MicroKernel encrypts the data in the file (if encryption is specified). Encryption occrs immediately; the MicroKernel has control ntil the entire file is encrypted, and the larger the file, the longer the encryption process takes. Reading data from an encrypted file is sloer than reading data from an nencrypted file. The MicroKernel decrypts a page hen it loads the page from the disk, then encrypts the page hen it rites to the disk again. If yo have a small cache or se a relatively large amont of modification operations, the MicroKernel mst execte the encryption rotine more freqently. To enhance performance, the MicroKernel performs logical operations (sch as SHIFT and XOR) on the bytes of the page sing the encrypted oner name as a key. If the Set Oner operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 41 The MicroKernel does not allo the attempted operation. 50 The file oner is already set. 51 The oner name is invalid. Positioning The Set Oner operation has no effect on positioning. Btrieve Programmer s Reference 167 Btrieve Operations

168 Stat (15) The Stat operation retrieves the defined characteristics of a file and statistics abot the file s contents, sch as the nmber of records in the file, the nmber of niqe key vales stored for each index in the file, and the nmber of nsed pages in the file. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X X Retrned X X X Prereqisites The file mst be open. Procedre 1. Set the Operation Code to Pass the Position Block for the file. 3. Indicate a Data Bffer to hold the statistics defined for the file. 4. Specify the Data Bffer Length, hich mst be long enogh to hold the file statistics. (For more information, see Table 2-20 and Table 2-21.) 5. Specify a Key Bffer that is at least 255 characters long. Btrieve Programmer s Reference 168 Btrieve Operations

169 6. Set the Key Nmber as follos: Specify 0 to exclde file version and nsed dplicate pointers information. Parse the retrned Data Bffer as shon in Table Specify 1 (0xFF) to inclde file version and nsed dplicate pointers information. Parse the retrned Data Bffer as shon in Table Details The MicroKernel retrns information abot all keys in the file, inclding those added since file creation. The key information incldes any applicable ACS definitions. Yo mst accont for this extra information in the Data Bffer. Specifically, do not se the same Data Bffer here that yo sed for the Create (0) operation. Becase the MicroKernel allos p to 119 keys and mltiple ACSs in a file, the longest possible Data Bffer is 33,455 bytes (that is, 16 + (11 * 16) + (119 * 265)). Hoever, yo probably do not need sch a large data bffer. In fact, yo may prefer to specify a smaller Data Bffer if yo ant only certain information. For example, yo cold set the Data Bffer Length to 1920 bytes (that is, 16 + (16 * 119)). In effect, sch a setting retrns all key information bt not necessarily all the ACSs. If yor application does not need information abot the ACSs, yo might prefer this method. Btrieve Programmer s Reference 169 Btrieve Operations

170 If yo specify a vale of 0 in the Key Nmber parameter, the MicroKernel retrns Stat information as shon in the folloing table. Table 2-20 Data Bffer Exclding File Version Information Element Description Length (in Bytes) File Specification Record Length 2 Page Size 2 Key Specification (repeated for each segment) Nmber of Indexes 2 Nmber of Records 4 File Flags 2 Reserved Word 2 Unsed Pages 2 Key Position 2 Key Length 2 Key Flags 2 Nmber of Uniqe Key Vales 4 Extended Data Type 1 Nll Vale 1 Reserved 2 Key Nmber 1 ACS Nmber 1 Btrieve Programmer s Reference 170 Btrieve Operations

171 Table 2-20 Element Data Bffer Exclding File Version Information contined Description Length (in Bytes) ACS Nmber 0 ACS ACS Nmber x ACS 265 If yo specify a vale of 1 in the Key Nmber parameter, the MicroKernel retrns Stat information as shon in the folloing table. Table 2-21 Data Bffer Inclding File Version Information Length (in Element Description Bytes) File Specification Record Length 2 Page Size 2 Nmber of Indexes 1 File Version Nmber 1 Nmber of Records 4 File Flags 2 Nmber of Unsed Dplicate Pointers 1 Reserved Byte 1 Unsed Pages 2 Btrieve Programmer s Reference 171 Btrieve Operations

172 Table 2-21 Element Key Specifications (repeated for each key segment) Data Bffer Inclding File Version Information contined Description Length (in Bytes) Key Position 2 Key Length 2 Key Flags 2 Nmber of Uniqe Key Vales 4 Extended Data Type 1 Nll Vale 1 Reserved 2 Key Nmber 1 ACS Nmber 1 ACS Nmber 0 ACS ACS Nmber x ACS 265 File Specifications The File Specification fields in the retrned Data Bffer are the same as those described for Create (14), ith the folloing exceptions: In the File Specification area: If the Data Bffer incldes file version information, the Nmber of Indexes is 1 byte long and is folloed by a 1-byte File Version Nmber. Do not translate the File Version Nmber vale to decimal. A vale of 0x70 indicates that the file is a 7.0 file; a vale of 0x60 indicates that the file is 6.x, and so on. When creating a file, the MicroKernel assigns a version nmber according to the attribtes defined for the file. Btrieve Programmer s Reference 172 Btrieve Operations

173 The Nmber of Records is a 4-byte vale representing the nmber of records in the file. In the File Flags ord, Bits 9 and 12 have the folloing meaning: Bit 9 = 1 and Bit 12 = 0 Bit 9 = 1 and Bit 12 = 1 File as created ith system data. (This does not necessarily mean that the system-defined log key is crrently in se; it may have been dropped.) File as created ithot system data. Stat does not indicate hether system data as inclded by defalt or explicitly. If the Data Bffer incldes file version information, a 1-byte Nmber of Unsed Dplicate Pointers follos the File Flags field and indicates ho many nsed dplicate pointers remain in the file. The reserved areas are allocated even thogh the MicroKernel ignores them on a Stat operation. Key Specifications The Key Specification fields in the retrned Data Bffer are the same as those described for Create (14), except that a 4-byte Nmber of Uniqe Key Vales follos the Key Flags field and indicates the nmber of records that have a niqe, non-dplicated vale for the specified key. ACSs The ACS definitions in the retrned Data Bffer are the same as those described for Create (14). Btrieve Programmer s Reference 173 Btrieve Operations

174 Reslt If the Stat operation is sccessfl, the MicroKernel retrns the file and key characteristics to the Data Bffer and the length of the Data Bffer in the Data Bffer Length. If the file is an extended file, the MicroKernel retrns the filename of the first extension file in the Key Bffer. If the filename of the first extension file is longer than 63 bytes, the MicroKernel trncates the filename. If the file is not an extended file, the MicroKernel initializes the first byte of the Key Bffer to 0. (Yo can se the Stat Extended operation to retrieve statistics regarding extended files.) If the Stat operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 22 The data bffer parameter is too short. Positioning The Stat operation has no effect on positioning. Btrieve Programmer s Reference 174 Btrieve Operations

175 Stat Extended (65) The Stat Extended operation has to sbfnctions. One sbfnction retrns the filenames and paths of an extended file s components: the base file and extension files. The other sbfnction reports hether a file is sing a system-defined log key, and by implication, hether the file is transaction drable. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X Prereqisites The file mst be open. Procedre 1. Set the Operation Code to Pass the Position Block for the file. 3. Store the extended stat strctre in the Data Bffer. See the Details section for more information abot the extended stat strctre. 4. Specify the Data Bffer Length. 5. Set the Key Nmber to 0. Btrieve Programmer s Reference 175 Btrieve Operations

176 Details To receive information abot an extended file s components, yo mst create an extended files descriptor in the Data Bffer, as follos. Table 2-22 Extended Files Descriptor Element Length (in Bytes) Description Signatre 4 Type of extended stat call. Specify 0x (This is eqivalent to ASCII ExSt.) Sbfnction 4 Type of extended stat call. Specify 0x Namespace 4 File naming convention. Specify 0x Max Files 4 Maximm nmber of filenames to retrn. Yo can set this vale higher than the nmber of extension files composing the extended file. (An extended file can contain p to 32 extension files.) First File Seqence 4 Seqence nmber of the first filename to retrn. Specify 0 to begin ith the base file, 1 to begin ith the first extension file, and so on. If yo specify a nmber higher than the nmber of extension files, the MicroKernel retrns Stats Code 0 and no filenames. To receive information abot a file s se of system data, yo mst create a system data descriptor in the Data Bffer, as follos. Table 2-23 Element System Data Descriptor Length (in Bytes) Description Signatre 4 Type of extended stat call. Specify 0x (This is eqivalent to ASCII ExSt.) Btrieve Programmer s Reference 176 Btrieve Operations

177 Table 2-23 System Data Descriptor Element Length (in Bytes) Description Sbfnction 4 Type of extended stat call. Specify 0x Reslt If the Stat Extended operation is sccessfl, the MicroKernel retrns the file s statistics in the Data Bffer and sets the Data Bffer Length parameter to the nmber of bytes retrned. For the extended files sbfnction, the MicroKernel retrns an extended files strctre in the Data Bffer, as follos. Table 2-24 Extended Files Retrn Bffer Element Length (in Bytes) Description Nmber of Files 4 Nmber of operating system files that comprise the extended file. Nmber of Extensions 4 Nmber of extension files retrned. Filename Portion (Repeated for each filename retrned) Length of Filename 4 Length of the extension filename. Filename n Extension filename. Btrieve Programmer s Reference 177 Btrieve Operations

178 For the system data sbfnction, the MicroKernel retrns a system data strctre in the Data Bffer, as follos. Table 2-25 System Data Retrn Bffer Element Length (in Bytes) Description Has System Data 1 Indicates hether the file s records contain a system-defined log key (also called system data). 1 = Yes and 0 = No. Has Log Key 1 Indicates hether the system-defined log key is crrently being sed, as opposed to being dropped. 1 = Yes and 0 = No. Is Loggable 1 Indicates hether the file has a niqe key that can be sed to implement transaction drability. This key can be either a serdefined niqe key or a system-defined log key. 1 = Yes and 0 = No. Log Key Nmber 1 Key nmber that the MicroKernel is crrently sing as the transaction log key. If the system-defined log key is being sed as the transaction log key, this vale is 125. Size of System Data 2 Size of the system-defined log key, hich is 8. System Data Version 2 The constant 700 (0x2BC). If the Stat Extended operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 06 The key nmber parameter is invalid. 22 The data bffer parameter is too short. 62 The descriptor is incorrect. Btrieve Programmer s Reference 178 Btrieve Operations

179 Step First (33) The Step First operation retrieves the first physical record of the file. The MicroKernel does not se a key path to retrieve the record. Parameters Operation Code Position Block Data Bffer Data Bffer Length Sent X X X Retrned X X X Key Bffer Key Nmber Prereqisites The file mst be open. Procedre 1. Set the Operation Code to 33. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record to retrieve. Btrieve Programmer s Reference 179 Btrieve Operations

180 Reslt If the Step First operation is sccessfl, the MicroKernel retrns the file s first physical record in the Data Bffer and sets the Data Bffer Length parameter to the nmber of bytes retrned. If the Step First operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. Positioning The Step First operation destroys logical crrency. Step First sets the physical crrency sing the retrieved record as the physical crrent record. The previos physical position points beyond the beginning of the file. Btrieve Programmer s Reference 180 Btrieve Operations

181 Step Last (34) The Step Last operation retrieves the last physical record of the file. The MicroKernel does not se a key path to retrieve the record. Parameters Operation Code Position Block Data Bffer Data Bffer Length Sent X X X Retrned X X X Key Bffer Key Nmber Prereqisites The file mst be open. Procedre 1. Set the Operation Code to 34. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record to retrieve. Btrieve Programmer s Reference 181 Btrieve Operations

182 Reslt If the Step Last operation is sccessfl, the MicroKernel retrns the file s last physical record in the Data Bffer and sets the Data Bffer Length parameter to the nmber of bytes retrned. If the Step Last operation is nsccessfl, the MicroKernel may retrn one of the folloing stats codes: 3 The file is not open. 9 The operation encontered the end-of-file. (hen the file is empty) 22 The data bffer parameter is too short. Positioning The Step Last operation destroys logical crrency. Step Last sets the physical crrency sing the retrieved record as the crrent physical record. The next physical position points beyond the end of the file. Btrieve Programmer s Reference 182 Btrieve Operations

183 Step Next (24) The Step Next operation retrieves the record to hich the next physical position points. The MicroKernel does not se a key path to retrieve the record. A Step Next operation issed immediately after any Get or Step operation retrns the record physically folloing the record retrieved by the previos operation. Parameters Operation Code Position Block Data Bffer Data Bffer Length Sent X X X Retrned X X X Key Bffer Key Nmber Prereqisites The file mst be open. Procedre 1. Set the Operation Code to 24. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record to retrieve. Btrieve Programmer s Reference 183 Btrieve Operations

184 Reslt If the Step Next operation is sccessfl, the MicroKernel retrns the file s next physical record in the Data Bffer and sets the Data Bffer Length parameter to the nmber of bytes retrned. If the Step Next operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. Positioning The Step Next operation does not establish logical crrency. Step Next sets the physical crrency sing the retrieved record as the physical crrent record. If a Step Next operation is issed immediately folloing a Delete operation (4), Step Next retrns the record that as established as the next physical record by the operation preceding the Delete. If a Step Next operation is issed immediately after an Open operation (0), Step Next retrns the first record in the file. Btrieve Programmer s Reference 184 Btrieve Operations

185 Step Next Extended (38) The Step Next Extended operation examines one or more records, starting at the next physical position and proceeding toard the end of the file. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Step Next Extended can also extract specified fields from existing records and retrn a ne set of records that contain only the extracted fields. Parameters Operation Code Position Block Data Bffer Data Bffer Length Sent X X X X Retrned X X X Key Bffer Key Nmber Prereqisites The file mst be open. Yo mst have established a next physical position. (For example, a Step Next Extended operation cannot follo a Delete operation.) Procedre 1. Set the Operation Code to 38. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. Btrieve Programmer s Reference 185 Btrieve Operations

186 For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Specify a Data Bffer large enogh to accommodate either the inpt data bffer or the retrned data bffer, hichever is larger. Initialize the Data Bffer according to the strctre shon in Table Specify the Data Bffer Length from the preceding step. The MicroKernel sets p a bffer as a orkspace for extended operations. Yo configre the size of this bffer sing the Extended Operation Bffer Size option. The sm of the Data Bffer strctre, pls the longest record to be retrieved, pls 355 bytes of reqester overhead, cannot exceed the configred bffer size. (Reqester overhead is not applicable in DOS orkstation engines.) Details The Step Next Extended operation shares the same Details as the Get Next Extended operation. Refer to Details for more information. Reslt If the Step Next Extended operation is sccessfl, the MicroKernel retrns one or more fields from one or more records to the Data Bffer (as shon in Table 2-13). The MicroKernel also sets the Data Bffer Length parameter to the nmber of bytes it retrned to the Data Bffer. If the Step Next Extended operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 9 The operation encontered the end-of-file. 22 The data bffer parameter is too short. Btrieve Programmer s Reference 186 Btrieve Operations

187 60 The specified reject cont has been reached. 61 The ork space is too small. 62 The descriptor is incorrect. 64 The filter limit has been reached. 65 The field offset is incorrect. 82 The MicroKernel lost positioning. 134 The MicroKernel cannot read the International Sorting Rle. 135 The specified International Sort Rle table is corrpt or otherise invalid. 136 The MicroKernel cannot find the specified Alternate Collating Seqence in the file. It is possible for the MicroKernel to retrn a nonzero stats code and also retrn valid data in the Data Bffer. In this case, the last record retrned may be incomplete. If the Data Bffer Length parameter retrned is greater than 0, check the Data Bffer for extracted data. If a field can only be partially filled becase the record is too short, then the MicroKernel retrns hat it can of the record to and inclding the partial field. If the partial field is the last field to be extracted, then the MicroKernel contines the operation. Otherise, the MicroKernel aborts the operation and retrns a Stats Code 22. For example, consider a Step Next Extended operation that retrieves three fields from to variable-length records. The first record is 55 bytes long, and the second is 50 bytes. The fields to be retrieved are defined as follos: Field 1 begins at offset 2 and is 2 bytes long. Field 2 begins at offset 45 and is 10 bytes long. Field 3 begins at offset 6 and is 2 bytes long. Btrieve Programmer s Reference 187 Btrieve Operations

188 When the MicroKernel performs the Step Next Extended operation, it retrns the first record ithot any problem. Hoever, hen attempting to extract 10 bytes from field 2 of the second record, the MicroKernel finds that only 5 bytes are available (beteen offset 45 and the end of the record, at offset 49). At this point, the MicroKernel does not pad the missing 5 bytes of field 2, and ths cannot extract field 3. Instead, the MicroKernel retrns Stats Code 22 and places all of field 1 and first 5 bytes of field 2 in the retrn Data Bffer. Positioning The Step Next Extended operation does not establish any logical crrency, bt the last record examined (not necessarily retrieved) becomes the crrent physical record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected. Note The MicroKernel does not allo Delete or Update operations after a Step Next Extended operation. Becase the crrent record is the last record examined, there is no ay to ensre that yor application old delete or pdate the intended record. Btrieve Programmer s Reference 188 Btrieve Operations

189 Step Previos (35) The Step Previos operation retrieves the record to hich the previos physical position points. The MicroKernel does not se an index path to retrieve a record for a Step Previos operation. A Step Previos operation performed immediately after any Get or Step operation retrns the record physically preceding the record that the previos operation retrieves. Parameters Operation Code Position Block Data Bffer Data Bffer Length Sent X X X Retrned X X X Key Bffer Key Nmber Prereqisites The file mst be open. Yo mst have an established previos physical position. (For example, a Step Previos cannot follo a Delete operation.) Procedre 1. Set the Operation Code to 35. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. Btrieve Programmer s Reference 189 Btrieve Operations

190 For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. 3. Set the Data Bffer Length to a vale greater than or eqal to the length of the record to retrieve. Reslt If the operation is sccessfl, the MicroKernel retrns the previos physical record in the Data Bffer and sets the Data Bffer Length parameter to the nmber of bytes retrned. If the operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 3 The file is not open. 9 The operation encontered the end-of-file. (at the beginning of the file) 22 The data bffer parameter is too short. Positioning The Step Previos operation does not establish logical crrency. Step Previos sets the physical crrency sing the retrieved record as the physical crrent record. Btrieve Programmer s Reference 190 Btrieve Operations

191 Step Previos Extended (39) The Step Previos Extended operation examines one or more records, starting at the previos physical position and proceeding toard the beginning of the file. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Step Previos Extended can also extract specified fields from existing records and retrn a ne set of records that contain only the extracted fields. Parameters Operation Code Position Block Data Bffer Data Bffer Length Sent X X X X Retrned X X X Key Bffer Key Nmber Prereqisites The file mst be open. Yo mst have established a previos physical position. (For example, a Step Previos Extended operation cannot follo a Delete operation.) Procedre 1. Set the Operation Code to 39. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file. Btrieve Programmer s Reference 191 Btrieve Operations

192 Details 3. Specify a Data Bffer large enogh to accommodate either the inpt data bffer or the retrned data bffer. Initialize the Data Bffer according to the strctre shon in Table Specify the Data Bffer Length from the preceding step. The MicroKernel sets p a bffer as a orkspace for extended operations. Yo configre the size of this bffer sing the Extended Operation Bffer Size option. The sm of the Data Bffer strctre, pls the longest record to be retrieved, pls 355 bytes of reqester overhead, cannot exceed the configred bffer size. (Reqester overhead is not applicable in DOS orkstation engines.) This operation ses the same inpt and retrned Data Bffers as the Get Next Extended operation. Refer to Details for more information. Reslt This operation retrns the same reslts as the Step Next Extended operation. Refer to Reslt for more information. Positioning The Step Previos Extended operation does not establish logical crrency, bt the last record examined (not necessarily retrieved) becomes the crrent physical record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected. Note The MicroKernel does not allo Delete or Update operations after a Step Previos Extended operation. Becase the crrent record is the last record examined, there is no ay to ensre that yor application old delete or pdate the intended record. Btrieve Programmer s Reference 192 Btrieve Operations

193 Stop (25) The Stop operation performs a nmber of termination rotines for the client, sch as releasing all locks and closing all open files associated ith that client. Note OS/2 developers: The Stop operation behaves the same as Reset (28). Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X Retrned Procedre Set the Operation Code to 25. Reslt If the Stop operation is sccessfl, the MicroKernel performs the folloing actions: 1. Aborts any active transactions. 2. Releases all locks held by the client. 3. Closes all files open for the client. 4. If no other clients (other applications registered ith the MicroKernel) exist and depending on the MicroKernel configration, the MicroKernel may terminate itself and free a nmber of resorces. Btrieve Programmer s Reference 193 Btrieve Operations

194 If the Stop operation is nsccessfl, the MicroKernel retrns a nonzero stats code. The most common nonzero Stats Code is 20 (Record Manager Inactive). This stats occrs becase the MicroKernel or the Reqester is not loaded. Positioning The Stop operation destroys all crrencies becase it closes any open files. Btrieve Programmer s Reference 194 Btrieve Operations

195 Unlock (27) The Unlock operation nlocks one or more records that have been locked explicitly (that is, the records ere locked sing a lock bias of +100, +200, +300, or +400). The Unlock operation releases locks held by the specified position block; therefore, if yo have the same file opened more than once, yo mst isse an Unlock for each position block before the record is completely nlocked. Similarly, each client that holds a lock on records in the file mst isse an Unlock before the record is completely nlocked. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned Prereqisites Yo mst have at least one record lock. Procedre To nlock a single-record lock, follo these steps: 1. Set the Operation Code to Pass the Position Block for the file that contains the locked record. 3. Set the Key Nmber to a non-negative vale. Btrieve Programmer s Reference 195 Btrieve Operations

196 To nlock a record locked by a mltiple-record lock, first retrieve the 4-byte position of the record to nlock by issing a Get Position operation (22) for that record. Then, isse the Unlock operation as follos: 1. Set the Operation Code to Pass the Position Block for the file that contains the locked record. 3. Store (in the Data Bffer) the 4-byte position that the MicroKernel retrns. 4. Set the Data Bffer Length to Set the Key Nmber parameter to 1. To nlock all the mltiple record locks on a file, follo these steps: 1. Set the Operation Code to Pass the Position Block for the file that contains the mltiple locks. 3. Set the Key Nmber parameter to 2. Reslt If the Unlock operation is sccessfl, the MicroKernel releases all the locks that the operation specified. If the Unlock operation is nsccessfl, the MicroKernel retrns a nonzero stats code most likely, Stats Code 81. Positioning The Unlock operation has no effect on positioning. Btrieve Programmer s Reference 196 Btrieve Operations

197 Update (3) The Update operation changes the information in an existing record. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Note When sing the no-crrency-change (NCC) option, the Update operation does not pdate the vale of the Key Bffer parameter; it does not retrn any information in that parameter. Key Nmber Sent X X X X X Retrned X X Prereqisites The file mst be open. Yo mst have established physical crrency in the file. (Althogh an Extended Get, Extended Step, or Get Key operation establishes the reqired position, these operations cannot be folloed by an Update.) In order to pdate a record hile inside a transaction, that record mst have been retrieved hile inside that transaction, and not before. Btrieve Programmer s Reference 197 Btrieve Operations

198 Procedre 1. Set the Operation Code to 3. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file containing the record. 3. Store the pdated data record in the Data Bffer. 4. Set the Data Bffer Length to the length of the pdated record. 5. Set the Key Nmber sed for retrieving the record. To se the NCC option, specify 1 (0xFF) for the Key Nmber. To se the system-defined log key (also called system data), specify 125. When performing a non-ncc Update operation immediately folloing a Get operation, pass the Key Nmber exactly as the MicroKernel retrned it on the Get operation; otherise, the MicroKernel pdates the record sccessflly bt retrns Stats Code 7 on the first Get operation performed after the pdate. Reslt If the Update operation is sccessfl, the MicroKernel pdates the record stored in the file ith the ne vale in the Data Bffer, adjsts the indexes to reflect any change in the key vales, and retrns the vale of the specified key in the Key Bffer. An NCC Update operation does not pdate the vale of the Key Bffer parameter. Btrieve Programmer s Reference 198 Btrieve Operations

199 If the application holds a single-record lock on the record to be pdated, the MicroKernel releases the lock. Hoever, a mltiple-record lock is never released by an Update operation. If the Update operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 5 The record has a key field containing a dplicate key vale. 8 The crrent positioning is invalid. 10 The key field is not modifiable. 22 The data bffer parameter is too short. 80 The MicroKernel encontered a record-level conflict. 83 The MicroKernel attempted to pdate or delete a record that as read otside the transaction. Positioning The Update operation and the NCC Update operation do not affect physical crrency. An Update operation that does not se the NCC option can affect logical crrency if the vale of the pdated key repositions the record in the index. For example, sppose an INTEGER key s logical crrent record has a vale of 1. For that same key, the logical next record has a vale of 2. If yo pdate 1 to 4, yo no longer have the same logical next record. In this example, after the Update operation, the logical next record has a vale that is greater than 4. An NCC Update operation does not affect logical crrency. This means that an application, having performed an NCC Update operation, has the same logical position in the file as it had prior to the Update operation. In sch a sitation, operations that follo Btrieve Programmer s Reference 199 Btrieve Operations

200 an NCC Update sch as Get Next (6), Get Next Extended (36), Get Previos (7), and Get Previos Extended (37) retrn vales based on the application s logical crrency prior to the NCC Update. Note The MicroKernel does not retrn any information in the Key Bffer parameter as the reslt of an NCC Update operation. Therefore, an application that mst maintain the logical crrency mst not change the vale of the Key Bffer folloing the NCC Update operation. Otherise, the next Get operation has npredictable reslts. Btrieve Programmer s Reference 200 Btrieve Operations

201 Update Chnk (53) The Update Chnk operation can change the information in one or more portions of a record (each portion being a chnk). It can also append information to an existing record (thereby lengthening the record), or trncate an existing record at a specified offset. Parameters Operation Code Position Block Data Bffer Data Bffer Length Key Bffer Key Nmber Sent X X X X X Retrned X X Prereqisites The file mst be open. Yo mst have an established crrent physical or logical record in the file. To pdate any chnk ithin a record hile inside a transaction, the record mst have been retrieved hile inside that transaction and not before. Note Althogh an extended operation or a Get Key operation (+50) establishes the reqired position, yo cannot isse an Update Chnk operation immediately after these operations, becase they do not retrn a single record. Btrieve Programmer s Reference 201 Btrieve Operations

202 Procedre 1. Set the Operation Code to 53. Optionally, yo can inclde a lock bias: 100 Single ait record lock. 200 Single no-ait record lock. 300 Mltiple ait record lock. 400 Mltiple no-ait record lock. For more information abot locking, refer to the Btrieve Programmer s Gide. 2. Pass the Position Block for the file containing the record. 3. Specify a Data Bffer, as described in Details. 4. Set the Data Bffer Length to a vale greater than or eqal to the nmber of bytes yor application has placed in the Data Bffer. See the Details section for more information abot calclating the Data Bffer Length. 5. Set the Key Nmber sed for retrieving the record in the Key Nmber parameter. To se the system-defined log key (also called system data), specify 125. Details Use one of the folloing chnk descriptors in the Data Bffer: Random Chnk Descriptor To pdate a single chnk per operation, or to pdate more than one chnk in a single operation hen the chnks are spaced randomly throghot the record. Rectangle Chnk Descriptor To pdate many chnks in an operation, hen each chnk is the same length and chnks are spaced eqidistantly in the record. Trncate Chnk Descriptor To trncate a record at a specified offset. Btrieve Programmer s Reference 202 Btrieve Operations

203 Random Chnk Descriptor Strctre The folloing example shos a record ith three randomly spaced chnks (shaded areas): chnk 0 (bytes 0x12 throgh 0x16), chnk 1 (bytes 0x2A throgh 0x31), and chnk 2 (bytes 0x41 throgh 0x4E) A 0B 0C 0D 0E 0F A 1B 1C 1D 1E 1F A 2B 2C 2D 2E 2F A 3B 3C 3D 3E 3F A 4B 4C 4D 4E 4F To define a random chnk descriptor, yor application mst create a strctre in the Data Bffer, based on the folloing table. Table 2-26 Random Chnk Descriptor Strctre Length (in Element Bytes) Description Sbfnction 4 Type of chnk descriptor; one of the folloing: 0x (Direct random chnk descriptor) Updates chnks stored directly in the Data Bffer. The data for pdating the first chnk is stored in the Data Bffer immediately after the last chnk definition (Chnk n), the data for the second chnk immediately follos the first, and so on. 0x (Indirect random chnk descriptor) Updates chnks from data at addresses specified by the Chnk Definitions. Btrieve Programmer s Reference 203 Btrieve Operations

204 Table 2-26 Random Chnk Descriptor Strctre Element NmChnks 4 Nmber of chnks to be pdated. The vale mst be at least 1. Althogh no explicit maximm vale exists, the chnk definitions mst fit in the Data Bffer, hich is limited in size as described in Table 2-9. Chnk Definition (Repeat for each chnk) Length (in Bytes) Description 12 Each Chnk Definition is a 4-byte Chnk Offset, folloed by a 4-byte Chnk Length, folloed by a 4-byte User Data, described as follos: Chnk Offset Indicates here the chnk begins as an offset in bytes from the beginning of the record. The minimm vale is 0, and the maximm vale is the offset of the last byte in the record, pls 1. Chnk Length Indicates ho many bytes are in the chnk. The minimm vale is 0, and the maximm vale 65,535; hoever, the chnk definitions mst fit in the Data Bffer, hich is limited in size as described in Table 2-9. User Data (Used only for indirect descriptors.) A 32-bit pointer to the actal chnk data. The format yo shold se depends on yor operating system. 1 The MicroKernel ignores this element for direct chnk descriptor sbfnctions. 1 For 16-bit applications, initialize User Data as a 16-bit offset and a 16-bit segment. User Data cannot address memory beyond the end of its segment. When Chnk Length is added to the offset portion of User Data, the reslt mst be ithin the segment that User Data defines. By defalt, the MicroKernel does not check for violations of this rle and does not properly handle sch violations. The folloing table shos a sample direct random chnk descriptor strctre. Element Sample Vale Length (in Bytes) Sbfnction 0x NmChnks 3 4 Btrieve Programmer s Reference 204 Btrieve Operations

205 Element Sample Vale Length (in Bytes) Chnk 0 Chnk Offset 0x12 4 Chnk Length 0x05 4 User Data N/A 4 Chnk 1 Chnk Offset 0x2A 4 Chnk Length 0x08 4 User Data N/A 4 Chnk 2 Chnk Offset 0x41 4 Chnk Length 0x0E 4 User Data N/A 4 Data for Chnk 0 N/A 5 Data for Chnk 1 N/A 8 Data for Chnk 2 N/A 14 Btrieve Programmer s Reference 205 Btrieve Operations

206 Rectangle Chnk Descriptor Strctre When chnks of the same length are spaced eqidistantly throghot a record, yo can describe all the chnks to pdate ith a rectangle chnk descriptor. For example, consider the folloing diagram, hich represents offset 0x00 throgh 0x4F in a record: A 0B 0C 0D 0E 0F A 1B 1C 1D 1E 1F A 2B 2C 2D 2E 2F A 3B 3C 3D 3E 3F A 4B 4C 4D 4E 4F The record contains three chnks (shaded areas): chnk 0 (bytes 0x19 throgh 0x1C), chnk 1 (bytes 0x29 throgh 0x2C), and chnk 2 (bytes 0x39 throgh 0x3C). Each chnk is for bytes long, and a total of 16 (0x10) bytes, calclated from the beginning of each chnk, separates the chnks from one another. Yo can pdate all three chnks sing a single rectangle descriptor. To pdate rectangle chnks, yo mst create a strctre in the Data Bffer based on Table Btrieve Programmer s Reference 206 Btrieve Operations

207 Table 2-27 Rectangle Chnk Descriptor Strctre Length Element (in Bytes) Description Sbfnction 4 Type of chnk descriptor; one of the folloing: 0x (Direct rectangle chnk descriptor) Updates chnks stored directly in the Data Bffer. The data for pdating the first chnk is stored in the Data Bffer immediately after the last chnk definition (Chnk n), the data for the second chnk immediately follos the first, and so on. 0x (Indirect rectangle chnk descriptor) Updates chnks from data at addresses specified by the Chnk Definitions. Nmber of Ros 4 Nmber of chnks on hich the rectangle chnk descriptor mst operate. The minimm vale is 1. No explicit maximm vale exists. Offset 4 Offset from the beginning of the record of the first byte to pdate. The minimm vale is 0, and the maximm vale is the offset of the last byte in the record, pls 1. If the record is vieed as a rectangle, this element refers to the offset of the first byte in the first ro to be retrieved. Bytes Per Ro 4 Nmber of bytes in each chnk to be pdated. The minimm vale is 0, and the maximm vale is 65,535; hoever, the chnk definitions mst fit in the Data Bffer, hich is limited in size as described in Table 2-9. Distance Beteen 4 Nmber of bytes beteen the beginning of each chnk. Ros User Data 4 (Used only ith indirect descriptors.) A 32-bit pointer to the actal chnk data. The format yo shold se depends on yor operating system. 1 The MicroKernel ignores this element for direct rectangle descriptors; hoever, yo mst still allocate the element and initialize it to 0. Btrieve Programmer s Reference 207 Btrieve Operations

208 Table 2-27 Element Application Distance Beteen Ros 4 (Used only ith indirect rectangle descriptors.) Nmber of bytes beteen the beginning of chnks in the rectangle, as the rectangle is stored in yor application s memory, at the address specified by User Data. The MicroKernel ignores this element for direct rectangle descriptors; hoever, yo mst still allocate the element and initialize it to 0. 1 For 16-bit applications, express User Data as a 16-bit offset folloed by a 16-bit segment. If the rectangle has the same nmber of bytes beteen ros hen it is in memory as hen it is stored as a record, set Application Distance Beteen Ros ith the same vale as Distance Beteen Ros. Hoever, if the rectangle is arranged in yor application s memory ith either more or feer bytes beteen ros, Application Distance Beteen Ros allos yo to pass that information to the MicroKernel. When yo se an indirect rectangle descriptor, the MicroKernel ses both the User Data and the Application Distance Beteen Ros elements to determine the locations from hich to read the data for the pdate. The MicroKernel reads data for the first ro from offset 0 of User Data. The MicroKernel reads the second ro s data from an address specified by User Data pls Application Distance Beteen Ros. The MicroKernel reads the third ro s data from the address specified by User Data pls (Application Distance Beteen Ros * 2), and so on. The folloing table shos a sample direct rectangle chnk descriptor strctre. Element Name Rectangle Chnk Descriptor Strctre Length (in Bytes) Description Sample Vale Length (in Bytes) Sbfnction 0x Btrieve Programmer s Reference 208 Btrieve Operations

209 Element Name Sample Vale Length (in Bytes) Nmber of Ros 3 4 Offset 0x19 4 Bytes Per Ro 0x04 4 Distance Beteen Ros 0x10 4 User Data 0 4 Application Distance Beteen Ros 0 4 Data (Ro 0) N/A 4 Data (Ro 1) N/A 4 Data (Ro 2) N/A 4 Trncate Descriptor Strctre The trncate descriptor allos yo to trncate a record at a specified offset. To se this type of chnk descriptor, yo mst create a strctre in the Data Bffer, based on the folloing table: Table 2-28 Element Trncate Descriptor Strctre Length (in Bytes) Description Sbfnction 4 Type of chnk descriptor. Specify 0x ChnkOffset 4 Byte offset into the record here trncation begins. That byte and every byte folloing it is eliminated. The minimm vale is 4. The maximm vale is the offset of the final byte in the record. Btrieve Programmer s Reference 209 Btrieve Operations

210 Next-in-Record Sbfnction Bias If yo add a bias of 0x to any of the sbfnctions previosly listed, the MicroKernel calclates the sbfnction s Offset element vales based on yor physical intrarecord crrency (that is, yor crrent physical position ithin the record). When yo se the Next-in-Record sbfnction, the MicroKernel ignores the Offset element in the chnk descriptor. If yo se this bias in combination ith a random chnk descriptor and it pdates more than one chnk in a single operation, the MicroKernel calclates the offset for all chnks (except the first) by adding the previos chnk s length to the previos chnk s offset. In other ords, the next-in-record bias applies to all chnks in the operation. Append Sbfnction Bias If yo add a bias of 0x to the random chnk descriptor s sbfnction or to the rectangle chnk descriptor s sbfnction, the MicroKernel calclates the sbfnction s Offset element vale to be one byte beyond the end of the record. Note Do not se this bias ith the Next-in-Record bias or the Trncate sbfnction. If yo se this bias in combination ith a random chnk descriptor and it pdates more than one chnk in a single operation, the MicroKernel calclates the offset for all chnks (except the first chnk) based on the record s length after the MicroKernel appends the previos chnk. Reslt If the Update Chnk operation is sccessfl, the MicroKernel pdates the portions of the record identified as chnks in the chnk descriptor portion of the Data Bffer. The ne Btrieve Programmer s Reference 210 Btrieve Operations

211 data for pdating the chnks is contained either in the chnk descriptor itself (for direct chnk descriptor sbfnctions) or in the memory address specified by the 32-bit pointer in each chnk s User Data element (for indirect chnk descriptor sbfnctions). After the Update Chnk operation completes, the MicroKernel adjsts the key indexes to reflect any change in the key vales, and, if necessary, pdates the Key Bffer parameter. In addition, if the application holds a single-record lock on the record to be pdated, the MicroKernel releases the lock. Hoever, a mltiple-record lock is never released by an Update Chnk operation. If the Update Chnk operation is nsccessfl, the MicroKernel retrns one of the folloing stats codes: 5 The record has a key field containing a dplicate key vale. 8 The crrent positioning is invalid. 10 The key field is not modifiable. 22 The data bffer parameter is too short. 58 The compression bffer length is too short. 62 The descriptor is incorrect. 80 The MicroKernel encontered a record-level conflict. 83 The MicroKernel attempted to pdate or delete a record that as read otside the transaction. 97 The data bffer is too small. 103 The chnk offset is too big. 106 The MicroKernel cannot perform a Get Next Chnk operation. Btrieve Programmer s Reference 211 Btrieve Operations

212 Positioning The Update Chnk operation does not change the physical crrency or the crrent logical record. Note When yo perform an Update Chnk operation folloing a Get operation, do not pass to the Update Chnk operation a Key Nmber that differs from the one specified in the preceding Get operation. If yo do, the positioning established by the MicroKernel is npredictable. Btrieve Programmer s Reference 212 Btrieve Operations

213 Version (26) For client applications, the Version operation retrns the local MicroKernel version and the Reqester version, if applicable. If a client application opens a file on a server or specifies a server file path name in the Key Bffer, the Version operation also retrns the MicroKernel version on that server. For server-based applications, the Version operation retrns the server-based MicroKernel version and revision nmbers. Parameters Operation Code Position Block Data Bffer Data Bffer Length Sent X X Retrned X X Key Bffer Key Nmber Prereqisites Either the MicroKernel or the Reqester mst be loaded before yo can isse a Version operation. Procedre 1. Set the Operation Code to Set the Data Bffer Length to at least 15. (For more information, see Table 2-29.) 3. To retrieve the version nmber of a server-based MicroKernel, yo mst specify either a valid Position Block for an opened file on that server or a valid pathname in the Key Bffer. Btrieve Programmer s Reference 213 Btrieve Operations

214 Reslt If yo have both a orkstation MicroKernel and client Reqester configred for access and the Version operation is sccessfl, the operation retrns the version information for the orkstation MicroKernel, the client Reqester, and the server-based MicroKernel. Specify a 15-byte Data Bffer and Data Bffer Length. If both the client Reqester and the orkstation MicroKernel are loaded and yo specify only a 5-byte Data Bffer and Data Bffer Length, the operation retrns only the client Reqester s version information. In the Data Bffer, the Version operation retrns a 5-byte Version Block for each MicroKernel or Reqester, according to the format shon in Table The fifth byte of each block identifies each MicroKernel or Reqester. Table 2-29 Version Block Element Length (in Bytes) Description Version Nmber 2 Btrieve version nmber. Revision Nmber 2 Btrieve revision nmber. Btrieve Programmer s Reference 214 Btrieve Operations

215 Table 2-29 Version Block contined Element Length (in Bytes) Description Reqester or Engine Type 1 Type of engine or reqester; one of the folloing: 9 (0x44) for Windos NT or Windos 95 orkstation 9 0x80 for Windos NT or Windos 95 orkstation Developer Kit D (0x39) for DOS orkstation L (0x4C) for Warp ServerO (0x4F) for OS/2 orkstation N (0x4E) for client Reqester S (0x53) for NetWare server T (0x54) for Windos NT server W (0x57) for Windos 3.x orkstation W 0x80 for Windos 3.x orkstation Developer Kit For example, if yo are rnning only Btrieve for NetWare 7.0, the Version operation retrns the folloing hexadecimal vales in the Data Bffer: Byte-sapping as appropriate, the hexadecimal vales become as follos: After converting these vales to decimal, the version nmber is 7, the revision nmber is 0, and the identifying component character is S (the letter eqivalent of ASCII 0x53). Btrieve Programmer s Reference 215 Btrieve Operations

216 If the Version operation is nsccessfl, the MicroKernel retrns a nonzero stats code. Positioning The Version operation has no effect on positioning. Btrieve Programmer s Reference 216 Btrieve Operations

217 appendixa Langage Interfaces This appendix discsses the folloing langage interfaces: C/C++ Cobol Delphi Pascal Visal Basic Table A-1 provides a list of the langage interface sorce modles provided in the Programming Interfaces installation option. Pervasive Softare provides the sorce code for each langage interface. Yo can find additional information in the sorce modles. Btrieve Programmer s Reference 217 Langage Interfaces

218 If yor programming langage does not have an interface, check if yor compiler spports mixed langage calls. If so, yo may be able to se the C interface. Table A-1 Langage Interface Sorce Modles Langage Compiler Sorce Modle C/C++ Most C/C++ compilers, inclding Borland, Microsoft, and WATCOM. This interface provides mltiple platform spport. BlobHdr.h (for Extended DOS platforms sing Borland or Phar Lap only) BMemCopy.obj (for Extended DOS platforms sing Borland or Phar Lap only) BMemCopy.asm (sorce for BMemCopy.obj) BtiTypes.h (platform-independent data types) BtrApi.h (Btrieve fnction prototypes) BtrApi.c (Btrieve interface code for all platforms) BtrConst.h (common Btrieve constants) BtrSamp.c (sample program) GenStat.h (Pervasive stats codes) Borland C++ Bilder CBBtrv.cpp CBBtrv.mak CBBMain.cpp CBBMain.dfm CBBMain.h Btrieve Programmer s Reference 218 Langage Interfaces

219 Table A-1 Langage Interface Sorce Modles contined Langage Compiler Sorce Modle Cobol Micro Focs Cobol all versions MfxBtrv.bin (DOS Rntime for Cobol Animator, non-intel byte-order integer) MfxBtrv.asm (sorce for this binary) Microsoft Cobol 3 CobrBtrv.obj (DOS 16-bit) CobpBtrv.obj (OS/2 16-bit) CobBtrv.asm (sorce for these objects) Mf2Btrv.bin (DOS rntime for Cobol animator, Intel byte-order integer) Mf2Btrv.asm (sorce for this binary) BtrSamp.cbl (sample program) Btrieve Programmer s Reference 219 Langage Interfaces

220 Table A-1 Langage Interface Sorce Modles contined Langage Compiler Sorce Modle Delphi Borland Delphi 1 Btr16.dpr BtrSam16.pas (sample program) BtrSam16.dfm BtrApi16.pas BtrConst.pas (common Btrieve constants) Borland Delphi 3 Btr32.dpr Pascal Borland Trbo Pascal 5 6 Btr32.dof BtrSam32.dfm BtrSam32.pas (sample program) BtrApi32.pas BtrConst.pas (common Btrieve constants) BtrApid.pas Borland Pascal 7 for DOS BtrSampd.pas (sample program) Extended DOS Pascal for Trbo Pascal 7 BtrConst.pas (common Btrieve constants) BlobHdr.pas Borland Trbo Pascal 1.5 BtrApi.pas Borland Pascal 7 for Windos BtrSamp.pas (sample program) BtrConst.pas (common Btrieve constants) BlobHdr.pas Btrieve Programmer s Reference 220 Langage Interfaces

221 Table A-1 Langage Interface Sorce Modles contined Langage Compiler Sorce Modle Visal Basic Microsoft Visal Basic for Windos 3.1 BtSamp16.vbp BtrSam16.bas (sample program) BtrFrm16.frm Microsoft Visal Basic for Windos NT and Windos 95 BtSamp32.vbp BtrSam32.bas (sample program) BtrFrm32.frm The folloing table provides a comparison of some common data types sed in data bffers for Btrieve operations, sch as Create and Stat. Table A-2 Common Data Types Used in the Btrieve Data Bffer Assembly C Cobol Delphi Pascal Visal Basic dobleord long 1 PIC 9(4) longint* longint* Long integer ord short int* PIC 9(2) smallint* integer* Integer byte char PIC X char char String byte nsigned char PIC X byte byte Byte 1 The vale of integers depends on the environment in hich yo develop. In 32-bit environments, integers are the same as long integers. In 16-bit environments, integers are the same as short, or small, integers. Btrieve Programmer s Reference 221 Langage Interfaces

222 C/C++ The C/C++ interface facilitates riting platform-independent applications. This interface spports development for the folloing operating systems: DOS (inclding Extended DOS), NetWare Loadable Modles (NLMs), OS/2, Windos (inclding Win32 applications), Windos NT, and Windos 95. This section discsses the folloing topics: Interface Modles Programming Reqirements Program Example Creating Applications ith the Tenberry DOS/4G Extender Compiling, Linking, and Rnning the Program Example Compiling C++ Bilder Applications Interface Modles This section describes in detail the modles that comprise the C langage interface. BtrApi.c The file BtrApi.c is the actal implementation of the C application interface. It provides spport for all applications that call BTRV and BTRVID, except NLMs, hich do not reqire any interface code. When making a Btrieve call ith either of these fnctions, compile BtrApi.c and link its object ith the other modles in yor application. Btrieve Programmer s Reference 222 Langage Interfaces

223 The BtrApi.c file contains #inclde directives that instrct yor compiler to inclde BtrApi.h, BtrConst.h, BlobHdr.h, and BtiTypes.h. By inclding these files, BtrApi.c takes advantage of the data types that provide the platform independence associated ith the interface. BtrApi.h The file BtrApi.h contains the prototypes of the Btrieve fnctions. The prototype definitions se the platform-independent data types defined in the file BtiTypes.h. BtrApi.h provides spport for all applications calling the BTRV and BTRVID fnctions. BtrConst.h The file BtrConst.h contains sefl constants specific to Btrieve. These constants can help yo standardize references to Btrieve operation codes, stats codes, file specification flags, key specification flags, and many more items. Yo can se the C application interface ithot taking advantage of BtrConst.h; hoever, inclding the file may simplify yor programming effort. BtiTypes.h The file BtiTypes.h defines the platform-independent data types. By sing the data types in BtiTypes.h on yor Btrieve fnction calls, yor application ports among operating systems. See BtiTypes.h for more information abot ho the data types are defined for each operating system. Btrieve Programmer s Reference 223 Langage Interfaces

224 BtiTypes.h also describes the sitches yo mst se to indicate the operating system on hich yor application rns. Table A-3 lists these operating system sitches. Table A-3 Operating System Sitches Operating System Application Type Sitch DOS 16-bit BTI_DOS 32-bit ith Tenberry Extender and BStb.exe 1 BTI_DOS_32R 32-bit ith Phar Lap 6 BTI_DOS_32P 32-bit ith Borland PoerPack BTI_DOS_32B NetWare 32-bit NLM BTI_NLM OS/2 16-bit BTI_OS2 32-bit BTI_OS2_32 Win16 16-bit BTI_WIN Win32 32-bit BTI_WIN_32 1 For more information, refer to Creating Applications ith the Tenberry DOS/4G Extender. BtrSamp.c The sorce file BtrSamp.c is a sample Btrieve program that yo can compile, link, and rn on any of the operating systems described in Table A-3. Btrieve Programmer s Reference 224 Langage Interfaces

225 Programming Reqirements If yo se the C application interface to make yor application platform independent, yo mst se the data types described in BtiTypes.h. To see ho these data types are sed, see the file BtrSamp.c. Note Yo mst also specify a directive that identifies the operating system on hich the program exectes. The available vales for the directive are listed in the header file BtiTypes.h. Specify the directive sing the appropriate command line option for yor compiler. Program Example The folloing example program, hich is inclded on yor distribtion media, shos ho to perform several of the more common Btrieve operations, and it performs those operations in the order reqired by the MicroKernel s dependencies (for example, yo mst open a file before performing I/O to it). Note Windos 3.x developers: The example ses the printf fnction to display text in a generic indo. All of the spported C/C++ compilers are capable of bilding a generic indo to display the otpt of Windos programs that employ standard I/O. By sing standard I/O, the example allos yo to concentrate on the details of programming a Btrieve application. Note 16-bit DOS developers: To compile the example, yo mst have a stack size of at least 8K. To rn the example, yo mst load the DOS Reqester ith the /T:1 flag. Btrieve Programmer s Reference 225 Langage Interfaces

226 Example A-1 BtrSamp.c /********************************************************** ** ** Copyright 1998 Pervasive Softare Inc. All Rights Reserved ** ************************************************************/ /*********************************************************** BTRSAMP.C This is a simple sample designed to allo yo to confirm yor ability to compile, link, and execte a Btrieve application for yor target environment sing yor compiler tools. This program demonstrates the C/C++ interface for Btrieve for DOS,Extended DOS, OS2 (16 and 32-bit), MS Windos, NetWare NLM, MS Windos NT and Windos 95. This program does the folloing operations on the sample database: - gets the Microkernel Database Engine version - opens sample.btr - gets a record on a knon vale of Key 0 - displays the retrieved record - performs a stat operation - creates an empty clone of sample.btr and opens it - performs a Get Next Extended operation to extract a sbset of the records in sample.btr - inserts those records into the cloned file - closes both files Btrieve Programmer s Reference 226 Langage Interfaces

227 Example A-1 BtrSamp.c contined IMPORTANT: Yo mst specify the complete path to the directory that contains the sample Btrieve data file, sample.btr. See IMPORTANT, belo. Yo can compile and rn this program on any of the platforms spported by the interface modles. Platforms are indicated by the platform sitches listed in btrapi.h. For MS Windos yo shold make an application that allos standard otpt via printf(). Note that most C/C++ compilers spport standard I/ O Windos applications. For MS Windos NT or OS2, yo shold make a console application. See the prologe in btrapi.h for information on ho to select a target platform for yor application. Yo mst specify a target platform. ***********************************************************/ #inclde <stdlib.h> #inclde <stdio.h> #inclde <string.h> #inclde <btrapi.h> #inclde <btrconst.h> /*********************************************************** Constants ************************************************************/ /*********************************************************** IMPORTANT: Yo shold modify the folloing to specify the Btrieve Programmer s Reference 227 Langage Interfaces

228 Example A-1 BtrSamp.c contined complete path to sample.btr for yor environment. ***********************************************************/ #ifdef BTI_NLM #define FILE1_NAME sys:\\pvs\\samples\\sample.btr #else #define FILE1_NAME c:\\pvs\\samples\\sample.btr #endif #ifdef BTI_NLM #define FILE2_NAME sys:\\pvs\\samples\\sample2.btr #else #define FILE2_NAME c:\\pvs\\samples\\sample2.btr #endif #define EXIT_WITH_ERROR 1 #define TRUE 1 #define FALSE 0 #define VERSION_OFFSET 0 #define REVISION_OFFSET 2 #define PLATFORM_ID_OFFSET 4 #define MY_THREAD_ID 50 /* Don t pad or strctres */ #if defined( BORLANDC ) #pragma option -a- #else #if defined(_msc_ver) defined( WATCOMC ) #pragma pack(1) #endif #endif Btrieve Programmer s Reference 228 Langage Interfaces

229 Example A-1 BtrSamp.c contined /*********************************************************** Type definitions for Client ID and version Strctres ************************************************************/ typedef strct { BTI_CHAR netorkandnode[12]; BTI_CHAR applicationid[2]; BTI_WORD threadid; } CLIENT_ID; typedef strct { BTI_SINT Version; BTI_SINT Revision; BTI_CHAR MKDEId; } VERSION_STRUCT; /*********************************************************** Definition of record from sample.btr ************************************************************/ typedef strct { BTI_LONG ID; BTI_CHAR FirstName[16]; BTI_CHAR LastName[26]; BTI_CHAR Street[31]; BTI_CHAR City[31]; BTI_CHAR State[3]; BTI_CHAR Zip[11]; Btrieve Programmer s Reference 229 Langage Interfaces

230 Example A-1 BtrSamp.c contined BTI_CHAR Contry[21]; BTI_CHAR Phone[14]; } PERSON_STRUCT; /*********************************************************** Type definitions for Stat/Create strctre ************************************************************/ typedef strct { BTI_SINT reclength; BTI_SINT pagesize; BTI_SINT indexcont; BTI_CHAR reserved[4]; BTI_SINT flags; BTI_BYTE dppointers; BTI_BYTE notused; BTI_SINT allocations; } FILE_SPECS; typedef strct { BTI_SINT position; BTI_SINT length; BTI_SINT flags; BTI_CHAR reserved[4]; BTI_CHAR type; BTI_CHAR nll; BTI_CHAR notused[2]; BTI_BYTE manalkeynmber; BTI_BYTE acsnmber; Btrieve Programmer s Reference 230 Langage Interfaces

231 Example A-1 BtrSamp.c contined } KEY_SPECS; typedef strct { FILE_SPECS filespecs; KEY_SPECS keyspecs[5]; } FILE_CREATE_BUF; /*********************************************************** Strctre type definitions for Get Next Extended operation ************************************************************/ typedef strct { BTI_SINT descriptionlen; BTI_CHAR crrencyconst[2]; BTI_SINT rejectcont; BTI_SINT nmberterms; } GNE_HEADER; typedef strct { BTI_CHAR fieldtype; BTI_SINT fieldlen; BTI_SINT fieldoffset; BTI_CHAR comparisoncode; BTI_CHAR connector; BTI_CHAR vale[3]; } TERM_HEADER; typedef strct Btrieve Programmer s Reference 231 Langage Interfaces

232 Example A-1 BtrSamp.c contined { BTI_SINT maxrecstoretrieve; BTI_SINT nofieldstoretrieve; } RETRIEVAL_HEADER; typedef strct { BTI_SINT fieldlen; BTI_SINT fieldoffset; } FIELD_RETRIEVAL_HEADER; typedef strct { GNE_HEADER gneheader; TERM_HEADER term1; TERM_HEADER term2; RETRIEVAL_HEADER retrieval; FIELD_RETRIEVAL_HEADER recordret; } PRE_GNE_BUFFER; typedef strct { BTI_SINT reclen; BTI_LONG recpos; PERSON_STRUCT personrecord; } RETURNED_REC; typedef strct { BTI_SINT nmretrned; Btrieve Programmer s Reference 232 Langage Interfaces

233 Example A-1 BtrSamp.c contined RETURNED_REC recs[20]; } POST_GNE_BUFFER; typedef nion { PRE_GNE_BUFFER prebf; POST_GNE_BUFFER postbf; } GNE_BUFFER, BTI_FAR* GNE_BUFFER_PTR; /* restore strctre packing */ #if defined( BORLANDC ) #pragma option -a. #else #if defined(_msc_ver) defined( WATCOMC ) #pragma pack() #endif #endif /*********************************************************** Main ***********************************************************/ int main(void) { /* Btrieve fnction parameters */ BTI_BYTE posblock1[128]; BTI_BYTE posblock2[128]; BTI_BYTE databf[255]; BTI_WORD datalen; BTI_BYTE keybf1[255]; BTI_BYTE keybf2[255]; Btrieve Programmer s Reference 233 Langage Interfaces

234 Example A-1 BtrSamp.c contined BTI_WORD keynm = 0; BTI_BYTE btrieveloaded = FALSE; BTI_LONG personid; BTI_BYTE file1open = FALSE; BTI_BYTE file2open = FALSE; BTI_SINT stats; BTI_SINT getstats = -1; BTI_SINT i; BTI_SINT posctr; CLIENT_ID clientid; VERSION_STRUCT versionbffer[3]; FILE_CREATE_BUF filecreatebf; GNE_BUFFER_PTR gnebffer; PERSON_STRUCT personrecord; printf( **************** Btrieve C/C++ Interface Demo ****************\n\n ); /* set p the Client ID */ memset(clientid.netorkandnode, 0, sizeof(clientid.netorkandnode)); memcpy(clientid.applicationid, MT, 2); /* mst be greater than AA */ clientid.threadid = MY_THREAD_ID; memset(versionbffer, 0, sizeof(versionbffer)); datalen = sizeof(versionbffer); Btrieve Programmer s Reference 234 Langage Interfaces

235 Example A-1 BtrSamp.c contined stats = BTRVID( B_VERSION, posblock1, &versionbffer, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); if (stats == B_NO_ERROR) { printf( Btrieve Versions retrned are: \n ); for (i = 0; i < 3; i++) { if (versionbffer[i].version!= 0) { printf( %d.%d %c\n, versionbffer[i].version, versionbffer[i].revision, versionbffer[i].mkdeid); } } printf( \n ); btrieveloaded = TRUE; } else { printf( Btrieve B_VERSION stats = %d\n, stats); if (stats!= B_RECORD_MANAGER_INACTIVE) { btrieveloaded = TRUE; } Btrieve Programmer s Reference 235 Langage Interfaces

236 Example A-1 BtrSamp.c contined } /* clear bffers */ if (stats == B_NO_ERROR) { memset(databf, 0, sizeof(databf)); memset(keybf1, 0, sizeof(keybf1)); memset(keybf2, 0, sizeof(keybf2)); } /* open sample.btr */ if (stats == B_NO_ERROR) { strcpy((bti_char *)keybf1, FILE1_NAME); strcpy((bti_char *)keybf2, FILE2_NAME); keynm = 0; datalen = 0; stats = BTRVID( B_OPEN, posblock1, databf, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); Btrieve Programmer s Reference 236 Langage Interfaces

237 Example A-1 BtrSamp.c contined printf( Btrieve B_OPEN stats (sample.btr) = %d\n, stats); if (stats == B_NO_ERROR) { file1open = TRUE; } } /* get the record ith key 0 = sing B_GET_EQUAL */ if (stats == B_NO_ERROR) { memset(&personrecord, 0, sizeof(personrecord)); datalen = sizeof(personrecord); personid = ; /* this is really a social secrity nmber */ *(BTI_LONG BTI_FAR *)&keybf1[0] = personid; keynm = 0; stats = BTRVID( B_GET_EQUAL, posblock1, &personrecord, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); printf( Btrieve B_GET_EQUAL stats = %d\n, stats); if (stats == B_NO_ERROR) { Btrieve Programmer s Reference 237 Langage Interfaces

238 Example A-1 BtrSamp.c contined } } printf( \n ); printf( The retrieved record is:\n ); printf( ID: %ld\n, personrecord.id); printf( Name: %s %s\n, personrecord.firstname, personrecord.lastname); printf( Street: %s\n, personrecord.street); printf( City: %s\n, personrecord.city); printf( State: %s\n, personrecord.state); printf( Zip: %s\n, personrecord.zip); printf( Contry: %s\n, personrecord.contry); printf( Phone: %s\n, personrecord.phone); printf( \n ); /* perform a stat operation to poplate the create bffer */ memset(&filecreatebf, 0, sizeof(filecreatebf)); datalen = sizeof(filecreatebf); keynm = (BTI_WORD)-1; stats = BTRVID(B_STAT, posblock1, &filecreatebf, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); if (stats == B_NO_ERROR) { Btrieve Programmer s Reference 238 Langage Interfaces

239 Example A-1 BtrSamp.c contined /* create and open sample2.btr */ keynm = 0; datalen = sizeof(filecreatebf); stats = BTRVID(B_CREATE, posblock2, &filecreatebf, &datalen, keybf2, keynm, (BTI_BUFFER_PTR)&clientID); } printf( Btrieve B_CREATE stats = %d\n, stats); if (stats == B_NO_ERROR) { keynm = 0; datalen = 0; stats = BTRVID( B_OPEN, posblock2, databf, &datalen, keybf2, keynm, (BTI_BUFFER_PTR)&clientID); printf( Btrieve B_OPEN stats (sample2.btr) = %d\n, stats); Btrieve Programmer s Reference 239 Langage Interfaces

240 Example A-1 BtrSamp.c contined } if (stats == B_NO_ERROR) { file2open = TRUE; } /* no extract data from the original file, insert into ne one */ if (stats == B_NO_ERROR) { /* getfirst to establish crrency */ keynm = 2; /* STATE-CITY index */ memset(&personrecord, 0, sizeof(personrecord)); memset(&keybf2[0], 0, sizeof(keybf2)); datalen = sizeof(personrecord); getstats = BTRVID( B_GET_FIRST, posblock1, &personrecord, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); printf( Btrieve B_GET_FIRST stats (sample.btr) = %d\n\n, getstats); } gnebffer = malloc(sizeof(gne_buffer)); Btrieve Programmer s Reference 240 Langage Interfaces

241 Example A-1 BtrSamp.c contined if (gnebffer == NULL) { printf( Insfficient memory to allocate bffer ); retrn(exit_with_error); } memset(gnebffer, 0, sizeof(gne_buffer)); memcpy(&gnebffer->prebf.gneheader.crrencyconst[0], UC, 2); hile (getstats == B_NO_ERROR) { gnebffer->prebf.gneheader.rejectcont = 0; gnebffer->prebf.gneheader.nmberterms = 2; posctr = sizeof(gne_header); /* fill in the first condition */ gnebffer->prebf.term1.fieldtype = 11; gnebffer->prebf.term1.fieldlen = 3; gnebffer->prebf.term1.fieldoffset = 108; gnebffer->prebf.term1.comparisoncode = 1; gnebffer->prebf.term1.connector = 2; memcpy(&gnebffer->prebf.term1.vale[0], TX, 2); posctr += sizeof(term_header); /* fill in the second condition */ gnebffer->prebf.term2.fieldtype = 11; gnebffer->prebf.term2.fieldlen = 3; gnebffer->prebf.term2.fieldoffset = 108; gnebffer->prebf.term2.comparisoncode = 1; gnebffer->prebf.term2.connector = 0; memcpy(&gnebffer->prebf.term2.vale[0], CA, 2); Btrieve Programmer s Reference 241 Langage Interfaces

242 Example A-1 BtrSamp.c contined posctr += sizeof(term_header); /* fill in the projection header to retrieve hole record */ gnebffer->prebf.retrieval.maxrecstoretrieve = 20; gnebffer->prebf.retrieval.nofieldstoretrieve = 1; posctr += sizeof(retrieval_header); gnebffer->prebf.recordret.fieldlen = sizeof(person_struct); gnebffer->prebf.recordret.fieldoffset = 0; posctr += sizeof(field_retrieval_header); gnebffer->prebf.gneheader.descriptionlen = posctr; datalen = sizeof(gne_buffer); getstats = BTRVID( B_GET_NEXT_EXTENDED, posblock1, gnebffer, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); printf( Btrieve B_GET_NEXT_EXTENDED stats = %d\n, getstats); /* Get Next Extended can reach end of file and still retrn some records */ if ((getstats == B_NO_ERROR) (getstats == B_END_OF_FILE)) { Btrieve Programmer s Reference 242 Langage Interfaces

243 Example A-1 BtrSamp.c contined printf( GetNextExtended retrned %d records.\n, gnebffer->postbf.nmretrned); for (i = 0; i < gnebffer->postbf.nmretrned; i++) { datalen = sizeof(person_struct); memcpy(databf, &gnebffer- >postbf.recs[i].personrecord, datalen); stats = BTRVID( B_INSERT, posblock2, databf, &datalen, keybf2, -1, /* no crrency change */ (BTI_BUFFER_PTR)&clientID); } printf( Inserted %d records in ne file, stats = %d\n\n, gnebffer->postbf.nmretrned, stats); } memset(gnebffer, 0, sizeof(gne_buffer)); memcpy(&gnebffer->prebf.gneheader.crrencyconst[0], EG, 2); } free(gnebffer); gnebffer = NULL; /* close open files */ if (file1open) { Btrieve Programmer s Reference 243 Langage Interfaces

244 Example A-1 BtrSamp.c contined datalen = 0; stats = BTRVID( B_CLOSE, posblock1, databf, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); printf( Btrieve B_CLOSE stats (sample.btr) = %d\n, stats); } if (file2open) { datalen = 0; stats = BTRVID( B_CLOSE, posblock2, databf, &datalen, keybf2, keynm, (BTI_BUFFER_PTR)&clientID); printf( Btrieve B_CLOSE stats (sample2.btr) = %d\n, stats); Btrieve Programmer s Reference 244 Langage Interfaces

245 Example A-1 BtrSamp.c contined } /********************************************************** ISSUE THE BTRIEVE STOP OPERATION - For mlti-tasking environments, sch as MS Windos, OS2, and NLM, stop frees all Btrieve resorces for this client. In DOS and Extended DOS, it removes the Btrieve engine from memory, hich e choose not to do in this example. In mlti-tasking environments, the engine ill not nload on stop nless it has no more clients. **********************************************************/ #if!defined(bti_dos) &&!defined(bti_dos_32r) && \!defined(bti_dos_32b) &&!defined(bti_dos_32p) if (btrieveloaded) { datalen = 0; stats = BTRVID(B_STOP, posblock1, databf, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); printf( Btrieve STOP stats = %d\n, stats); if (stats!= B_NO_ERROR) { stats = EXIT_WITH_ERROR; } } #endif } retrn(stats); Btrieve Programmer s Reference 245 Langage Interfaces

246 Creating Applications ith the Tenberry DOS/4G Extender Using the Tenberry extended DOS sitch for yor 32-bit extended DOS application provides optimm performance, becase doing so frees yor application from having to copy data to real-mode memory in order to pass the data to the MicroKernel. To se the extended DOS sitch, follo these steps: 1. Compile yor 32-bit application and inclde the C interface. Be sre to define the BTI_DOS_32R macro to yor compiler. 2. Rn a compiler tility on the object modles to make them compatible ith the Tenberry linker. (For the WATCOM compiler, this tility is called omp. The 10.0 compiler does not reqire omp.) 3. Create a.def file, as in the folloing example sed to create the sample program BtrSamp.exe: LIBRARY btrsamp.dll DATA NONSHARED EXPORTS ImportedFnctions_ 4. Link yor application sing the Tenberry linker (Gl) and specify the Btrieve stb, as in the folloing example: gl -format lin -stack stb bstb.exe -cod Btrieve Programmer s Reference 246 Langage Interfaces

247 Compiling, Linking, and Rnning the Program Example The C Interface for Btrieve is platform-independent and compiler-independent. In general for yor compiler, yo mst do the folloing: In the BtrSamp.c file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. Identify the appropriate import library. The locations are as follos: Microsoft Watcom and Borland \Intf\ImpLib\W32 \Intf\ImpLib\W32x Set the appropriate platform sitch. The sitches are shon in Table A-3. Update the inclde directories setting. Yo mst inclde the crrent directory. Use the appropriate strctre alignment. The sample program contains a pragma for strctre alignment. Becase yo mst either se a similar pragma in yor on application or set a compiler sitch for strctre alignment, the instrctions in this section identify the appropriate compiler sitch to se. This section provides instrctions for some common development environments. If yor development environment is not discssed, yo can adapt these instrctions. In Microsoft Visal C++, to compile, link, and rn the program example: 1. In the Developer Stdio programming environment, choose Ne from the File men. 2. In the Ne dialog, on the Projects tab, do the folloing: a. Set the type to Console Application. (BtrSamp rns from a DOS prompt.) b. Set the Name to BtrSamp. Btrieve Programmer s Reference 247 Langage Interfaces

248 c. Set the location to the \Intf\C directory. d. Click OK. Developer Stdio creates a ne project called BtrSamp. 3. In the FileVie tab of the orkspace, right click on the BtrSamp project, choose the Add Files to Project command, and add the folloing files: \Intf\C\BtrApi.c \Intf\C\BtrSamp.c \Intf\ImpLib\Win32\W3Btrv7.lib Click OK. 4. In the BtrSamp.c file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. 5. Choose Settings from the Project men. On the C++ tab, do the folloing: In the Preprocessor category, add BTI_WIN_32 in the Preprocessor Definitions box and add the crrent directory (.) in the Additional Inclde Directories box. In the Code Generation category, set the Strctre Member Alignment to 1 Byte. Click OK. 6. Choose Rebild All from the Bild men. Microsoft Visal C++ bilds the program example and places BtrSamp.exe in yor project file directory. 7. In a DOS prompt indo, rn BtrSamp.exe. In Watcom C++, to compile, link, and rn the program example: 1. In the IDE programming environment, choose Ne Project from the File men. Btrieve Programmer s Reference 248 Langage Interfaces

249 2. In the Enter Project Filename dialog, set the File Name to BtrSamp.pj and click OK. 3. In the Ne Target dialog, do the folloing: Set the Target Name to BtrSamp. Set the Target Environment to Win32. Set the Image Type to Exectable [.exe]. Click OK. 4. Choose Ne Sorce from the Sorces men and add the folloing files: \Intf\C\BtrApi.c \Intf\C\BtrSamp.c \Intf\ImpLib\Win32x\W3Btrv7.lib Click OK. 5. In the BtrSamp.c file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. 6. Choose C Compiler Sitches from the Sorce Options sbmen on the Sorces men and do the folloing: In the File Option Sitches dialog, add the crrent directory to the Inclde directories box, as in the folloing example: $(%atcom)\h;$(%atcom)\h\nt;. In the Sorce Sitches dialog, add BTI_WIN_32 to the Macro Definitions box and set the Strctre Alignment to Pack strctres. Click OK. 7. Choose the Make All Targets btton from the toolbar. Btrieve Programmer s Reference 249 Langage Interfaces

250 WATCOM C++ bilds the program example and places BtrSamp.exe in yor project file directory. 8. In a DOS prompt indo, rn BtrSamp.exe. In Borland C++, to compile, link, and rn the program example: 1. In the Borland C++ programming environment, choose Ne Project from the Project men. 2. In the Ne Target dialog: Set the Project Path and Name to \Intf\C\BtrSamp. Set the Target Name to BtrSamp. Set the Target Type to Application [.exe]. Set the Target Model to Console. Trn off the Class Library checkbox in the Frameorks grop. Click the Advanced btton and specify.c node in the Initial Nodes grop and trn off the.rc and.def check boxes. Click OK. 3. In the Project indo, right click on the BtrSamp project, choose Add Node, and add the folloing files: \Intf\C\BtrApi.c \Intf\C\BtrSamp.c \Intf\ImpLib\Win32x\W3Btrv7.lib Click OK. 4. In the BtrSamp.c file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. Btrieve Programmer s Reference 250 Langage Interfaces

251 5. Choose Project from the Options men and do the folloing: Select the Directories topic and add the crrent directory to the Inclde list in the Sorce Directories grop, as in the folloing example: c:\bc5\inclde;. Select the Defines topic nder Compiler and add BTI_WIN_32 to the Defines box. Select the Processor topic nder 32-bit Compiler and set the Data Alignment to Byte. Click OK. 6. Choose Bild All from the Project men. Borland C++ bilds the program example and places BtrSamp.exe in yor project file directory. 7. In a DOS prompt indo, rn BtrSamp.exe. Btrieve Programmer s Reference 251 Langage Interfaces

252 Compiling C++ Bilder Applications In C++ Bilder, to compile, link, and rn the program example: 1. Choose Open Project from the File men and select the CBBtrv.mak file. 2. Choose Project from the Options men, select the Directories/Conditionals tab, and do the folloing: Add the \Intf\C directory to the Inclde Path. Add the \Intf\Implib\Win32x directory to the Library Path. 3. Choose Make from the Project men. C++ Bilder bilds the program example and places CBBtrv.exe in yor project file directory. 4. Choose Rn from the Rn men. 5. In the Btrieve Sample Application indo, click the Rn Test btton. The folloing example C++ Bilder program shos ho to perform several of the more common Btrieve operations, and it performs those operations in the order reqired by the MicroKernel s dependencies (for example, yo mst open a file before performing I/O to it). Example A-2 CBBMain.cpp /********************************************************** ** ** Copyright 1998 Pervasive Softare Inc. ** All Rights Reserved ***********************************************************/ /*********************************************************** CBBMain.cpp This is a simple sample designed to allo yo to confirm yor ability to compile, link, and execte a Btrieve application Btrieve Programmer s Reference 252 Langage Interfaces

253 Example A-2 CBBMain.cpp for yor target environment sing yor compiler tools. This program demonstrates the C/C++ interface for Btrieve for MS Windos NT and Windos 95 ith Borland s C++ Bilder. This program does the folloing operations on the sample database: - gets the Microkernel Database Engine version - opens sample.btr - gets a record on a knon vale of Key 0 - displays the retrieved record - performs a stat operation - creates an empty clone of sample.btr and opens it - performs a Get Next Extended operation to extract a sbset of the records in sample.btr - inserts those records into the cloned file - closes both files To compile this sample, yo mst make the folloing files from the Btrieve C interface directory available to the IDE: - btrapi.c - btrapi.h - btrconst.h IMPORTANT: Yo mst specify the complete path to the directory that contains the sample Btrieve data file, sample.btr. See IMPORTANT, belo. ***********************************************************/ // #inclde <vcl\vcl.h> #pragma hdrstop #inclde CBBMain.h #inclde <btrapi.h> #inclde <btrconst.h> Btrieve Programmer s Reference 253 Langage Interfaces

254 Example A-2 CBBMain.cpp // #pragma resorce *.dfm /*********************************************************** Constants ***********************************************************/ #define EXIT_WITH_ERROR 1 #define TRUE 1 #define FALSE 0 #define VERSION_OFFSET 0 #define REVISION_OFFSET 2 #define PLATFORM_ID_OFFSET 4 #define MY_THREAD_ID 50 /* Don t pad or strctres */ /* Borland s help says this is the defalt. Don t believe it.*/ #pragma option -a1 /*********************************************************** Type definitions for Client ID and version Strctres ***********************************************************/ typedef strct { BTI_CHAR netorkandnode[12]; BTI_CHAR applicationid[2]; BTI_WORD threadid; } CLIENT_ID; typedef strct { BTI_SINT Version; BTI_SINT Revision; BTI_CHAR MKDEId; } VERSION_STRUCT; /*********************************************************** Btrieve Programmer s Reference 254 Langage Interfaces

255 Example A-2 CBBMain.cpp Definition of record from sample.btr ***********************************************************/ typedef strct { BTI_LONG ID; BTI_CHAR FirstName[16]; BTI_CHAR LastName[26]; BTI_CHAR Street[31]; BTI_CHAR City[31]; BTI_CHAR State[3]; BTI_CHAR Zip[11]; BTI_CHAR Contry[21]; BTI_CHAR Phone[14]; } PERSON_STRUCT; /*********************************************************** Type definitions for Stat/Create strctre ***********************************************************/ typedef strct { BTI_SINT reclength; BTI_SINT pagesize; BTI_SINT indexcont; BTI_CHAR reserved[4]; BTI_SINT flags; BTI_BYTE dppointers; BTI_BYTE notused; BTI_SINT allocations; } FILE_SPECS; typedef strct { BTI_SINT position; BTI_SINT length; BTI_SINT flags; BTI_CHAR reserved[4]; BTI_CHAR type; Btrieve Programmer s Reference 255 Langage Interfaces

256 Example A-2 CBBMain.cpp BTI_CHAR nll; BTI_CHAR notused[2]; BTI_BYTE manalkeynmber; BTI_BYTE acsnmber; } KEY_SPECS; typedef strct { FILE_SPECS filespecs; KEY_SPECS keyspecs[5]; } FILE_CREATE_BUF; /*********************************************************** Strctre type definitions for Get Next Extended operation ***********************************************************/ typedef strct { BTI_SINT descriptionlen; BTI_CHAR crrencyconst[2]; BTI_SINT rejectcont; BTI_SINT nmberterms; } GNE_HEADER; typedef strct { BTI_CHAR fieldtype; BTI_SINT fieldlen; BTI_SINT fieldoffset; BTI_CHAR comparisoncode; BTI_CHAR connector; BTI_CHAR vale[3]; } TERM_HEADER; typedef strct { BTI_SINT maxrecstoretrieve; BTI_SINT nofieldstoretrieve; Btrieve Programmer s Reference 256 Langage Interfaces

257 Example A-2 CBBMain.cpp } RETRIEVAL_HEADER; typedef strct { BTI_SINT fieldlen; BTI_SINT fieldoffset; } FIELD_RETRIEVAL_HEADER; typedef strct { GNE_HEADER gneheader; TERM_HEADER term1; TERM_HEADER term2; RETRIEVAL_HEADER retrieval; FIELD_RETRIEVAL_HEADER recordret; } PRE_GNE_BUFFER; typedef strct { BTI_SINT reclen; BTI_LONG recpos; PERSON_STRUCT personrecord; } RETURNED_REC; typedef strct { BTI_SINT nmretrned; RETURNED_REC recs[20]; } POST_GNE_BUFFER; typedef nion { PRE_GNE_BUFFER prebf; POST_GNE_BUFFER postbf; } GNE_BUFFER, BTI_FAR* GNE_BUFFER_PTR; // Btrieve Programmer s Reference 257 Langage Interfaces

258 Example A-2 CBBMain.cpp // non-exported forard declarations void printlb(tlistbox *LB, char *msg); TForm1 *Form1; // fastcall TForm1::TForm1(TComponent* Oner) : TForm(Oner) { } // void fastcall TForm1::ExitBttonClick(TObject *Sender) { Form1->Close(); } // void fastcall TForm1::RnBttonClick(TObject *Sender) { rntest(); } /*********************************************************** Helper fnction to rite to ListBox ***********************************************************/ void printlb(tlistbox *LB, char *msg) { LB->Items->Add(msg); } /*********************************************************** This is here all the ork gets done ***********************************************************/ BTI_SINT rntest(void) { /* Btrieve fnction parameters */ BTI_BYTE posblock1[128]; BTI_BYTE posblock2[128]; Btrieve Programmer s Reference 258 Langage Interfaces

259 Example A-2 CBBMain.cpp BTI_BYTE databf[255]; BTI_WORD datalen; BTI_BYTE keybf1[255]; BTI_BYTE keybf2[255]; BTI_WORD keynm = 0; BTI_BYTE btrieveloaded = FALSE; BTI_LONG personid; BTI_BYTE file1open = FALSE; BTI_BYTE file2open = FALSE; BTI_SINT stats; BTI_SINT getstats; BTI_SINT i; BTI_SINT posctr; CLIENT_ID clientid; VERSION_STRUCT versionbffer[3]; FILE_CREATE_BUF filecreatebf; GNE_BUFFER_PTR gnebffer; PERSON_STRUCT personrecord; BTI_CHAR tmpbf[1024]; /********************************************************** Print the program title **********************************************************/ printlb(form1->listbox1, **** Btrieve -- C++ Bilder Sample **** ); /* set p the Client ID */ memset(clientid.netorkandnode, 0, sizeof(clientid.netorkandnode)); memcpy(clientid.applicationid, MT, 2); /* mst be greater than AA */ clientid.threadid = MY_THREAD_ID; Btrieve Programmer s Reference 259 Langage Interfaces

260 Example A-2 CBBMain.cpp memset(versionbffer, 0, sizeof(versionbffer)); datalen = sizeof(versionbffer); stats = BTRVID( B_VERSION, posblock1, &versionbffer, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); if (stats == B_NO_ERROR) { strcpy(tmpbf, Btrieve Versions retrned are: ); printlb(form1->listbox1, tmpbf); for (i = 0; i < 3; i++) { if (versionbffer[i].version!= 0) { sprintf(tmpbf, versionbffer[i].revision, versionbffer[i].mkdeid ); printlb(form1->listbox1, tmpbf); } } printlb(form1->listbox1, ); btrieveloaded = TRUE; %d.%d %c, versionbffer[i].version, } else { sprintf(tmpbf, Btrieve B_VERSION stats = %d, stats ); printlb(form1->listbox1, tmpbf); if ( stats!= B_RECORD_MANAGER_INACTIVE ) { btrieveloaded = TRUE; } } Btrieve Programmer s Reference 260 Langage Interfaces

261 Example A-2 CBBMain.cpp /* clear bffers */ if (stats == B_NO_ERROR) { memset(databf, 0, sizeof(databf)); memset(keybf1, 0, sizeof(keybf1)); memset(keybf2, 0, sizeof(keybf2)); } /* open sample.btr */ if (stats == B_NO_ERROR) { /******************************************************** IMPORTANT: Yo shold modify the folloing to specify the complete path to sample.btr for yor environment. ********************************************************/ strcpy((bti_char *)keybf1, c:\\sample\\sample.btr ); strcpy((bti_char *)keybf2, c:\\sample\\sample2.btr ); keynm = 0; datalen = 0; stats = BTRVID( B_OPEN, posblock1, databf, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); sprintf(tmpbf, Btrieve B_OPEN stats = %d, stats ); printlb(form1->listbox1, tmpbf); if (stats == B_NO_ERROR) { file1open = TRUE; } Btrieve Programmer s Reference 261 Langage Interfaces

262 Example A-2 } CBBMain.cpp /* get the record ith key 0 = sing B_GET_EQUAL */ if (stats == B_NO_ERROR) { memset(&personrecord, 0, sizeof(personrecord)); datalen = sizeof(personrecord); personid = ; /* this is really a social secrity nmber */ *(BTI_LONG BTI_FAR *)&keybf1[0] = personid; keynm = 0; stats = BTRVID( B_GET_EQUAL, posblock1, &personrecord, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); sprintf(tmpbf, Btrieve B_GET_EQUAL stats = %d, stats ); printlb(form1->listbox1, tmpbf); if (stats == B_NO_ERROR) { sprintf(tmpbf, ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, The retrieved record is: ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, ID: %ld, personrecord.id ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, Name: %s %s, personrecord.firstname, personrecord.lastname ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, Street: %s, personrecord.street ); Btrieve Programmer s Reference 262 Langage Interfaces

263 Example A-2 CBBMain.cpp printlb(form1->listbox1, tmpbf); sprintf(tmpbf, City: %s, personrecord.city ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, State: %s, personrecord.state ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, Zip: %s, personrecord.zip ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, Contry: %s, personrecord.contry ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, Phone: %s, personrecord.phone ); printlb(form1->listbox1, tmpbf); sprintf(tmpbf, ); printlb(form1->listbox1, tmpbf); } } /* perform a stat operation to poplate the create bffer */ memset(&filecreatebf, 0, sizeof(filecreatebf)); datalen = sizeof(filecreatebf); keynm = (BTI_WORD)-1; stats = BTRVID(B_STAT, posblock1, &filecreatebf, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); if (stats == B_NO_ERROR) { /* create and open sample2.btr */ keynm = 0; datalen = sizeof(filecreatebf); stats = BTRVID(B_CREATE, posblock2, Btrieve Programmer s Reference 263 Langage Interfaces

264 Example A-2 CBBMain.cpp &filecreatebf, &datalen, keybf2, keynm, (BTI_BUFFER_PTR)&clientID); } sprintf(tmpbf, Btrieve B_CREATE stats = %d, stats ); printlb(form1->listbox1, tmpbf); if (stats == B_NO_ERROR) { keynm = 0; datalen = 0; stats = BTRVID( B_OPEN, posblock2, databf, &datalen, keybf2, keynm, (BTI_BUFFER_PTR)&clientID); } sprintf(tmpbf, Btrieve B_OPEN stats = %d, stats ); printlb(form1->listbox1, tmpbf); if (stats == B_NO_ERROR) { file2open = TRUE; } /* no extract data from original file, insert into ne one */ if (stats == B_NO_ERROR) { /* getfirst to establish crrency */ keynm = 2; /* STATE-CITY index */ Btrieve Programmer s Reference 264 Langage Interfaces

265 Example A-2 CBBMain.cpp memset(&personrecord, 0, sizeof(personrecord)); memset(&keybf2[0], 0, sizeof(keybf2)); datalen = sizeof(personrecord); getstats = BTRVID( B_GET_FIRST, posblock1, &personrecord, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); sprintf(tmpbf, Btrieve B_GET_FIRST stats = %d, getstats ); printlb(form1->listbox1, tmpbf); } gnebffer = (GNE_BUFFER_PTR)malloc(sizeof(GNE_BUFFER)); if (gnebffer == NULL) { strcpy(tmpbf, Insfficient memory to allocate bffer ); printlb(form1->listbox1, tmpbf); retrn(exit_with_error); } memset(gnebffer, 0, sizeof(gne_buffer)); memcpy(&gnebffer->prebf.gneheader.crrencyconst[0], UC, 2); hile (getstats == B_NO_ERROR) { gnebffer->prebf.gneheader.rejectcont = 0; gnebffer->prebf.gneheader.nmberterms = 2; posctr = sizeof(gne_header); /* fill in the first condition */ gnebffer->prebf.term1.fieldtype = 11; Btrieve Programmer s Reference 265 Langage Interfaces

266 Example A-2 CBBMain.cpp gnebffer->prebf.term1.fieldlen = 3; gnebffer->prebf.term1.fieldoffset = 108; gnebffer->prebf.term1.comparisoncode = 1; gnebffer->prebf.term1.connector = 2; memcpy(&gnebffer->prebf.term1.vale[0], TX, 2); posctr += sizeof(term_header); /* fill in the second condition */ gnebffer->prebf.term2.fieldtype = 11; gnebffer->prebf.term2.fieldlen = 3; gnebffer->prebf.term2.fieldoffset = 108; gnebffer->prebf.term2.comparisoncode = 1; gnebffer->prebf.term2.connector = 0; memcpy(&gnebffer->prebf.term2.vale[0], CA, 2); posctr += sizeof(term_header); /* fill in the projection header to retrieve hole record */ gnebffer->prebf.retrieval.maxrecstoretrieve = 20; gnebffer->prebf.retrieval.nofieldstoretrieve = 1; posctr += sizeof(retrieval_header); gnebffer->prebf.recordret.fieldlen = sizeof(person_struct); gnebffer->prebf.recordret.fieldoffset = 0; posctr += sizeof(field_retrieval_header); gnebffer->prebf.gneheader.descriptionlen = posctr; datalen = sizeof(gne_buffer); getstats = BTRVID( B_GET_NEXT_EXTENDED, posblock1, gnebffer, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); Btrieve Programmer s Reference 266 Langage Interfaces

267 Example A-2 CBBMain.cpp sprintf(tmpbf, Btrieve B_GET_NEXT_EXTENDED stats = %d, getstats ); printlb(form1->listbox1, tmpbf); /* Get Next Extended can reach end of file and still retrn */ /* some records */ if ((getstats == B_NO_ERROR) (getstats == B_END_OF_FILE)) { sprintf(tmpbf, GetNextExtended retrned %d records., gnebffer->postbf.nmretrned); printlb(form1->listbox1, tmpbf); for (i = 0; i < gnebffer->postbf.nmretrned; i++) { datalen = sizeof(person_struct); memcpy(databf, &gnebffer-> postbf.recs[i].personrecord, datalen); stats = BTRVID( B_INSERT, posblock2, databf, &datalen, keybf2, -1, /* no crrency change */ (BTI_BUFFER_PTR)&clientID); } sprintf(tmpbf, Inserted %d records in ne file, stats = %d, gnebffer->postbf.nmretrned, stats); printlb(form1->listbox1, tmpbf); } memset(gnebffer, 0, sizeof(gne_buffer)); memcpy(&gnebffer->prebf.gneheader.crrencyconst[0], EG, 2); } Btrieve Programmer s Reference 267 Langage Interfaces

268 Example A-2 CBBMain.cpp free(gnebffer); gnebffer = NULL; /* close open files */ if (file1open) { datalen = 0; stats = BTRVID( B_CLOSE, posblock1, databf, &datalen, keybf1, keynm, (BTI_BUFFER_PTR)&clientID); } sprintf(tmpbf, Btrieve B_CLOSE stats (sample.btr) = %d, stats ); printlb(form1->listbox1, tmpbf); if (file2open) { datalen = 0; stats = BTRVID( B_CLOSE, posblock2, databf, &datalen, keybf2, keynm, (BTI_BUFFER_PTR)&clientID); Btrieve Programmer s Reference 268 Langage Interfaces

269 Example A-2 CBBMain.cpp sprintf(tmpbf, Btrieve B_CLOSE stats (sample2.btr) = %d, stats ); printlb(form1->listbox1, tmpbf); } /********************************************************** ISSUE THE BTRIEVE STOP OPERATION - For mlti-tasking environments, sch as MS Windos, OS2, and NLM, stop frees all Btrieve resorces for this client. In DOS and Extended DOS, it removes the Btrieve engine from memory. In mltitasking environments, the engine ill not nload on stop nless it has no more clients. **********************************************************/ if (btrieveloaded) { datalen = 0; stats = BTRVID(B_STOP, posblock1, databf, &datalen, keybf1, keynm,(bti_buffer_ptr)&clientid); sprintf(tmpbf, Btrieve B_STOP stats = %d, stats ); printlb(form1->listbox1, tmpbf); if (stats!= B_NO_ERROR) { stats = EXIT_WITH_ERROR; } } } retrn(stats); Btrieve Programmer s Reference 269 Langage Interfaces

270 Cobol Animated Cobol developers: The Cobol animator passes stack parameters from left to right, hile the non-animated Cobol interface passes parameters from right to left. Hoever, Cobol passes integers in the Intel high-lo format for both animated and nonanimated applications. Also, the object modles MF2BtrV.OBJ & CSUPPORT.OBJ have been dropped from the Cobol interface. Use the modle COBRBtrV.OBJ in place of these. Non-animated Cobol developers: All nmerical vales passed to the MicroKernel as a parameter mst be in the Intel format (lo-high byte order). To accomplish this, define the vales as COMP-5. OS/2 non-animated developers: For an OS/2 modle, define OS2=1 to yor assembler. If yo do not, then the assembled modle is for DOS. Program Example The folloing example program, hich is inclded on yor distribtion media, shos ho to perform several of the more common Btrieve operations, and it performs those operations in the order reqired by the MicroKernel s dependencies (for example, yo mst open a file before performing I/O to it). Example A-3 Btrsamp.cbl * * * Copyright 1998 Pervasive Softare Inc. All Rights Reserved * Btrieve Programmer s Reference 270 Langage Interfaces

271 Example A-3 Btrsamp.cbl contined * * BTRSAMP.CBL * This is a sample COBOL program that makes Btrieve calls * from an application sing Micro Focs COBOL v3.x. * * IDENTIFICATION DIVISION. * PROGRAM-ID. TEST1. * * ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-PC. OBJECT-COMPUTER. IBM-PC. * * DATA DIVISION. * WORKING-STORAGE SECTION. * * BTRIEVE OP CODES * 01 B-OPEN PIC 9(4) COMP-5 VALUE B-INSERT PIC 9(4) COMP-5 VALUE B-GETFIRST PIC 9(4) COMP-5 VALUE B-UPDATE PIC 9(4) COMP-5 VALUE B-CLOSE PIC 9(4) COMP-5 VALUE 1. * 01 B-STATUS PIC 9(4) COMP-5 VALUE KEY-NUMBER PIC 9(4) COMP-5 VALUE 0. Btrieve Programmer s Reference 271 Langage Interfaces

272 Example A-3 Btrsamp.cbl contined 01 BUF-LEN PIC 9(4) COMP-5 VALUE FILE-NAME PIC X(13) VALUE SPACES. 01 POSITION-BLOCK PIC X(128) VALUE SPACES. 01 DATA-BUFFER. 02 DECIMAL-FIELD PIC 9(4) COMP-3 VALUE STRING-FIELD PIC X(36) VALUE SPACES. 01 DSP-STATUS PIC 9(5) COMP-5. * * * PROCEDURE DIVISION. BEGIN. * * Open TEST.BTR * * MOVE 0 TO BUF-LEN. MOVE 0 TO KEY-NUMBER. MOVE TEST.BTR TO FILE-NAME. CALL _BTRV USING B-OPEN, B-STATUS, POSITION-BLOCK, DATA-BUFFER, BUF-LEN, FILE-NAME, KEY-NUMBER. IF B-STATUS NOT = 0 DISPLAY Error opening file. Stats= B-STATUS ELSE DISPLAY File FILE-NAME sccessflly opened END-IF. * * Insert into TEST.BTR * * Btrieve Programmer s Reference 272 Langage Interfaces

273 Example A-3 Btrsamp.cbl contined MOVE 1 TO DECIMAL-FIELD. MOVE Record 1 TO STRING-FIELD. MOVE 40 TO BUF-LEN. MOVE 0 TO KEY-NUMBER CALL _BTRV USING B-INSERT, B-STATUS, POSITION-BLOCK, DATA-BUFFER, BUF-LEN, FILE-NAME, KEY-NUMBER. IF B-STATUS NOT = 0 DISPLAY Error inserting into file. Stats= B- STATUS ELSE DISPLAY Inserted: DECIMAL-FIELD STRING-FIELD END-IF. * * GetFirst * * MOVE 40 TO BUF-LEN. MOVE 0 TO KEY-NUMBER CALL _BTRV USING B-GETFIRST, B-STATUS, POSITION- BLOCK, DATA-BUFFER, BUF-LEN, FILE-NAME, KEY-NUMBER. IF B-STATUS NOT = 0 DISPLAY Error Getting first record. Stats= B- STATUS ELSE DISPLAY Retrieved: DECIMAL-FIELD STRING-FIELD END-IF. * * Update into TEST.BTR Btrieve Programmer s Reference 273 Langage Interfaces

274 Example A-3 Btrsamp.cbl contined * * MOVE 2 TO DECIMAL-FIELD. MOVE Record 2 TO STRING-FIELD. MOVE 40 TO BUF-LEN. MOVE 0 TO KEY-NUMBER CALL _BTRV USING B-UPDATE, B-STATUS, POSITION-BLOCK, DATA-BUFFER, BUF-LEN, FILE-NAME, KEY-NUMBER. IF B-STATUS NOT = 0 DISPLAY Error pdating file. Stats= B-STATUS ELSE DISPLAY Updated to: DECIMAL-FIELD STRING-FIELD END-IF. * * Close TEST.BTR * * MOVE 0 TO BUF-LEN. MOVE 0 TO KEY-NUMBER CALL _BTRV USING B-CLOSE, B-STATUS, POSITION-BLOCK, DATA-BUFFER, BUF-LEN, FILE-NAME, KEY-NUMBER. IF B-STATUS NOT = 0 DISPLAY Error closing file. Stats= B-STATUS ELSE DISPLAY Sccessflly closed TEST.BTR END-IF. STOP RUN. Btrieve Programmer s Reference 274 Langage Interfaces

275 Delphi This section discsses the folloing topics: Program Example Compiling, Linking, and Rnning the Program Example Program Example The folloing example program, hich is inclded on yor distribtion media, shos ho to perform several of the more common Btrieve operations, and it performs those operations in the order reqired by the MicroKernel s dependencies (for example, yo mst open a file before performing I/O to it). Example A-4 Btrsam32.pas {********************************************************** ** ** Copyright 1998 Pervasive Softare Inc. All Rights Reserved ** ***********************************************************} {********************************************************** BTRSAM32.DPR This is a simple sample designed to allo yo to confirm yor ability to compile, link, and execte a Btrieve application for yor target 32-bit environment sing yor compiler tools. This program demonstrates the Delphi interface for Btrieve on 32-Bit MS Windos NT and Windos 95, for Delphi 2.0 and 3.0. Btrieve Programmer s Reference 275 Langage Interfaces

276 Example A-4 Btrsam32.pas contined This program does the folloing operations on the sample file: - gets the Microkernel Database Engine version sing BTRVID - opens sample.btr - gets a record on a knon vale of Key 0 - displays the retrieved record - performs a stat operation - creates an empty clone of sample.btr and opens it - performs a Get Next Extended operation to extract a sbset of the records in sample.btr - inserts those records into the cloned file - closes both files IMPORTANT: Yo mst specify the complete path to the directory that contains the sample Btrieve data file, sample.btr. See IMPORTANT, belo. Delphi 2.0/3.0 Btrieve projects mst be compiled after selecting the folloing from the Delphi project environment pll-don mens: PROJECT OPTIONS... COMPILER CODE GENERATION ALIGNED RECORD FIELDS ( de-select this ) Btrieve Programmer s Reference 276 Langage Interfaces

277 Example A-4 If yo don t do this step, hen the record is printed ot, it ill seem jmbled becase the record strctre is not byte-packed. Yo may, instead, se the (*A-*) compiler directive, or declare all records as packed, as shon belo. For more information, see the Delphi docmentation. PROJECT FILES: - btr32.dpr Borland project file - btr32.dof Borland project file - btrsam32.dfm Borland project file - btrsam32.pas Sorce code for the simple sample - btrapi32.pas Delphi interface to Btrieve - btrconst.pas Btrieve constants file **********************************************************} nit btrsam32; interface Btrsam32.pas contined ses Windos, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls, BtrConst, BtrAPI32; {*********************************************************** Program Constants ***********************************************************} const { program constants } MY_THREAD_ID = 50; EXIT_WITH_ERROR = 1; Btrieve Programmer s Reference 277 Langage Interfaces

278 Example A-4 Btrsam32.pas contined VERSION_OFFSET = 0; REVISION_OFFSET = 2; PLATFORM_ID_OFFSET = 4; {********************************************************** IMPORTANT: Yo shold modify the folloing to specify the complete path to sample.btr for yor environment. **********************************************************} FILE_1 = c:\pvs\samples\sample.btr ; FILE_2 = c:\pvs\samples\sample2.btr ; {*********************************************************** Record type definitions for Version operation ***********************************************************} type CLIENT_ID = packed record netorkandnode : array[1..12] of char; applicationid : array[1..3] of char; threadid : smallint; end; VERSION_STRUCT = packed record version : smallint; revision : smallint; MKDEId : char; end; {*********************************************************** Definition of record from sample.btr ***********************************************************} Btrieve Programmer s Reference 278 Langage Interfaces

279 Example A-4 Btrsam32.pas contined {* Use zero-based arrays of char for riteln() compatibility *} PERSON_STRUCT = packed record ID : longint; FirstName : array[0..15] of char; LastName : array[0..25] of char; Street : array[0..30] of char; City : array[0..30] of char; State : array[0..2] of char; Zip : array[0..10] of char; Contry : array[0..20] of char; Phone : array[0..13] of char; end; {*********************************************************** Record type definitions for Stat and Create operations ***********************************************************} FILE_SPECS = packed record reclength : smallint; pagesize : smallint; indexcont : smallint; reserved : array[0..3] of char; flags : smallint; dppointers : byte; notused : byte; allocations : smallint; end; KEY_SPECS = packed record position : smallint; length : smallint; Btrieve Programmer s Reference 279 Langage Interfaces

280 Example A-4 Btrsam32.pas contined flags : smallint; reserved : array [0..3] of char; keytype : char; nllchar : char; notused : array[0..1] of char; manalkeynmber : byte; acsnmber : byte; end; FILE_CREATE_BUF = packed record filespecs : FILE_SPECS; keyspecs : array[0..4] of KEY_SPECS; end; {*********************************************************** Record type definitions for Get Next Extended operation **********************************************************} GNE_HEADER = packed record descriptionlen : smallint; crrencyconst : array[0..1] of char; rejectcont : smallint; nmberterms : smallint; end; TERM_HEADER = packed record fieldtype : byte; fieldlen : smallint; fieldoffset : smallint; comparisoncode : byte; connector : byte; Btrieve Programmer s Reference 280 Langage Interfaces

281 Example A-4 vale end; Btrsam32.pas contined : array[0..2] of char; RETRIEVAL_HEADER = packed record maxrecstoretrieve : smallint; nofieldstoretrieve : smallint; end; FIELD_RETRIEVAL_HEADER = packed record fieldlen : smallint; fieldoffset : smallint; end; PRE_GNE_BUFFER = packed record gneheader : GNE_HEADER; term1 : TERM_HEADER; term2 : TERM_HEADER; retrieval : RETRIEVAL_HEADER; recordret : FIELD_RETRIEVAL_HEADER; end; RETURNED_REC = packed record reclen : smallint; recpos : longint; personrecord : PERSON_STRUCT; end; POST_GNE_BUFFER = packed record nmretrned : smallint; recs : packed array[0..19] of RETURNED_REC; end; Btrieve Programmer s Reference 281 Langage Interfaces

282 Example A-4 Btrsam32.pas contined GNE_BUFFER_PTR = ^GNE_BUFFER; GNE_BUFFER = packed record case byte of 1 : (prebf : PRE_GNE_BUFFER); 2 : (postbf : POST_GNE_BUFFER); end; {*********************************************************** Delphi-generated form definition ***********************************************************} TForm1 = class(tform) RnBtton: TBtton; ExitBtton: TBtton; ListBox1: TListBox; procedre FormCreate(Sender: TObject); procedre ExitBttonClick(Sender: TObject); procedre RnBttonClick(Sender: TObject); private { Private declarations } ArroCrsor, WaitCrsor: HCrsor; stats: smallint; bfferlength: smallint; personrecord: PERSON_STRUCT; recordsread: longint; procedre RnTest; pblic { Pblic declarations } end; Btrieve Programmer s Reference 282 Langage Interfaces

283 Example A-4 var Form1: TForm1; {*********************************************************** Program starts here ***********************************************************} implementation {$R *.DFM} Btrsam32.pas contined {********************************************************** Program Variables ***********************************************************} var { Btrieve fnction parameters } posblock1 : string[128]; posblock2 : string[128]; databffer : array[0..255] of char; datalen : ord; keybf1 : string[255]; keybf2 : string[255]; keynm : smallint; btrieveloaded : boolean; personid : longint; file1open : boolean; file2open : boolean; stats : smallint; getstats : smallint; i : smallint; posctr : smallint; Btrieve Programmer s Reference 283 Langage Interfaces

284 Example A-4 Btrsam32.pas contined client : CLIENT_ID; versionbffer : array[1..3] of VERSION_STRUCT; filecreatebf : FILE_CREATE_BUF; gnebffer : GNE_BUFFER_PTR; personrecord : PERSON_STRUCT; {********************************************************** A helper procedre to rite to the ListBox ***********************************************************} procedre WritelnLB( LB: TListBox; Str: String); begin LB.Items.Add(Str); end; procedre TForm1.FormCreate(Sender: TObject); begin ArroCrsor := LoadCrsor(0, IDC_ARROW); WaitCrsor := LoadCrsor(0, IDC_WAIT); end; {********************************************************** This is the main procedre of the sample ***********************************************************} procedre TForm1.RnTest; begin ListBox1.Clear; WritelnLB( ListBox1, Test started... ); { initialize variables } btrieveloaded := FALSE; file1open := FALSE; Btrieve Programmer s Reference 284 Langage Interfaces

285 Example A-4 Btrsam32.pas contined file2open := FALSE; keynm := 0; stats := B_NO_ERROR; getstats := B_NO_ERROR; { set p the Client ID } fillchar(client.netorkandnode, sizeof(client.netorkandnode), #0); client.applicationid := MT + #0; { mst be greater than AA } client.threadid := MY_THREAD_ID; fillchar(versionbffer, sizeof(versionbffer), #0); datalen := sizeof(versionbffer); stats := BTRVID( B_VERSION, posblock1, versionbffer, datalen, keybf1[1], keynm, client); if stats = B_NO_ERROR then begin ritelnlb( ListBox1, Btrieve Versions retrned are: ); for i := 1 to 3 do begin ith versionbffer[i] do begin if (version > 0) then begin ritelnlb(listbox1, inttostr(version) +. + inttostr(revision) + + MKDEId); Btrieve Programmer s Reference 285 Langage Interfaces

286 Example A-4 Btrsam32.pas contined end end end; btrieveloaded := TRUE; end else begin ritelnlb(listbox1, Btrieve B_VERSION stats = + inttostr(stats)); if stats <> B_RECORD_MANAGER_INACTIVE then begin btrieveloaded := TRUE; end end; { open sample.btr } if stats = B_NO_ERROR then begin fillchar(databffer, sizeof(databffer), #0); fillchar(keybf1, sizeof(keybf1), #0); keynm := 0; datalen := 0; keybf1 := FILE_1 + #0; keybf2 := FILE_2 + #0; stats := BTRVID( B_OPEN, posblock1, databffer, datalen, keybf1[1], keynm, client); Btrieve Programmer s Reference 286 Langage Interfaces

287 Example A-4 Btrsam32.pas contined ritelnlb(listbox1, Btrieve B_OPEN stats = + inttostr(stats)); if stats = B_NO_ERROR then begin file1open := TRUE; end end; {* get the record sing key 0 = a knon vale sing B_GET_EQUAL *} if stats = B_NO_ERROR then begin fillchar(personrecord, sizeof(personrecord), #0); datalen := sizeof(personrecord); personid := ; {* this is really a social secrity nmber *} stats := BTRVID( B_GET_EQUAL, posblock1, personrecord, datalen, personid, keynm, client); ritelnlb(listbox1, Btrieve B_GET_EQUAL stats = + inttostr(stats)); if stats = B_NO_ERROR then ith personrecord do begin ritelnlb(listbox1, ); ritelnlb(listbox1, Selected fields from the retrieved record are: ); ritelnlb(listbox1, ID: + inttostr(id)); Btrieve Programmer s Reference 287 Langage Interfaces

288 Example A-4 Btrsam32.pas contined ritelnlb(listbox1, Name: + FirstName + + LastName); ritelnlb(listbox1, Street: + Street); ritelnlb(listbox1, City: + City); ritelnlb(listbox1, State: + State); ritelnlb(listbox1, Zip: + Zip); ritelnlb(listbox1, Contry: + Contry); ritelnlb(listbox1, Phone: + Phone); ritelnlb(listbox1, ); end; end; { perform a stat operation to poplate the create bffer } fillchar(filecreatebf, sizeof(filecreatebf), #0); datalen := sizeof(filecreatebf); keynm := -1; stats := BTRVID(B_STAT, posblock1, filecreatebf, datalen, keybf1[1], keynm, client); if (stats = B_NO_ERROR) then begin { create and open sample2.btr } keynm := 0; datalen := sizeof(filecreatebf); stats := BTRVID(B_CREATE, posblock2, filecreatebf, Btrieve Programmer s Reference 288 Langage Interfaces

289 Example A-4 Btrsam32.pas contined datalen, keybf2[1], keynm, client); ritelnlb(listbox1, Btrieve B_CREATE stats = + inttostr(stats)); end; if (stats = B_NO_ERROR) then begin keynm := 0; datalen := 0; stats := BTRVID( B_OPEN, posblock2, databffer, datalen, keybf2[1], keynm, client); ritelnlb(listbox1, Btrieve B_OPEN stats = + inttostr(stats)); if (stats = B_NO_ERROR) then begin file2open := TRUE; end; end; { no extract data from the original file, insert into ne one } if (stats = B_NO_ERROR) then begin Btrieve Programmer s Reference 289 Langage Interfaces

290 Example A-4 Btrsam32.pas contined { getfirst to establish crrency } keynm := 2; { STATE-CITY index } fillchar(personrecord, sizeof(personrecord), #0); fillchar(keybf1, sizeof(keybf1), #0); datalen := sizeof(personrecord); getstats := BTRVID( B_GET_FIRST, posblock1, personrecord, datalen, keybf1[1], keynm, client); ritelnlb(listbox1, Btrieve B_GET_FIRST stats = + inttostr(getstats)); ritelnlb(listbox1, ); end; { Allocate memory on heap } gnebffer := ne(gne_buffer_ptr); fillchar(gnebffer^, sizeof(gne_buffer), #0); strpcopy(gnebffer^.prebf.gneheader.crrencyconst, UC ); hile (getstats = B_NO_ERROR) do begin gnebffer^.prebf.gneheader.rejectcont := 0; gnebffer^.prebf.gneheader.nmberterms := 2; posctr := sizeof(gne_header); { fill in the first condition } Btrieve Programmer s Reference 290 Langage Interfaces

291 Example A-4 Btrsam32.pas contined gnebffer^.prebf.term1.fieldtype := 11; gnebffer^.prebf.term1.fieldlen := 3; gnebffer^.prebf.term1.fieldoffset := 108; gnebffer^.prebf.term1.comparisoncode := 1; gnebffer^.prebf.term1.connector := 2; strpcopy(gnebffer^.prebf.term1.vale, TX ); inc(posctr, (sizeof(term_header))); { fill in the second condition } gnebffer^.prebf.term2.fieldtype := 11; gnebffer^.prebf.term2.fieldlen := 3; gnebffer^.prebf.term2.fieldoffset := 108; gnebffer^.prebf.term2.comparisoncode := 1; gnebffer^.prebf.term2.connector := 0; strpcopy(gnebffer^.prebf.term2.vale, CA ); inc(posctr, sizeof(term_header)); { fill in the projection header to retrieve hole record } gnebffer^.prebf.retrieval.maxrecstoretrieve := 20; gnebffer^.prebf.retrieval.nofieldstoretrieve := 1; inc(posctr, sizeof(retrieval_header)); gnebffer^.prebf.recordret.fieldlen := sizeof(person_struct); gnebffer^.prebf.recordret.fieldoffset := 0; inc(posctr, sizeof(field_retrieval_header)); gnebffer^.prebf.gneheader.descriptionlen := posctr; datalen := sizeof(gne_buffer); getstats := BTRVID( B_GET_NEXT_EXTENDED, Btrieve Programmer s Reference 291 Langage Interfaces

292 Example A-4 Btrsam32.pas contined posblock1, gnebffer^, datalen, keybf1, keynm, client); ritelnlb(listbox1, Btrieve B_GET_NEXT_EXTENDED stats = + inttostr(getstats)); { Get Next Extended can reach end of file and still retrn some records } if ((getstats = B_NO_ERROR) or (getstats = B_END_OF_FILE)) then begin ritelnlb(listbox1, GetNextExtended retrned + inttostr(gnebffer^.postbf.nmretrned) + records. ); for i := 0 to gnebffer^.postbf.nmretrned - 1 do begin datalen := sizeof(person_struct); personrecord := gnebffer^.postbf.recs[i].personrecord; stats := BTRVID( B_INSERT, posblock2, personrecord, datalen, keybf2, -1, { no crrency change } client); if (stats <> B_NO_ERROR) then begin Btrieve Programmer s Reference 292 Langage Interfaces

293 Example A-4 Btrsam32.pas contined ritelnlb(listbox1, Btrieve B_INSERT stats = + inttostr(stats)); break; end; end; ritelnlb(listbox1, Inserted + inttostr(gnebffer^.postbf.nmretrned) + records in ne file, stats = + inttostr(stats)); ritelnlb(listbox1, ); end; fillchar(gnebffer^, sizeof(gne_buffer), #0); gnebffer^.prebf.gneheader.crrencyconst := EG ; end; dispose(gnebffer); { close open files } keynm := 0; if file1open = TRUE then begin datalen := 0; stats := BTRVID( B_CLOSE, posblock1, databffer, datalen, keybf1[1], keynm, client); Btrieve Programmer s Reference 293 Langage Interfaces

294 Example A-4 ritelnlb(listbox1, Btrieve B_CLOSE stats (sample.btr) = + inttostr(stats)); end; if file2open = TRUE then begin datalen := 0; stats := BTRVID( B_CLOSE, posblock2, databffer, datalen, keybf2[1], keynm, client); ritelnlb(listbox1, Btrieve B_CLOSE stats (sample2.btr) = + inttostr(stats)); end; { FREE RESOURCES } datalen := 0; stats := BTRVID( B_STOP, posblock1, DataBffer, datalen, keybf1[1], 0, client ); WritelnLB(ListBox1, Btrieve B_STOP stats = + inttostr(stats) ); end; Btrsam32.pas contined procedre TForm1.ExitBttonClick(Sender: TObject); begin Btrieve Programmer s Reference 294 Langage Interfaces

295 Example A-4 Close; end; Btrsam32.pas contined procedre TForm1.RnBttonClick(Sender: TObject); begin SetCrsor(WaitCrsor); RnTest; SetCrsor(ArroCrsor); end; end. Compiling, Linking, and Rnning the Program Example In Delphi 3, to compile, link, and rn the program example: 1. Choose Ne Application from the File men. 2. Choose Open from the File men and open the B32.dpr project file in the \Intf\Delphi directory. 3. In the BtrSam32.pas file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. 4. Click the Rn btton on the toolbar. Delphi compiles and links the program example. 5. Click the Rn Test btton in the Btrieve Sample Application indo. Delphi rns the program example. Btrieve Programmer s Reference 295 Langage Interfaces

296 In Delphi 1, to compile, link, and rn the program example: 1. Choose Open Project from the File men and open the B16.dpr project file in the \Intf\Delphi directory. 2. In the BtrSam16.pas file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. 3. Click the Rn btton on the toolbar. Delphi compiles and links the program example. 4. Click the Rn Test btton in the Btrieve Sample Application indo. Delphi rns the program example. Btrieve Programmer s Reference 296 Langage Interfaces

297 Pascal This section discsses the folloing topics: Sorce Modles Compiling and Linking Using the Interface Program Example Programming Notes Sorce Modles The Pascal interface is comprised of the folloing sorce modles: BtrApiD.PAS Btrieve fnctions interface nit for 16-bit DOS. BtrApiW.PAS Btrieve fnctions interface nit for Win16. BtrConst.PAS Common Btrieve constants nit. BtrSampD.PAS Sample Btrieve program for 16-bit DOS. BtrSampW.PAS Sample Btrieve program for Win16. BtrApiD.PAS and BtrApiW.PAS The files BtrApiD.PAS and BtrApiW.PAS contain the sorce code implementation of the Pascal application interface for 16-bit DOS and Win16. These files provide spport for applications calling Btrieve fnctions. Btrieve Programmer s Reference 297 Langage Interfaces

298 In order for Trbo Pascal to properly compile and link the Btrieve interface ith the other modles in yor application, yo can compile BtrApiD.PAS or BtrApiW.PAS to create a Trbo Pascal nit hich yo then list in the ses clase of yor application s sorce code. BtrConst.PAS The file BtrConst.PAS contains sefl constants specific to Btrieve. These constants can help yo standardize references to Btrieve operation codes, stats codes, file specification flags, key specification flags, and many more items. To se BtrConst.PAS, yo can compile it to create a Trbo Pascal nit hich yo then list in the ses clase of yor application s sorce code. Yo can se the Pascal application interface ithot taking advantage of BtrConst.PAS; hoever, sing the file may simplify yor programming effort. BtrSampD.PAS and BtrSampW.PAS The sorce files BtrSampD.PAS and BtrSampW.PAS are sample Btrieve programs that yo can compile, link, and rn. Btrieve Programmer s Reference 298 Langage Interfaces

299 Compiling and Linking Using the Interface This section provides instrctions for some common development environments. If yor development environment is not discssed, yo can adapt these instrctions. Using Borland Pascal 7 for Windos, to compile, link, and rn the program example: 1. Choose Open from the File men and open the BtrSampW.pas file. 2. In the BtrSampW.pas file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. 3. Choose Make from the Compile men. Click OK. Borland Pascal compiles and links the program example. 4. Choose Rn from the Rn men. Borland Pascal rns the program example. Using Borland Pascal 7 for DOS, to compile, link, and rn the program example: 1. Choose Open from the File men and open the folloing files: \Intf\Pascal\BtrConst.pas \Intf\Pascal\BtrApiD.pas \Intf\Pascal\BtrSampD.pas 2. In the BtrSampD.pas file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. 3. Choose Compiler from the Options men and set the Conditional Defines to BTI_DOS. Btrieve Programmer s Reference 299 Langage Interfaces

300 4. Choose Directories from the Options men and set EXE and TPU to the \Intf\Pascal directory. 5. In the BtrConst.pas file, choose Make from the Compile men. 6. In the BtrApiD.pas file, choose Make from the Compile men. 7. In the BtrSampD.pas file, choose Make from the Compile men. 8. In a DOS prompt, rn BtrSampD.exe. Note The program example ses the BtrvID call; therefore, yo mst load the Btrieve DOS Reqester ith the /T:1 flag. Also, yo mst load the appropriate Reqester (BReqest for NetWare servers and BReqNT for Windos NT servers). Using Borland Trbo Pascal 1.5 for Windos, to compile, link, and rn the program example: 1. Choose Open from the File men and open the folloing files: \Intf\Pascal\BtrConst.pas \Intf\Pascal\BtrApiW.pas \Intf\Pascal\BtrSampW.pas 2. In the BtrSampW.pas file, edit the paths to the Sample.btr and Sample2.btr files as appropriate. 3. In the BtrConst.pas file, choose Make from the Compile men. 4. In the BtrApiW.pas file, choose Make from the Compile men. 5. In the BtrSampW.pas file, choose Make from the Compile men. 6. Choose Rn from the Rn men. Borland Trbo Pascal rns the program example. Btrieve Programmer s Reference 300 Langage Interfaces

301 Program Example The folloing example program, hich is inclded on yor distribtion media, shos ho to perform several of the more common Btrieve operations, and it performs those operations in the order reqired by the MicroKernel s dependencies (for example, yo mst open a file before performing I/O to it). Example A-5 Btrsamp.pas {********************************************************** ** ** Copyright 1998 Pervasive Softare Inc. All Rights Reserved ** ***********************************************************} {********************************************************** BTRSAMPW.PAS This program demonstrates the Btrieve Interface for MS Windos sing Borland Pascal version 7.0 or Trbo Pascal for Windos version 1.5. This program does the folloing operations on the sample file: - gets the Microkernel Database Engine version sing BTRVID - opens sample.btr - gets a record on a knon vale of Key 0 - displays the retrieved record - performs a stat operation - creates an empty clone of sample.btr and opens it - performs a Get Next Extended operation to extract a sbset of the records in sample.btr - inserts those records into the cloned file - closes both files Btrieve Programmer s Reference 301 Langage Interfaces

302 Example A-5 Btrsamp.pas contined IMPORTANT: Yo mst specify the complete path to the directory that contains the sample Btrieve data file, sample.btr. See IMPORTANT, belo. ***********************************************************} program btrsamp; ses WinCrt, { text mode I/O library for Windos } Strings, { Pascal System fnctions } btrapi, { btrieve interface nit } btrconst; { Btrieve Constants Unit } const {********************************************************* IMPORTANT: Yo shold modify the folloing to specify the complete path to sample.btr for yor environment. **********************************************************} FILE1_NAME = c:\pvs\samples\sample.btr + #0; FILE2_NAME = c:\pvs\samples\sample2.btr + #0; { program constants } MY_THREAD_ID = 50; EXIT_WITH_ERROR = 1; VERSION_OFFSET = 0; REVISION_OFFSET = 2; PLATFORM_ID_OFFSET = 4; {********************************************************** Record type definitions for Version operation ***********************************************************} Btrieve Programmer s Reference 302 Langage Interfaces

303 Example A-5 Btrsamp.pas contined type CLIENT_ID = packed record netorkandnode : array[0..11] of char; applicationid : array[0..2] of char; threadid : integer; end; VERSION_STRUCT = packed record version : integer; revision : integer; MKDEId : char; end; {********************************************************** Definition of record from sample.btr ***********************************************************} {* Use zero-based arrays of char for riteln() compatibility *} PERSON_STRUCT = packed record ID : longint; FirstName : array[0..15] of char; LastName : array[0..25] of char; Street : array[0..30] of char; City : array[0..30] of char; State : array[0..2] of char; Zip : array[0..10] of char; Contry : array[0..20] of char; Phone : array[0..13] of char; end; Btrieve Programmer s Reference 303 Langage Interfaces

304 Example A-5 Btrsamp.pas contined {********************************************************** Record type definitions for Stat and Create operations ***********************************************************} FILE_SPECS = packed record reclength : integer; pagesize : integer; indexcont : integer; reserved : array[0..3] of char; flags : integer; dppointers : byte; notused : byte; allocations : integer; end; KEY_SPECS = packed record position : integer; length : integer; flags : integer; reserved : array [0..3] of char; keytype : char; nllchar : char; notused : array[0..1] of char; manalkeynmber : byte; acsnmber : byte; end; FILE_CREATE_BUF = packed record filespecs : FILE_SPECS; keyspecs : array[0..4] of KEY_SPECS; end; Btrieve Programmer s Reference 304 Langage Interfaces

305 Example A-5 Btrsamp.pas contined {********************************************************** Record type definitions for Get Next Extended operation ***********************************************************} GNE_HEADER = packed record descriptionlen : integer; crrencyconst : array[0..1] of char; rejectcont : integer; nmberterms : integer; end; TERM_HEADER = packed record fieldtype : byte; fieldlen : integer; fieldoffset : integer; comparisoncode : byte; connector : byte; vale : array[0..2] of char; end; RETRIEVAL_HEADER = packed record maxrecstoretrieve : integer; nofieldstoretrieve : integer; end; FIELD_RETRIEVAL_HEADER = packed record fieldlen : integer; fieldoffset : integer; end; PRE_GNE_BUFFER = packed record Btrieve Programmer s Reference 305 Langage Interfaces

306 Example A-5 Btrsamp.pas contined gneheader : GNE_HEADER; term1 : TERM_HEADER; term2 : TERM_HEADER; retrieval : RETRIEVAL_HEADER; recordret : FIELD_RETRIEVAL_HEADER; end; RETURNED_REC = packed record reclen : integer; recpos : longint; personrecord : PERSON_STRUCT; end; POST_GNE_BUFFER = packed record nmretrned : integer; recs : packed array[0..19] of RETURNED_REC; end; GNE_BUFFER_PTR = ^GNE_BUFFER; GNE_BUFFER = packed record case byte of 1 : (prebf : PRE_GNE_BUFFER); 2 : (postbf : POST_GNE_BUFFER); end; {********************************************************** Variables ***********************************************************} var { Btrieve fnction parameters } posblock1 : string[128]; Btrieve Programmer s Reference 306 Langage Interfaces

307 Example A-5 posblock2 databffer datalen keybf1 keybf2 keynm Btrsamp.pas contined btrieveloaded : boolean; personid : longint; file1open : boolean; file2open : boolean; stats : integer; getstats : integer; i : integer; posctr : integer; : string[128]; : array[0..255] of char; : ord; : string[255]; : string[255]; : integer; client : CLIENT_ID; versionbffer : array[1..3] of VERSION_STRUCT; filecreatebf : FILE_CREATE_BUF; gnebffer : GNE_BUFFER_PTR; personrecord : PERSON_STRUCT; {********************************************************** Program starts here ***********************************************************} begin { btrsamp } { initialize variables } btrieveloaded := FALSE; file1open := FALSE; file2open := FALSE; keynm := 0; Btrieve Programmer s Reference 307 Langage Interfaces

308 Example A-5 Btrsamp.pas contined stats := B_NO_ERROR; getstats := B_NO_ERROR; riteln; riteln( ************ Btrieve Pascal Interface for Windos Demo ************ ); riteln; { set p the Client ID } fillchar(client.netorkandnode, sizeof(client.netorkandnode), #0); {$ifdef ver70} {Note: Delphi 1.0 is ver80} client.applicationid := MT + #0; { mst be greater than AA } {$else} strpcopy(client.applicationid, MT ); { mst be greater than AA } strcat(client.applicationid, #0); {$endif} client.threadid := MY_THREAD_ID; fillchar(versionbffer, sizeof(versionbffer), #0); datalen := sizeof(versionbffer); stats := BTRVID( B_VERSION, posblock1, versionbffer, datalen, Btrieve Programmer s Reference 308 Langage Interfaces

309 Example A-5 Btrsamp.pas contined keybf1[1], keynm, client); if stats = B_NO_ERROR then begin riteln( Btrieve Versions retrned are: ); for i := 1 to 3 do begin ith versionbffer[i] do begin if (version > 0) then begin riteln(version,., revision,, MKDEId); end end end; btrieveloaded := TRUE; end else begin riteln( Btrieve B_VERSION stats =, stats); if stats <> B_RECORD_MANAGER_INACTIVE then begin btrieveloaded := TRUE; end end; {* open sample.btr *} if stats = B_NO_ERROR then begin fillchar(databffer, sizeof(databffer), #0); fillchar(keybf1, sizeof(keybf1), #0); keynm := 0; datalen := 0; keybf1 := FILE1_NAME; keybf2 := FILE2_NAME; Btrieve Programmer s Reference 309 Langage Interfaces

310 Example A-5 Btrsamp.pas contined stats := BTRVID( B_OPEN, posblock1, databffer, datalen, keybf1[1], keynm, client); riteln( Btrieve B_OPEN stats =, stats); if stats = B_NO_ERROR then begin file1open := TRUE; end end; {* get the record sing key 0 = a knon vale sing B_GET_EQUAL *} if stats = B_NO_ERROR then begin fillchar(personrecord, sizeof(personrecord), #0); datalen := sizeof(personrecord); personid := ; {* this is really a social secrity nmber *} stats := BTRVID( B_GET_EQUAL, posblock1, personrecord, datalen, personid, keynm, client); Btrieve Programmer s Reference 310 Langage Interfaces

311 Example A-5 Btrsamp.pas contined riteln( Btrieve B_GET_EQUAL stats =, stats); if stats = B_NO_ERROR then ith personrecord do begin riteln; riteln( Selected fields from the retrieved record are: ); riteln( ID:, ID); riteln( Name:, FirstName,, LastName); riteln( Street:, Street); riteln( City:, City); riteln( State:, State); riteln( Zip:, Zip); riteln( Contry:, Contry); riteln( Phone: riteln; end; end;, Phone); { perform a stat operation to poplate the create bffer } fillchar(filecreatebf, sizeof(filecreatebf), #0); datalen := sizeof(filecreatebf); keynm := -1; stats := BTRVID(B_STAT, posblock1, filecreatebf, datalen, keybf1[1], keynm, client); Btrieve Programmer s Reference 311 Langage Interfaces

312 Example A-5 Btrsamp.pas contined if (stats = B_NO_ERROR) then begin { create and open sample2.btr } keynm := 0; datalen := sizeof(filecreatebf); stats := BTRVID(B_CREATE, posblock2, filecreatebf, datalen, keybf2[1], keynm, client); riteln( Btrieve B_CREATE stats =, stats); end; if (stats = B_NO_ERROR) then begin keynm := 0; datalen := 0; stats := BTRVID( B_OPEN, posblock2, databffer, datalen, keybf2[1], keynm, client); riteln( Btrieve B_OPEN stats (sample2.btr) =, stats); if (stats = B_NO_ERROR) then begin file2open := TRUE; end; Btrieve Programmer s Reference 312 Langage Interfaces

313 Example A-5 end; Btrsamp.pas contined { no extract data from the original file, insert into ne one } if (stats = B_NO_ERROR) then begin { getfirst to establish crrency } keynm := 2; { STATE-CITY index } fillchar(personrecord, sizeof(personrecord), #0); fillchar(keybf1, sizeof(keybf1), #0); datalen := sizeof(personrecord); getstats := BTRVID( B_GET_FIRST, posblock1, personrecord, datalen, keybf1[1], keynm, client); riteln( Btrieve B_GET_FIRST stats (sample.btr) =, getstats); riteln; end; if maxavail < SizeOf(GNE_BUFFER) then begin riteln( Insfficient memory to allocate bffer ); halt(exit_with_error); end else begin { Allocate memory on heap } gnebffer := ne(gne_buffer_ptr); Btrieve Programmer s Reference 313 Langage Interfaces

314 Example A-5 Btrsamp.pas contined end; fillchar(gnebffer^, sizeof(gne_buffer), #0); strpcopy(gnebffer^.prebf.gneheader.crrencyconst, UC ); hile (getstats = B_NO_ERROR) do begin gnebffer^.prebf.gneheader.rejectcont := 0; gnebffer^.prebf.gneheader.nmberterms := 2; posctr := sizeof(gne_header); { fill in the first condition } gnebffer^.prebf.term1.fieldtype := 11; gnebffer^.prebf.term1.fieldlen := 3; gnebffer^.prebf.term1.fieldoffset := 108; gnebffer^.prebf.term1.comparisoncode := 1; gnebffer^.prebf.term1.connector := 2; strpcopy(gnebffer^.prebf.term1.vale, TX ); inc(posctr, (sizeof(term_header))); { fill in the second condition } gnebffer^.prebf.term2.fieldtype := 11; gnebffer^.prebf.term2.fieldlen := 3; gnebffer^.prebf.term2.fieldoffset := 108; gnebffer^.prebf.term2.comparisoncode := 1; gnebffer^.prebf.term2.connector := 0; strpcopy(gnebffer^.prebf.term2.vale, CA ); inc(posctr, sizeof(term_header)); { fill in the projection header to retrieve hole record } gnebffer^.prebf.retrieval.maxrecstoretrieve := 20; gnebffer^.prebf.retrieval.nofieldstoretrieve := 1; inc(posctr, sizeof(retrieval_header)); Btrieve Programmer s Reference 314 Langage Interfaces

315 Example A-5 Btrsamp.pas contined gnebffer^.prebf.recordret.fieldlen := sizeof(person_struct); gnebffer^.prebf.recordret.fieldoffset := 0; inc(posctr, sizeof(field_retrieval_header)); gnebffer^.prebf.gneheader.descriptionlen := posctr; datalen := sizeof(gne_buffer); getstats := BTRVID( B_GET_NEXT_EXTENDED, posblock1, gnebffer^, datalen, keybf1, keynm, client); riteln( Btrieve B_GET_NEXT_EXTENDED stats =, getstats); { Get Next Extended can reach end of file and still retrn some records } if ((getstats = B_NO_ERROR) or (getstats = B_END_OF_FILE)) then begin riteln( GetNextExtended retrned, gnebffer^.postbf.nmretrned, records. ); for i := 0 to gnebffer^.postbf.nmretrned - 1 do begin {$ifdef ver70} datalen := sizeof(person_struct); personrecord := gnebffer^.postbf.recs[i].personrecord; Btrieve Programmer s Reference 315 Langage Interfaces

316 Example A-5 Btrsamp.pas contined stats := BTRVID( B_INSERT, posblock2, personrecord, datalen, keybf2, -1, { no crrency change } client); if (stats <> B_NO_ERROR) then begin riteln( Btrieve B_INSERT stats =, stats); break; end; {$else} {Trbo Pascal for Windos 1.5 does not spport break } if (stats = B_NO_ERROR) then begin datalen := sizeof(person_struct); personrecord := gnebffer^.postbf.recs[i].personrecord; stats := BTRVID( B_INSERT, posblock2, personrecord, datalen, keybf2, -1, { no crrency change } client); end; if (stats <> B_NO_ERROR) then begin riteln( Btrieve B_INSERT stats =, stats); end; {$endif} Btrieve Programmer s Reference 316 Langage Interfaces

317 Example A-5 Btrsamp.pas contined end; riteln( Inserted, gnebffer^.postbf.nmretrned, records in ne file, stats =, stats); riteln; end; fillchar(gnebffer^, sizeof(gne_buffer), #0); gnebffer^.prebf.gneheader.crrencyconst := EG ; end; dispose(gnebffer); { close open files } keynm := 0; if file1open = TRUE then begin datalen := 0; stats := BTRVID( B_CLOSE, posblock1, databffer, datalen, keybf1[1], keynm, client); riteln( Btrieve B_CLOSE stats (sample.btr) =, stats); end; if file2open = TRUE then begin datalen := 0; Btrieve Programmer s Reference 317 Langage Interfaces

318 Example A-5 Btrsamp.pas contined stats := BTRVID( B_CLOSE, posblock2, databffer, datalen, keybf2[1], keynm, client); riteln( Btrieve B_CLOSE stats (sample2.btr) =, stats); end; { FREE RESOURCES } datalen := 0; stats := BTRVID(B_STOP, posblock1, DataBffer, datalen, keybf1[1], 0, client); riteln( Btrieve B_STOP stats =, stats) end. Programming Notes Calling a Btrieve fnction alays retrns an INTEGER vale that corresponds to a stats code. After a Btrieve call, yor application shold alays check the vale of this stats code. A Stats Code of 0 indicates a sccessfl operation. Yor application mst be able to recognize and resolve a non-zero stats. Btrieve Programmer s Reference 318 Langage Interfaces

319 Althogh yo mst provide all parameters on every call, the MicroKernel does not se every parameter for every operation. See Chapter 2, Btrieve Operations for a more detailed description of the parameters that are relevant for each operation. Note If yor application ses Pascal record strctres that contain variant strings, consider that odd-length elements in a Pascal record may reqire an extra byte of storage (even if the record is not packed). This is an important consideration hen yo define the record length for the Create (14) operation. See yor Pascal reference manal for more information on record types. Btrieve Programmer s Reference 319 Langage Interfaces

320 Visal Basic This section discsses the folloing topics: Program Example Compiling, Linking, and Rnning the Program Example Creating 32-Bit Applications Program Example The folloing example program shos ho to perform several of the more common Btrieve operations, and it performs those operations in the order reqired by the MicroKernel s dependencies (for example, yo mst open a file before performing I/O to it). Example A-6 Btrsam32.bas Attribte VB_Name = BtrSam32 Rem ******************************************************** Rem Rem Copyright 1998 Pervasive Softare Inc. All Rights Reserved Rem Rem ******************************************************* Rem BTSAMP32.VBP Rem BTRFRM32.FRM Rem BTRSAM32.BAS Btrieve Programmer s Reference 320 Langage Interfaces

321 Example A-6 Btrsam32.bas contined Rem This is an example that demonstrates the Visal Basic Rem interface to Btrieve. A VB program mst se the Rem Windos-specific interface WBTRV32.DLL for 32 bit apps Rem and WBTRCALL.DLL for 16 bit applications. Rem Rem Yo can rn this program ith VB 4.0 nder Windos 3.1, Rem Windos NT, or Windos 95. Rem Rem This example creates a Btrieve file ith 2 keys and then Rem does some insert and read operations on that file. Rem Rem Note abot the Btrieve key bffer size: yor key bffer Rem shold alays be at least as large as the key bffer length Rem parameter that yo spply to Btrieve. If yo indicate that Rem yor key bffer is 10 bytes long and it is only 8, Btrieve Rem may rite past the end of yor key bffer hen pdating Rem the key bffer ith a key vale. Note that Btrieve retrns Rem a key vale in the key bffer after an insert operation. Rem Rem ********************************************************* Rem This sample code shos a orkarond to the Visal Basic Rem Long variable type alignment problem. This problem, hich Rem manifests itself as a stats 29 on BCREATE operations ith Rem more than one index, as an incorrect vale for the total Rem nmber of records in a BSTAT operation, and as incorrect Rem vales for data being retrned as Long variable types, is Rem a design limitation of Visal Basic. Rem Btrieve Programmer s Reference 321 Langage Interfaces

322 Example A-6 Rem We orkarond this strctre member alignment isse by Rem sing a User Defined Type. This orkarond breaks the data Rem into for (4) nits. Each nit is one (1) byte. Once the Rem data has been retrned from the DLL (on BSTAT and in data), Rem e se byte sapping and conversion from Hexadecimal to Rem Decimal to retrn the correct vale. Rem Rem For more information abot the Strctre Member Alignment Rem isse, contact Microsoft or conslt the VB4DLL.TXT file Rem inclded ith Visal Basic. Rem ******************************************************** DefInt A-Z Global Const BOPEN = 0 Global Const BCLOSE = 1 Global Const BINSERT = 2 Global Const BUPDATE = 3 Global Const BDELETE = 4 Global Const BGETEQUAL = 5 Global Const BGETNEXT = 6 Global Const BGETGREATEROREQUAL = 9 Global Const BGETFIRST = 12 Global Const BCREATE = 14 Global Const BSTAT = 15 Global Const BSTOP = 25 Global Const BVERSION = 26 Global Const BRESET = 28 Global Const KEY_BUF_LEN = 255 Rem Key Flags Btrsam32.bas contined Btrieve Programmer s Reference 322 Langage Interfaces

323 Example A-6 Btrsam32.bas contined Global Const DUP = 1 Global Const MODIFIABLE = 2 Global Const BIN = 4 Global Const NUL = 8 Global Const SEGMENT = 16 Global Const SEQ = 32 Global Const DEC = 64 Global Const SUP = 128 Rem Key Types Global Const EXTTYPE = 256 Global Const MANUAL = 512 Global Const BSTRING = 0 Global Const BINTEGER = 1 Global Const BFLOAT = 2 Global Const BDATE = 3 Global Const BTIME = 4 Global Const BDECIMAL = 5 Global Const BNUMERIC = 8 Global Const BZSTRING = 11 Global Const BAUTOINC = 15 Declare Fnction BTRCALL Lib btrv32.dll (ByVal OP, ByVal Pb$, Db As Any, DL As Integer, Kb As Any, ByVal Kl, ByVal Kn) As Integer Rem ***************************************************** Rem Strctres to overcome problems ithin Visal Basic. Rem This User Defined Type allos s to convert the data Rem coming in from (or going to) or interface. By treating Rem the data as a byte e can concatenate the data back Rem into a Long variable type ithot conversion problems. Btrieve Programmer s Reference 323 Langage Interfaces

324 Example A-6 Btrsam32.bas contined Type typ_byte4 fld_field1 As Byte fld_field2 As Byte fld_field3 As Byte fld_field4 As Byte End Type Rem ********************************************************* Rem Btrieve Strctres Type KeySpec KeyPos As Integer KeyLen As Integer KeyFlags As Integer KeyTot As typ_byte4 KeyType As String * 1 Reserved As String * 5 End Type Type FileSpec RecLen As Integer PageSize As Integer IndxCnt As Integer NotUsed As String * 4 FileFlags As Integer Reserved As String * 2 Allocation As Integer KeyBf0 As KeySpec KeyBf1 As KeySpec End Type Btrieve Programmer s Reference 324 Langage Interfaces

325 Example A-6 Btrsam32.bas contined Rem Note that de to the ay Visal Basic 4.0 handles arrays Rem of ser-defined types, the above type ses Rem Rem KeyBf0 As KeySpec Rem KeyBf1 As KeySpec Rem Rem rather than Rem Rem KeyBf(0 To 1) As KeySpec Rem Rem Each Key description mst be a separate entry in the Rem FileSpec. Rem Rem KeyBf is treated similarly in StatFileSpecs, belo. Rem Type StatFileSpecs RecLen As Integer PageSize As Integer IndexTot As Integer RecTot As typ_byte4 FileFlags As Integer Reserved As String * 2 UnsedPages As Integer KeyBf0 As KeySpec KeyBf1 As KeySpec End Type Type RecordBffer Nmber As Doble Btrieve Programmer s Reference 325 Langage Interfaces

326 Example A-6 End Type Btrsam32.bas contined Dmmy As String * 26 Type VersionBf Major As Integer Minor As Integer Engine As String * 1 End Type Global FileBf As FileSpec Global DataBf As RecordBffer Global StatFileBffer As StatFileSpecs Global PosBlk$ Global BfLen As Integer Global DBLen As Integer Sb PrintLB(Item As String) BtrFrm32.List1.AddItem Item End Sb Sb RnTest() PrintLB ( Btrieve Sample Test Started ) PrintLB ( ) Rem Local variables needed for conversion from byte to long. Dim loc_rectot As Long Dim h_field1 As String Dim h_field2 As String Dim h_field3 As String Btrieve Programmer s Reference 326 Langage Interfaces

327 Example A-6 Dim h_field4 Dim h_total Btrsam32.bas contined As String As String Rem ************************** filename$ = XFACE.BTR PosBlk$ = Space$(128) KeyBffer$ = Space$(KEY_BUF_LEN) Rem Rem ***************** Btrieve Create ********************* Rem Rem ************* SET UP FILE SPECS FileBf.RecLen = 34 FileBf.PageSize = 1024 FileBf.IndxCnt = 2 FileBf.FileFlags = 0 Rem ************* SET UP KEY SPECS FileBf.KeyBf0.KeyPos = 1 FileBf.KeyBf0.KeyLen = 8 FileBf.KeyBf0.KeyFlags = EXTTYPE + MODIFIABLE FileBf.KeyBf0.KeyType = Chr$(BFLOAT) FileBf.KeyBf1.KeyPos = 9 FileBf.KeyBf1.KeyLen = 26 FileBf.KeyBf1.KeyFlags = EXTTYPE + MODIFIABLE + DUP FileBf.KeyBf1.KeyType = Chr$(BSTRING) Btrieve Programmer s Reference 327 Langage Interfaces

328 Example A-6 Btrsam32.bas contined BfLen = Len(FileBf) KeyBfLen = Len(filename$) KeyBffer$ = filename$ Stats = BTRCALL(BCREATE, PosBlk$, FileBf, BfLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error Creating File. Stats = + Str$(Stats) PrintLB (Msg$) Else Msg$ = File XFACE.BTR Created Sccessflly! PrintLB (Msg$) End If Open File KeyBfLen = KEY_BUF_LEN KeyBffer$ = filename$ BfLen = Len(DataBf) KeyNm = 0 Stats = BTRCALL(BOPEN, PosBlk$, DataBf, BfLen, ByVal KeyBffer$, KeyBfLen, KeyNm) If Stats <> 0 Then Msg$ = Error Opening file! + Str$(Stats) PrintLB (Msg$) GoTo Fini Else Msg$ = File Opened Sccessflly! PrintLB (Msg$) End If Btrieve Programmer s Reference 328 Langage Interfaces

329 Example A-6 Btrsam32.bas contined Insert First Record yr = 1992 mo = 1 dy = 1 DataBf.Nmber = DateSerial(yr, mo, dy) BfLen = Len(DataBf) KeyBffer$ = Space$(KEY_BUF_LEN) KeyBfLen = KEY_BUF_LEN DataBf.Dmmy = first record Stats = BTRCALL(BINSERT, PosBlk$, DataBf, BfLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error on Insert. + Str$(Stats) PrintLB (Msg$) Else Msg$ = Insert Record #1 Sccessfl! PrintLB (Msg$) End If Insert Second Record yr = 1993 mo = 1 dy = 1 DataBf.Nmber = DateSerial(yr, mo, dy) BfLen = Len(DataBf) KeyBffer$ = Space$(KEY_BUF_LEN) KeyBfLen = KEY_BUF_LEN DataBf.Dmmy = second record Btrieve Programmer s Reference 329 Langage Interfaces

330 Example A-6 Btrsam32.bas contined Stats = BTRCALL(BINSERT, PosBlk$, DataBf, BfLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error on Insert. + Str$(Stats) PrintLB (Msg$) Else Msg$ = Insert Record #2 Sccessfl! PrintLB (Msg$) End If Insert Third Record yr = 1994 mo = 1 dy = 1 DataBf.Nmber = DateSerial(yr, mo, dy) BfLen = Len(DataBf) KeyBffer$ = Space$(KEY_BUF_LEN) KeyBfLen = KEY_BUF_LEN DataBf.Dmmy = third record Stats = BTRCALL(BINSERT, PosBlk$, DataBf, BfLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error on Insert. + Str$(Stats) PrintLB (Msg$) Else Msg$ = Insert Record #3 Sccessfl! PrintLB (Msg$) Btrieve Programmer s Reference 330 Langage Interfaces

331 Example A-6 End If Btrsam32.bas contined Get First Record BfLen = Len(DataBf) KeyBffer$ = Space$(255) KeyBfLen = KEY_BUF_LEN Stats = BTRCALL(BGETFIRST, PosBlk$, DataBf, BfLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error on BGETFIRST. + Str$(Stats) PrintLB (Msg$) Else Msg$ = BGETFIRST okay for : + Str$(Year(DataBf.Nmber)) + DataBf.Dmmy PrintLB (Msg$) End If Get Next Record BfLen = Len(DataBf) KeyBffer$ = Space$(KEY_BUF_LEN) KeyBfLen = KEY_BUF_LEN Stats = BTRCALL(BGETNEXT, PosBlk$, DataBf, BfLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error on BGETNEXT. + Str$(Stats) PrintLB (Msg$) Else Btrieve Programmer s Reference 331 Langage Interfaces

332 Example A-6 Btrsam32.bas contined Msg$ = BGETNEXT okay for: + Str$(Year(DataBf.Nmber)) + DataBf.Dmmy PrintLB (Msg$) End If Get Next Record BfLen = Len(DataBf) KeyBffer$ = Space$(KEY_BUF_LEN) KeyBfLen = KEY_BUF_LEN Stats = BTRCALL(BGETNEXT, PosBlk$, DataBf, BfLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error on BGETNEXT. + Str$(Stats) PrintLB (Msg$) Else Msg$ = BGETNEXT okay for: + Str$(Year(DataBf.Nmber)) + DataBf.Dmmy PrintLB (Msg$) End If Get Eqal BfLen = Len(DataBf) KBf# = KeyBfLen = 8 Stats = BTRCALL(BGETEQUAL, PosBlk$, DataBf, BfLen, KBf#, KeyBfLen, 0) If Stats <> 0 Then Btrieve Programmer s Reference 332 Langage Interfaces

333 Example A-6 Btrsam32.bas contined Msg$ = Error on Get Eqal. Stats = + Str$(Stats) PrintLB (Msg$) Else PrintLB ( BGETEQUAL okay on folloing key: + Str$(DataBf.Nmber)) End If Stat Call DBLen = Len(StatFileBffer) KeyBffer$ = Space$(KEY_BUF_LEN) KeyBfLen = KEY_BUF_LEN Stats = BTRCALL(BSTAT, PosBlk$, StatFileBffer, DBLen, ByVal KeyBffer$, KeyBfLen, 0) If Stats <> 0 Then Msg$ = Error in Stat Call. Stats = + Str$(Stats) PrintLB (Msg$) GoTo Fini Else Rem ********************************** Rem Code to ork arond problems ith Visal Basic s Doble Rem Word alignment. This code converts the byte data to Rem hexadecimal, concatenates each byte, and converts it to Rem decimal for display. h_field1 = Hex(StatFileBffer.RecTot.fld_Field1) h_field2 = Hex(StatFileBffer.RecTot.fld_Field2) h_field3 = Hex(StatFileBffer.RecTot.fld_Field3) h_field4 = Hex(StatFileBffer.RecTot.fld_Field4) h_total = &H & h_field4 & h_field3 & h_field2 & h_field1 loc_rectot = Val(h_total) Btrieve Programmer s Reference 333 Langage Interfaces

334 Example A-6 Rem ********************************** Msg$ = Nmber of Records = & loc_rectot PrintLB (Msg$) End If Fini: Stats = BTRCALL(BRESET, PosBlk$, PatientVar, BfLen, KeyBffer$, KeyBfLen, KeyNm) If Stats Then Msg$ = Error on B-Reset! + Str$(Stats) PrintLB (Msg$) Else Msg$ = BRESET okay. PrintLB (Msg$) End If Stats = BTRCALL(BSTOP, PosBlk$, PatientVar, BfLen, KeyBffer$, KeyBfLen, KeyNm) If Stats Then Msg$ = Error on B-Stop! + Str$(Stats) PrintLB (Msg$) Else Msg$ = BSTOP okay. PrintLB (Msg$) End If PrintLB ( ) PrintLB ( Btrieve Sample Test Completed ) End Sb Btrsam32.bas contined Btrieve Programmer s Reference 334 Langage Interfaces

335 Compiling, Linking, and Rnning the Program Example In Visal Basic, to compile, link, and rn the program example: 1. In the Visal Basic programming environment, choose Open Project from the File men. 2. Open the appropriate project file in the \Intf\Vb directory: For 32-bit environments, open the BtSamp32.vbp project file. For 16-bit environments, open the BtSamp16.vbp project file. 3. Click the Start btton on the toolbar. Visal Basic compiles and links the program example and creates a Btrieve Visal Basic Sample indo. 4. In the Btrieve Visal Basic Sample indo, click the Rn Test btton. Visal Basic rns the program example. Creating 32-Bit Applications When developing 32-bit applications ith Visal Basic 4.0 and later, a strctre alignment isse may case problems ith Btrieve calls. To optimize performance, Visal Basic adds extra bytes into strctres to perform doble ord alignment on some fields in the strctre. This is often apparent hen a strctre contains a Long (4-byte) integer or a single (4-byte) or doble (8-byte) precision floating point field. For example: Type DataBffer Fld1 As String * 2 Fld2 As Long End Type Btrieve Programmer s Reference 335 Langage Interfaces

336 This strctre actally occpies 8 bytes rather than 6, becase to extra dmmy bytes are inserted into the strctre to move Fld2 to a doble-ord bondary. Note that this problem actally exists in most compilers, inclding C/C++ and Pascal. Hoever, other compilers provide a configration option yo can se to specify the type of strctre alignment yo ant the compiler to se; Visal Basic 4.0 does not provide sch a configration option. When sing a Visal Basic Type strctre as a Data Bffer parameter in a Btrieve call, these extra bytes are not apparent to Btrieve. For example, if reading a 6-byte record from a file ith a Get First sing the strctre defined above, Btrieve retrns the six bytes of data in the first 6 bytes of the strctre; Btrieve does not add any extra bytes, and sbseqent access to Fld2 does not prodce the correct data. There are several ays to ork arond this problem in yor Visal Basic application. The sample code in BtrSAM32.BAS is one example of a orkarond. Folloing is an otline of ho this orkarond ses some intermediate type strctres. 1. Declare all type bffers ith String fields ith the same size as the nmber field that yo old otherise se. 2. Declare to intermediate type bffers: one that consists of jst a 4-byte string field, and one that consists of jst a 4-byte long or float field. 3. Use this type bffer from step 1 to read a record from the data file. 4. Copy the 4-byte string from the Btrieve Data Bffer into the intermediate bffer containing only the string field. 5. Use the Visal Basic LSet operation to set the nmeric intermediate bffer eqal to the string intermediate bffer. (This is eqivalent to a C memmove fnction, in hich the bytes are copied regardless of the nderlying field types in the strctre.) Similar steps can be sed to ork arond the problem hen performing insert or pdate operations. Btrieve Programmer s Reference 336 Langage Interfaces

337 appendix B Data Types The MicroKernel provides standard and extended data types. These types allo the MicroKernel to recognize and collate key vales based on the internal storage format of the 18 data types that compilers most commonly se. This capability provides yo ith greater flexibility in defining keys. Note The MicroKernel does not convert data to key types. Each application is responsible for maintaining data typing information. For historical reasons, the to standard data types, STRING and UNSIGNED BINARY, are also offered as extended data types. Internally, the MicroKernel compares string keys on a byte-by-byte basis, from left to right. The MicroKernel sorts string keys according to their ASCII vale, hoever, yo can define string keys to be case insensitive or to se an ACS. The MicroKernel compares nsigned binary keys one ord at a time. It compares these keys from right to left becase the Intel 8086 family of processors reverses the high and lo bytes in an integer. If a particlar data type is available in more than one size (for example, both 4- and 8-byte FLOAT vales are alloed), the Key Length parameter (sed in the creation of a ne key) defines the size that ill be expected for all vales of that particlar key. Any attempt to define a key sing a Key Length that is not alloed reslts in a Stats 29 (Invalid Key Length). Btrieve Programmer s Reference 337 Data Types

338 Table B-1 lists the extended key types and their associated codes. Table B-1 Extended Key Types and Codes Type Code Type Code STRING 0 BFLOAT 9 INTEGER 1 LSTRING 10 FLOAT 2 ZSTRING 11 DATE 3 UNSIGNED BINARY 14 TIME 4 AUTOINCREMENT 15 DECIMAL 5 NUMERICSTS 17 MONEY 6 NUMERICSA 18 LOGICAL 7 CURRENCY 19 NUMERIC 8 TIMESTAMP 20 The folloing sections, arranged alphabetically by key type, describe the extended key types and their internal storage formats. AUTOINCREMENT The AUTOINCREMENT key type is a signed Intel integer that can be either to or for bytes long. Internally, AUTOINCREMENT keys are stored in Intel binary integer format, ith the high-order and lo-order bytes reversed ithin a ord. The MicroKernel sorts AUTOINCREMENT keys by their absolte vales, comparing the vales stored in Btrieve Programmer s Reference 338 Data Types

339 different records a ord at a time from right to left. AUTOINCREMENT keys are incremented each time yo insert a record into the file. The folloing restrictions apply to AUTOINCREMENT keys: An AUTOINCREMENT key cannot contain dplicate nonzero key vales. An AUTOINCREMENT key cannot be segmented. Hoever, an AUTOINCREMENT key can be inclded as a segment of another key, as long as the AUTOINCREMENT key has been defined as a separate, single key first, and the AUTOINCREMENT key nmber is loer than the segmented key nmber. An AUTOINCREMENT key cannot overlap another key. All AUTOINCREMENT keys mst be ascending. The MicroKernel treats AUTOINCREMENT key vales as follos hen yo insert records into a file: If yo specify a vale of binary 0 for the AUTOINCREMENT key, the MicroKernel assigns a vale to the key based on the folloing criteria: If yo are inserting the first record in the file, the MicroKernel assigns the vale of 1 to the AUTOINCREMENT key. If records already exist in the file, the MicroKernel assigns the key a vale that is one nmber higher than the highest existing absolte vale in the file. If yo specify a nonzero vale for the AUTOINCREMENT key, the MicroKernel inserts the record into the file and ses the specified vale as the key vale. If a record containing that vale already exists in the file, the MicroKernel retrns an error stats code and does not insert the record. Btrieve Programmer s Reference 339 Data Types

340 When yo delete a record containing an AUTOINCREMENT key, the MicroKernel completely removes the record from the file. The MicroKernel does not rese the deleted key vale nless yo specify that vale hen yo insert another record into the file. As mentioned previosly, the MicroKernel alays sorts AUTOINCREMENT keys by their absolte vales. For example, yo can do the folloing: Specify a negative vale for an AUTOINCREMENT key hen yo insert a record. Update a record and negate the vale for the AUTOINCREMENT key. In any case, the MicroKernel sorts the key according to its absolte vale. This allos yo to se negation to flag records ithot altering the record s position in the index. In addition, hen yo perform a Get operation and specify a negative vale in the key bffer, the MicroKernel treats the negative vale as the absolte vale of the key. Yo can initialize the vale of a field in all or some records to zero and later add an index of type AUTOINCREMENT. This featre allos yo to prepare for an AUTOINCREMENT key ithot actally bilding the index ntil it is needed. When yo add the index, the MicroKernel changes the zero vales in each field appropriately, beginning its nmbering ith a vale eqal to the greatest vale crrently defined in the field, pls one. If nonzero vales exist in the field, the MicroKernel does not alter them. Hoever, the MicroKernel retrns an error stats code if nonzero dplicate vales exist in the field. Btrieve Programmer s Reference 340 Data Types

341 BFLOAT The BFLOAT key type is a single or doble-precision real nmber. A single-precision real nmber is stored ith a 23-bit mantissa, an 8-bit exponent biased by 128, and a sign bit. The internal layot for a 4-byte float is as follos: bit exponent Sign 23-bit mantissa The representation of a doble-precision real nmber is the same as that for a singleprecision real nmber, except that the mantissa is 55 bits instead of 23 bits. The least significant 32 bits are stored in bytes 0 throgh 3. The BFLOAT type is commonly sed in BASIC applications. CURRENCY The CURRENCY data type represents an 8-byte signed qantity, sorted and stored in Intel binary integer format; therefore, its internal representation is the same as an 8 byte INTEGER data type. The CURRENCY data type has an implied for digit scale of decimal places, hich represents the fractional component of the crrency data vale. DATE The DATE key type is stored internally as a 4-byte vale. The day and the month are each stored in 1-byte binary format. The year is a 2-byte binary nmber that represents the Btrieve Programmer s Reference 341 Data Types

342 entire year vale. The MicroKernel places the day into the first byte, the month into the second byte, and the year into a to-byte ord folloing the month. DECIMAL The DECIMAL key type is stored internally as a packed decimal nmber ith to decimal digits per byte. The internal representation for an n-byte DECIMAL field is as follos: byte 0 byte 1 byte nð digit 1 digit 2 digit 3 digit 4... digit 2nÐ1 sign nibble The sign nibble is either 0xF or 0xC for positive nmbers and 0xD for negative nmbers. The decimal point is implied; no decimal point is stored in the DECIMAL field. Yor application is responsible for tracking the location of the decimal point for the vale in a DECIMAL field. All the vales for a DECIMAL key type mst have the same nmber of decimal places in order for the MicroKernel to collate the key correctly. The DECIMAL type is commonly sed in COBOL applications. Btrieve Programmer s Reference 342 Data Types

343 Btrieve Programmer s Reference 343 Data Types FLOAT The FLOAT key type is consistent ith the IEEE standard for single and doble-precision real nmbers. The internal format for a 4-byte FLOAT consists of a 23-bit mantissa, an 8- bit exponent biased by 127, and a sign bit, as follos: A FLOAT key ith 8 bytes has a 52-bit mantissa, an 11-bit exponent biased by 1023, and a sign bit. The internal format is as follos: bit exponent Sign 23-bit mantissa bit mantissa bit exponent Sign 20-bit mantissa bytes 3-0: bytes 7-4:

344 INTEGER The INTEGER key type is a signed hole nmber and mst contain an even nmber of bytes. Internally, INTEGER fields are stored in Intel binary integer format, ith the highorder and lo-order bytes reversed ithin a ord. The MicroKernel evalates the key from right to left, a ord at a time. The sign mst be stored in the high bit of the rightmost byte. The INTEGER type is commonly sed in C applications. Length in Bytes Vale Ranges LOGICAL The LOGICAL key type is stored as a 1 or 2-byte vale. The MicroKernel collates LOGICAL key types as strings. Doing so allos yor application to determine the stored vales that represent tre or false. LSTRING The LSTRING key type has the same characteristics as a reglar STRING type, except that the first byte of the string contains the binary representation of the string s length. The length stored in byte 0 of an LSTRING key determines the nmber of significant bytes. Btrieve Programmer s Reference 344 Data Types

345 The MicroKernel ignores any vales beyond the specified length of the string. The LSTRING type is commonly sed in Pascal applications. MONEY The MONEY key type has the same internal representation as the DECIMAL type. NUMERIC NUMERIC vales are stored as ASCII strings, right jstified ith leading zeros. Each digit occpies one byte internally. The rightmost byte of the nmber incldes an embedded sign ith an EBCDIC vale. Table B-2 indicates ho the rightmost digit is represented hen it contains an embedded sign for positive and negative nmbers. Table B-2 Rightmost Digit ith Embedded Sign Digit Positive Negative $ - %. & / ' 0 ( 1 ) 2 * 3 + 4, 5 ^ ` Btrieve Programmer s Reference 345 Data Types

346 For positive nmbers, the rightmost digit can be represented by 1 throgh 0 instead of A throgh {. The MicroKernel processes positive nmbers represented either ay. The NUMERIC type is commonly sed in COBOL applications. NUMERICSA The NUMERICSA key type (sometimes called NUMERIC SIGNED ASCII) is a COBOL data type that is the same as the NUMERIC data type, except that the embedded sign has an ASCII vale instead of an EBCDIC vale. NUMERICSTS The NUMERIC STS key type (sometimes called SIGN TRAILING SEPARATE) is a COBOL data type that has vales resembling those of the NUMERIC data type. NUMERICSTS vales are stored as ASCII strings and right jstified ith leading zeros. Hoever, the rightmost byte of a NUMERICSTS string is either + (ASCII 0x2B) or - (ASCII 0x2D). This differs from NUMERIC vales that embed the sign in the rightmost byte along ith the vale of that byte. STRING The STRING key type is a seqence of characters ordered from left to right. Each character is represented in ASCII format in a single byte, except hen the MicroKernel is determining hether a key vale is nll. Btrieve Programmer s Reference 346 Data Types

347 TIME The TIME key type is stored internally as a 4-byte vale. Hndredths of a second, second, minte, and hor vales are each stored in 1-byte binary format. The MicroKernel places the hndredths of a second vale into the first byte, folloed respectively by the second, minte, and hor vales. TIMESTAMP The TIMESTAMP data type represents a time and date vale. In applications that se Pervasive s Scalable SQL or ODBC Interface, se this data type to stamp a record ith the time and date of the last pdate to the record. TIMESTAMP vales are stored in 8- byte nsigned vales representing septa seconds (10-7 second) since Janary 1, 0001 in a Gregorian calendar. TIMESTAMP is intended to cover time and data vales made p of the folloing components: year, month, day, hor, minte, and second. The folloing table indicates the valid vales of each of these components: YEAR 0001 to 9999 MONTH 01 to 12 DAY 01 to 31, constrained by the vale of MONTH and YEAR in the Gregorian calendar. Btrieve Programmer s Reference 347 Data Types

348 HOUR 00 to 23 MINUTE 00 to 59 SECOND 00 to 59 The Programming Interfaces installation option contains sample conversion fnctions that can be integrated into applications hich access Btrieve data sing Pervasive s Scalable SQL or ODBC Interface, or vice versa. These fnctions inclde: 1) converting the nmber of septa seconds since Janary 1, 0001 to a date and time; and 2) converting a date and time to the nmber of septa seconds since Janary 01, Refer to the Programming Interfaces on-line samples for these to fnctions. Also refer to the SQL Langage Reference for additional docmentation on sing the TIMESTAMP data type in SQL environments. UNSIGNED BINARY The MicroKernel sorts UNSIGNED BINARY keys as nsigned INTEGER keys. An UNSIGNED BINARY key mst contain an even nmber of bytes (2, 4, 6, and so on). The MicroKernel compares UNSIGNED BINARY keys a ord at a time, from right to left. An UNSIGNED BINARY key is sorted in the same manner as an INTEGER key. The differences beteen an UNSIGNED BINARY key and an INTEGER key are that an INTEGER has a sign bit, hile an UNSIGNED BINARY type does not, and an UNSIGNED BINARY key can be longer than 4 bytes. ZSTRING The ZSTRING key type corresponds to a C string. It has the same characteristics as a reglar string type except that a ZSTRING type is terminated by a byte containing a Btrieve Programmer s Reference 348 Data Types

349 binary 0. The MicroKernel ignores any vales beyond the first binary 0 it enconters in the ZSTRING, except hen the MicroKernel is determining hether a key vale is nll. Btrieve Programmer s Reference 349 Data Types

350 appendix C Qick Reference of Btrieve Operations This appendix provides a smmary of Btrieve operations in nmerical order by operation code. Table C-1 Qick Reference of Btrieve Operations Operation Code Description Open Makes a file available for access. Close Releases a file from availability. Insert Inserts a ne record into a file. Update Updates the crrent record. Delete Removes the crrent record from the file. Get Eqal Retrns the record hose key vale matches the specified key vale. Get Next Retrns the record folloing the crrent record in the index path. Get Previos Retrns the record preceding the crrent record in the index path. Get Greater Than Retrns the record hose key vale is greater than the specified key vale. Get Greater Than or Eqal Retrns the record hose key vale is eqal to or greater than the specified key vale. Btrieve Programmer s Reference 350 Qick Reference of Btrieve Operations

351 Table C-1 Qick Reference of Btrieve Operations contined Operation Code Description Get Less Than Retrns the record hose key vale is less than the specified key vale. Get Less Than or Eqal Retrns the record hose key vale is eqal to or less than the specified key vale. Get First Retrns the first record in the specified index path. Get Last Retrns the last record in the specified index path. Create Creates a file ith the specified characteristics. Stat Retrns file and index characteristics, and nmber of records. Extend Divides a data file over to logical disk drives. This operation is not spported in Btrieve 6.0 and later. Set Directory Changes the crrent directory. Get Directory Retrns the crrent directory. Begin Transaction à Marks the beginning of a set of logically related operations. Operation 19 begins an exclsive transaction. Operation 1019 begins a concrrent transaction. End Transaction Marks the end of a set of logically related operations. Abort Transaction Removes operations performed dring an incomplete transaction. Btrieve Programmer s Reference 351 Qick Reference of Btrieve Operations

352 Table C-1 Qick Reference of Btrieve Operations contined Operation Code Description Get Position Retrns the position of the crrent record. Get Direct/Chnk Retrns data from the specified portions (chnks) of a record at a specified position. Get Direct/Record Retrns the record at a specified position. Step Next Retrns the record from the physical location folloing the crrent record. Stop Terminates the orkstation MicroKernel (not available for serverbased MicroKernels). Version Retrns the version nmber of the MicroKernel. Unlock Unlocks a record or records. Reset Releases all resorces held by a client. Set Oner Assigns an oner name to a file. Clear Oner Removes an oner name from a file. Create Index Creates an index. Drop Index Removes an index. Step First Retrns the record in the first physical location in the file. Step Last Retrns the record in the last physical location in the file. Btrieve Programmer s Reference 352 Qick Reference of Btrieve Operations

353 Table C-1 Qick Reference of Btrieve Operations contined Operation Code Description Step Previos Retrns the record in the physical location preceding the crrent record. Get Next Extended Retrns one or more records that follo the crrent record in the index path. Filtering conditions can be applied. Get Previos Extended Retrns one or more records that precede the crrent record in the index path. Filtering conditions can be applied. Step Next Extended Retrns one or more sccessive records from the location physically folloing the crrent record. Filtering conditions can be applied. Step Previos Extended Retrns one or more preceding records from the location physically preceding the crrent record. Filtering conditions can be applied. Insert Extended Inserts one or more records into a file. Continos Operation Server-based MicroKernels only. Places the specified file in or removes the file from continos operation mode, for se in system backps. Get By Percentage Retrns the record located approximately at a position derived from the specified percentage vale. Find Percentage Retrns a percentage figre based on the crrent record s position in the file. Get Key Detects the presence of a key vale in a file, ithot retrning an actal record. Btrieve Programmer s Reference 353 Qick Reference of Btrieve Operations

354 Table C-1 Qick Reference of Btrieve Operations contined Operation Code Description Update Chnk 53 Updates specified portions (chnks) of the crrent record. This operation can also append data to a record or trncate a record. Stat Extended 65 Retrns filenames and paths of an extended file s components and reports hether a file is sing a system-defined log key. Single-record ait lock Locks only one record at a time. If the record is already locked, the MicroKernel retries the operation. Single-record no-ait lock Locks only one record at a time. If the record is already locked, the MicroKernel retrns an error stats code. Mltiple-record ait lock Locks several records concrrently in the same file. If the record is already locked, the MicroKernel retries the operation. Mltiple-record no-ait lock Locks several records concrrently in the same file. If the record is already locked, the MicroKernel retrns an error stats code. No-ait page lock In a concrrent transaction, tells the MicroKernel not to ait if the page to be changed has already been changed by another active concrrent transaction. This bias can be combined ith any of the record locking biases (+100, +200, +300, or +400). Btrieve Programmer s Reference 354 Qick Reference of Btrieve Operations

355 Index A Abort Transaction operation 36 Accelerated file open mode 154 ACS. See Alternate collating seqence. Adding an index to an existing file 67 ALT constant 58 Alternate collating seqence Create operation and 59 creating keys that se 58 flag in Stat operation for 173 ISR 64 locale-specific 63 ser-defined 62 AND and OR operations in filters 129 Ascending sort order 58 Attribtes file 54 key 58 AUTOINCREMENT data type 338 B Balanced indexes 54 BALANCED_KEYS constant 54 Begin Transaction operation 38 BFLOAT data type 341 BIN constant 58 Blank trncation 54 BLANK_TRUNC constant 54 BRQSHELLINIT fnction 15 BTRCALL fnction 14 BTRCALL32 fnction 15 BTRCALLBACK fnction 15 BTRCALLID fnction 15 BTRCALLID32 fnction 15 Btrieve fnction parameters 16 fnctions 13 operations, sing 33 BTRSAMP.C 226 BTRV fnction 14 BTRVID fnction 14 Btrieve Programmer s Reference 355 Index

356 BTRVINIT fnction 15 BTRVSTOP fnction 15 C C langage interface 222 C++ Bilder 252 Case-insensitive keys 58, 59 Chnk descriptors Get Direct/Chnk operation and 91 Update Chnk operation and 202 Clear Oner operation 41 ClientID parameter 23 Close operation 43 COBOL langage interface 270 Code page ID in locale-specific ACS 63 Compression, data 54 Continos Operation operation 45 Contry ID in locale-specific ACS 63 Create Index operation 67 Create operation alternate collating seqence in 59 data bffer 64 description of 50 file specifications in 53 CURRENCY data type 341 D Data Bffer Length parameter 20 Data Bffer parameter 20 Data compression 54 Data encryption 165 Data maniplation operations 26 Data retrieval operations 26 Data types abot 337 AUTOINCREMENT 338 BFLOAT 341 CURRENCY 341 DATE 341 DECIMAL 342 extended 338 FLOAT 343 INTEGER 344 LOGICAL 344 LSTRING 344 MONEY 345 NUMERIC 345 NUMERICSA 346 NUMERICSTS 346 Btrieve Programmer s Reference 356 Index

357 STRING 346 TIME 347 TIMESTAMP 347 UNSIGNED BINARY 348 ZSTRING 348 DATA_COMP constant 54 Data-only files, creating 53 DATE data type 341 DECIMAL data type 342 Delete operation 73 Deleting an index 75 Delphi langage interface 275 DESC_KEY constant 58 Descending sort order 58 Directory retrning the crrent 104 setting the crrent 163 Drop Index operation 75 DUP constant 58 DUP_PTRS constant 54 Dplicate keys 58 Dplicate pointers, reserved 54 E End Transaction operation 78 Exclsive file open mode 155 Extend operation (obsolete) 351 Extended data types 58, 337, 338 Extended key types 60 EXTTYPE_KEY constant 58 F File access operations 26 File flags (attribtes) 54 File information operations 26 File open modes 153 File specification block 53 Files closing 43 creating 50 opening 152 statistics 168 File-specific operations 26 Filters for extended operations 127 Find Percentage operation 80 Flags file 54, 173 key 58 FLOAT data type 343 Free space threshold 54 Btrieve Programmer s Reference 357 Index

358 FREE_10 constant 54 FREE_20 constant 54 FREE_30 constant 54 Fnctions, Btrieve 13 G Get By Percentage operation 84 Get Direct/Chnk operation 89 Get Direct/Record operation 101 Get Directory operation 104 Get Eqal operation 105 Get First operation 107 Get Greater operation 109 Get Greater Than or Eqal operation 111 Get Key operation 113 Get Last operation 116 Get Less Than operation 118 Get Less Than or Eqal operation 120 Get Next Extended operation 125 Get Next operation 122 Get Position operation 136 Get Previos Extended operation 141 Get Previos operation 138 I Inclde system data 54 INCLUDE_SYSTEM_DATA constant 54 Indexes balanced 54 creating 67 dropping 75 rebilding 76 Insert Extended operation 147 Insert operation 144 INTEGER data type 344 International Sort Rles 64 K Key Bffer parameter 21 Key flags (attribtes) 58 Key Length parameter 24 Key Nmber parameter 22 Key nmbers, assigning 54, 61 Key specification blocks 56 Key vales, finding specific 113 KEY_ONLY constant 54 Key-only files, creating 54 Btrieve Programmer s Reference 358 Index

359 L Linked dplicate keys 58 Linking a 32-bit extended DOS application ith the C interface 246 Locale-specific ACSs 63 Lock biases 30 LOGICAL data type 344 LSTRING data type 344 M Maniplation operations 26 MANUAL_KEY constant 58 MEFS bias ith file open modes 155 MOD constant 58 Modifiable keys 58 Modification operations 26 MONEY data type 345 Mltiple record locks 196 N NAMED_ACS constant 58 Next-in-record sbfnction bias 98, 210 NO_INCLUDE_SYSTEM_DATA constant 54 NOCASE_KEY constant 58 No-crrency-change Insert Extended operation and 147 Insert operation and 145 Update operation and 197 Normal file open mode 153 NUL constant 58 Nll keys 58 NUMBERED_ACS constant 58 NUMERIC data type 345 NUMERICSA data type 346 NUMERICSTS data type 346 O Obsolete fnctions 15 Open modes 153 operation 152 Operation Code parameter 17 Operations, sing in applications 33 Oner names clearing 41 setting 165 Btrieve Programmer s Reference 359 Index

360 P Page preallocation 54 Pascal langage interface 297 Pointers, reserved dplicate 54 Position Block parameter 19 PRE_ALLOC constant 54 R Random chnk descriptors 91, 203 Read-only file open mode 154 Rebilding a damaged index 76 Records deleting 73 inserting 144 inserting mltiple 147 pdating 197 Rectangle chnk descriptors 95, 206 REPEAT_DUPS_KEY constant 58 Repeating dplicate keys 58 Reqester version, retrieving 213 Reserved dplicate pointers 54 Reset operation 161 Resorces, releasing 161 Retrieval operations 26 Retrieving records eqal to the index path 105 first in physical location 179 first in the index path 107 Get By Percentage operation and 84 Get Direct/Record operation and 101 getting one or more chnks of a record 89 greater than or eqal to the index path 111 greater than the index path 109 last in physical location 181 last in the index path 116 less than or eqal to the index path 120 less than the index path 118 next in physical location 183, 185 next in the index path 122, 125 previos in physical location 189, 191 previos in the index path 138, 141 sing established physical location 136 RQSHELLINIT fnction 15 Btrieve Programmer s Reference 360 Index

361 S Scroll bars, implementing 84 SEFS Bias ith file open modes 155 SEG constant 58 Segmented keys 58 Server engine version, retrieving 213 Session-specific operations 25 Set Directory operation 163 Set Oner operation 165 Single record locks 195 Sort order in keys 58 string 337 SPECIFY_KEY_NUMS constant 54 Standard data types 58, 337 Stat Extended operation 175 Stat operation 168 Stats Code parameter 17 Step First operation 179 Step Last operation 181 Step Next Extended operation 185 Step Next operation 183 Step Previos Extended operation 191 Step Previos operation 189 Stop operation 193 STRING data type 346 System data 54 T TIME data type 347 TIMESTAMP data type 347 Transactions aborting 36 beginning 38 ending 78 Trncate chnk descriptors 209 U Unlock operation 195 UNSIGNED BINARY data type 348 Update Chnk operation 201 Update operation 197 Use VATs 54 User-defined ACSs 62 V VAR_RECS constant 54 Variable-length records and Extended operations 132 flag 54 Btrieve Programmer s Reference 361 Index

362 Variable-tail Allocation Tables (VATs) 54 VATS_SUPPORT constant 54 Verify file open mode 154 Version operation 213 Visal BASIC langage interface 320 W WBRQSHELLINIT fnction 15 WBTRVINIT fnction 15 WBTRVSTOP fnction 15 Workstation engine version, retrieving 213 Z ZSTRING data type 348 Btrieve Programmer s Reference 362 Index

363 User Comments Pervasive Softare old like to hear yor comments and sggestions abot or manals. Please rite yor comments belo and send them to s at: Pervasive Softare Inc. Docmentation 8834 Capital of Texas Highay Astin, Texas USA Pervasive.SQL 7 Btrieve Programmer s Reference Part # Febrary 1998 Telephone: Fax: [email protected] Yor name and title: Company: Address: Phone nmber: Fax: Yo may reprodce these comment pages as needed so that others can send in comments also.

364 I se this manal as: qan overvie qa ttorial qa reference qa gide Excellent Good Fair Poor Completeness q q q q Readability (style) q q q q Organization/Format q q q q Accracy q q q q Examples q q q q Illstrations q q q q Useflness q q q q Please explain any of yor above ratings: In hat ays can this manal be improved? Yo may reprodce these comment pages as needed so that others can send in comments also.