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 docs@pervasive.com. 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