Whether you are using compiled or interpretive BASIC, the steps for calling Btrieve are the same. To access data in a Btrieve file, your BASIC application must first execute a standard BAsIC OPEN statement to NUL to allocate a BASIC field buffer, as in the following statement:
OPEN "NUL" AS #1
When BASIC processes an OPEN statement, it allocates an area called the File Control Block (FCB). This block contains, among other things, a buffer area which stores records from the file as they are transferred to and from the disk. BASIC allows you to define this buffer area as a set of contiguous string variables with the FIELD statement.
2011Revl.OO 5-5
For example, if a you define a file to contain addresses, your application might include the following FIELD statement:
FIELD #1,30 AS NAM$, 30 AS STREET$, 30 AS CITY$, 2 AS STATE$, 5 AS ZIP$
This statement indicates that the field buffer, which was previously allocated for file #1, contains records in which the first 30 characters contain a name, and the next 30 characters contain a street, etc.
BASIC restricts your total statement length to 255 characters. If your record contains very many fields, you may not be able to completely describe your data in a single BASIC statement. BASIC allows you to use as many FIELD statements as necessary to describe the records. The variable names in all the field statements are in effect at the same time. Each new FIELD statement redefines the buffer from the first character position. Therefore, you have to use a dummy field as the first entry in subsequent FIELD statements to account for the fields which have already been defined.
For example, if the records defined by the previous FIELD statement contained a phorie number after the zip code, you could define the phone number field in the following statement:
FIELD #1, 97 AS DUMMY$, 7 AS PHONE$
Since Btrieve uses the buffer in the FCB for record transfers, the application must include a FIELD statement in order to access the data returned by Btrieve. See your BASIC reference manual for a more complete description of the OPEN and FIELD statements. You must use an LSET command to store values in the buffer defined by a FIELD statement.
After a standard BASIC OPEN statement opens the Btrieve file, your application is ready to issue calls to the Btrieve Record Manager. First your application performs a Btrieve Open operation. Mter that, Btrieve handles all file reads, writes, and modifications through Btrieve calls. Your application
J
/
should perform a Btrieve Close operation before it terminates. -"
5-6 20lfRevl.OO
Application Interfaces
All calls to Btrieve from a BASIC program must be in the following format:
CALL BTRV (Operation, Status, FCB, Data Buffer Length, Key Buffer, Key Number)
For interpretive BASIC, BTRV should be a numeric variable with a value of O. In compiled BASIC, BTRV is an external name resolved by the linker.
Though all parameters are required on every call, Btrieve does not use all the parameters to perform every operation. In some cases, Btrieve ignores their value. For a more detailed description of relevant parameters, see Chapter 5 ofthis manual. The following sections describe each parameter.
OPERATION CODE
The operation parameter determines which Btrieve function you want to perform. The variable you specify must be an integer type and can be anyone of the legal Btrieve operation codes described in Chapter 6 of this manual.
(Also see Appendix A for a complete list of these codes.) Your application must specify a valid operation code on every Btrieve call. The Btrieve Record Manager never changes the code.
STATUS CODE
The status parameter contains a coded value that indicates whether any errors occurred during the Btrieve operation. The Btrieve Record Manager returns a status of 0 after a successful operation. Btrieve indicates any errors that occur during processing by returning a non-zero value in the status parameter.
A BASIC application must always pass an integer variable as the status parameter on a Btrieve call. Mer a Btrieve call, the application must always check the value of the status variable to ascertain whether the call was successful. See Appendix B for a list of Btrieve error messages and their possible causes.
201lRevl.OO 5-7
FILE CONTROL BLOCK (FCB)
BASIC allocates an area called the File Control Block (FCB) when it processes an OPEN statement. Btrieve uses this block to maintain its positioning information and to transfer data records. Therefore, your
application must pass the address of the FCB to the Record Manager on every call. Your application should use a different FCB address for each separate Btrieve file it accesses.
To determine the address of the FCB, your BASIC application must use a V ARPTR statement. In the following example, BASIC returns the address of the FCB for the file opened as #1, in the integer variable FCB.ADDR%.
FCB.ADDR%
=
VARPTR(#1)See your BASIC reference manual for a more complete description of the V ARPTR statement.
DATA BUFFER LENGTH
For any operation using the data buffer, your program must pass the length of the data buffer in an integer variable. For a file with fixed length records, this parameter should match the record length specified when you first created the file. When you are inserting records in or updating a file with variable length records, this parameter should equal the record length specified when you first created the file, plus the number of characters included beyond the fixed length portion. When you are retrieving variable length records, this parameter should be large enough to accommodate the longest record in the file.
KEY BUFFER
On each Btrieve call, your BASIC program must pass a string variable containing the key value. If the key value is an integer, your program must convert it to a string using the MKI$ statement before calling Btrieve. If the key consists of two or more non-contiguous segments, you must concatenate them into a single string variable and pass the variable as the key buffer.
Depending on the operation, your program may set the variable, or the Record Manager may return it.
5-8 2011Revl.OO
(
Application Interfaces The Record Manager returns an error if the string variable passed as the key buffer is shorter than the key's defined length. If your application's first call does not require initialization of the key buffer, you should assign the string variable the value SPACE$(x), where x represents the key's defined length.
Until your application assigns some value in BASIC to the string variable, it has a length of O.
KEY NUMBER
You may define up to 24 different keys when you first create a Btrieve file.
When your application accesses the file, it must tell the Record Manager which access path to follow for a particular operation. The key number
parameter is an integer variable with a value from 0 through 23, with 0 being the first key segment defined for the file. Btrieve never alters this value.