jBASE Secondary Indexes Change History

These pages document the change history for jBASE secondary indexes.

Two major revisions have been released

Patches 3219 and 3220 -Released on July 8, 1997

New (N) option for create-index.

The (N) option on create-index is now synonymous with the -n option on create-index. When used, any index keys that equate to a null string will not be stored.

This compatibility option added for Sequoia Pick computability on the create-index command.

New (S) option for create-index and delete-index.

When the (S) option is used for create-index or delete-index, it does it silently. This computability option was added for Sequoia Pick computability on these commands. The things we silence are different, but the effect is the same. Remember there is the -v option on create-index and rebuild-index which displays a period for every 1000 index keys rebuilt.

New (M) option or -m option for create-index.

This is a major difference caused by this patch. This option changes the way we handle multi-values in a record being updated.

For example , with this patch, if a record is written away like this -->

PIPE
001 123]456]789

Then we will now, by default, create 3 index values based on "123" , "456" and "789". With the -m or (M) option on create-index, we will build a single index value based on "123]456]789".

Prior to this patch the default was the opposite way around and by default we would use a single index value of "123]456]789" and the mechanism to change this default was different prior to this patch, you had to use a syntax like this on the create-index command

% create-file filename indexname by M1

This patch makes us compatible with Sequoia Pick and also make the command line more logically consistent.

The use of multi-values is also restricted with a later patch.

Note also the new (Vnn) option below.

New (Vnnn) option for create-index.

This new option for create-index was added for computability with Sequoia Pick. What it does is limit the number of multi-values in a record that are used to create an index key. Without this option then ALL multi-values will each generate an index definition. This option restricts it to the first nnn values.

A special case of (V0) exists. In this case where the multi-value count is set to 0, we assume no multi-values are required and so we don't split the attribute into multi-values but treat the entire attribute as a single entity -- in effect then (V0) option is identical to the (M) option.

Remember the jBASE syntax already allows an individual value to be used instead. For example -->

% CREATE-INDEX FILENAME INDEXNAME BY 4.3

means just use the third multi-value in attribute 4.

Use of Sequoia Pick syntax for create-index.

The Sequoia Pick syntax for create-index is much simpler that the jBASE syntax and is of the format

: CREATE-INDEX FILENAME DICTITEM

This creates an index called DICTITEM and the index definition is based on the dictionary item DICTITEM.

jBASE now supports this by converting on-line the Sequoia Pick syntax to the jBASE syntax and notifying the user of the equivalent converted command (unless the (S) option is used).

When this happens we examine the dictionary definition and use it as follows -->

Attribute 2 tells us what attribute number to extract
Attribute 7 tells us any lookup code i.e. what to convert any matching string using.
Attribute 8 tells us any conversions to apply when building the index data
Attribute 9 tells us if it is a left or right (numeric) sort.

If a complex definition exists in attribute 8, then the conversion will fail and the user will have to use the jBASE syntax.

This example shows a DICT item in jBASE and how , if you run the create-index command against it, it will be converted to the jBASE syntax and run.

% COPY DICT filename INDEX1 \(T
INDEX1
001 A
002 3
003 Description
004
005
006
007 D2
008 MCU
009 R
01010

% CREATE-INDEX filename INDEX1
Notice: Command converted to 'CREATE-INDEX -lD2 filename BY-AR OCONV(3,"MCU")'
Index definition 'INDEX1' created successfully
Warning: You now need to rebuild the index data for file 'filename' using rebuild-index.

Removal of Mnn syntax on create-index.

Because of the new (M) option on create-index, noted earlier, we no longer require the Mnn syntax when creating an index. For example, prior to this patch, to create an index on a multi-valued attribute 1 you would do this -->

% CREATE-INDEX FILENAME INDEXNAME BY M1

Now that a multi-valued create is done by default, the above command would simply become

% CREATE-INDEX FILENAME INDEXNAME BY 1

And if you now want to suppress the multi-value create, you would do this

% CREATE-INDEX FILENAME INDEXNAME BY 1 (M)

Extra attribute to INDICES function.

Attribute <13> returned with the INDICES function now shows any option passed to create-index with the (Vnn) option and is therefore a count on the limit on the number of values extracted per attribute to create an index entry. By default this value is 0.

The values returned by INDICES were changed yet again in a later patch.

Different tuning when creating or rebuilding an index.

We have experienced some difficulty with certain ranges of index data taking a long time to rebuild. A temporary resolution has been added with this patch and a more permanent solution will be made available in the next patch when a new file layout will be created.

Patches 3267 and 3268 - Released August 1, 1997 (Return to Top)

New File Layout

The layout of the index files (e.g. filename]I) has been completely restructured. This has resulted in the substantially better balanced leafs as well as improved performance. The old style layout is not compatible with the new style layout. For the time being both layouts will be supported and old indexes created before this patch date will work. However this is not guaranteed in the future and you should think about rebuilding the indexes at some point with a command like this

% rebuild-index -a FILENAME

You can continue to create the old style indexes if you set an environment variable as shown below. This may be useful if there are any problems found with the new style indexes. The command is

% export JBCOLDINDEXTYPE=1

At some point JAC will discontinue support for the old style index files, probably around release jBASE release 4.0. You are advised therefore to rebuild all your indexes in a timely manner, preferably before the end of 1997. To do this you will need to delete the index definition using delete-index and re-create it with create-index.

create-index builds index data by default.

The create-index command no longer requires the -r option to force it to rebuild the index data. It will create the index data as a default. If you want to create the index definition but defer the building of the index data then use the new -a option. For example

% create-index -a fb4 index4 by 1
Index definition 'index4' created successfully
Warning: You now need to rebuild the index data for file 'fb4' using rebuild-index.

Change to the INDICES function

The data that was previously returned in attribute 1 was used to decide if we could support a SELECT command using the index. This has now been made redundant. The data returned from the INDICES function is now fully defined in the section INDICES function.

Multi-value selects limited

With this patch we have removed the anomaly when a multi-valued index is created with two or more record components. Consider the following command

jsh-> create-index FILENAME INDEXNAME BY 1 BY 2 : "*" : 3

In the above definition the index key is built out of three attributes. Should these attributes all have differing numbers of multi-values it makes it difficult to create an index key that is logically consistent. Therefore in the above example it would now fail to create the index definition.

You can still create multi-part index definitions by using the (M) option (or the -m option) to the create-index command as this disables multi-value part of jBASE secondary indexes .

query-index and key-select select defaults

Prior to this patch any usage of query-index and key-select (both command are synonymous with each other) you needed the -mJQL option to create a query that used jQL type syntax. This is now the default and so following this patch the following command will do what you expect (i.e. select all customers whose name begins with COOP).

jsh-> KEY-SELECT CUSTOMERS WITH SURNAME EQ "COOP]"

(X) option on create-index

The "X" option on CREATE-INDEX will set-up the index, but not run the existing file through it - in other words, it doesn't make any attempt to index what is already in the file. The file will still me marked as 'in-sync'. The net result is that you get an index later with only newly-written or modified records - very nice when you're dealing with huge files and you only want to process what's changed or created since the index was set-up.

SELECTINDEX uses raw data

The SELECTINDEX command has been corrected for computability. It now ignores any "lookup" code defined for the index and just uses the raw data used in the statement. For example, if you had an index on a date field, the following jBC code would be correct if you were looking for all records whose date is "25-July-1956" (a historic day).

SELECTINDEX "DATE" , ICONV("25-JULY-1956") TO LISTNAME
LOOP WHILE READNEXT record_key FROM LISTNAME DO blah blah blah

Before this patch you would have not used the ICONV as SELECTINDEX incorrectly applied any lookup code before starting the selection.

The SELECTINDEX and SELECT .. ATKEY statements both use raw data whereas the key-select and query-index programs assume the index specification is in external representation and pass it though any defined lookup code.

http://807199.827977/r5/knowledgebase/manuals/3.0/SecondaryIndexes/html/changehist.htm last modified on 06/19/09 05:29 AM