Index masking is a mechanism through which the application can control which indexes a given record will be stored in. Usage is relatively simple, and best explained by example.
Masked files are created by adding ISMASKED to the mode when calling isBuild or isbuild, and are opened in the same way.
The library will return an EBADARG error if a masked file is opened without ISMASKED in the mode or ISMASKED is added to the open mode on an unmasked file.
Given a file with three indexes, where a value of 1 represents the primary, 2 the middle index, and 3 the last, the following call will add a record to the primary index only:
issetmask( isfd, ISMASK(2) + ISMASK(3) ); iswrite( isfd, record_data );
To rewrite a record such that it will be masked in the primary:
issetmask( isfd, ISMASK(1) ); isrewrite( isfd, record_data );
isrewrite could also be isrewcurr or isrewrec. isRewrite could also be isRewCurr or isRewRec.
The mask value for the current record can be obtained via a call to
isgetmask( isfd );
Record masks must be set explicitly - if reading through a file with the intention of adjusting mask values you must call issetmask for each record you wish to change.
Files built with masking active will allow multiple copies of identical indexes to be added to the file. This is to allow the developer to store different record subsets in separate indexes, but it is important to note that only the last of these indexes can be accessed via isstart. isindex should be used instead.
If using the base API calls you should enquire and set the mask values directly, rather than using isgetmask and issetmask. For example:
if( isam->mask & ISMASK(1) ) /* current record masked in primary */ isam->mask = ISMASK(2) + ISMASK(3); /* mask 2nd and 3rd indexes */
Masking is a custom extension - files built with ISMASKED are not cisam™ compatible.
You should not remove indexes from a masked file once it has been populated.
As of version 6.1, the flag in the index header that denotes masked files has been changed - you will need to run fixflags (available from Sales and Support) to patch older files.
See Null Key Masking for an alternate method of filtering indexes.