Okay. LISTSERV@DEARN seems to be completely kaputt and forwarded a DIST job
to LISTSERV@FRECP11 with GERMAN recipients but *NOT* with ERIC@FRECP11 on it.
Then to PSUVM with same german recipients list. So, I'm sending this out as
mail, let's see what happens.
Eric
Temporary helpfile on the LISTSERV DATABASE facility - 21 Sep 1987
A- Scope of the LISTSERV database functions
The LISTSERV database functions are general-purpose, document-oriented
search-and-display facilities. They are quite different from "usual"
commercial database systems.
1. Definitions
A LISTSERV "database" is a set of physical CMS files, each of which
contains one or more "documents" of homogeneous "type". To each database
"type" is associated a database "driver", which is responsible for
analyzing the contents of the various documents and building a database
"index".
This structure is transparent to the user, who sees the database as being
a collection of "documents". Each document is assigned a unique "item
number" and a "date/time" field (which will usually be either the
creation or last modification date/time, depending on the database type).
Depending on the type of database, one or more "keywords" and "document
portions" may have been defined for each entry. A "keyword" is a
name/value pair, such as "REFCODE 2562783". It is external to the
document contents. A "document portion" is a name identifying a portion
of the document, such as "DESCR" or "HEADER". There is a built-in
document portion, "ALL", which is common to all the database types and
corresponds to the complete document.
2. NOTEBOOK databases
Most LISTSERV databases will be of the "NOTEBOOK" type. These correspond
to the list logs being optionally kept on disk. The NOTEBOOK database
driver provides two additional document portions, "HEADER" and "BODY",
and two keywords: "SENDER" and "SUBJECT". Abbreviations and synonym are
also provided for these keywords:
Header HDR
Body Text
Subject
SEnder From
The minimum abbreviations are capitalized. Please note that "FROM" is a
reserved database keyword (when not abbreviated) and it must therefore be
quoted if it appears in a search sequence (see below).
B. Sending search requests to LISTSERV
A search requests consists in a series of "rules" or "database
subcommands" which must be sent to LISTSERV as a CJLI job. The following
job skeleton can be used in the majority of cases:
//DB JOB Echo=NO
DATABASE SEARCH DD=Rules
//Rules DD *
rule 1
rule 2
...
/*
Each line in the RULES dataset is a search subcommand. Subcommands can be
continued in the next line by appending a dash to all but the last
physical line in the command. This dash is replaced with a blank when the
concatenation process occurs. Example:
//Rules DD *
Search 'a very long string that takes a lot of space' and not -
'another very long string that will fill up another input line' -
in sampledb from 8 may 1986 to june 87
/*
C. Syntax
1. The SEARCH/SELECT command
The first command in your set of rules will probably be a SEARCH command.
You must establish a "list of hits" by means of that command before being
allowed to display any information. The syntax of this command is quite
complex, and its description has been split into several paragraphs.
a. General syntax
Search search-rules <date-rules> <keyword-rules> <db-list>
SELect
b. Database list specification
For each SEARCH command, you may specify a list of databases to be
searched. The default is to narrow the search, ie use the result of the
previous search as input. This is of course possible only if the previous
SEARCH command yielded one or more hits.
The syntax of the "db-list" specification is the following:
IN <(> dbspec1 <dbspec2<...>> <)>
The parenthesis are optional. If they are omitted, database names may not
be reserved keywords like SINCE or WHERE.
The syntax of "dbspec" is the following:
db-name<.<(>range1<,><range2<,><...>><)>>
where "db-name" is the name of the database to be searched, and "range"
are optional parameters restricting the search to a sub-list of entries
in this database. Each "range" may be either a single entry number like
"1274", or a range of numbers like "12-17", "827-" or "-40". They are
separated by either commas or blanks, and may optionally be enclosed in
parenthesis (this is required only if the separator is a blank).
Example:
IN REXXLIST.200-,12-13 REXXGRP VMSHARE.(61 80-100 12)
b. Date rules specification
You may optionally restrict the search to only those entries that lay
within a given interval of time. This is accomplished by specifying one
of the following date rules:
SINCE date-spec
FROM date-spec1 TO date-spec2
UNTIL date-spec
The format of a "date-spec" is quite complex because of the number of
ways a date/time format may be expressed:
TODAY <hh:mm<:ss>>
year
day monthno
<day><->monthname<-><year>
mm/yy
mm-yy
yy/mm/dd
yy-mm-dd
A date specification might therefore be:
FROM 14 JULY TO OCT 87
SINCE 86
UNTIL 06-23-87
c. Keyword rules specification
You may request the actual document search to take place only for those
entries which match a set of "keyword comparisons" rules. The syntax is
the following:
WHERE kwd-expression
WITH
"kwd-expression" is, generally speaking, an arithmetical expression of
keyword/value comparisons bound by logical operators. Comparison
operators have a higher precedence than logical operators. The available
comparison operators are:
= IS
^= <> IS NOT
>
<
>=
<=
CONTAINS
DOES NOT CONTAIN
The latter two allow you to search for a substring in a keyword string.
Available logical operators are:
^ NOT
& AND
| / OR
Finally, if no valid comparison operator is specified between two
arguments, "IS" is assumed.
Thus, the following expressions are possible:
WHERE SENDER IS ARTHUR@DENT AND SUBJECT DOES NOT CONTAIN LOST
WITH (QTY > 100 | VALUE > 1000) & MAT = COPPER
WITH SENDER ATIARAN@LAND AND SUBJECT CONTAINS 'BE TRUE'
d. Search rules specification
Finally, you must specify what is to be searched inside the document. If
you do not want anything to be sought at all (eg if you are only
selecting known items from the database), you can specify an asterisk as
placeholder to waive the search. Otherwise you must specify an
arithmetical expression where arguments are a search strings, bound by
logical operators (see above for complete list). The default operator is
"AND", so that a search for "INTERPRET STEM PROBLEM" will select all
entries where "INTERPRET", "STEM" and "PROBLEM" can be found (but not
necessarily in the same line).
e. Reserved words and quoting
Document and keyword search arguments need not be quoted unless they are
also a reserved keyword. Any non-quoted word will be stripped of leading
and trailing blanks and converted to uppercase before the search. If you
want to search for a string containing blanks, or if the search argument
is also a reserved word like UNTIL, you must quote it using either single
or double quotes. If quotes are to appear inside the string, they must be
doubled.
Strings quoted in single-quotes are upcased and result in a case-ignored
search, whereas double-quotes cause the case to be respected during the
search. Thus, a search for "TEXT" would not find a hit on "text", whereas
'TEXT' would.
2. The FORMAT command
The FORMAT command allows you to define formats for displaying
information about selected items. The FORMAT command itself does not
cause any information to be displayed; rather, it prepares a display
format specification which may be used later on in LIST/INDEX commands.
The syntax of the FORMAT command is:
Format fmtname<:> fmtspec1 <fmtspec2<...>>
Each "fmtspec" defines a column in the output chart, using the following
syntax:
fieldname<(<start><,end>)><.cols<just>> <"heading"<hd-just>>
This will create a column in the table, under the specified heading
(which defaults to the - uppercase - field name if omitted), where a
substring (start,end) of the specified field will be displayed. The
default for "start" and "end" are 1 and 255, respectively. The width of
the columns is controlled by the "cols" specification, which defaults to
12 columns. Finally, the data in the column will be justified according
to the "just" specification, which defaults to "L", whilst the header is
is justified as indicated by "hd-just", which defaults to "L" too. The
possible values for these justification types are as follows:
L -- Left justification
R -- Right justification
C -- Centered
R0 -- Right justification with leading zeroes (for numerics)
Note that the "R0" justification type is invalid for headings.
Each fieldname must be a valid "keyword" name for the database against
which the format will be used. In addition, some common keywords are
provided irrespective of the database type:
DATABASE -- Name of the database (1-8 characters)
DATE -- Date of the database entry (yy/mm/dd)
TIME -- Time of the database entry (hh:mm:ss)
#RECS -- Number of records in the database entry
# -- Reference number of the database entry
Example:
Format listing: #.4R0 date(,5).5 "Date" partno.5R0 "Part no"c -
database.8 "Type"
3. The LIST/INDEX command
The LIST/INDEX command allows you to list information about selected
items in the database. Its format is:
List <fmt1 <fmt2 <...>>>
Index
Where each of the "fmt" specifications is either the name of a predefined
FORMAT or an individual "fmtspec" (see definition above). For each
database, there exists a predefined format called "INDEX", which is used
if no "fmt" specification is given in the parameters. It may also be
invoked explicitly.
Example:
List sender.17 "Sender"l index
4. The PRINT command
The PRINT command allows you to display "portions" or "keywords" of the
selected documents. However, it should be noted that it was primarily
intended to display "document portions", not "keywords" which ought to be
displayed by means of the LIST command. The syntax of the PRINT command
is:
Print <part1 <part2 <...>>> <OF> <range1 <range2 <...>>> <, part1 ...>
Each "part" must be a valid "document portion" or "keyword" for the
database against which the PRINT command is issued. "ALL" is the default
and is always valid, regardless of the database type. You may optionally
specify "ranges" (xxxx, xxxx-yyyy, xxxx- or -yyyy) to further restrict
the list of database items to be displayed. However, this does NOT allow
you to display a document that has not been previously selected by means
of a SEARCH/SELECT command.
Finally, you may place more than one set of print specifications on the
command line, provided you separate them with commas.
Example:
Select copper wire (1/100 or 1/20) since june where qty < 100
Print description of 113 120-123, price_history of 144
|
