5.11. Search Reference

The supplied simple/srchform.html and simple/results.html pages show example search forms. Modify them to present the search in any way desired. Be careful to use the proper variable names for passing to Interchange. It is also necessary to copy the hidden variables as-is. They are required to interpret the request as a search.

---

Note: The following definitions frequently refer to field name and column and column number. All are the references to the columns of a searched text file as separated by delimiter characters.

---

The field names can be specified in several ways.

ProductFiles

If the file to be searched is left empty in the search form or definition (it is set with mv_search_file (fi)), the text files associated with the products databases will be searched, and field names are already available as named in the first line of the file(s). This is defined to be products.txt in the Interchange demo catalogs.
Be careful if using SQL! If the database is changed and not exported with [tag export products][/tag], searches will not be successful.

Other database files

If the file or files to be searched are ASCII delimited files, and have field names specified on the first line of the file, Interchange will read the first line (of the first file) and determine the field names.

Other files

If the file or files to be searched are ASCII delimited files, but don't have field names specified on the first line of the file, set the variable mv_field_names to a comma-separated list of field names as they will be referenced.

Fields can also always be specified by an integer column number, with 0 as the first column.

mv_all_chars

Scan abbreviation: ac=[1|0]. Set this if searching is anticipated for lots of punctuation characters that might be special characters for Perl. The characters ()[]\$^ are included.

mv_base_directory

Scan abbreviation: bd=/directory/name. In the text search, set to the directory from which to base file searches. File names without leading / characters will be based from there. In the Glimpse search, passed to Glimpse with the -H option, and Glimpse will look for its indices there. Default is ProductDir.
If an absolute path directory is used, for security enable it in the users session with:

            [set /directory/name]1[/set]

This prevents users from setting an arbitrary value and viewing arbitrary files.

mv_begin_string

If this is set, the string will only match if it is at the beginning of a field. The handling is a bit different for the default AND search compared to the OR search. With OR searches all words are searched for from the beginning of the field, with AND searches all are.
This is a multiple parameter. If mv_coordinate is in force, it should be set as many times as necessary to match the field/searchstring combination. If set only once, it applies to all fields. If set more than once but not as many times as the fields, it will default to off.

mv_cache_key

Not normally set by the user. It is a value that provides a pointer to the search reference by the more function.

mv_case

If this item is set to No, the search will return items without regard to upper or lower case. This is the default. Set to Yes if case should be matched. Implement with a checkbox <INPUT TYPE=CHECKBOX> field.
If stacked to match the mv_search_field and mv_searchspec variables, and mv_coordinate is set, it will operate only for the corresponding field.
Scan abbreviation: cs

mv_column_op

In the coordinated search, the operation that will be performed to check the field for a search match. These operations are supported:

        !=              Not equal to
        !~              Not matching regular expression
        <               Less than
        <=              Less than or equal to
        <>              Not equal to
        =               Equal to
        ==              Equal to
        =~              Matching regular expression
        >               Greater than
        >=              Greater than or equal to
        em              Exact match
        eq              Equal to
        ge              Greater than or equal to
        gt              Greater than
        le              Less than or equal to
        lt              Less than
        ne              Not equal to
        rm              Matching regular expression
        rn              Not matching regular expression

If stacked to match the mv_search_field and mv_searchspec variables, and mv_coordinate is set, it will operate only for the corresponding field.

Note that several of the operators are the same. They do either numeric or string comparisons based on the status of mv_numeric (alias nu) for that column.

mv_coordinate

If this item is set to Yes, and the number of search fields equals the number of search specs, the search will return only items that match field to spec. (The search specifications are set by stacked mv_searchspec and mv_search_field variables.)
Case sensitivity, substring matching, and negation all work on a field-by field basis according to the following:
If only one instance of the option is set, it will affect all fields.
If the number of instances of the option is greater than or equal to the number of search specs, all will be used independently. Trailing instances will be ignored.
If more than one instance of the options are set, but fewer than the number of search specifications, the default setting will be used for the trailing unset options.
If a search specification is blank, it will be removed and all case-sensitivity/negation/substring options will be adjusted accordingly. If you need a blank string to match on, use quotes ("").

mv_dict_end

If the string at the beginning of a line lexically exceeds this value, matching will stop. Ignored without mv_dict_look.

mv_dict_fold

Make dictionary matching case-insensitive. Ignored without mv_dict_look.

---

Note: This is the reverse sense from mv_case.

---

mv_dict_limit

Automatically set the limiting string (mv_dict_end) to be one character greater than the mv_dict_look variable, at the character position specified. A value of 1, for instance, will set the limiting string to "fprsythe" if the value of mv_dict_look is "forsythe". A useful value is -1, which will increment the last character (setting the mv_dict_end to "forsythf" in our example). This prevents having to scan the whole file once a unique match is found.

---

Note: The order of this and the mv_dict_end variable is significant. Each will overwrite the other.

---

If this is set to a non-numeric value, an automatic mode is entered which looks for a dictionary-indexed file that corresponds to the file name plus .field, where field is whatever mv_dict_limit is set to. The actual value of mv_dict_limit is set to -1. If the file does not exist, the original file is silently used. Also, the value of mv_return_fields is set to 1 to correspond to the location of the key in the auto-indexed file.
To illustrate:

            <INPUT TYPE=hidden NAME=mv_dict_limit  VALUE=category>
            <INPUT TYPE=hidden NAME=mv_search_file VALUE="products.txt">

is equal to:

            <INPUT TYPE=hidden NAME=mv_dict_limit    VALUE="-1">
            <INPUT TYPE=hidden NAME=mv_search_file   VALUE="products.txt.category">
            <INPUT TYPE=hidden NAME=mv_return_fields VALUE="1">

The real utility would be in a form construct like

            Search for
            <SELECT NAME=mv_dict_limit>
            <OPTION> author
            <OPTION> title
            </SELECT> beginning with <INPUT NAME=mv_dictlook>

which would allow automatic binary search file selection.
Combined with the INDEX attribute to the Database directive, this allows fast binary search qualification combined with regular mv_searchspec text searches.

mv_dict_look

The string at which to begin matching at in a dictionary-based search. If not set, the mv_dict_end, mv_dict_fold, and mv_dict_case variables will be ignored. May be set in a search profile based on other form variables.

mv_dict_order

Make dictionary matching follow dictionary order, where only word characters and whitespace matter. Ignored without mv_dict_look.

mv_doit

This can be set to search to make a form with a process action be a search page by default. The mv_todo variable takes precedence.

mv_exact_match

Normally Interchange searches match words, as opposed to sentences. This behavior can be overridden with mv_exact_match, which when set will place quotes around any value in mv_searchspec or mv_dict_look.

mv_field_file

If you want to search a file which has no field header on the first line, you can specify a file to get the field names from. It expects a single line with the field names separated by TAB characters.

mv_field_names

Deprecated in favor of in-list sorting. Defines the field names for the file being searched. This guarantees that they will be available, and prevents a disk access if using named fields on a search file (that is not the product database ASCII source, where field names are already known). This must be exactly correct, or it will result in anomalous search operation. Usually passed in a hidden field or search profile as a comma-separated list.

---

Note: Use this on the product database only if planning on both pre-sorting with mv_sort_field and then post-sorting with [sort]field:opt[/sort].

---

mv_first_match

Normally Interchange will return the first page of a search. If this variable is set, it will start the search return at the match specified, even if there is only one page. If set to a value greater than the number of matches, it will act as if no matches were found.

mv_head_skip

Normally Interchange searches all lines of an index/product file but the first. Set this to the number of lines to skip at the beginning of the index. Default is 1 for the text search, which skips the header line in the product file. Default is 0 for a Glimpse search.

mv_index_delim

Sets the delimiter for counting fields in a search index. The default is TAB. It should rarely be changed unless you are searching a pipe-delimited or colon-delimited file.

mv_like_field

Specifies a field in a database search which should be used for a screening function based on the SQL like function. Needs mv_like_spec.

mv_like_spec

The string that should be searched for in mv_like_field. The behavior of the % character and case-sensitivity depends on your SQL implementation.

mv_matchlimit

Function depends upon context. When the search results display is handled by one of the mechanisms which works with [more] lists (such as [search-region]), mv_matchlimit determines the number of results per page. If more matches than mv_matchlimit are found, the search paging mechanism will be employed if the proper [more-list] is present. When the search results are displayed as one continuous list (i.e.: with [loop search="..."]), mv_matchlimit is equivalent in function to mv_max_matches.
To have no matchlimit, use none instead of a number. all does the same thing (since returning "all" is just anothing way of looking at no matchlimit).
If no matchlimit is provided, or an invalid setting (some other string or 0) the default is taken from catalog variable MV_DEFAULT_MATCHLIMIT, and if that's not set, is 50.

mv_max_matches

The maximum number of records that will be returned in a search. Default is unlimited. If search results paging with [more-list] is to be employed, Use mv_matchlimit to set the number of results per page.

mv_min_string

Sets the minimum size of a search string for a search operation. Default is 4 for the Glimpse search, and 1 for the text search.

mv_negate

Specifies that records NOT matching the search criteria will be returned. Default is no. It is not operative for the Glimpse search.
If stacked to match the mv_search_field and mv_searchspec variables, and mv_coordinate is set, it will operate only for the corresponding field.

mv_orsearch

If this item is set to Yes, the search will return items matching any of the words in searchspec. The default is No.

mv_profile

Selects one of the pre-defined search specifications set by the SearchProfile directive. If the special variable within that file, mv_last, is defined, it will prevent the scanning of the form input for further search modifications. The values of mv_searchspec and mv_dict_look are always scanned, so specify this to do the equivalent of setting multiple checkboxes or radioboxes with one click, while still reading the search input text.

mv_record_delim

Sets the delimiter for counting records in a search index. The default is newline, which works for the products and most line-based index files.

mv_return_fields

The field(s) that should be returned by the match, specified either by field name or by column number, separated by commas. Do not list the same field more than once per search. Specify 0 as the first field to be returned if searching the products database, since that is the key for accessing database fields.

As with SQL queries, you can use the '*' shortcut to return all fields. For example:

    [loop search="fi=nation/ra=yes/rf=*"]

when used with a hypothetical 'nation' table would be equivalent to:

    [loop search="
          fi=nation
          ra=yes
          rf=code,sorder,region,name,tax
    "]

as well as:

    [loop search="fi=nation/ra=yes/rf=0,1,2,3,4"]

and:

    [query sql="select * from nation"][/query]

However, you probably rarely need to use every single field in a row. For maximum maintainability and execution speed the best practice is to list by name only the fields you want returned.

mv_return_spec

Returns the string specified as the search (i.e., the value of mv_searchspec) as the one and only match. Typically used in a SKU/part number search.

mv_search_field

The field(s) to be searched, specified either by column name or by column number.
If the number of instances matches the number of fields specified in the mv_searchspec variable and mv_coordinate is set to true, each search field (in order specified on the form) will be matched with each search spec (again in that order).

mv_search_file

In the text search, set this variable to the file(s) to be scanned for a match. The default, if not set, is to scan the default ProductFiles (i.e., products.txt). If set multiple times in a form (for a text search), will cause a search all the files. One file name per instance.
In the Glimpse search, follows the Glimpse wildcard-based file name matching scheme. Use with caution and a liberal dose of the Glimpse man page.

mv_search_match_count

Set by the search to indicate the total number of matches found.

mv_search_page

The Interchange-style name of the page that should display the search results. This overrides the default value of search.

mv_searchspec

The actual search string that is typed in by the customer. It is a text INPUT TYPE=TEXT field, or can be put in a select (drop-down) list to enable category searches. If multiple instances are found, they will be concatenated just as if multiple words had been placed in a text field.
The user can place quotes around words to specify that they match as a string. To enable this by default, use the mv_exact_match variable.
If mv_dict_look has a value, and mv_searchspec does not, then mv_searchspec will be set to the value of mv_dict_look.
If the number of instances matches the number of fields specified in the mv_search_field variable and mv_coordinate is set to true, each search field (in order specified on the form) will be matched with each search spec (again in that order).

mv_searchtype

If set to Glimpse, selects the Glimpse search (if Glimpse is defined).
If set to db, iterates over every row of the database (not the associated text source file).
If set to sql, same as db.
If set to text, selects the text-based search.
When using st=db, returned keys may be affected by TableRestrict. See CATALOG.CFG.
Defaults to text if Glimpse is not defined; defaults to Glimpse if it is defined. This can allow use of both search types if that is desirable. For instance, searching for very common strings is better done by the text-based search. An example might be searching for categories of items instead of individual items.

mv_small_data

Tells the search engine that there is a small amount of data in the file and that it should perform the search function on every line.

Normally, when Interchange can find a fixed search expression it produces a "screening" function which will allow records to be quickly rejected when they don't match. If there are less than 50 records in the file or database, this may be counterproductive.

mv_sort_field

The file field(s) the search is to be sorted on, specified in one of two ways. If the file(s) to be searched have a header line (the first line) that contains delimiter-separated field names, it can be specified by field name. It can also be specified by column number (the code or key is specified with a value of 0, for both types). These can be stacked if coming from a form or placed in a single specification separated by commas.

---

Note: If specifying a sort for the product database, mv_field_names must be specified if doing a fieldname-addressed post-sort.

---

mv_sort_option

The way that each field should be sorted. The flags are r, n, and f, reverse, numeric, and case-insensitive respectively. These can be stacked if coming from a form or placed in a single specification separated by commas. The stacked options will be applied to the sort fields as they are defined, presuming those are stacked.

mv_spelling_errors

The number of spelling errors that will be tolerated. Ignored unless using Glimpse. For a large table, limit this to two.

mv_substring_match

If mv_substring_match is set to Yes, matches on substrings as well as whole words. Typically set this for dictionary-based searches.
If stacked to match the mv_search_field and mv_searchspec variables and mv_coordinate is set, it will operate only for the corresponding field.

mv_unique

If set to a true value, causes the sort to return only unique results. This operates on whatever the search return is, as defined by mv_return_fields.

mv_value

This is normally only used in the one-click search (va=var=value). It allows setting of a session variable based on the clicked link, which makes for easy definition of headers and other display choices. (If had trouble using mv_searchspec for this before, this is what is needed.)