Index Manipulation

Here are the commands to create indexes and/or find out how they are sorted or filtered.


SORT

Routine to determine how the records in an index have to be sorted.

Indexes can be sorted with up to ten levels. If you don't need that many levels a compare value of -1 indicates that only previous levels have to be taken into consideration (Assembler only).

If an indexid is passed, than the sort data will be overwritten. If a bufferid is passed or default used, then a new index will be created. This new index will automatically become the default index. The index itself has to be built with a call to indexUPDATE.

Default fields are not accepted by this command.

Possible values for compare:

name    bit val char    meaning
mark    0   1   mMaA    mark records if equal (get value 255)
line    2   4   lL      place is a line number
text    3   8   tT      sorted as text (character field only)
case    4   16  cC      compare case dependant (character field only)
rvrs    5   32  -rR     reverse order (sort backwards)

If 'text' is set in compare, then eight characters are used with place as offset in the character array (consided as groups of eight characters). The characters will be sorted properly (not by their character code). If 'line' is also set, then the place will be the start of the given line.

When a character field is sorted an 'text' is not indicated, then the text is considered as raw data and sorted by the character code (no case conversion).

If an element is not provided, it will be put at the end, except when 'text' is indicated, then it will be put at the start (so that "Jo" will come before "Jona").

Equal records can be marked with mark value 255 is 'mark' is set in compare for the first level.

Sbasic
    SORTfile #indexid, compare, field, place,...
    field : short
    place : short[1]
    the last three parameters can be repeated up to ten times
    fields can't be passed by name
Assembler
    SORT
    indexid
    ten times : short compare
                short field
                short place
    return long indexid
C
    long DDsortfile(long indexid, short number, short compare,
                    short field, short place,...);
    the last three parameters have to be repeated 'number' times

errors, code,   meaning
itnf    -7      invalid bufferid or indexid
imem    -3      insufficient memory

FILTer

Routine to determine which records should be in the index and which not.

Indexes can be filtered with up to ten levels. If you don't need that many levels a compare value of -1 indicates that only previous levels have to be taken into consideration (Assembler only). The levels are evaluated from left to right.

If an indexid is passed, than the filter data will be overwritten. If a bufferid is passed or default used, then a new index will be created. This new index will automatically become the default index. The index itself has to be built with a call to indexUPDATE.

Default fields are not accepted by this command.

Possible values for compare:

name    bit val char    meaning
mark    0   1   mMaA    mark records if equal (get value 255)
line    2   4   lL      place is a line number
text    3   8   tT      sorted as text (character field only)
case    4   16  cC      compare case dependant (character field only)
rvrs    5   32  -rR     reverse order (sort backwards)
equ     6   64  =       value in field has to be equal (not char/raw)
smal    7   128 <       value in field has to be smaller (not char/raw)
larg    8   256 >       value in field has to be larger (not char/raw)
str     9   512 sS      string has to be in field

These compare codes allow you to test whether

Sbasic
    FILTER #indexid, compare, field, place, value,...
    place : short[1]
    field : short
    value : 'special', used to compare
    the last four parameters can be repeated up to ten times
    fields can't be passed by name
Assembler
    FILT
    indexid
    ten times: short compare
               short field
               short place
               'special' value to compare
    return long indexid
C
    long DDfilter(long indexid, short number, short compare,
                  short field, short place, char *value[8],...);
    the last four parameters have to be repeated `number' times

errors, code,   meaning
itnf     -7     invalid bufferid
imem     -3     insufficient memory

Index UPDate

This command is used to actually build the index. It can also be used to re-build it if there already is one.

Records which are locked when the index is being updated are not included in the index.

Please note that it can not be pedicted which record will be the current after execution of this command. This also means that it is possible that the current record is actually not visible (meaning not in the index).

Sbasic
    indexUPDATE #indexid
Assembler
    IUPD
    indexid
C
    long DDindexupdate(long indexid);
  
errors, code,   meaning
itnf    -7      invalid indexid (or bufferid)
imem    -3      insufficient memory
ipar    -15     something in the sort or filter data is impossible
...             any error returned by GETrec (except fdiu)

Get Index Sort Level

Get the sort data for one specific level.

Sbasic
    GETsort #indexid, level, cmp, fld, place
    level : short
    cmp : short, updated compare
    fld : short, updated field
    place : short, updated
Assembler
    GISL
    indexid
    short level
    update short compare (always updated)
    update short field (always updated)
    update short place (always updated)
C
    long DDgetsort(long indexid, short level, short *cmp,
                   short *fld, short *place);
  
errors, code,   meaning
itnf    -7      invalid indexid (or bufferid)
orng    -4      level not in 1-10 range

Set Index Sort Level

Set the sort data for one specific level. Should be followed by an indexUPDATE.

Sbasic
    SETsort #indexid, level, compare, fld, place
    level : short
    fld : short
    place : short
Assembler
    SISL
    indexid
    short level
    ptr to short compare
    ptr to short field
    ptr to short place
C
    long DDsetsort(long indexid, short level, short *cmp,
                   short *fld, short *place);
  
errors, code,   meaning
itnf    -7      invalid indexid (or bufferid)
orng    -4      level not in 1-10 range

Get Index Filter Level

Get the filter data for one specific level.
Sbasic
    GETfilter #indexid, level, cmp, fld, place, value
    level : short
    cmp : short, updated compare
    fld : short, updated field
    place : short, updated
    value : pointer to 'special', contents updated
Assembler
    GIFL
    indexid
    short level
    update short compare (always updated)
    update short field (always updated)
    update short place (always updated)
    update 'special' value (always updated)
C
    long DDgetfilter(long indexid, short level, short *cmp,
                     short *fld, short *place, char *value[8]);

errors, code, meaning
itnf    -7    invalid indexid (or bufferid)
orng    -4    level not in 1-10 range

Set Index Filter Level

Set the sort filter for one specific level. Should be followed by an indexUPDATE.

Sbasic
    SETfilter #indexid, level, compare, fld, place, value
    level : short
    fld : short
    place : short
    value : 'pointer' to special
Assembler
    SIFL
    indexid
    short level
    ptr to short compare
    ptr to short field
    ptr to short place
    ptr to 'special'
C
    long DDsetfilter(long indexid, short level, short *cmp, short *fld,
                     short *place, char *value[8]);
  
errors, code,   meaning
itnf    -7      invalid indexid (or bufferid)
orng    -4      level not in 1-10 range
PROGS, Professional & Graphical Software
last edited September 6, 1996