Drop Index (32)

Drop Index (32)

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


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

•

The file must be open.

•

The key must exist in the file.

•

No transactions can be active.

1

Set the operation code to 32.

2

Pass the position block of the file that contains the key to drop.

3

Store the number of the key to drop in the key number parameter. To drop the system-defined log key (also called system data), specify 125.

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

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 allows you to leave gaps in the key numbering; 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 the Create Index operation (31), which allows you to specify a key number.

However, if you delete a key and do not 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. (Users can clone files using the Btrieve Maintenance utility. Cloning is the process of creating a new, empty file with the same statistics as an existing file.)

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:


6	The key number parameter is invalid.
41	The MicroKernel Engine does not allow the attempted operation.

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.