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 transactional interface automatically renumbers all higher-numbered keys, unless you specify otherwise. The transactional interface 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 transactional interface renumbers the keys as 1 and 6.

If you do not want the transactional interface 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 transactional interface places the pages that were allocated to that index on a list of free space for later use. Unless you specify otherwise, the transactional interface renumbers the higher-numbered keys.

If the Drop Index operation is unsuccessful, the transactional interface returns one of the following status codes:


6	The key number parameter is invalid.
41	The transactional interface does not allow the attempted operation.

If processing is interrupted while the transactional interface is dropping an index, you can access the data in the file by the file’s other keys. The transactional interface 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.