search_message_archive

The search_message_archive function returns data about messages that meet the search criteria provided.

search_message_archive lists max_results match_any contains_words search_for_contains_where not_contains_words search_for_not_contains_where search_body_for_not_contains

Parameters

lists

The name(s) of the list(s) to search for, or if a single '*' is provided, all lists on the server.

max_results

Integer number of results to limit the search to, or 0 if all results should be returned.

match_any

Boolean field (0 or 1) indicating whether the words provided should be considered a match if any of them are found, or only if all of them are found. Any = 1, All = 0

contains_words

A Tcl list of words to search for. At least one word must be provided.

search_for_contains_where

Should only the header be searched (=1), only the body (=2), or both (=3) for the words in the contains list?

not_contains_words

A Tcl list of words that cannot exist in the message for it to be returned as a hit. This argument may be the empty list {}.

search_for_not_contains_where

Should only the header be searched (=1), only the body (=2), or both (=3) for the not contains list?

Return value

A Tcl list of key/value pairs, if successful. No data if no messages were found that matched the criteria provided. The format is Message ID and then the number of hits for that message, such as {1123 3 1145 3 1178 2}. Messages are returned in Message ID order with the higest number of hits first.

Remarks

A message search must look in either the header, the body, or both. It is an error to not make one of these two variables true.

Words are indexed that are over one character long and less than 30, so searching for enything longer or shorter than this will always fail to find results.

If MatchAny is true the Message ID is returned if any of the words in the contains word list are found. If MatchAny is false all the words must be found in the message for the Message ID to be returned.

Note that the number of hits simply refers to the number of messages that the word(s) were found, not to the number of times the word was found in the message. So if a message had "rabbit" four times in the message it would count as one hit when searching for "rabbit".

Example

search_message_archive jazztalk-discuss 0 1 {flute accordian tuba} 1 1 {bass} 1 1