BTRIEVE

BTRIEVE is a ready-made record management system that allows you to ignore physical file structures and concentrate on the logical structure of a file. Sunbelt's implementation of BTRIEVE allows execution of all BTRIEVE Functions by the PL/B program. BTRIEVE is not supported in the Linux runtimes. Features and benefits of BTRIEVE include:
Each data file may have up to 24 key fields or access paths. BTRIEVE maintains separate internal indexes for each access path.

• Files may be partitioned among different logical and/or physical drives. Both files must be available when attempting to access the data.

• Support is included for duplicate, modifiable, segmented, null and descending keys.

• Keys into the data may be added or dropped as necessary.

• File size is restricted only by the available disk space.

• All keys are maintained when the file is accessed.

• Provisions are included for a relational database.

• Two types of keys are supported - standard and extended. Standard keys are string (ASCII strings) and binary (unsigned 2 byte integers). Extended key types include IEEE floating point, zero terminated string, packed decimal, etc.

• Transaction processing is supported.

• Network data access (multi-user) capability is built into the BTRIEVE file I/O routines.

• Data may be accessed in ascending or descending sequence dependent on the values of the designated key fields.

• A relational structure may exist between BTRIEVE files.

• A complete set of utilities is included with your BTRIEVE software (not from Sunbelt) to maintain and create BTRIEVE files. These include the ability to COPY the contents of one BTRIEVE file to another, DROP a supplemental index, create a supplemental index, etc.

The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

opcode

Required. A previously defined Numeric Variable or Expression representing the BTRIEVE Function Code

status

Required. A previously defined Numeric Variable returning the Btrieve status code (0 = Successful).

bfile

Required. A previously defined BFILE definition label.

buffer

Required. A previously defined Character String Variable or SKIP directive indicating the beginning of the input or output buffer space for BTRIEVE file I/O.

length

Required. A previously defined Numeric Variable or Expression representing the amount of data sent to or received from Btrieve.

key

Required. A previously defined Character String Variable representing a key value sent to or received from BTRIEVE.

keynum

Required. A previously defined Numeric Variable or representing the amount of data sent to or received from Btrieve.

Flags Affected: OVER

Note the following:

1. All calls to the BTRIEVE record manager return a status value. This value is placed in the variable {status}. You should always check the value of {status} after every BTRIEVE instruction. {status} is always a return value from BTRIEVE.

2. {bfile} is the BFILE declaration previously declared in the user data area. Its contents are initialized upon execution of a BTRIEVE OPEN operation. The BTRIEVE record manager references and updates this upon all file operations. Your application program must allocate a separate BFILE declaration for each BTRIEVE file it opens. Unlike conventional PL/B ISAM file I/O, if you have multiple indexes, you must only have one BFILE definition and thus execute only one open operation.

3. All data transferred from and to the BTRIEVE record manager use the {buffer} area. This is an area from 1 to n bytes in length (with 'n' not to exceed the maximum allowed by BTRIEVE). {buffer} must be a valid DIM or INIT variable and indicates the starting point of the total buffer. It is recommended {buffer} be setup using the SKIP parameter. {buffer} may be both a sending and receiving variable for BTRIEVE.

4. The actual amount of data passed from {buffer} to BTRIEVE or received from BTRIEVE is determined by {length}.

5. Dependent on the particular operation, {key} is the key value to or from the BTRIEVE record manager. {key} is both a sending and receiving variable for BTRIEVE.

6. You may have up to 24 different keys for each BTRIEVE file. {keynum} tells the BTRIEVE record manager that access path to follow for this particular operation. {keynum} is a FORM variable, INTEGER variable, an immediate value or an EQUated value with a range from 0 to 23. The BTRIEVE record manager does not alter the {keynum} field. {keynum} is an input field only for BTRIEVE and has other purposes for some of the BTRIEVE operations. See the BTRIEVE manual for more details.

7. The OVER flag is set if the BTRIEVE record manager cannot be accessed (i.e., BREQUEST has not been loaded for a workstation.

8. Network versions of BTRIEVE are not supported with SUNDB86L.

Functions:

The Btrieve operation code determines the type of BTRIEVE function to perform. The operation may be a read, write, delete, update, or other function. The variable specified must be a Numeric Variable, an Expression, an Equated value, or a decimal value. The application program is responsible for specifying a valid {opcode} on every BTRIEVE instruction. The BTRIEVE record manager never changes {opcode}. The valid opcode values and the operations they perform are:

Example:

This example program opens, reads, and writes to a Btrieve file.

See Also: Disk I/O Instructions