From: rich@pencil.cs.missouri.edu (Rich Winkel)
Subject: USING LISTSERV'S ARCHIVE AND DATABASE FUNCTIONS (autopost)
Followup-To: alt.activism.d
Originator: rich@pencil.cs.missouri.edu
Organization: PACH
Date: Sun, 8 Nov 1992 09:30:05 GMT

LISTSERV@UMCVMB acts as a network file server for two sets of
ACTIV-L-related files, the "library" and the "database".

The library contains a hand-picked collection of some
of the most important articles posted to activ-l since its inception.
Any file in the library can be retrieved via email.  To retrieve a
file, mail the following command to listserv@umcvmb:

GET file name ACTIV-L

Note that all file names consist of two words separated by a blank.
Example: "GET AMLDBASE DOC ACTIV-L" retrieves the file you are
currently reading.

To get a nicely formatted list of the files in the library, send the
command "GET ACTIV-L ARCHIVE".  To get a somewhat uglier (but
guaranteed to be up-to-date) list, send the command "INDEX".

In addition to the library, listserv automatically places every
article posted to activ-l into a database which any networker can
utilize via email.  The following is a short tutorial on using
listserv's database language to search and retrieve articles from the
activ-l log.  It isn't meant to be an exhaustive reference, but
hopefully it will get people up to speed quickly.  Please send
suggestions / complaints / ramblings to MATHRICH@UMCVMB.MISSOURI.EDU.
For a complete description of listserv's database language, mail the
command INFO DATABASE to any listserver.

Database "jobs" (for want of a better word) consist of a sequence of
database commands, bracketed by several lines of listserv "job control
language" (JCL) commands, mailed in a single mail file to a listserver.
The JCL commands are (for our purposes) always the same.  They are:

//SEARCH JOB ECHO=NO
DATABASE SEARCH DD=RULES
//RULES DD *
                       <<--- any number of database
                       <<--- commands go here
/*

In our case, the job would be mailed to LISTSERV@UMCVMB.

*** SEARCH COMMAND ***

The most important and complicated command is the Search command.
(alias Select, minimum abbreviation "S").  Its basic syntax is outlined
below:

SEARCH rules [IN ACTIV-L] [date_rules] [keyword_rules]

(arguments in []'s are optional)

In general, "rules" is a search string or boolean expression applied to
the message body of each article, "IN ACTIV-L" specifies which database
to search, "date_rules" defines a range of dates of interest (as given
in the Date:  field in the articles' mail header), and "keyword_rules"
is a keyword-delimited boolean expression applied to the Subject:
and/or From:  fields in the mail header.  (this is gibberish, I know...
wait until we get to some examples.  Then it will be perfectly opaque)

Note:  The "IN ACTIV-L" argument must be specified in the first search
command in a job.  Thereafter, each subsequent search command which
omits the "IN ACTIV-L" implicitly assumes it, AND will restrict its
search to those articles which were selected by the previous search
command.  In other words, the logical tests in each search for which
"IN ACTIV-L" is not specified are, in effect, ANDed with the tests
in all previous search commands up to the last one which specified
"IN ACTIV-L".

Example: The sequence of commands

SEARCH ABERCROMBIE IN ACTIV-L
search warheads missles
SEARCH BANANAS OR PINEAPPLES

will select those articles which contain the strings "abercrombie",
"warheads" and "missles", and either "bananas" or "pineapples" (or
both), in their message body.  A subsequent

SEARCH BANANAS IN ACTIV-L

will select all articles which contain "bananas" (i.e. because
"IN ACTIV-L" is specified, the results of the previous searches are
forgotten and the search domain is reset to the entire database)

In the above example, note the following:
The searches are case insensitive by default.
The search strings need not occur as discrete words in the
   articles in order to get a match.  (a search string of "MAN" will
   match both "man" and "woman")
Blank-separated search strings (WARHEADS MISSLES) are treated as
   separate logical tests ANDed together (i.e. the words need not occur
   together on the same line, but must both appear somewhere in the
   same article in order to satisfy the expression)

More complex search expressions are possible:

search table and (chair or stool) but not seat
search table and (chair or (stool and seat))
search table and not (chair or stool)

Note: "but not" = "and not" = "not"

If a search string contains embedded blanks, or a logical operator (AND,
OR, NOT, =, &, |, ^, <, >) or parentheses, or a reserved keyword (IN,
FROM, SINCE, TO, UNTIL, WHERE, WITH) then it should be quoted:

search 'in' in activ-l
search 'military industrial complex' in activ-l
search "not important" in activ-l

The difference between single (') and double (") quoting is that double
quoting causes a case-sensitive search.

search "Ronald Reagan" or 'dippity doo'

The above search would select articles containing the string
"Ronald Reagan" (must be an exact match) or the string "dippity doo"
(case insensitive).

The special rule "*" matches any text.  The following command selects
all articles in activ-l:

search * in activ-l

Date Rules

Date rules narrow a search to a specific period of time.  The syntax is
very forgiving because of the number of valid date formats.  The
following are all legal dates:

TODAY
91        (year 1991)
25 12     (christmas)
jan       (january)
12/25     (christmas)
12-25     (christmas)
25 dec 90 (christmas 1990)
90/12/25  (christmas 1990)

Notes:
   Month names can be shortened to any non-ambiguous abbreviation.
   Clock time may optionally be specified in the format hour:minute.

Dates are combined with the following date rules to designate a range
of time:

SINCE date time
FROM date time TO date time
UNTIL date time

The following examples illustrate the 3 possible ways to search by date:

search chair since 91/01/01
   selects articles since jan 1, 1991 which contain the string "chair"
   in the message body.

search (chair or table) in activ-l from 90/12/01 to 25 dec 90
   selects articles between December 1st and December 25, 1990 which
   contain either "chair" or "table" in the message body.

search * until today 18:00
   selects all articles posted before 6 PM today.

Note: the boundary date(s) are included in the selected range.

Keyword Rules

For our purposes, keyword rules are used to scan Subject:  and From:
fields of mail headers.  Keyword rules consist of the word "WHERE" or
"WITH", followed by a series of one or more comparisons.  Valid
comparison operators are (synonyms listed together on the same line):

=, "IS"
^=, <>, "IS NOT"
"CONTAINS"
"DOES NOT CONTAIN"
"SOUNDS LIKE"
"DOES NOT SOUND LIKE"

Logical operators are (synonyms listed together on the same line):

^, "NOT"
&, "AND", "BUT"
|, /, "OR"

The keyword SUBJECT is used to refer to the Subject: field in the
mail header, and SENDER refers to the From: field.

Examples:

search * in activ-l where subject contains (peace or prosperity)
   selects all articles with subject containing "peace" or "prosperity"

search (house or senate) and (vote) where sender is MATHRICH@UMCVMB.BITNET
   selects articles posted by me (:-) which contain the string
   "vote" and either "house" or "senate" (or both) in the message body.

search * where sender contains harel and subject does not contain peace
   selects articles posted by Harel which don't have the word "peace"
   in the subject.


Search commands (or any other database command) which are too long
to put on a single line can be continued to the next line by placing
a dash at the end of the line:

search (chairs or history) and 'corn flakes' in activ-l since 90/12/01 -
where sender contains (harel or winkel) and subject does not contain -
'peaches and cream'

Note:  To avoid ambiguity, quoted strings should not be broken up into
separate lines.

*** INDEX COMMAND ***

Once you've selected the articles of interest using the SEARCH command,
you can get a quick listing of what you've selected with the index
command.  Index displays, in a tabular format, the item number, date,
time, number of lines, and subject of every article selected.
Unfortunately it doesn't display the sender.  The syntax is just:

INDEX

Note: don't confuse this INDEX command with the library index
command mentioned above.  They're two separate things.

*** LIST COMMAND ***

This is an alternative to the index command which allows the user to
customize which mail header fields to display.  The full syntax is
explained in the original listserv documentation.  A convenient
version of the list command (which displays the sender) is:

LIST #.5R0 DATE.8 SENDER.10 #RECS.5R SUBJECT.80

*** PRINT COMMAND ***

After you get back an index of your search and you've decided which
articles you want, you can submit a new job to retrieve them (or if
you're sure of what you're doing, you can retrieve them in the same job)
The PRINT command with no arguments prints all the articles currently
selected.  If you've already received an index listing, you can print
articles by their item number (listed in the index).  Print will
accept a list or range of item numbers of articles to print.

Examples:

PRINT

Prints all selected articles.

PRINT 236 352 772

Prints just those three articles.

PRINT 329-350

Prints all articles in the specified range.

Note:  If you submit a job to retrieve articles by item number (you
would have to first get the item numbers by doing an index in a previous
job), you need to re-select the activ-l database before you can do any
printing.  The fastest way to do this is to preceed the print command
with a "SEARCH * IN ACTIV-L".

Listserv places an upper limit on the total number of lines produced
by one job.  If you exceed this limit an error message will be printed
and your output will be truncated.  Just split up your prints into
separate jobs if this happens.

*** FOR CMS AND VMS USERS ONLY ***

If you are on an IBM VM/CMS or DEC VAX/VMS system connected to BITNET,
you can access the database interactively.  To do this, you first
need to get a copy of the appropriate commands to run on your
system.

On VM/CMS systems:
TELL LISTSERV AT UMCVMB GET LDBASE EXEC
TELL LISTSERV AT UMCVMB GET LSVIUCV MODULE
After you receive these files, type LDBASE UMCVMB to start a session.

On VAX/VMS systems:
SEND LISTSERV@UMCVMB GET LDBASE COM
After you receive this file, type @LDBASE to install the program and
display detailed instructions.

Notes:

The JCL commands listed at the top of this tutorial are not
needed in interactive mode.  You can go right into your first SEARCH
command.

There is a relatively small line limit per command on interactive
output.  To get a large amount of data, you need to have it mailed to
you as a file.  To do this, simply prefix the INDEX or PRINT command
with the word SENDBACK:

SENDBACK PRINT 234 432

Would return the specified print output to you in a mail file.

*** (end) ***

Newsgroups: misc.activism.progressive