Summary of Btrieve API Operations

The Btrieve API provides over 40 operations that you can call from your application program. The following tables summarize these operations. Refer to Chapter 2, Btrieve API Operations, for complete descriptions of the Btrieve API operations. Refer to Appendix A, Quick Reference of Btrieve Operations, for a summary of Btrieve API operations ordered by operation code.

Session-Specific Operations

The following operations allow you to set or retrieve the current directory, shut down a workstation transactional interface, retrieve the transactional interface version number, terminate a client connection with the server transactional interface, and begin, end, or abort a transaction. In applications that handle multiple clients, these operations are specific to the calling client.

Table 1-3 Session-Specific Operations
Operation	Code	Description
Set Directory	17	Changes the current directory.
Get Directory	18	Returns the current directory.
Stop	25	Terminates the workstation transactional interface (not available for server-based transactional interface).
Version	26	Returns the version number of the transactional interface.
Reset	28	Releases all resources held by a client.
Begin Transaction	19 1019	Marks the beginning of a set of logically related operations. Operation 19 begins an exclusive transaction. Operation 1019 begins a concurrent transaction.
End Transaction	20	Marks the end of a set of logically related operations.
Abort Transaction	21	Removes operations performed during an incomplete transaction.

File-Specific Operations

The following operations deal with a specific file, and therefore use the position block parameter to identify the file on which to operate. The file-specific operations are of three types:

File access and information. These operations allow you to create a file, open and close a file, retrieve file statistics, set and clear the file's owner name, start or stop continuous operation mode on a file, unlock a file, and create and drop indexes on a file.

Data retrieval. These operations allow you to retrieve a single record or a set of records given specified criteria. The Btrieve API supports data retrieval either by logical location in an index path or by physical location. For more information, refer to "Accessing Records" in the Pervasive PSQL Programmer's Guide.

In addition, you can apply biases to the operation codes to control file and record locking in multi-client situations. For more information, refer to "Supporting Multiple Clients" in the Pervasive PSQL Programmer's Guide.

Data manipulation. These operations allow you to insert, update, or delete data.

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 with the specified characteristics.
Stat	15	Returns file and index characteristics, and number of records.
Stat Extended	65	Returns file names and paths of an extended file's components and reports whether a file is using a system-defined log key.
Set Owner	29	Assigns an owner name to a file.
Clear Owner	30	Removes an owner name from a file.
Continuous Operation	42	Places the specified file in or removes the file from continuous operation mode, for use in system backups.
Unlock	27	Unlocks a record or records.
Create Index	31	Creates an index.
Drop Index	32	Removes an index.

Table 1-5 Data Retrieval Operations
Operation	Code	Description
Index-Based (Logical) Data Retrieval
Get Equal	5	Returns the first record in the specified index path whose key value matches the specified key value.
Get Next	6	Returns the record following the current record in the index path.
Get Previous	7	Returns the record preceding the current record in the index path.
Get Greater Than	8	Returns the first record in the specified index path whose key value is greater than the specified key value.
Get Greater Than or Equal	9	Returns the first record in the specified index path whose key value is equal to or greater than the specified key value.
Get Less Than	10	Returns the first record in the specified index path whose key value is less than the specified key value.
Get Less Than or Equal	11	Returns the first record in the specified index path whose key value is equal to or less than the specified key value.
Get First	12	Returns the first record in the specified index path.
Get Last	13	Returns the last record in the specified index path.
Get Next Extended	36	Returns one or more records that follow the current record in the index path. Filtering conditions can be applied.
Get Previous Extended	37	Returns one or more records that precede the current record in the index path. Filtering conditions can be applied.
Get Key	+50	Detects the presence of a key value in a file, without returning an actual record.
Get By Percentage	44	Returns the record located approximately at a position derived from the specified percentage value.
Find Percentage	45	Returns a percentage figure based on the current record's position in the file.
Non-Index-Based (Physical) Retrieval
Get Position	22	Returns the position of the current record.
Get Direct/Chunk	23	Returns data from the specified portions (chunks) of a record at a specified position.
Get Direct/Record	23	Returns the record at a specified position.
Step Next	24	Returns the record from the physical location following the current record.
Step First	33	Returns the record in the first physical location in the file.
Step Last	34	Returns the record in the last physical location in the file.
Step Previous	35	Returns the record in the physical location preceding the current record.
Step Next Extended	38	Returns one or more successive records from the location physically following the current record. Filtering conditions can be applied.
Step Previous Extended	39	Returns one or more preceding records from the location physically preceding the current record. Filtering conditions can be applied.
Get By Percentage	44	Returns the record located approximately at a position derived from the specified percentage value.
Find Percentage	45	Returns a percentage figure based on the current record's position in the file.
Concurrency Control Biases (Add to the Appropriate Operation Code)
Single-record wait read lock	+100	Locks only one record at a time. If the record is already locked, the client retries the operation.
Single-record no-wait read lock	+200	Locks only one record at a time. If the record is already locked, the transactional interface returns an error status code.
Multiple-record wait read lock	+300	Locks several records concurrently in the same file. If the record is already locked, the client retries the operation.
Multiple-record no-wait read lock	+400	Locks several records concurrently in the same file. If the record is already locked, the transactional interface returns an error status code.
No-wait page write lock	+500	In a concurrent transaction, tells the transactional interface not to wait if the page to be changed has already been changed by another active concurrent transaction. This bias can be combined with any of the record locking read biases (+100, +200, +300, or +400).

Table 1-6 Data Manipulation Operations
Operation	Code	Description
Insert	2	Inserts a new record into a file.
Update	3	Updates the current record.
Delete	4	Removes the current record from the file.
Insert Extended	40	Inserts one or more records into a file.
Update Chunk	53	Updates specified portions (chunks) of the current record. This operation can also append data to a record or truncate a record.

Unsupported Operations

When looking at transactional interface traces or SDK header files, you may see operations that are not listed in the reference for Btrieve API operations. These are for the internal use of Pervasive PSQL and you should not use them in your applications. The following operations are not supported.

Table 1-7 Unsupported Operations
Operation	Code	Description
B_MISC_DATA	41	Reserved for use by transactional interface
B_EXTEND	16	Reserved for use by SQL engine
Begin Transaction (nested) via Btrieve	2019	Reserved for use by transactional interface