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.)