The operations documented here are the ones your application can perform using the Btrieve API. For each operation you will find the following information:

The Btrieve API operations are listed alphabetically.

The Abort Transaction operation (B_ABORT_TRAN) terminates the current transaction and removes the results of all operations performed since the beginning of the transaction. It also unlocks all files and records locked by the transaction.

You must issue a successful Begin Transaction (19 or 1019) before you issue an Abort Transaction operation.

Set the operation code to 21. The MicroKernel Engine ignores all other parameters on an Abort Transaction call.

If the Abort Transaction operation is successful, the MicroKernel Engine returns status code 0. The results of all Insert, Update, and Delete operations issued since the beginning of the transaction are removed from the files.

If the Abort Transaction operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Abort Transaction operation has no effect on any file currency information.

The Begin Transaction operation (B_BEGIN_TRAN) defines the start of a transaction. Transactions are useful when you need to perform multiple Btrieve API operations as a single event. For example, use a transaction if your database would become logically inconsistent if some operations were successful, but at least one operation failed to complete successfully.

By enclosing a set of operations between Begin and End Transaction operations, you can ensure that the MicroKernel Engine does not permanently complete any operations in the set unless you request the completion with an explicit End Transaction (20). Changes made within a transaction are not visible to other users until the End Transaction operation is successfully performed.

The MicroKernel Engine prohibits certain operations during transactions because they have too great an effect on the file or on performance. These operations include Set Owner (29), Clear Owner (30), Create Index (31), and Drop Index (32).

Your application must end or abort any previous transaction before issuing a Begin Transaction operation.

Set the operation code to 19 to begin an exclusive transaction, or 1019 to begin a concurrent transaction. The MicroKernel Engine ignores all parameters except the operation code on any Begin Transaction call.

On any Begin Transaction operation, you can specify default lock biases:

On a Begin Concurrent Transaction operation, you can add +500 to the operation code (1519), which forces the MicroKernel Engine not to retry the Insert, Update, and Delete operations within a transaction.

In addition, you can combine the +500 bias with a default lock bias. For example, using 1019 + 500 + 200 (1719) begins a concurrent transaction, suppresses retries for Insert, Update, and Delete operations, and specifies single no-wait read locks at the same time.

For more information about transactions and locking, see PSQL Programmer's Guide.

If the Begin Transaction operation is successful, the MicroKernel Engine returns status code 0.

If the Begin Transaction operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Begin Transaction operation has no effect on any file currency information.

The Clear Owner operation (B_CLEAR_OWNER) removes an owner name that you have previously assigned to a file with the Set Owner operation. If the file was previously encrypted, the MicroKernel Engine decrypts the file during a Clear Owner operation. For more information, see Owner Names in Advanced Operations Guide.

After a Clear Owner operation, the MicroKernel Engine no longer requires the owner name to open or modify a file. If you encrypted the data in the file when you assigned the owner, the MicroKernel Engine decrypts the data during a Clear Owner operation. The more data that was encrypted, the longer the Clear Owner operation takes.

If the Clear Owner operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Clear Owner operation has no effect on any file currency information.

The Close operation (B_CLOSE) closes the file associated with a specified position block and releases any locks your application has executed for the file. Your application should always perform a Close operation when it has finished accessing a file. After a Close operation, your application cannot access the file again until it issues another Open (0) for that file.

You can close a file even while inside a transaction. However, the Close operation does not end the transaction. You must explicitly end or abort the transaction. If you abort the transaction, changes made inside the transaction are aborted. If you end the transaction, changes are committed.

If the Close operation is successful, the position block for the closed file is no longer valid.

If the Close operation fails, the file remains open and the MicroKernel Engine returns the following status code:

The Close operation destroys both the physical and the logical currency information of the file.

The Continuous Operation operation (B_CONTINUOUS) allows you to perform system backups without closing active MicroKernel Engine files. Any changes you make while a file is being backed up are stored in a temporary file called a delta file. Except for changes written to the delta file, the system backup includes the contents of all files placed in continuous operation mode. The MicroKernel Engine automatically rolls the delta file changes into the backed up files when those files are taken out of continuous operation mode.

This operation also allows you to safely copy a file while that file is still active. In a client/server set up, the client that begins Continuous Operation on a file must be the client that stops Continuous Operation on that file.

When defining the set of files to be backed up, keep in mind the following information:

When writing a server-based application that calls the Continuous Operation operation, make sure you call btrvID, and use a valid client ID so you can begin and end continuous operation under the same client.

The Btrieve API allows you to define multiple backup sets by specifying a different client ID for each backup set through the btrvID function. However, two sets cannot contain the same files.

While the MicroKernel Engine rolls changes from the delta file into the data file, users can continue to update, insert, and read the MicroKernel Engine file just as they normally would. The MicroKernel Engine appends new pages to the delta file while rolling in changes, if an insert requires such an action. No changes are lost.

If your application uses the btrv function, do not unload the application while any file is in continuous operation mode. If you do, you may be unable to remove the affected files from continuous operation mode. This is because the default client ID that the MicroKernel Engine originally assigned as the owner of the affected files may have been reassigned to another application. Because the MicroKernel Engine no longer knows the proper owner of the affected files, it is unable to remove those files from continuous operation mode.

If the system crashes while in continuous operation mode or while the MicroKernel Engine is rolling the changes from a delta file into the file, then the MicroKernel Engine rolls all changes into the file when it is first opened after the system is rebooted.

If the Continuous Operation operation is successful, the MicroKernel Engine returns status code 0, but it returns no values either in the data buffer or in the data buffer length parameter.

If the operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

In addition to the preceding codes, your application can return standard
I/O error codes such as status code 18.

If the MicroKernel Engine returns a nonzero status code, the Continuous Operation operation returns in the data buffer the portion of the input string that generated the error. If no input string was used, the data buffer contains the file names that caused the error. The data buffer length reflects the length of the output string in the data buffer. At this point, the data buffer length contains the length of that file name.

The Continuous Operation operation does not establish any currency on the file.

The Create operation (B_CREATE) lets you generate a new data file from within your application. The Create operation also has subfunctions that allow you to delete or rename a file (see Delete and Rename Subfunctions for the Create Operation).

If you are creating an empty file over an existing file, ensure that the existing file is closed before executing the Create operation.

The data buffer contains specifications for the file and keys to be created. Both Create (14) and Stat (15) use the same data buffer structure, so they are documented together here with the slight differences noted. The following tables show the structure of the information for the BTRV type of entry points and also for the BTRVEX type, both of which are described under Btrieve API Functions.

Note that the order of elements in the specification differs between the two types of entry points. Details for these elements are found under the following topics:

The data buffer contains a file specification, followed by zero or more key specification blocks, followed by zero or more ACS blocks.

Store the file specification in the first 16 or 32 bytes of the data buffer. The bytes are numbered beginning with 0. Store the information for the record length, page size, and number of indexes as integers.

Logical Fixed Record Length. The logical record length is the number of bytes of fixed-length data in the file. Do not include variable-length data in the logical record length.

Page Size. Page size is determined by your file format version. See Choosing a Page Size in PSQL Programmer's Guide. The following table gives page size examples for different file format versions.

Record Count. The number of records in the file. This value is returned by Stat (15). For Create (14), set this field to 0.

Number of Keys. The number of indexes is the number of keys (not key segments) you are defining for the file. To create a data-only file, set the number of indexes to 0.

File Version. The MicroKernel Engine file version to be created. In earlier releases, the MicroKernel Engine used a two-byte integer to receive the number of indexes on a create operation. The high-order byte of this integer was always 0 because the maximum number of indexes is 119. This high-order byte has historically been used in the Stat (15) operation to return the file version, but it can now be used to specify the Create file version without causing errors in previous applications. The supported file versions for Create are 6.0, 7.0, 8.0, 9.0, 9.5, and 13.0, which are represented in the specified byte with hex values 0x50, 0x60, 0x70, 0x80, 0x90, 0x95, and 0xD0, respectively. The following table lists file version flag values for different file format versions.

Number of extra pointers. For Create (14), the number of duplicate pointers to reserve for future keys. For Stat (15), the number of remaining pointers. Used with Reserve Duplicate Pointers flag. When this flag is not used, set this field to 0.

Physical Page Size. Used when the Page Compression file flag is set. If the Page Compression flag is not specified, set this field to 0. This field was previously marked as unused.

In data files version 6.x and later, logical pages map to physical pages, stored in a Page Allocation Table (PAT). A physical page is exactly the same size as a logical page. Page compression can be used with file format 9.5 and later. Database pages are compressed at the page level. Each logical page is compressed into one or more physical page units. These individual physical pages are smaller in size than a logical page.

The physical page size field can be used to specify the physical page size to be used for the file. The value specified in this field is multiplied by 512 to determine the actual physical page size used. If 0 is specified, the engine uses a default value of 512 bytes for the physical page size.

The value specified for the physical page size cannot be larger than the value specified for the logical page size. If it is then the engine will round down the value specified for the physical page size so that it is the same as the logical page size. The logical page size needs to be an exact multiple of the physical page size. If it is not then the logical page size is rounded down so that it becomes an exact multiple of the physical page size. If, as a result of these manipulations, the logical and physical values end up to be the same, then page level compression will not turned on for this file. See also Creating a File with Page Level Compression in PSQL Programmer's Guide

File Flags. The bit settings in the File Flags word specify file attributes. The following table shows the binary, hexadecimal, and decimal representations of file flag values.

Avoid using incompatible flags. Flags are incompatible if they use the same bit positions. Unused bits are reserved for future use. Set them to 0.

To combine file attributes, add their respective file flag values. For example, to specify a file that allows variable-length records and uses blank truncation, initialize the file flags word to 3 (2 + 1). The MicroKernel Engine ignores the blank truncation and free space bits if the variable length records bit is set to 0.

If you set the page preallocation bit, use the last 2 bytes in the file specification block (allocation) to store an integer value that specifies the number of pages to preallocate to the file. If you set the Data Compression bit, the MicroKernel Engine ignores the variable length records bit. If you set the key-only file bit, the MicroKernel Engine ignores the system data bits.

The database engine automatically uses data compression on files that use system data and have a record length that exceeds the maximum length allowed. See Table 8 in PSQL Programmer's Guide.

Set the duplicate pointers bit if you anticipate adding an index sometime after creating a file, and if that index has duplicate values and will not be marked as repeating-duplicatable. Setting this bit causes the MicroKernel Engine to reserve space in each record of the file for pointers that link the duplicate values. By reserving this space, you can possibly lower retrieval time and save disk space, especially if the keys are long and you anticipate that many records will have duplicate key values.

Set the key number bit if you need to assign a specific number to a key, and place the desired key number in the Manually Assigned key number element (offset 0x0E) of the key specification block. The MicroKernel Engine does not require consecutive key numbers, and files can have gaps between key numbers. When a key is created, by default the MicroKernel Engine assigns the lowest available key number to that index (beginning with 0). However, some applications may require a key number different from the default assignment.

Set the Use VATs bit if the file uses variable-tail allocation tables. To use VATs, a file must use variable-length records.

Preallocated Pages. You can specify the number of pages to preallocate. Use this element only if you specified the page preallocation file flag. For more information about page preallocation, see Page Preallocation in PSQL Programmer's Guide.

Place zero or more key specification blocks immediately after the file specification. Allocate a 16- or 24-byte key specification block for each key segment in the file. Store the information for the key position and the key length as integers.

As shown in the following table, the maximum number of key segments allowed depends on the file page size and file format.

See also the status codes 26: The number of keys specified is invalid and 29: The key length is invalid, both in Status Codes and Messages.

The following table shows the data buffer structure of the key specification. Each key specification block is 16 bytes for BTRV type entry points or 24 bytes for BTRVEX types. Where two data types are given, but first is used with BTRV and the second with BTRVEX. The offsets repeat for each key block.

Key Position. The key position is the byte offset at which the key or key segment begins. Positions are relative to 1. A key at the beginning of the record starts at position 1. There is no position 0.

Key Length. The length of the key or key segment. The maximum length of a key, including all key segments, is 255 bytes.

Key Flags. The bit settings in the key flag word specify key attributes. The following table shows the binary, hexadecimal, and decimal representations of key flag values.

Avoid using incompatible flags. Flags are incompatible if they use the same bit positions. Unused bits are reserved for future use. Set them to 0.

To combine key attributes, sum their values. For example, if the key is an extended type, part of a segmented key, and collated in descending order, then initialize the key flag word to 336 (256 + 16 + 64).

The Segmented Key attribute indicates that the next key specification block in the data buffer refers to the next segment of the same key. Follow these rules for segmented keys:

The ACS applies only to keys of type STRING, LSTRING, ZSTRING, WSTRING, and WZSTRING. You cannot define a key that is both case-insensitive and uses an ACS. In a file in which a key has an ACS designated for some segments but not for others, the segments that designate an ACS are sorted by the specified ACS, while the segments with no ACS are sorted according to their respective types.

Extended Data Type. You specify the Extended Data Type byte of the key specification block as a binary value. Table 15 shows the codes for the extended data types.

Extended data type codes 12, 13, 16, and 21–24 are reserved for future use.

You can define the STRING and UNSIGNED BINARY data types as either standard or extended types. This maintains compatibility with applications that were developed with earlier versions of Btrieve API, while allowing newer applications to use extended data types exclusively.

Regarding the data type you assign to a key, MicroKernel Engine does not ensure that the records you input adhere to the data types defined for the keys. For example, you could define a TIMESTAMP key in a file, but store a character string there. Your Btrieve API application would work fine, but an ODBC application that tries to access the same data using the ODBC TIMESTAMP format might fail, because the byte format could be different and the algorithms used to generate the timestamp value could be different. For complete descriptions of the data types, see SQL Engine Reference.

Null Value. Represents an exclusion value for the key. If you have defined a key as a null key, you must supply a value for the MicroKernel Engine to recognize as the null value for each key segment. This is in reference to the legacy null and does not reflect true nulls. For a discussion of null support, see Null Value in PSQL Programmer's Guide.

Manually Assigned Key Number. The MicroKernel Engine allows an application to assign specific key numbers when creating a file with indexes. To manually assign key numbers to each index for a file, specify each key’s number as a binary value in the key specification block, and set the key number bit (0x400) in the File Flags word.

Key numbers must be unique to the file and must be specified in ascending order, beginning with key 0. They must also be valid (less than the maximum number of keys for the file’s page size).

The ability to manually assign key numbers complements to the ability to delete a key and not have the MicroKernel Engine renumber all keys that have a key number greater than the deleted key. For example, if an application drops an index and instructs the MicroKernel Engine not to renumber higher-numbered keys, and if a user then clones the affected file without assigning specific key numbers, the cloned file has different key numbers than the original.

ACS Number. For keys that use a specific ACS, the key specification block provides the ACS number by which to collate the key. The ACS number is based on its position in the data buffer. The first ACS following the last key specification block is ACS number 0. Following ACS 0 is ACS 1, which is followed by ACS 2, and so on.

In the data buffer for a Create operation, collating sequences appear one after another immediately following the last key specification block. The 265 bytes used to specify an ACS, ISR, or ICU collation are described in the following tables.

User-Defined ACS Files. To create an ACS that sorts string values differently from the ASCII standard, your application must place 265 bytes directly into the data buffer.

For examples of user-defined ACS files, see Alternate Collating Sequences in PSQL Programmer's Guide.

International Sort Rules (ISRs). To specify an ISR table name, your application must place 265 bytes directly into the data buffer.

Unicode collations. To specify a Unicode collation according to the International Components for Unicode (ICU) standard, your application must place 265 bytes directly into the data buffer.

The data buffer length must be long enough to include the file specifications, the key specifications, and any ACS files that have been defined. Do not specify the file record length in this parameter.

For example, to create a file using the BTRV entry point that has two keys of one segment each and an ACS, the data buffer for the Create operation should be at least 313 bytes long, as follows:

The key number for the Create operation determines whether the MicroKernel Engine warns you when a file of the same name already exists, and also whether the MicroKernel Engine should use a local or remote engine when creating the file.

Use the following table to choose the value for the key number parameter.

The Create operation has two additional subfunctions that you can use to delete or rename files.

Before Pervasive.SQL v8.5, it was always possible to manipulate MicroKernel Engine files through the operating system because the engine depended on the rights and privileges given to the PSQL user by the operating system.

After the introduction of PSQL database security in v8.5, these operating system access rights might be removed when a database is secured against unauthorized access. The options for programmatically deleting or moving a file may change because operating system rights are not always available.

The rename and delete subfunctions are implemented as Create operations with alternate key numbers. You do not need to provide a file specification as you do when creating a new data file. The following table shows how you set up the Create operation to use the rename or delete subfunctions.

These subfunctions have been modified to work with the security model in that they will accept a URI in place of a file name in the key buffer and data buffer, if needed, to indicate a MicroKernel Engine file to delete or rename. This allows you to provide security information with the operation. For details about URI connection strings, see Database URIs in PSQL Programmer's Guide.

The security information is processed just like a normal Create or Open operation. The user must be authenticated and have DB_RIGHT_CREATE, DB_RIGHT_ALTER and DB_RIGHT_OPEN privileges for the existing files and for the directory where the new file will be located if applicable.

If the Create operation is successful, the MicroKernel Engine either warns you of the existence of a file with the same name or creates the new file according to your specifications. The new file does not contain any records. The Create operation does not open the file. Your application must perform an Open operation before it can access the file.

If the Create operation fails, the MicroKernel Engine returns one of the following status codes:

The Create operation establishes no currency on the file.

The Create Index operation (B_BUILD_INDEX) adds a key to an existing file.

The MicroKernel Engine allows you to assign specific key numbers when creating a key. This capability complements the ability to delete a key and not have the MicroKernel Engine renumber all keys that have a key number greater than that of the deleted key. If an application drops an index and instructs the MicroKernel Engine not to renumber higher-numbered keys, and a user then clones the affected file without assigning specific key numbers, the cloned file has different key numbers than the original.

If you define an ACS in the data buffer, the MicroKernel Engine first checks for an existing ACS (using the name you specified) before adding it to the file. If the MicroKernel Engine finds an existing ACS with the name you specified, the MicroKernel Engine does not duplicate the ACS definition in the file, but does associate the ACS with the new key.

If you specify the Use Named ACS attribute in the Key Flags word, the MicroKernel Engine uses the ACS name supplied in the data buffer to locate an ACS of the same name within the file, then assigns that ACS to the new key.

If a file is opened by more than one MicroKernel Engine client and one of the clients starts a Create Index process, remote clients can perform Get and Step operations on the open file while the MicroKernel Engine client creates the key.

If the key being created is not an autoincrement key, the Get and Step operations of remote clients can have lock biases, and when the Create Index process is completed, you can update and delete the locked records without issuing additional read operations. This is possible because the MicroKernel Engine does not have to change the images of the records in order to create the key.

However, if the key being created is an autoincrement key, then the MicroKernel Engine has to both build the index and change every record with a zero value in the appropriate field. Remote clients that perform Get or Step operations without a lock bias before or during the key creation can receive status code 80 when they execute an update or delete operation after the successful completion of the key creation.

Also, the MicroKernel Engine returns status code 84 if a client tries to create an autoincrement key while another client has locked a record. Similarly, the MicroKernel Engine returns status code 85 if a client attempts to execute a Get or Step operation with a lock bias during index creation for an autoincrement key by another client.

The MicroKernel Engine immediately adds the new key to the file. The time required for this operation depends on the total number of records to be indexed, the size of the file, and the length of the new index.

If the Create Index operation is successful, the number of the new key is either the number you specified or one of the following:

You can use the new key to access your data as soon as the operation completes.

If the Create Index operation is unsuccessful, the MicroKernel Engine drops whatever portion of the new index it has already built. The file pages allocated to the new index prior to the error are placed on a list of free space for the file and reused when you insert records or create another key.

If the operation fails during the creation of an autoincrement key, any values that have already been altered remain altered. The MicroKernel Engine can return the following status codes:

If processing is interrupted during the creation of a key, you can access the data in the file through the file’s other keys. However, the MicroKernel Engine returns a nonzero status code if you try to access data by the incomplete index. To correct this problem, drop the incomplete index with a Drop Index (32) and reissue Create Index.

The Create Index operation has no effect on any file currency information.

The Delete operation (B_DELETE) removes an existing record from a file. The space that the deleted record occupied is then available for inserting new records.

The Delete operation is not a valid operation if performed immediately after an extended Get or extended Step operation.

After you perform a Delete operation, a later Get Next or Get Previous operation must use the same key number as the last operation that established logical position. If you use another value, the MicroKernel Engine returns status code 7.

The MicroKernel Engine does not allow Delete operations after a Get Key (+50). Before the MicroKernel Engine performs a Delete operation, it compares the current usage count of the data page it intends to modify with the usage count of the data page when the record was read. To obtain the usage count, the MicroKernel Engine must read the data page.

Because the Get Key operation does not read the data page, no usage count is available for comparison on the Delete. The Delete fails because the MicroKernel Engine cannot perform its passive concurrency conflict checking without the compare. When the Delete fails, the MicroKernel Engine returns status code 8.

If the Delete operation is successful, the MicroKernel Engine removes the record from the file, releases the record lock (if one existed for the deleted record), and adjusts all key indexes to reflect the deletion.

If the Delete operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

Delete operations never reduce file size. Empty Space created by deletion of records is reused when records are added in the future. Recovering disk space can only be done by recreating the file and inserting all the records into it.

The Delete operation destroys the complete physical location information and the logical current record position but does not change the physical and logical positions of either the next record or the previous record.

The Drop Index operation (B_DROP_INDEX) deletes a key from an existing file.

If you drop the system-defined log key, you can rebuild it using Create Index (31).

When you delete a key, the MicroKernel Engine automatically renumbers all higher-numbered keys, unless you specify otherwise. The MicroKernel Engine renumbers by decrementing the higher-numbered keys by 1. For example, suppose you have a file with key numbers 1, 4, and 7. If you drop key 4, the MicroKernel Engine renumbers the keys as 1 and 6.

If you do not want the MicroKernel Engine to automatically renumber keys, add a bias of 128 to the value you supply for the key number parameter. This bias allows you to leave gaps in the key numbering, and consequently you can drop a damaged index and then rebuild it without affecting the numbering of other keys in the file. You rebuild the index using Create Index (31), which allows you to specify a key number.

However, if you delete a key without renumbering higher-numbered keys and then a user clones the affected file without assigning specific key numbers, the cloned file has different key numbers from the original.

If the Drop Index operation is successful, the MicroKernel Engine places the pages that were allocated to that index on a list of free space for later use. Unless you specify otherwise, the MicroKernel Engine renumbers the higher-numbered keys.

If the Drop Index operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

If processing is interrupted while the MicroKernel Engine is dropping an index, you can access the data in the file by the file’s other keys. The MicroKernel Engine returns status code 56 if you try to access the file by an incomplete index. If processing is interrupted, reissue the Drop Index operation.

The Drop Index operation has no effect on physical file currency information. However, dropping the key used to establish the last logical currency destroys the logical currency.

The End Transaction operation (B_END_TRAN) completes a transaction and makes the appropriate changes to the data files. It also unlocks all files and records locked by the transaction.

Before issuing an End Transaction operation, your application must issue a successful Begin Transaction (19 or 1019).

Set the operation code to 20. While the MicroKernel Engine ignores all other parameters on an End Transaction call, you should initialize them to 0 to ensure compatibility with future releases.

If the End Transaction operation is successful, all the operations within the transaction are recorded in your file. Your application cannot abort a transaction after an End Transaction operation.

If the End Transaction operation is unsuccessful, the MicroKernel Engine returns the following status code:

The End Transaction operation has no effect on any file currency information.

The Find Percentage operation (B_GET_PERCENT) is one of two Btrieve API operations that window-oriented applications can use to implement scroll bars. The other is Get By Percentage (44). Find Percentage returns the approximate position of a record either relative to a key path or as the record’s physical location within the file. The position is expressed as a percentage value. See Result for a definition of the range of percentage values.

The Find Percentage operation is provided specifically to support scroll bar implementation. Because many factors affect the accuracy of this operation – that is, whether the returned percentage value accurately reflects the position of the record or key value – you should not rely on the accuracy of this operation for other purposes.

To optimize the Find Percentage operation, the MicroKernel Engine assumes that a file has an even distribution of records among the data pages and keys among the index pages. However, distribution can be affected by the following situations:

The granularity setting is optional and allows you to choose the factor by which the percentage is measured. In releases before PSQL 9, this value was always 10000.

If you want to specify the granularity, follow these steps:

The following table summarizes positions and layouts for these steps.

For example, if you want to get the 100th record from a file that contains 365 records, you can use Find Percentage (45) with 100 as the percentage and 365 as the granularity.

If the Find Percentage operation is successful, the MicroKernel Engine returns the relative position of the specified key value or record to the data buffer. This position is expressed as a percentage of the offset into the key path or file and is a value in the range of 0 (0 percent) through 10000 (100.00 percent). Note this is not the physical or logical position.

The percentage value is returned as a 4-byte integer in low-byte, high-byte order. For example, when using default granularity:

The MicroKernel Engine also returns a data buffer length of at least 4 if the operation is successful.

If the Find Percentage operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Find Percentage operation does not change any currency information.

The Get By Percentage operation (B_SEEK_PERCENT) is one of two Btrieve API operations that can be used by window-oriented applications for implementing scroll bars. The other is the Find Percentage (45). Get By Percentage retrieves a record by that record’s relative position in the file, where the position is based on a percentage value you supply when you call the operation. You must also specify whether the position is relative to a specified key path or represents the record’s actual physical location in the file.

If you are not specifying a granularity (see Granularity), the range of acceptable percentage values for the first two bytes of the data buffer parameter is from 0 (indicating the beginning of the key path or file) through 10000 (the end of the key path or file). The value corresponds to a range of 0% to 100.00%, assuming two implied decimal places. If you want to find the record approximately 33.33% through the file, pass the value 3333 in the data buffer. Be sure to store the value as an integer (in low-byte, high-byte order). For example, to seek to the 50 percent point in the file, use a value of 5000 (0x1388). After byte-swapping 0x1388, store 0x88 and 0x13 in the first two bytes of the data buffer parameter.

If you wish to specify a granularity for the search, set your data buffer parameter as specified in Granularity.

The Get By Percentage operation is provided specifically to support scroll bar implementation. Because many factors affect the accuracy of this operation – that is, whether the returned record is positioned at the actual percentage point you specify in the file – you should not rely on the accuracy of this operation for other purposes.

To optimize the Get By Percentage operation, the MicroKernel Engine assumes that a file has an even distribution of records among the data pages and keys among the index pages. However, distribution can be affected by the following situations:

The granularity setting is optional and allows you to choose the factor by which the percentage is measured. In releases before PSQL 9, this value was always 10000.

If you want to specify the granularity, follow these steps:

For example if you want to get the 100th record from a file that contains 365 records, you can use Get By Percentage (44) with 100 as the percentage and 365 as the granularity.

If the Get By Percentage operation is successful, the MicroKernel Engine returns to the data buffer a record that is either from the designated position relative to the specified key path or from the physical position in the file. The MicroKernel Engine returns the length of the record in bytes into the data buffer length parameter. If the operation seeks the record by a key path, the MicroKernel Engine returns the key value for the specified key path in the key buffer parameter. If the operation seeks the record by physical record order, the MicroKernel Engine does not return any information in the key buffer parameter.

If the Get By Percentage operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

If successful when seeking a record relative to a specified key path, the Get By Percentage operation establishes the new logical and physical currencies based respectively on the specified key number and the retrieved record.

If successful when seeking a record based on the record’s physical location within the file, the Get By Percentage operation establishes the new physical currency based on the retrieved record.

If the Get By Percentage operation is unsuccessful, the MicroKernel Engine changes no currency.

The Get Direct/Chunk operation (B_GET_DIRECT) can retrieve one or more portions, called chunks, of a record. This operation is especially useful on files containing records longer than the maximum data buffer size. Such records are too long to be retrieved by the other Get and Step operations due to restrictions on the length of the data buffer parameter. Your application specifies the record from which chunks are to be retrieved by supplying its physical address. The location of a chunk in a record is generally specified by its offset and length.

Use one of the following chunk descriptors in the data buffer:

The following example shows a record with three randomly spaced chunks (areas containing [*]): chunk 0 (bytes 0x12 through 0x16), chunk 1 (bytes 0x2A through 0x31), and chunk 2 (bytes 0x41 through 0x4E).

To fetch random chunks, you must create a structure in the data buffer, based on the following table.

The following table shows a sample data buffer for a 32-bit application for fetching direct random chunks using a BTRV entry point.

When chunks of the same length are spaced equidistantly throughout a record, you can describe all the chunks to retrieve with a rectangle chunk descriptor. For example, consider the following diagram, which represents offset 0x00 through 0x4F in a record:

The record contains three chunks (areas containing [*]): chunk 0 (bytes 0x19 through 0x1C), chunk 1 (bytes 0x29 through 0x2C), and chunk 2 (bytes 0x39 through 0x3C). Each chunk is four bytes long, and a total of 16 (0x10) bytes, calculated from the beginning of each chunk, separates the chunks from one another.

You can retrieve all three chunks using a single rectangle descriptor. To fetch rectangle chunks, you must create a structure in the data buffer based on the following table.

When you use an indirect descriptor, be sure that the User Data pointer is initialized so that the chunks retrieved do not overwrite your chunk descriptor. The MicroKernel Engine uses the descriptor when copying the returned chunks to the locations that the User Data elements specify. In the event that you overwrite your chunk descriptor, the MicroKernel Engine returns status code 62.

If the rectangle has the same number of bytes between rows when it is in memory as when it is stored as a record, set Application Distance Between Rows with the same value as Distance Between Rows. However, if the rectangle is arranged in your application’s memory with either more or fewer bytes between rows, Application Distance Between Rows allows you to pass that information to the MicroKernel Engine.

When you use an indirect rectangle descriptor, the MicroKernel Engine uses both the User Data and the Application Distance Between Rows elements to determine the locations in which to store the data after retrieving it. The MicroKernel Engine stores data from the first row in offset 0 of User Data. The MicroKernel Engine stores the second row’s data to an address specified by User Data + Application Distance Between Rows. The MicroKernel Engine stores the third row’s data in the address specified by User Data + (Application Distance Between Rows * 2), and so on.

The following table shows a sample data buffer for a 32-bit application for fetching a direct rectangle chunk using a BTRV entry point.

If you add a bias of 0x40000000 to any of the subfunctions previously listed, the MicroKernel Engine calculates the subfunction Offset element values based on your physical intrarecord currency (that is, your current physical location within the record). When you use the Next-in-Record subfunction, the MicroKernel Engine ignores the Offset element in the chunk descriptor.

If the Get Direct/Chunk operation is successful and a direct chunk descriptor is used, the MicroKernel Engine returns the chunks one after another in the data buffer. If you used an indirect random chunk descriptor, the MicroKernel Engine returns the data to the locations that each chunk’s User Data element specifies. If you used an indirect rectangle descriptor, the MicroKernel Engine returns the data to locations it derives from the User Data and Application Distance Between Rows elements.

The MicroKernel Engine also stores the total length of the chunks retrieved in the data buffer length parameter. (The returned value reflects all bytes retrieved, whether they were retrieved and stored directly into the data buffer, or the indirect descriptor was used to retrieve and store the bytes elsewhere.) If the operation was partially successful, your application can use the value returned in the data buffer length parameter to determine which chunks could not be retrieved and how many bytes of the final chunk were retrieved.

The Get Direct/Chunk operation is only partially successful if any chunk begins beyond the end of the record (resulting in the MicroKernel Engine returning status code 103), or if any chunk’s offset and length combine to exceed the length of the record. In the latter case, the MicroKernel Engine returns status code 0 but ceases processing subsequent chunks, if any, in the operation.

The following status codes indicate a partially successful Get Direct/Chunk operation. When the MicroKernel Engine returns one of these status codes, your application should check the data buffer length parameter’s return value to see how much data the MicroKernel Engine actually returned.

If the MicroKernel Engine returns any of the following status codes, it has returned no data.

The Get Direct/Chunk operation has no effect on logical currency. In terms of physical currency, Get Direct/Chunk makes the record from which chunks are retrieved the physical current record.

The Get Direct/Record operation (B_GET_DIRECT) retrieves a record using its physical location in the file instead of using one of the defined key paths.

Use Get Direct/Record to accomplish the following:

If the Get Direct/Record operation is successful, the MicroKernel Engine returns the requested record in the data buffer, the length of the record in the data buffer length parameter, and the key value for the specified key path in the key buffer.

If the Get Direct/Record operation is unsuccessful and the MicroKernel Engine cannot return the requested record, the MicroKernel Engine returns one of the following status codes:

The Get Direct/Record operation erases any existing logical currency information and establishes the new logical currency according to the key number specified. It has no effect on the physical currency information.

The Get Directory operation (B_GET_DIR) returns the current directory for a specified logical disk drive.

Your application can issue a Get Directory operation at any time. The key buffer should be at least 65 characters long.

The MicroKernel Engine returns the current directory, terminated by a binary 0, in the key buffer.

The Get Directory operation has no effect on any file currency information.

The Get Equal operation (B_GET_EQUAL) retrieves a record that has a key value equal to that specified in the key buffer. If the key allows duplicates, this operation retrieves the first record (chronologically) of a group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Equal operation is successful, the MicroKernel Engine returns the requested record in the data buffer and the length of the record in the data buffer length parameter.

If the Get Equal operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

This operation returns status code 4 if the key contains a nonzero value in a null indicator segment. You cannot use GetEqual to find records that are NULL, because by definition NULL is indeterminate, or not equal to anything. If you need to find NULL values, use GetFirst followed by GetNext.

The Get Equal operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

The Get First operation (B_GET_FIRST) retrieves the logical first record based on the specified key. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get First operation is successful, the MicroKernel Engine returns the requested record in the data buffer, stores the corresponding key value in the key buffer, and returns the length of the record in the data buffer length parameter.

If the Get First operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Get First operation establishes the complete logical and physical currencies and makes the retrieved record the current one. The logical previous position points beyond the beginning of the file.

The Get Greater Than operation (B_GET_GT) retrieves a record in which the field specified by the key number has the next greater value than the one in the key buffer. If the key allows duplicates, this operation retrieves the first record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Greater Than operation is successful, the MicroKernel Engine stores the record in the data buffer, the key value in the key buffer, and the length of the record in the data buffer length parameter.

If the Get Greater Than operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Get Greater Than operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

The Get Greater Than or Equal operation (B_GET_GE) retrieves a record in which the value for the key specified by the key number is equal to or greater than the value you supply in the key buffer. The MicroKernel Engine first tries to satisfy the equal requirement. If the key allows duplicates, this operation retrieves the first record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Greater Than or Equal operation is successful, the MicroKernel Engine stores the record in the data buffer, the key value in the key buffer, and the length of the record in the data buffer length parameter.

If the Get Greater Than or Equal operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Get Greater Than or Equal operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

The Get Key bias allows you to perform a Get operation without actually retrieving a data record. You can use Get Key to detect the presence of a value in a file. A Get Key operation is generally faster than its corresponding Get operation. You can use the Get Key operation with any of the following Get operations:

The parameters are the same as those for the corresponding Get operation, except that the MicroKernel Engine ignores the data buffer length and does not return a record in the data buffer.

The prerequisites for a Get Key operation are the same as those for the corresponding Get operation.

The MicroKernel Engine does not allow Delete or Update operations after a Get Key (+50). Before the MicroKernel Engine performs Update or Delete operations, it compares the current usage count of the data page it intends to modify with the usage count of the data page when the record was read. To obtain the usage count, the MicroKernel Engine must read the data page.

Because the Get Key operation does not read the data page, no usage count is available for comparison on the Update or Delete. The Update or Delete fails because the MicroKernel Engine cannot perform its passive concurrency conflict checking without the compare. When the Update or Delete fails, the MicroKernel Engine returns status code 8.

If the MicroKernel Engine finds the requested key, it returns the key value in the key buffer and status code 0. Otherwise, the MicroKernel Engine returns a status code indicating why it cannot find the key value.

The Get Key operation establishes the current positioning in a similar manner to the corresponding Get operation. However, when a Get Key operation involves a key that allows duplicates, the MicroKernel Engine ignores the duplicate instances of the current retrieved key value. After a Get Key operation, the logical previous position points to the record containing the previous lesser key value. The logical next position points to the record with the next greater key value.

For example, assume you perform a Get Key/Get Equal operation (55) on a last name key that contains eight occurrences of Smith and a single Smythe. The logical next position does not point to the next Smith, but to Smythe.

Because a Get Key operation does not positively identify any one record, the MicroKernel Engine does not allow an Update or Delete operation to follow a Get Key operation.

The Get Last operation (B_GET_LAST) retrieves the logical last record based on the specified key. If duplicates exist for the last key value, the record returned is the last duplicate. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Last operation is successful, the MicroKernel Engine returns the requested record in the data buffer, stores the corresponding key value in the key buffer, and returns the length of the record in the data buffer length parameter.

If the Get Last operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Get Last operation establishes the complete logical and physical currencies and makes the retrieved record the current one. The logical next position points beyond the end of the file.

The Get Less Than operation (B_GET_LT) retrieves a record in which the value for the key specified by the key number has the previous lesser value than the value you supply in the key buffer. If the key allows duplicate values, this operation retrieves the last record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Less Than operation is successful, the MicroKernel Engine returns the record in the data buffer, the key value for the record in the key buffer, and the length of the record in the data buffer length parameter.

If the Get Less Than operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Get Less Than operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

The Get Less Than or Equal operation (B_GET_LE) retrieves a record in which the value for the key specified by the key number has an equal or a previous lesser value than the value you supply in the key buffer. The MicroKernel Engine first tries to satisfy the equal requirement. If the key allows duplicate values, this operation retrieves the last record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Less Than or Equal operation is successful, the MicroKernel Engine returns the record in the data buffer, the key value for the record in the key buffer, and the length of the record in the data buffer length parameter.

If the Get Less Than or Equal operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Get Less Than or Equal operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

The Get Next operation (B_GET_NEXT) retrieves the record in the logical next position (based on the specified key). You can use the Get Next operation to retrieve records within a group of records that have duplicate key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Next operation is successful, the MicroKernel Engine returns the record in the data buffer, the key value for the record in the key buffer, and the length of the record in the data buffer length parameter.

If the Get Next operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The operation returns status code 9 if the logical next position points beyond the end of the file.

The Get Next operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

The Get Next Extended operation (B_GET_NEXT_EXTENDED) examines one or more records, starting at the logical next position and proceeding toward the end of the file, based on the specified key. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only.

Get Next Extended can also extract specified portions from records and return only those portions to an application.

The following table shows the structure of the input data buffer.

In operations that specify the comparison code as extended operation code 7 (bias +8), the collation field may refer to an existing ACS, ISR table, ICU collation, or code page, as shown in the following table. The format is the signature byte followed by the name.

The MicroKernel Engine interprets AND and OR operators in a filter with the extended Get and Step operations in strict left-to-right order. It evaluates an expression in the filter and proceeds as follows:

The search for records stops if any one of the following conditions is met:

To get the next entire record that satisfies the filtering condition, set the filter portion as desired and set the descriptor fields as follows:

To retrieve the next 12 records without using a filtering condition and extract 4 fields from each record, set the filter Number of Terms to 0 and set the descriptor fields as follows:

When retrieving one or more fields or portions of records with an extended operation, you must ensure that the data buffer can hold the information that the operation returns. The following table shows the structure of the returned data buffer.

If all returned records or fields of records are fixed length, your application can easily calculate the location of data within the returned data buffer. However, your application may need to perform extra steps to extract the variable-length portion of records from the data buffer that an extended operation returns.

The MicroKernel Engine does not pad any record image in the returned data buffer when returning the variable-length portion of a record. Consequently, if you allow room in the returned data buffer for the maximum number of bytes that the variable-length portion of a record could occupy, but the actual data returned is less than that maximum, the MicroKernel Engine starts the field description for the next returned field immediately following the data for the current field.

For example, assuming an entry point using 4-byte record addresses, suppose your fixed-record length is 100 bytes, your variable-length portion is up to 300 bytes, and you want to return just the variable-length portion of 5 records. You would use the descriptor element of the input buffer to set a Field Length of 300 and a Field Offset of 100. For the returned buffer, you need 2 bytes for the Number of Records + 306 bytes for each record (that is, 2 bytes for the length, 4 bytes for the address, and 300 bytes for the data), as shown in the following calculation:

2 + ((2 bytes + 4 bytes + 300 bytes) * 5) = 1532 bytes

However, suppose that the variable-length portion of the first record returned contains only 50 bytes of data. This means the 2-byte length for the second record returned is stored at offset 58 in the data buffer, immediately following the image of the first record’s field. In such a situation, your application must parse the length, position, and data from the data buffer that the MicroKernel Engine returns.

If the Get Next Extended operation is successful, the MicroKernel Engine returns the following:

If the Get Next Extended operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

It is possible for the MicroKernel Engine to return a nonzero status code and also return valid data in the data buffer. In this case, the last record returned may be incomplete. If the data buffer length parameter returned is greater than 0, check the data buffer for extracted data.

If a field can only be partially filled because the data buffer is too short, then the MicroKernel Engine returns what it can of the record to and including the partial field. If the partial field is the last field to be extracted, then the MicroKernel Engine continues the operation. Otherwise, the MicroKernel Engine aborts the operation and returns a status code 22.

For example, consider a Get Next Extended operation that retrieves 3 fields from 2 variable-length records. The first record is 55 bytes long and the second is 50 bytes long. The data buffer allows 50 bytes for return data. The 3 fields to be retrieved are defined as follows:

When the MicroKernel Engine performs the Get Next Extended operation, it returns the first record without any problem. However, when attempting to extract field 2’s 10 bytes from the second record, the MicroKernel Engine finds that only 5 bytes are available (between offset 45 and the end of the record, at offset 49). At this point, the MicroKernel Engine does not pad the missing 5 bytes of field 2, and thus cannot extract field 3. Instead, the MicroKernel Engine returns status code 22 and places all of field 1 and the first 5 bytes of field 2 in the return data buffer.

Depending on the fields and the operators used in the filtering condition, the MicroKernel Engine may be able to optimize your request. After reaching a certain rejected record, it returns status code 64, indicating that no records can satisfy the filtering conditions in the rest of the file.

The Get Next Extended operation establishes the complete logical and physical currencies. The last record examined becomes the current record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected, but is still not past the optimization limit. For example, if the extended operation returns status 9, the current record is that last record in the file. If status 60 (reject count reached) is returned, then the current record is the last record rejected. If status 64 (Filter Limit Reached) is returned, then the current record is the last record that satisfies the optimization criteria. Even thought the MicroKernel Engine had to look at the next record after this to determine that the optimization limit was exceeded, it sets the current record back to the previous record that did satisfy that criteria.

The Get Position operation (B_GET_POSITION) returns the physical position of the current record. Get Position fails if there is no established physical currency when you issue the operation. Once you determine a record’s position (address), you can use Get Direct/Record (23) to retrieve that record directly by its physical location in the file. The MicroKernel Engine does not perform any disk I/O to process a Get Position request.

If the Get Position operation is successful, the MicroKernel Engine returns the position of the record in the data buffer. The position is a binary value that indicates the offset of the record in the file. The MicroKernel Engine also sets the data buffer length to 4 bytes for BTRV type entry points or 8 bytes for BTRVEX type entry points.

If the Get Position operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

The Get Position operation has no effect on positioning.

The Get Previous operation (B_GET_PREVIOUS) retrieves the record in the logical previous position based on a specified key. You can use the Get Previous operation to retrieve a record within a group of records that have duplicate key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

If the Get Previous operation is successful, the MicroKernel Engine updates the key buffer with the key value for the previous record, returns the previous record in the data buffer, and returns the length of the record in the data buffer length parameter.

If the Get Previous operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

This operation returns status code 9 if the logical previous position points beyond the beginning of the file.

The Get Previous operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

The Get Previous Extended operation (B_GET_PREV_EXTENDED) examines one or more records, starting at the logical previous position and proceeding toward the beginning of the file, based on the specified key. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only.

Get Previous Extended can also extract specified portions of records and return only those portions to an application.

This operation uses the same input and returned data buffers as Get Next Extended (36). See that operation for more information.

This operation returns the same results as Get Next Extended (36). See that operation for more information.

The Get Previous Extended operation establishes the complete logical and physical currencies. The last record examined becomes the current record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected.

The Insert operation (B_INSERT) inserts a record into a file. The MicroKernel Engine adjusts the B‑trees for the keys to reflect the key values for the new record.

If the Insert operation is successful, then the MicroKernel Engine places the new record in the file, updates the B-trees for the keys to reflect the new record, and returns the value of the specified key in the key buffer. If you insert a record that contains an autoincrement key value initialized to binary 0, the MicroKernel Engine also returns the inserted record in the data buffer, including the autoincrement value assigned by the MicroKernel Engine. An NCC Insert operation does not change the value of the key buffer parameter.

If the Insert operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

An Insert operation that does not specify the NCC option establishes the complete logical and physical currencies and makes the inserted record the current one. The logical currency is based on the specified key.

An NCC Insert operation establishes physical currency without affecting logical currency. This means that an application, having performed an NCC Insert operation, has the same logical position in the file as it had prior to the Insert operation. In such a situation, operations that follow an NCC Insert – such as Get Next (6), Get Next Extended (36), Get Previous (7), and Get Previous Extended (37) – return values based on the application’s logical currency before the NCC Insert.

The MicroKernel Engine establishes the physical currency to a newly inserted record for both the standard Insert and the NCC Insert operations. Operations following an NCC Insert operation – such as Step Next (24), Step Next Extended (38), Step Previous (35), Step Previous Extended (39), Update (3), Delete (4), and Get Position (22) – operate based on the new physical currency.

The Insert Extended operation (B_EXT_INSERT) inserts one or more records into a file. The MicroKernel Engine adjusts the B-trees for the keys to reflect the key values for the new records.

The following table shows the structure of the input data buffer.

If the Insert Extended operation is successful, the MicroKernel Engine places the new records in the file, updates all B-trees to reflect the new records inserted if it is not an NCC Insert Extended operation, returns in the key buffer the value of the specified key from the last record inserted. In addition, in the first 2- or 4-byte unsigned integer of the returned data buffer, the MicroKernel Engine places the number of records successfully inserted into the file. Following the count, the MicroKernel Engine stores the record addresses of the inserted records. The following table shows the structure of the output data buffer.

If the operation is only partially successful and the MicroKernel Engine returns a nonzero status code, the first 2- or 4-byte unsigned integer of the data buffer equals the number of records that were successfully inserted. The record that caused the error is the number of records that were successfully inserted plus one.

If Insert Extended is unsuccessful, the MicroKernel Engine returns one of the following status codes:

An Insert Extended operation that does not specify the NCC option establishes the complete logical and physical currencies and makes the last inserted record the current one, unless the key value of the inserted record is null. The logical currency is based on the specified key.

An NCC Insert Extended operation establishes physical currency without affecting logical currency. This means that an application, having performed an NCC Insert Extended operation, has the same logical position in the file as it had prior to the operation. In such a situation, operations that follow an NCC Insert Extended operation – such as Get Next (6), Get Next Extended (36), Get Previous (7), and Get Previous Extended (37) – return values based on the application’s logical currency prior to the NCC Insert Extended operation.

The MicroKernel Engine establishes the physical currency to a newly inserted record for both the standard Insert Extended and the NCC Insert Extended operations. Therefore, operations following an NCC Insert Extended operation – such as Step Next (24), Step Next Extended (38), Step Previous (35), Step Previous Extended (39), Update (3), Delete (4), and Get Position (22) – operate based on the new physical currency.

An NCC Insert Extended operation is useful when an application must save its logical position in the file prior to executing the Insert Extended operation in order to perform another operation based on the original logical currency, such as a Get Next (6)operation.

To achieve this effect without an NCC Insert Extended operation, your application would have to execute the following steps:

The NCC Insert Extended operation has the same effect in terms of logical currency, but can have a different effect in terms of physical currency. For example, executing Get Next (6) after either procedure produces the same result, but executing Step Next (24) might return different records.

The Login/Logout operation (B_LOGIN/B_LOGOUT) allows a user to specify his/her user credentials and obtain authentication and authorization tokens from the database engine. This operation also allows the user to reset his/her login credentials so that they must be entered again to gain access to the database.

If the Login or Logout operation is successful, the database engine returns status 0. Otherwise, one of the following status codes may be returned:

The combined length of the database URI must be less than 255 bytes. This is due to the maximum size of the key buffer.

The Login operation has a performance cost. You should not code applications to login and logout on every file. Instead, login once to a database at the beginning of a session, then logout when the database work is complete.

The Login/Logout operation has no effect on any file currency information.

The Open operation (B_OPEN) makes a file available for access. To access a file, your application must first perform an Open operation. The file does not have to reside in the current directory as long as you specify the full or relative path name.

This section describes the open modes that are supported.

When you open a file, you can instruct the MicroKernel Engine through the open mode to use either a local or remote engine. You specify the open mode in the key number parameter.

There is no fixed limit on the maximum number of open files. The number of files that can be opened at once depends on the available memory.

A file is opened only once by the MicroKernel Engine. The engine recognizes and handles the situation in which more than one client at a time opens a file, or where a single client has more than one position block in the file. When you open an extended file, the engine uses a single handle and opens the base file and all extension files.

If the Open operation is successful, the MicroKernel Engine assigns a file handle to the file, reserves the position block passed on the Open call for the newly opened file, and makes the file available for access.

If the Open operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:

Table 30 shows open modes involving local clients.