For more information... RTFM!
NAVIGATION
PAGES THAT LINK HERE
ACCOUNT LOGIN

You are not logged in

Powered by Interchange version 5.7.0

Search parameters

Search specifications are made up of a number of parameters.  The parameters, along with their full name and abbreviation, are listed in this section.

Note that this list does not include any of the special form variables, which also happen to be prefixed with "mv_".

Note

Note

The terms "field" and "column" are used interchangeably in this document.

mv_all_chars (ac)

Set this true if searching is anticipated for lots of punctuation characters that might be special characters for Perl.  The "()[]$^" characters are included.

mv_base_directory (bd)

In a text file search, set to the directory in which to files should be found.  File names without leading / characters will be looked for in the specified directory.  The default is DataDir.  For security, absolute path directory can only be specified if the following is set in the user's session:

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

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

mv_begin_string (bs)

If this is set true, the string will only match if it is at the beginning of a column.  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 column, whereas AND searches look for the specified string anywhere in the column.

If mv_coordinate is in force then this can be stacked (set as many times as necessary) to match the column/searchstring combination.  If set only once, it applies to all columns.  If set more than once but not as many times as the columns then it will default to false for the remaining columns.

mv_case (cs)

If this item is set false then the search will return items without regard to upper or lower case.  This is the default.  Set this true if case-sensitivity is important.

If stacked to match the mv_search_field and mv_searchspec parameters, and mv_coordinate is true, then this will operate only for the corresponding field/column.

mv_column_op (op)

If mv_coordinate is true then this specifies the operation that will be performed to check the column for a search match.  A list of the supported search options can be found in the Coordinated and joined searches section of the Interchange search engine page.

If stacked to match the mv_search_field and mv_searchspec parameters, and mv_coordinate is true, it will operate only for the corresponding column.

mv_coordinate (co)

If this parameter is set true, 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 column-by-column basis according to the following:

  • If only one instance of the option is set, it will affect all columns.
  • If the number of instances of the option is greater than or equal to the number of search strings, all will be used independently.  Trailing instances will be ignored.
  • If more than one instance of the option is set, but fewer than the number of search strings, the default setting will be used for the trailing unspecified matches.
  • 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_delay_page (dp)

mv_dict_end (de)

If the string at the beginning of a line lexically exceeds this value, matching will stop.  This is ignored if mv_dict_look is not set true.

mv_dict_fold (df)

Make dictionary matching case-insensitive.  This is ignored if mv_dict_look is not set true.

Note

Note

This is the reverse sense from mv_case.

mv_dict_limit (di)

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

Note

Note

The order of this and the mv_dict_end parameter is significant, as 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.

For instance:

<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 the following:

Search for:
<select name="mv_dict_limit">
    <option>author</option>
    <option>title</option>
</select>

beginning with:
<input name="mv_dictlook">

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

mv_dict_look (dl)

The string at which to begin matching at in a dictionary-based search.  If not set true then the mv_dict_end, mv_dict_fold and mv_dict_case parameters will be ignored.  This may be set in a search profile, based upon other form variables.

If stacked to match the mv_search_field and mv_searchspec parameters, and mv_coordinate is true, then it will operate only for the corresponding field.

mv_dict_order (do)

Make dictionary matching follow dictionary order, where only word characters and whitespace matter.  This is ignored if mv_dict_look is not set true.

mv_exact_match (em)

Normally the search matches words, as opposed to sentences.  This behaviour can be overridden with mv_exact_match which, when set true, will place quotes around any value in mv_searchspec or mv_dict_look.

mv_field_file (ff)

If you want to search a file which has no column header on the first line, you can specify a file that lists the column names.  The file should contain a single line, with the column names separated from one another with a tab character.

mv_field_names (fn)

Deprecation notice

Deprecation notice

This parameter has been deprecated in favour of in-list sorting.  Please do not use this parameter, as it may be removed, without warning, at any time.

mv_first_match (fm)

Normally the search will return the first row of a search resultset.  If this parameter is given then it will start the search return at the specified row, even if there is only one page.  If it is set to a value greater than the number of matches then it will act as if no matches were found at all.

mv_head_skip (hs)

Normally, for text file searches, Interchange looks at all rows in the file/index except for the first.  Set this to the number of lines to skip at the beginning of the file/index.  The default, for text file searches, is 1, which skips the header line in the file.  The default is 0 for other forms of searches, such database table searches.

mv_index_delim (il)

Sets the delimiter for counting columns in a search index.  The default is a tab.  It should rarely be changed unless you are searching a text file delimited with some other character, such as a pipe or a colon etc.

mv_like_field (lf)

Specifies a column in a table search which should be used for a screening function, based upon the SQL LIKE function.  The mv_like_spec parameter is also required when mv_like_field is used.

mv_like_spec (ls)

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

mv_list_only (lo)

mv_matchlimit (ml)

This function depends upon its context.

When the search results display is handled by one of the mechanisms which works with [more-list] sub-tags (such as the [search-region] tag), mv_matchlimit determines the number of results per page.  If more matches than mv_matchlimit are found then the search paging mechanism will be employed as long as the proper [more-list] loop sub-tag is present.

When the search results are displayed as one continuous list (such as with [loop search="..."]), mv_matchlimit is equivalent, in function, to mv_max_matches.

To have no match limit, use "none" instead of a number.  "all" does the same thing, as "returning all" is just another way of describing having no match limit.

If no matchlimit is provided, or an invalid setting is given (some other string or 0) the default is taken from the MV_DEFAULT_MATCHLIMIT variable.  If there is still no value, then a default value of 50 will be used.

mv_max_matches (mm)

The maximum number of rows that will be returned from a search.  The 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 (ms)

Sets the minimum size of a search string for a search operation.  The default is 1 for the text-file-based searches.

mv_more_alpha (ma)

If true then [more-list] will group results by letter, instead of by page number.  For instance "A B C" instead of "1 2 3".

The mv_sort_field parameter is required for this facility to operate, as the first mv_sort_field, column will be used to determine the groups.

The first three letters of each result row's mv_sort_field column will be used in the "next" page link labels, unless the mv_more_alpha_chars parameter is specified.

mv_more_alpha_chars (mc)

Combined with the mv_more_alpha switch, listed above, this value determines the number of letters in each [more-list] page link label.  For instance, if this value is 2 then page links could be listed as "AA AB AC".  The default is 3.

mv_more_id (mi)

mv_more_permanent (pm)

"Permanent more" feature that allows you to create page-able searches that are shared between visitors and are cache-able by search engines.

Warning

Warning

If your data changes, a saved search could be wrong when referenced from a bookmark, saved link or a link from a search engine's index.  The "permanent more" cache will need to be reinitialised, by re-running the query, before the links will be correct once again.

Warning

Warning

This facility can create a very large set of files.  You will need to monitor your filesystem to make sure that you don't run out of inodes.

Availability

Availability

This search parameter was introduced in version 5.2.1, and is therefore not available for use with any earlier Interchange version.

mv_negate (ne)

If true, this specifies that rows NOT matching the search criteria should be returned.

If stacked to match the mv_search_field and mv_searchspec parameters, and mv_coordinate is true, then it will operate only for the corresponding field.

mv_numeric (nu)

If this parameter is set true then search operators will perform a numeric comparison, instead of a string comparison.  The default is false, which instructs search operators perform a string comparison.

mv_orsearch (os)

If this parameter is set true then the search will return rows matching any of the words in the mv_searchspec.  The default is false, which makes the default an "and" search.

mv_profile (mp)

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 radio buttons with one click, while still reading the search input text.

mv_range_alpha (rg)

mv_range_look (rl)

mv_range_max (rx)

mv_range_min (rm)

mv_return_all (ra)

Return all of the rows from the named table.

mv_record_delim (dr)

Sets the delimiter for counting rows in a text-based search index.  The default is an ASCII CR ("\r") character, which works for most line-based index files.

mv_return_fields (rf)

The column(s) that should be returned by the match, specified either by column name or by the column number, starting from zero.  If more than one column is specified then they should be separated from one another with a comma (,).  Do not list the same column more than once.  You should always return the key column first, so that it can be used with the [PREFIX-code] loop sub-tag.

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

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

When used with a hypothetical "nation" table, this would be equivalent to the following:

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

as well as:

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

and:

[query sql=|
    SELECT  *
    FROM    nation
|]
[/query]

and even:

[query sql=|
    SELECT  code,sorder,region,name,tax
    FROM    nation
|]
[/query]
Note

Note

You probably don't need to make use of every single column in a row, so, for maximum maintainability and execution speed, the best practise is to only list the columns you need to use.

mv_return_file_name (rn)

mv_return_reference (rr)

mv_return_spec (rs)

If true then the one and only match from the search will be the value of the mv_searchspec itself.  This could be useful in testing, or to just confirm that a result was found.

mv_search_field (sf)

The column(s) that should be searched, specified either by column name or by the column number, starting from zero.  If more than one column is specified then they should be separated from one another with a comma (,).

A table name can also be specified using the "tablename:colname" syntax.

If the number of instances matches the number of columns specified in the mv_searchspec parameter and mv_coordinate is true then each mv_search_field will be matched with each search mv_searchspec in the order provided.

mv_search_file (fi)

Set this parameter to the table(s) and/or text file(s) to be scanned.  If not specified otherwise, the default is to scan all of the DefaultTables table(s).

mv_search_immediate (si)

mv_search_label (lb)

mv_search_line_return (lr)

mv_search_page (sp)

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

mv_searchspec (se)

The string to search for in the requested table(s).  Quotes (") can be placed around words to specify that they should match as a string, and not as individual words.  To enable this by default, use the mv_exact_match parameter.

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 columns specified in the mv_search_field parameter, and mv_coordinate is set true, then each search column (in order specified) will be matched with each mv_searchspec.

If the number of instances matches the number of values specified in the mv_search_field parameter and mv_coordinate is true then each mv_search_field will be matched with each search mv_searchspec in the order provided.

mv_searchtype (st)

If this parameter is set to "db" or "sql" then the search will iterate over every row in the selected table(s) to find matching rows.  If this parameter is set to "text" then the text-based search mode will be enabled.  If this parameter is set to "ref" then the search will iterate over the results of a some previous search (see mv_search_label).

Note

Note

If this parameter is set to "db" or "sql" then returned rows may be affected by the TableRestrict local configuration directive.

mv_sort_field (tf)

This parameter specifies table column(s) that should be used to sort the search results.  This can be specified in one of two ways: 

  1. By column name.  This is always available if mv_searchtype is db or sql.  This is only available in "mv_searchtype=text" searches if the search file has a header row with column names.
  2. By column number, numbered from zero.

These can be stacked if coming from a HTML <form>, or placed in a single parameter, with column names separated from one another with a comma.

If the parameter's value contains a colon (:) then the value to the right of the colon will be expected to be a mv_sort_option modifier.  For example, a mv_sort_field value of "title:r" would sort any results using the "title" column, and return them in reverse order.

mv_sort_option (to)

This specifies direction in which each column should be sorted.  The options are r (reverse), n (numeric) and f (case-insensitive).  These can be stacked if coming from a HTML <form>, or placed in a single parameter, with columns separated from one another with a comma.

Stacked options will be applied to the columns specified using mv_sort_field, as long as those are also stacked.

mv_spelling_errors (er)

mv_sql_query (sq)

for text-based searches (st=text only),

This search parameter allows you to specify a SQL-like query to run over the lines a file when using text-based search (st=text).  This is not the same as sending SQL to a real database server, such as MySQL or PostgreSQL etc.

The SQL will be modified, according to set rules, before it is used.  For example:

Artist: <input name="artist"><br>
Title:  <input name="title">

<input type="hidden" name="mv_sql_query" value="
    SELECT  code
    FROM    products
    WHERE   artist LIKE artist
    AND     title LIKE title
"
>

If the right-most side of a WHERE/AND/OR clause is found to be an alphanumeric, unquoted word then it will be replaced with the same-named form value, or the same-named scratchpad variable if mv_sql_query is used in a one-click search.  Quoted right-most values, and values that contain non-alphanumeric characters, are taken literally.

If the left-most side of a WHERE/AND/OR clause is a quoted word then the behaviour is reversed, so the word will be replaced with the same-named form value, or the same-named scratchpad variable if mv_sql_query is used in a one-click search.

In the following example, the user will be allowed to select whether they want to search either the title or artist column:

Search for: <input name="searchstring"><br>
Search in:  <input type="radio" name="column" value="title"> title <br>
            <input type="radio" name="column" value="artist"> artist

<input type=hidden name="mv_sql_query" value="
    SELECT  code
    FROM    products
    WHERE  'column' LIKE searchstring
"
>

mv_substring_match (su)

If this parameter is set true then matches on substrings will count as well as matches on whole words so, a search for "Kev" will find "Kevin", for instance.

If stacked to match the mv_search_field and mv_searchspec parameters, and mv_coordinate is true, then it will operate only for the corresponding field.

mv_unique (un)

If set true then the sort will only return unique results.  This operates the defined search return columns, as specified using the mv_return_fields search parameter.

mv_value (va)

This is normally only used in One-click searches.  It allows setting of a session form value based upon the clicked link.  See the "setting display options with mv_value" page.

Category:  Interchange database
Last modified by: Kevin Walsh
Modification date: Saturday 19 April 2008 at 3:22 PM (EDT)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us