User Index Facility
Create a row in the SYSPTRS table called %USER.INDEX%. When Btree.Extract is run, OpenInsight looks for this row before Btree.Extract does any other processing. Be aware that when you create %USER.INDEX%, all system processing that accesses Btree.Extract will access this row and attempt to follow its specifications.
The %USER.INDEX% row must have two fields, and can have an optional third field, which is described in the following table:
| Column position | Parameter | Description |
|---|---|---|
| 1 | USER.INDEX | This literal text must be the first field in USER.INDEX. |
| 2 | parsing_module | In this field of the %USER.INDEX% row, enter the name of your own parsing routine. |
The routine named in this column should examine the search data that has been passed to Btree.Extract to determine whether the custom comparison routine should be called. If you choose, this preprocessor can alter the search data.
Btree.Extract passes four arguments to parsing_module:
Parser(search_val, start_value, user_index_flag, compare_mod)
Parameters for parsing_module (which must be entered in uppercase) are as follows:
| Parameter | Description |
|---|---|
| Search_val | Value of the srch_strng argument, as passed to Btree.Extract. It may contain special characters or patterns that trigger the custom compare module. If a custom compare module is called later in the Btree.Extract process, the value of search_val as (possibly) modified by the parsing routine will be passed to that compare module, to determine an index value hit or miss. If srch_strng contains multiple search criteria, Btree.Extract parses and passes each one to the parsing module one at a time. All And and Or logic for multiple search criteria is therefore handled by Btree.Extract. parsing_module is invoked for each value. |
| start_value | Your parsing module can use a start_value argument to pass a value to Btree.Extract indicating the point in the index from which to start examining index values. If start_value is null (the default), the search will begin at one end or the other of the Btree index, depending on the direction of the search (determined in user_index_flag, described below). If a specific value is passed, Btree.Extract begins from the point in the index where that value would be found. |
| user_index_flag | An argument for user_index_flag determines whether the custom compare module will be called to examine the search value. The flag can have these values: Flag - Description 0 - Do not use the custom compare module. (Default) 1 - Use the custom compare module and read index values in ascending order. 2 - Use the custom compare module and read index values in descending order. |
| compare_mod | parsing_module returns in compare_mod the name of the compare module that is to be called by Btree.Extract. If null (the default), the compare module used is that specified in default_compare (of the %USER.INDEX% row). If user_index_flag is 1 or 2, but no comparison module is specified in either the SYSPTRS row or in compare_mod, a "null load" error will occur when Btree.Extract is called. The compare module specified in this column contains custom logic you have developed to compare the search data against values in the Btree index. Based on its own comparison logic, the compare module determines whether the search data matches values in the index. Btree.Extract calls the compare module for each value in the Btree index, starting as specified in start_value. |
The compare module (the value of compare below) is called by Btree.Extract with the following parameters.
Compare(candidate, search_val, flag)
| Parameter | Description |
|---|---|
| candidate | The argument for candidate is the value extracted from the Btree index by Btree.Extract. The candidate value is passed to the compare module, and is used to compare against the search data. |
| search_val | A value for search_val has been returned by the parser. Values are compared against candidate by the custom compare routine. |
| flag | If the value of flag is true upon entry, the value of candidate is the last value in the current Btree leaf node (flag is otherwise false). The compare module must set flag with one of the following values: Value - Description 0 - Successful search. 1 - Unsuccessful search. 2 - Terminate search. 3 - Cancel search and return a null list of keys from Btree.Extract. |
In addition to the arguments just described, the labeled Common area USERIX is available to the parsing and compare routines. There are two labeled common variables to provide additional information about the indexed values. The labeled block is defined as follows.
Common /USERIX/ UIX.SM.FLAG, UIX.DCONV
The variable UIX.SM.FLAG is a Boolean value, true if the column is left-justified sorted, and false if the column is right-justified. The variable UIX.DCONV contains the output conversion to be applied to the value to change it to its external representation (data is stored in the index in its internal representation).
Examples
Example: Parser
Subroutine Parser(search_val, start_value, user_index_flag, comp_mod)
/* This subroutine establishes three independent subroutines, each with a different purpose within the user index facility of Btree.Extract. */
/* This code is an example of a user index parser routine to intercept Soundex lookups (it looks for values starting
with "$"). */
Declare Subroutine Soundex ;* code supplied below
Equate TRUE To 1
Equate TRIGGER To "$"
Equate COMP_MOD To "COMPARE"
/* The following code examines the index lookup value and determines whether it is a Soundex lookup. If not, the search value is passed through to Btree.Extract as normal. */
If search_val[1,1] = TRIGGER Then
search_val[1,1] = "" ;* delete the trigger character
Soundex(search_val) ;* convert to Soundex value
user_index_flag = TRUE;* use custom compare in ascending
start_value = search_val[1,1];* start at first letter
COMP_MOD = COMP_MOD ; * specify the compare module
End
Return