====== Make.Index ======

^Published By^Date^Version^Knowledge Level^Keywords^
|Sprezzatura Ltd|01 JUL 1989|1.15+|EXPERT|MAKE.INDEX, FILECOPY, BTREE, XREF, RELATIONAL, INDEX, CAPTURE|

When moving files around the system, I'm sure that you could not help but
notice that a FILECOPY removes all indexes on the destination file. There is
some logic in this, but it can make life really difficult when trying to
install new versions of software - how can we reinstall the missing indexes?

I know that when I first had this problem I just developed CAPTURE scripts
to call up the main menu, go to Files, Indexing, Update etc. etc. This was a
mess. More often than not, a "Stickum" on the menu would get in the way and
my system would sit there flashing at me as the wrong characters got fed
into the wrong screen. I thought that there had to be a better way and
started playing around. What I thought must be an easy process turned out to
be more complex, but it all revolves around a system subroutine called
MAKE.INDEX. (A routine that puts all the extra necessary pointers and
records onto the system to tell it that it has an index on a field (or to
remove it)).

The calling syntax is for MAKE.INDEX is

<code>
         CALL MAKE.INDEX(File,Field.name,Old.record,New.record)
</code>

where

  * File: name of the file the index is on
  * Field.name: dict item in the file
  * Old.record: compiled dict item before the index was added
  * New.record: compiled dict item after the index was added

As you will be aware from the documentation on the utility diskette,
indexing information is stored in various fields on the indexed dictionary
item. When the dictionary item is filed away, DICT.MFS recompiles it and
adds the new object code back into the item before writing it away.


==== BTREE INDEXES ====

A BTREE index is one of the most easy to set up. A dictionary item with a
BTREE index is distinguished by the presence of a 1 in field 6. Thus to add
a BTREE index to a field we would read in the dictionary item for the field,
add a 1 into field 6, write the item out again to recompile it, then read it
in to a new variable and call MAKE.INDEX. E.g. (assuming no errors
encountered)

<code>
    DECLARE SUBROUTINE MAKE.INDEX
    FILE = "DICT USERS"
    ITEM = "SURNAME"
    OPEN FILE TO DICT THEN
       READ REC FROM DICT,"SURNAME" THEN
           REC<6> = 1
           WRITE REC ON DICT,"SURNAME"
           READ NEW.REC FROM DICT,"SURNAME" THEN
              MAKE.INDEX(FILE,ITEM,REC,NEW.REC)
           END
       END
    END
</code>

==== XREF INDEXES ====

This is, of necessity, the most complicated index to set up. When you set up
an XREF index, a new symbolic field is added into the dictionary which is
used to do the XREFing. This field has the name field.name.XREF and contains
a call to the system routine XREF with the necessary stop list and delimiter
information. Thus to add an XREF index to a field we must first create this
extra dictionary item AS WELL AS altering the original dictionary item to
tell it that an XREF index exists, by adding the name of the symbolic xref
item into field 22 of the original dictionary item. Thus (assuming setup as
above)

<code>
    OPEN FILE TO DICT THEN
      READ REC FROM DICT,"SURNAME" THEN
         GOSUB CREATE.XREF
         MAKE.INDEX(FILE,ITEM,"",REC.XREF)
         REC<22> = ITEM : ".XREF"
         WRITE REC ON DICT, "SURNAME" THEN
         READ NEW.REC FROM DICT,"SURNAME" THEN
            MAKE.INDEX(FILE,ITEM,REC,NEW.REC)
         END
       END
    END
    RETURN

    CREATE.XREF:
    *
    * Generate XREF item here, call it REC.XREF - See listing for logic
    *
    WRITE REC.XREF ON DICT,ITEM : ".XREF"
    READ REC.XREF FROM DICT, ITEM : ".XREF" ELSE
       * Error handling
    END
    RETURN
</code>

==== RELATIONAL INDEXES ====

This is nearly as simple as BTREEs, it merely requires that the dict item be
told what it is related to by putting file*field*sort.order into field 23.
Thus using the above example to relate the surname field to NAMES file in
the KEYS field in ascending numerical order, (assuming setup as above)

<code>
      OPEN FILE TO DICT THEN
         READ REC FROM DICT,"SURNAME" THEN
            REC<23> = "NAMES*KEYS*AR"
            WRITE REC ON DICT,"SURNAME"
            READ NEW.REC FROM DICT,"SURNAME" THEN
               MAKE.INDEX (FILE,ITEM,REC,NEW.REC)
            END
         END
      END
</code>

(Volume 1, Issue 3, Pages 4,9)