Btrieve requires certain information from your application in order to perform record and file management operations. Your application uses the Btrieve call parameters to specify the information Btrieve needs and to provide places for Btrieve to return information. On every Btrieve call, your application must pass to Btrieve every parameter required for the language you are using, even when Btrieve does not expect a value to be stored in that parameter. This section gives a general description ofthe parameters and how Btrieve uses them.
1-16 2011Rev1.00
'\ ! /
(-Introduction to Btrieve
NOTE:
For specific information about how to use a parameter with a particular language, refer to Chapter 5, "Language Interfaces."
For information about how Btrieve uses a parameter for a particular operation, refer to Chapter 6, "Btrieve Record Operations. "
OPERATION CODE
The operation code parameter tells Btrieve which operation you want to perform. Your application must specifY a valid operation code for every Btrieve call. The variable you specifY to hold the operation code must be a 2-byte integer. Btrieve never changes the operation code value.
STATUS CODE
All Btrieve operations return a status code value, informing your application of any errors. A status code of 0 indicates that the operation was successful.
For some languages, particularly C and Pascal, the Btrieve call is an integer function, and your application does not have to specifY a separate parameter to hold the status code. If the language you use requires a separate status code parameter, specifY a 2-byte integer to contain the return value.
POSITION BLOCK
Btrieve uses the position block parameter to contain positioning pointers and other information necessary for accessing a particular file. Your application uses the position block to identify to Btrieve the file you want to access on a particular operation. Btrieve expects the position block to be a 12B-byte block of memory. Depending on the application language, the position block can be a string, an array, or part of the language's file buffer (as in BASIC).
2011Rev1.00 1-17
Your application must assign a unique position block to each Btrieve file it needs to open and initialize the block to blanks or binary zeros before issuing the Btrieve Open operation. Your application should ~ write to a position block once it has been initialized and assigned to a file, unless you first issue a Btrieve Close operation for that file. You can then reinitialize the position block so that it can be used with another Btrieve file. Writing over the position block for an open Btrieve file can result in errors or file damage.
DATA BUFFER
The data buffer is a block of memory that holds specific kinds of information required by a Btrieve operation.
On operations that involve reading from or writing to a Btrieve file, the data buffer contains the records that your application transfers to and from the file. For example, when your application retrieves a record from a file,
Btrieve reads the record from the file and then writes the record into the area of memory designated as the data buffer for that operation.
For other operations, the data buffer contains file specifications, definitions, and other information that Btrieve needs in order to process the operation.
When your application issues a Create operation, for example, it constructs a data buffer that contains the specifications for the file you want to create, in the order that Btrieve expects them. Btrieve then reads the data buffer and creates the file according to the specifications.
Btrieve recognizes the data buffer as a series of bytes in memory. It does not distinguish any fields or variables as entities within the data buffer. You can define the data buffer to be any type of variable that your language supports:
a structure, an array, or a simple string variable. For some versions of BASIC, the data buffer is the area of the file control block (FCB) defined by the FIELD statement.
1-18 201lRev1.00
'\ )
Introduction to Btrieve
DATA BUFFER LENGTH
For every operation that requires a data buffer, your application must specifY the length ofthe data buffer, in bytes, to Btrieve. This is necessary because
• Btrieve allows you to define files that allow variable length records. You must specifY how many bytes you want Btrieve to read from or write to those records.
• Btrieve does not recognize any of your program's data structures.
Hence, it does not know implicitly how many bytes long the data buffer is. This creates the possibility of writing meaningless data to your files, or of returning more data than your data buffer can hold and
overwriting the area of memory immediately after the data buffer.
Your application should define the data buffer as a 2-byte integer. On all operations, Btrieve writes a value back to the data buffer length parameter, even if that value is 0 (indicating that no data was returned). Therefore, you should always initialize the data buffer to the proper length for an operation before you issue the Btrieve call.
Use the following guidelines for initializing the value in the data buffer length parameter:
• When you read from or write to an existing file that contains fixed length records, specify a value equal to the record length defined for the file.
• When you read from or write to an existing file that contains variable length records, specifY a value equal to the length defined for the fixed length portion of the record, plus the number of bytes that you want to read or write beyond the fixed length portion.
• When you issue any other operation, specifY the exact length of the data buffer required for that operation. These requirements are included in the discussion of the individual Btrieve operations in Chapter 5 of this manual.
2011Rev1.00 1-19
KEY BUFFER
Your application must pass a variable for the key buffer on every Btrieve call. '\
Depending on the particular operation, your application may set the key ) buffer to a particular value, or Btrieve may return a value to the key buffer.
For some languages, Btrieve cannot implicitly determine the length of the key buffer. Therefore, you should always ensure that the variable you specify for the key buffer is long enough to hold the entire value required by the
operation. Otherwise, Btrieve requests may destroy other data stored in memory following the key buffer.
KEY NUMBER
The key number parameter is always a signed 2-byte integer variable. For most Btrieve operations, this parameter tells the Record Manager which access path to follow for a particular operation. For other operations, your application uses the key number parameter to specify the file open mode, encryption, logical drive, or other information. Btrieve never returns an altered value to the key number parameter.
When you use the key number parameter to specify an access path for a file, the number must be in the range from 0 to 23, since Btrieve allows up to 24 keys or key segments in a file.
1-20 2011Rev1.00
(--Introduction to Btrieve