EchoList - The EchoMail Conference List Page 1 Query Facility Users Guide as of: 28 Feb 1993 PURPOSE The EchoList system supports remote Queries via NetMail and EchoMail messages. This guide provides an overview of the facility and instructions for it's use. It is assumed that you are familiar with the kind of information stored in the EchoList database, either from the monthly EchoList reports, or the technical documentation contained in the Update Instructions (currently ELMOD293.LZH). OVERVIEW ELISTQRY is a message-based version of the query facility I use locally against the database. As such, what you include in your Query request message looks pretty much like command line arguments to a DOS command. Query messages must be addressed to ECHOLIST at 1:1/201 with a subject of ECHO QUERY. These messages can be sent direct via NetMail or in an EchoMail conference whose Moderator permits it. The reply will be posted back to you via the same message forum as your request--NetMail or EchoMail. The arguments you supply in the body text of the message boil down to three categories: Selection criteria, output format, and the search strings themselves. The search strings are either an exact match for a Tag or Key, or a regular expression to look for in various text fields. For those not familiar with the term "regular expression", you just need to supply a string of alphanumeric characters you want to look for. For those interested, there is a detailed explanation later in this document. QUERY MESSAGES To query the EchoList database, submit a NetMail message to "ECHOLIST" at 1:1/201. The message subject must be "ECHO QUERY". The body of the message text has the arguments for the query program. They can be strung out on a single line or on multiple lines--it doesn't matter. All arguments in the message are considered part of a single query. The only exception to the comments above about the message text is the optional "OPTIONS" statement. If you're familiar with the ELMODxxx.LZH update instructions than you know about this command. If you use it, it must be on a line by itself, and the only option is, for NetMail Queries, "OPTION HOLD", which causes your reply to be hold for your pickup rather than routed back to you. The OPTION statement is irrelevant in EchoMail Queries. The arguments can come in any order. The CAPITALIZED part of these keywords is the minimum abbreviation you can use. The To-name, subject and keywords are NOT case sensitive. Copyright (c) 1993 by Michael G. Fuchs EchoList - The EchoMail Conference List Page 2 Query Facility Users Guide as of: 28 Feb 1993 QUERY ARGUMENTS These arguments can use either '/' or '-', whichever you're comfortable with. Selection criteria: (specify only one, to identify the field(s) to search) /T [default] Search arguments are areaname Tags (exact match) /K Search arguments are area Keys (exact match) /PT Search args are partial Tags (reg exp) /PK Search args are partial Keys (reg exp) /PM Search args check all Moderator names (reg exp) /PD Search args check Title & Description (reg exp) /PG Search args check Gateways, Origin, Distribution (reg exp) Output format: (specify only one) /DETAIL Produces detailed database entries for each match. /LIST Produces a Tag or Key list, with titles. /RULES Produces a Rules file-name list, with titles. /SEEN Include seen-by lists in detail output. /PATH Include path lists in detail output. /TAB Separate fields with tabs in list or rules. The default Output format is /DETAIL if the Selection criteria is an exact match (/T or /K). The default Output format is /LIST if the Selection criteria is any of the partial string matches. All other text string arguments are used as the search strings. For /T or /K criteria, they must match the entry's index value exactly. For partial-field criteria (/Px) the strings are regular expressions. If you're not familiar with regular expressions, you just supply an alphanumeric string you want found anywhere in the fields specified in the selection criteria. Either way, you can supply as many strings as you like. Search strings for /T and /K Selections are automatically converted to uppercase for you. But all other field criteria you must specify the exact case you want. Be SURE to end your parameters with a "tear line" ("---"). EXAMPLES To select a series of specific Tags, with full detail: To: ECHOLIST At: 1:1/201 Subject: ECHO QUEry In the body of the message: /T /DETAIL /SEEN /PATH A_CAD SYSOP MODERATOR --- Copyright (c) 1993 by Michael G. Fuchs EchoList - The EchoMail Conference List Page 3 Query Facility Users Guide as of: 28 Feb 1993 To produce a list of Tags, Keys and Titles for entries containing a specific Moderator name: In the body of the message: /PM Fuchs /LIST --- To produce a list of Tags, Keys and Titles for entries containing a specific word in the title or description, but you're not sure of the spelling or capitalization: In the body of the message: /PD Amiga AMIGA amiga /LIST --- or... /PD [Aa]miga AMIGA /LIST --- Copyright (c) 1993 by Michael G. Fuchs EchoList - The EchoMail Conference List Page 4 Query Facility Users Guide as of: 28 Feb 1993 REGULAR EXPRESSIONS - as used in EchoList Queries This is meant to give a brief introduction to Regular Expressions to those of you not familiar with them. You don't need to understand any of this to use the query capability of the EchoList system. But if you do understand it, you will be able to do more powerful queries against the database. Most everyone using a microcomputer these days is familiar with the concept of wild-card characters as used to define the file names you want to search for in a directory listing (*.*, *.txt, ELIST???.*). A Regular Expression is a much more robust, formal method for defining pattern matching arguments for string searching. I have encountered different "special characters" used in different software that supports Regular Expression searching, but the basic operation is the same. The special characters defined here are those used in the query facilities for the EchoList, and I don't claim they'll match the syntax used in other software you encounter. (The following description is largely complements of the Rogue Wave Tools.h++ Reference Manual.) The Details So what is it? A Regular Expression is a string of characters that defines a criteria for finding matches in another string. I'll go through the generalities first, and then explain a couple of limitations (modifications) as you use them with the EchoList. From here on I'll shorten "Regular Expression" to RE. The following rules determine one-character REs that match a single character. 1.1 Any character that is not a special character (see below) matches itself. 1.2 A backslash (\) followed by any special character matches the literal character itself. I.E., this "escapes" the special character. 1.3 The special characters are: + * ? . [ ] ^ $ 1.4 The period (.) matches any character except the newline. E.G., ".umpty" matches either "Humpty" or "Dumpty". 1.5 A set of characters enclosed in brackets ([]) is a one-character RE that matches any of the characters in that set. E.G., "[akm]" matches either "a" or "k" or "m". A range of characters can be indicated with a dash. E.G., "[a-z]" matches any lower-case letter; "[A-Za-z0-9]" matches any alphanumeric. 1.6 If the first character in a set ([]) is a caret (^), then the RE matches any character except those in the set. It does not, however, match an empty string. E.G., "[^akm]" matches any single character except "a" or "k" or "m". The caret loses it's special meaning if it is not the first character in the set specification. Copyright (c) 1993 by Michael G. Fuchs EchoList - The EchoMail Conference List Page 5 Query Facility Users Guide as of: 28 Feb 1993 You combine the above single character REs, along with some additional special characters, to develop multi-character Regular Expressions. The following rules can be used to build multi-character REs. 2.1 A one-character RE followed by an asterisk (*) matches zero or more occurrences of the RE. Hence, [a-z]* matches zero or more lower-case characters. 2.2 A one-character RE followed by a plus (+) matches one or more occurrences of the RE. Hence, [a-z]+ matches one or more lower-case characters. 2.3 A question mark (?) identifies an optional element. The preceding RE can occur zero or once in the search string--no more. E.G., xy?z matches either xyz or xz, but not xyyz. 2.4 The concatenation of REs is a RE that matches the corresponding concatenation of strings. E.G., [A-Z][a-z]* matches any capitalized word. Finally, the entire regular expression can be anchored to match only the beginning or end of a line (or field, for the EchoList). 3.1 If a caret (^) is at the beginning of the RE, then the matched string must be at the beginning of a line. 3.2 If a dollar sign ($) is at the end of the RE, then the matched string must be at the end of a line. While not likely to be of much use within the EchoList system, the following escape codes can be used to match control characters. \b backspace \r carriage return \e ESC (escape) \t tab \f formfeed \xddd the literal hex number 0xddd \n newline \^c Control code. E.G., \^D is "control-D". EchoList Search Considerations When using regular expressions to search an index field (either Tag or Key) your RE will automatically be converted to upper-case, since there will be no lower-case letters in those fields. When searching other fields, you will need to pay attention to case, as the matches will be case-specific. When searching long text fields, the newline comparisons will generally only match the end-of-field, since newlines are not stored in the database. Text fields are word-wrapped as needed for a specific report. Examples... Copyright (c) 1993 by Michael G. Fuchs EchoList - The EchoMail Conference List Page 6 Query Facility Users Guide as of: 28 Feb 1993 Tag or Key searching with ZM will return all entries that have the characters "ZM" anywhere in the field. Using ^ZM will return those values starting with "ZM". Using ^Z[MO] will return any value starting with either "ZM" or "ZO". A Moderator search with ^Jo.+Sm would find John Smith, Jon Smythe, Joachim Aloysius Nathanial Smithereens, and so forth. If others provide a better explanation or better examples, I'll be happy to incorporate them. Enjoy. --- Copyright (c) 1993 by Michael G. Fuchs