Database

LISTSERV provides the facility for users to retrieve old mail that has been distributed on mailing lists. Each mailing list has an associated database (called a notebook or list archive database) in which list mail is stored. Note that databases may not be maintained for every mailing list, this is done at the discretion of a list owner. The notebook databases are the most commonly used of the LISTSERV databases. However, every LISTSERV server also has a database of all the EARN/BITNET computer nodes (called the BITEARN database). This is available to all LISTSERV users. The backbone LISTSERV servers also have a database of all the LISTSERV computer nodes (called the PEERS database). In addition to these databases, a LISTSERV server may have any number of different databases that have been created locally.

DATABASE Keywords

The documents in a database all have specific attributes in common. These attributes are exploited by defining a set of keywords for that database. A database keyword is something like a luggage tag that is attached to each document in a database. Any number of tags may be attached to a document, each one containing information about that document (for example, the date and time it was stored in the database or the author's name and e-mail address). These keywords can then be used when searching for documents, or the information they contain may be displayed. The keywords used by each database may differ, but there are certain keywords common to all of the databases maintained by LISTSERV. These are:

DATABASE

The name of a database (one to eight characters)

DATE

The date of the document's entry into a database

TIME

The time of the document's entry into a database

#RECS

The number of lines in a document

#

The document number in a database

Notebook Database Keywords

The most common of the LISTSERV databases are the notebook or list archive databases. Each of these databases is associated with a mailing list and holds copies of all the mail messages distributed on that list. These notebook databases have the following additional keywords available for use when searching for or displaying information from a document:

Subject

Set to the contents of the Subject: mail header in a mail message.

SEnder

Set to the e-mail address of the sender of a mail message

The notebook databases also support the division of each document into predefined segments or sections. The keywords associated with each document section can be used to display information from either or both of these sections. They are:

Header

The section of the document that contains the headers of a mail message (which include, for example, the From: and To: mail headers).

Body | Text

The section of the document that contains the text of a mail message.

All

Both the Header and Body sections of mail message. This is default.

Note that not all databases have the same additional keywords available for use, nor are all documents split into sections. To be able to use keywords effectively when searching for or displaying information from documents, you should know what keywords and document sections are available for each different database.

Locating LISTSERV DATABASES

Each LISTSERV maintains its own independent set of databases and it will be necessary for you to first locate the server that holds the database that interests you. To determine what databases are available at a LISTSERV server, use either the DATABASE or DBase command. LISTSERV will return the names of all the databases it maintains along with a brief, one line description of each. The command format is:

---

DataBase  LIST

---

When you are searching for the notebook database of a mailing list, it will always be located at the LISTSERV server that manages that mailing list. Therefore, the address of a mailing list (for example, IBMPC-L@CEARN) shows which LISTSERV will maintain that list's notebook database (in this case, LISTSERV at node CEARN). Once you have located a database you wish to search, you may access it either through a batch or an interactive database session.

Batch DATABASE Access

Users from any network that can reach the LISTSERV servers may send database commands to a server through the batch facility. Users on the EARN/BITNET network where the LISTSERV servers are located may also use the interactive database facility (see below). The batch facility entails sending e-mail to a server that contains a database job. Note that e-mail should, in this case, be sent to the LISTSERV server where you want the job to be executed and not addressed to any mailing lists. A database job consists of a number of database commands that are formatted in a special way. These commands go into the body of the mail (one per line) and are executed sequentially by LISTSERV. Note also that LISTSERV will ignore the contents of the mail's Subject: header, so ensure the commands are in the body of the mail message. The results of these commands will be returned to you by mail once all the commands have been executed. If the database job contains unknown commands or syntax errors, these will be ignored and processing will continue with the next command in sequence. However, if the error count passes a certain threshold, processing of the database job will be stopped and any remaining commands ignored. LISTSERV will notify you of any errors that are encountered in a database job. The following sample format of a database job can be used for any database commands:

     // JOB
     DATABASE SEARCH DD=RULES
     //RULES DD *
     command1
     command2
     ...
     /*
     // EOJ

In the above example, the first line starts the database job and any line before this will be ignored (as will blank lines found anywhere in the mail message). The next line specifies that this is a database job and gives the name of the section that holds the database commands (this comes after the DD= keyword). In the example, the command section is called RULES, but any name of any length can be used instead. Following this, the command section starts, signaled by its name and the DD * string. From this point until the line that ends the command section, any number of LISTSERV database commands may be entered. The last two lines signal the end of the command section and the end of the database job, respectively. If any lines of text are found in the e-mail after the line that finishes a database job, LISTSERV will execute these as non-database LISTSERV commands (see the section Sending Commands to LISTSERV). This commonly occurs by mistake when signatures are automatically put in to a mail message when it is sent. If you wish to avoid this and the accompanying invalid command notification that LISTSERV will send to you, ensure that such features of your mailing system are disabled prior to sending database jobs to LISTSERV servers. For example, a database job to search for Mathematical Institutions in the BITEARN database would be:

     // JOB
     DATABASE SEARCH DD=FINDMATH
     //FINDMATH DD *
     SEARCH MATH IN BITEARN
     INDEX
     /*
     // EOJ

Where the commands that will be executed are SEARCH and INDEX (these commands are explained in detail in the DATABASE Commands section). After having posted this database job to any LISTSERV (since the BITEARN database is resident at all of them), you would expect to receive a response similar to the following:

     > SEARCH MATH IN BITEARN
     --> Database BITEARN, 47 hits.
 
     > INDEX
     Ref# Conn  Nodeid   Site
     ---- ----  ------   ----
     0156 85/08 BENGUS   Ben-Gurion University Mathematic...
     ....

For more information on batch access to LISTSERV databases, send the command GET LISTDB MEMO to your nearest (or any) LISTSERV. For more information on the Command Job Language of LISTSERV (used to construct database jobs), send the command GET LISTJOB MEMO to your nearest (or any) LISTSERV.

Interactive DATABASE Access

As well as using batch access to LISTSERV databases, EARN/BITNET users that work on VM/CMS or VAX/VMS systems can use a special user interface program (called LDBASE) for interactive database access. That is, they have the ability to open a database session with a LISTSERV server during which commands and their results are passed between the user and the server by means of interactive messages. The LDBASE interface is the client program that establishes and controls an interactive database session between the user and a LISTSERV server. If this program is not already available at your site, it can be retrieved from any LISTSERV server. For VM/CMS users, send the following commands to your nearest LISTSERV:

TELL LISTSERV AT node-name GET LDBASE EXEC
TELL LISTSERV AT node-name GET LSVIUCV MODULE

where node-name is the location of your nearest (or any) LISTSERV server. The LDBASE command will be ready for use as soon as you receive these two files onto a minidisk.

For VAX/VMS users, send the following command to your nearest LISTSERV:

$ SEND LISTSERV@node-name GET LDBASE.COM

where node-name is the location of your nearest (or any) LISTSERV server. The command to install the LDBASE program in your directory is:

$ @LDBASE

For VM/CMS and VAX/VMS systems, these two programs have the same function: once an interactive session is requested, they attempt to establish a network connection to the LISTSERV holding the databases you wish to access. The format of the command is:

---

LDBASE  < node-name >

---

Where node-name specifies the location of the LISTSERV server with which you wish to commence an interactive session. The first time you use this command without specifying the node-name parameter, you will be asked to supply a node name you wish to have as your default node. From then on, omitting a node name with this command will automatically give you a session with the LISTSERV server at the location you have given. Otherwise, you will be given an interactive session with the LISTSERV located at the node you specified with the command. The LDBASE command will inform you when an interactive session has been successfully established. From this point, you may enter and re-enter any number of database commands until you terminate the session with the QUIT command.

Some database commands can result in large amounts of output (for example the Print command). To reduce the amount of information passed over the network by such commands, output has been restricted in the following way: if you have established an interactive database session with a LISTSERV server that is not located on the same computer as you, command output is limited to the first thirty lines. You will be informed if any output to you has been suppressed. If this is the case, you can retrieve the complete command output by using the SENDback command or by constructing a database job where command output will be e-mailed back to you.

DATABASE Commands

These commands are designed to give the LISTSERV user access to any databases for which they have appropriate authority. With them, databases may be searched and documents displayed or retrieved. Note that some of the commands you can construct may become too long to fit onto one line. If this is the case, commands may be split over as many lines as desired by using the '-' (hyphen) continuation character. To use this, end each line with this character and continue entering your command on the following line. LISTSERV will not execute the command until you enter the last line of the command (which should not end with a continuation character).

---

Search    Search a for documents holding a given text string
SELect    A synonym for the Search command
Index     Display the list of documents selected in a Search
Print     Display the contents of documents selected in a Search
SENDback  Send yourself a copy of one or more selected documents
Format    Change the format and data displayed by an Index command
List      Display data from selected documents in a given format
QUIT      End an interactive database session

---

Search

The Search (or SELect) command is used to search through the documents in a specified database for a given string of text. The text may be one word, a series of different words or a phrase. You may also include a number of optional search criteria with which a search can be restricted. Once a search has been initiated with this command, you will be informed of the number of documents that match your search criteria (these are called the number of hits). These documents then form the group on which subsequent database commands are executed. The Search command should be the first database command you use when you start a database session. You must have a number of hits before issuing any of the other database commands. The format of the Search command is:

---

Search  search-rules  < optional-rules >

search-rules

---

The search-rules specify the text string to be searched for in the documents within a database . If you are interested in making your selection of documents based solely on the other optional-rules (described below) then you may give a search-rule value of '*' (asterisk), otherwise, a text string must be provided here. A text string may be comprised of one or more words separated by logical operators or it may be a phrase (in which case it must be quoted). If a text string is given as a series of words that are not quoted and no logical operator separates them, the logical operator AND is assumed. For example, the following commands are identical:

SEARCH PC VIRUS
SEARCH PC AND VIRUS

These commands will result in a search for documents that hold the words PC and VIRUS anywhere in their text. Note that both of these words must be present in a document for it to be selected (as denoted by the logical operator AND). A full list of logical operators is given in the keyword-rules section below. A phrase is constructed by the use of quotes in the text string. Phrases may also be separated by logical operators. For example:

SEARCH 'PC VIRUS' OR 'Virus Warning'

results in a search for documents that hold the phrases PC VIRUS or Virus Warning in their text. When using quotes to specify a phrase, ensure that the correct number of blank characters are present between each word in the phrase. Searching for PC VIRUS with one blank character between PC and VIRUS will not match strings that have multiple blank characters in the same position. You may use either single or double quotes to enclose a phrase. However, there is an important difference between them. Using double quotes will result in a case-sensitive search for the text in a phrase while single quotes (or no quotes at all) yields a non-case-sensitive search. If a phrase itself contains a quotation mark in it, then it must be doubled:

SEARCH 'The Forum''s decision'

optional-rules

The optional-rules part of the Search command is comprised of a database-list, date-rules and keyword-rules. One or more of these elements may be included in a Search command. They may appear, in any order, after the search-rules have been specified and may be identified by the appearance of their reserved-words in the Search command text. Each of these optional-rules are described below under their own headings.

 

database-list

A database-list identifies the database whose documents are to be included in the search. It must be present in a Search command until a number of documents have been selected as hits. Once you have a group of hits, the database-list can be omitted and all subsequent Search commands will act solely upon this selected group of documents (including additional Search commands which do not specify a new database. This can be used to further reduce the number of selected documents). If you wish to search for new documents not already among the group of hits, a new database-list should again be included in the Search command. It has the following format:

---

IN  db-name

---

Here, the database name that you specify must be preceded by the reserved-word IN. Therefore, if you wanted to search for the phrase 'Infinite Loop' in a database called BUGS, you would form your search command in the following way:

SEARCH 'Infinite Loop' IN BUGS

Within a database, each document is assigned a unique, sequential number. You will see the number assigned to each document in response to an Index command (which lists all the documents selected). This number may change between different database sessions, however, it will not change during a session. Therefore, they may also be used to further narrow a search for documents within a database by specifying a list of one or more document numbers, an upper or lower limit for document numbers or a range of numbers. This information is appended to the given database name with the following format:

db-name. < ( >  number <,> number- <,> number-number <,>

All document numbers are appended to the database name by a '.' (full stop) character. If you are going to specify more than one document number, they may either be enclosed in parentheses or else they must be separated by commas. For example, in a database called PROJECTS, you could include in your search all the documents with numbers up to and including 10, document number 15, all those between and including numbers 20 and 30 and all documents above and including number 45 with either of the following commands:

SEARCH * IN PROJECTS.(-10 15 20-30 45-)
SEARCH * IN PROJECTS.-10,15,20-30,45-

Including document numbers in a Search command is useful only when reducing the quantity of hits from a previous database search.

 

date-rules

The date-rules option can be used to further restrict the search of documents to those that fall within a given time interval. The reserved-words in the Search command that indicate the presence of date-rules are:

---

SINCE  date  <  time  >
FROM   date  <  time  >  TO  date  <  time  >
UNTIL  date  <  time  >

---

Here, the optional time parameter may be supplied in the form of hh:mm<:ss>, where hh represents the hour, mm the minutes and the optional ss, for the seconds. The date parameter can be supplied in any of the following formats:

TODAY
yy
yy/mm/dd
yy-mm-dd
mm/yy
mm-yy
dd mm
< dd- > month-name < -yy >

Where yy is a two-digit representation of the year, mm is a two-digit month number and dd is a two-digit day number. The special string TODAY inserts today's date into the date-rule clause. The month-name parameter can be used to provide the name of a month. This can be abbreviated to any length and the first month (in chronological order) that matches the month-name supplied will be selected for use.

 

keyword-rules

The keyword-rules use a predefined set of keywords for the database being searched. See the section DATABASE Keywords for a description of keywords specific to notebook databases that can be used in database searches. The format of keyword-rules is:

---

WHERE  keyword-tag  expression

---

Here, WHERE is the reserved-word that denotes the presence of a keyword-rule in a search command. (Note that WITH is a synonym for WHERE and they can be used interchangeably). The keyword-tag identifies a valid keyword for the database where the search is to be done. Note that these can differ between different types of databases. In the case of notebook databases, this includes the Subject and SEnder keywords. The expression that follows the keyword-tag must be satisfied if any document is to be counted as a hit. These expressions may be written in the following format:

---

IS  value
=  value
IS NOT  value
&circ.=  value
>  value
>=  value
<  value
<=  value
CONTAINS  value
DOES NOT CONTAIN  value
SOUNDS LIKE  value
DOES NOT SOUND LIKE  value

---

Where the value given is either a number or a string of text. All text strings that contain more than one word must be enclosed in quotes. If no comparison operator is put before the value then IS is assumed. The above expressions are all self-explanatory with the exception of SOUNDS LIKE and DOES NOT SOUND LIKE. These are used to make phonetic searches on keywords where the value you supply in the expression does not have to match exactly to the information in the keyword-tag. Some examples:

SEARCH * IN PSYCH-L WITH SENDER 'gregson@une.nsw.au'
SEARCH * IN PROG-L WHERE SUBJECT CONTAINS 'Binary Tree'
SEARCH * IN EARN-UG WHERE SENDER SOUNDS LIKE 'Smith'

In the first example, a search will be initiated in the PSYCH-L notebook database for all mail messages that have a SEnder keyword value of gregson@une.nsw.au. The second will search the PROG-L notebook database for all e-mail whose Subject keyword includes the string Binary Tree. The last example will select mail messages that have been sent by anyone to the EARN-UG mailing list whose userid could be smith, smythe or even Smithers. It is also possible to construct complex expressions by making use of logical (or boolean) operators. These operators can also be used in the search-rules section of a Search command. They are:

---

NOT  or  ^
AND  or  BUT  or  &
OR  or  |  or  /

---

Note that when you use these logical operators, it is advisable that you enclose the expression in parentheses. For example:

 ... IN PHYSICS WHERE SUBJECT CONTAINS (Nuclear OR Particle)

Index

This command is used to display information from all of the documents which have been selected with a Search command. This information will help you decide what to do next (for example, issue a new Search command or perhaps review the contents of one or more of the documents with a Print command). Information from each of the selected documents will be displayed in a predefined format (depending on the type of database you have searched). For every document, you can expect to be shown details such as its number, its size, the date it was created or last modified and any other information relevant to the type of database you are searching. Each type of database has its own predefined display format when the Index command is issued. The information shown and the way it is displayed can be customized through the use of the Format command. The format of the Index command is:

---

Index  < fmt-name >

---

Where fmt-name is the optional name of a display format you have previously defined with a Format command. If you do not specify a fmt-name parameter, the default display format (which has the format name of INDEX) will be used.

Print

This command can be used to review the contents of one or more documents that have been selected through a Search command. It is therefore designed to be used when you have narrowed down the number of selected documents (perhaps through successive Search commands) to those that are definitely of interest to you since this command can generate a lot of output. The Print command has the following format:

---

Print  < options >

---

Where options provides a list of one or more documents whose contents you wish to have displayed. If you do not identify any specific documents by omitting the options parameter, you will be shown the complete contents (or the first thirty lines) of all the documents that you currently have selected. If you do wish to provide options with the Print command, they have the format:

---

< sections keyword-tags >  < OF >  < document-numbers >  <,...>

---

Here, the sections and keyword-tags parameters are used to identify which sections or keywords from the selected documents you wish to have displayed. This can be a list of one or more document sections or keywords valid for the database you have been searching. A description of document sections and keywords available for notebook databases is given in the DATABASE Keywords section. The document-numbers parameter may then be included to identify those specific documents you wish to have displayed. The numbers of all currently selected documents may be seen with the Index command. If no document numbers are given, the Print command acts on all of the currently selected documents. Otherwise, you may provide a list of one or more document numbers, an upper or lower limit of document numbers or a range of numbers. These parameters to the Print command may be given multiple times by separating them with a ',' (comma) character. Consider the following example for a notebook database:

PRINT SUBJECT OF -10, SENDER OF 13-15, 19 21, BODY OF 30-

This Print command gives four separate instructions for displaying information from the documents that have already been selected with a Search command. The first set of parameters asks that the information held in the Subject keyword for all documents whose numbers are up to and including 10 be displayed. The second set of parameters, that the information from the SEnder keyword for all documents in the range of 13 to 15 be displayed. The next set of parameters specifies that the entire contents (that is, both the Header and Body document sections) of documents 19 and 21 be displayed. Finally, the last set of parameters asks that the Body document sections of all documents with numbers greater than and including 30 are shown. Therefore, if a Search command has selected a group of documents whose numbers are 9, 10, 12, 13, 14, 15, 19, 20, 21, 29, 30 and 31, then the above Print command will display information regarding all of these documents except numbers 12, 20 and 29. Note that in interactive mode, the results of a Print command are sent directly to your screen. If you wish to retrieve the results of a Print command as a file, then you must use the SENDback command.

 

SENDback

This command is used to have command output returned to you in a file. Its use is valid only if you have established an interactive database session with a LISTSERV server. If you are using the batch access method, you will always receive the output of any database commands as e-mail. The SENDback command has the format:

---

SENDback  command

---

where command can be either a valid Print or Index command. You will receive the output requested as a file called database-name OUTPUT. For example:

SENDBACK INDEX
SENDBACK PRINT SENDER BODY OF 23-26

Format

This command may be used to change the way information about the documents you have selected is displayed to you with the Index command. The Index command will use a default display format unless a new format is defined and specified as an Index parameter. The Format command can alter the selection, placement, length and headings of the fields that will be presented. Once a display format is defined with the Format command, it can be used repeatedly for the duration of the database session. The Format command syntax is:

---

Format  fmt-name:  field1  < field2 >  < ..... >

---

Where fmt-name is the name you have chosen for the format you are about to define. You will use this name as a parameter of the Index when you wish to use it. The format name must be followed by a ':' (colon) character. The field parameters then go on to define the presentation of the information available from a database. Each field consists of a database keyword and a description of how the information from that keyword is to be displayed. See the section DATABASE Keywords for a description of keywords common to all LISTSERV databases and those specific to notebook databases that can be used in the Format command. Each field parameter has the following format:

---

keyword  < (from <,to> ) >< .width <just> >  <"heading" <just> >

---

Here the keyword parameter identifies a database keyword whose information you wish to put in a display field. Immediately following this, you may optionally include the from and to parameters (in parentheses). They control the number and position of the characters passed from the database keyword to the display field you are now defining. For example, you want to define a display field for the database name. This information comes from the DATABASE keyword, however, you only want to use characters 4 to 7 from this keyword. This field definition would then start with DATABASE(4,7). If the name of database is SU-ATOMS, only the ATOM string will then be passed from the keyword to the display field. The default values for from and to are 1 and 255, respectively. Usually, you will not need to use these parameters. Following this is the section defining the width and optional new heading for the display field. It must be be preceded by a '.' (full-stop) character. The width is the number of characters you wish to use for displaying the keyword information for this field. The heading parameter defines a new title for the display field (the default is the name of the keyword being referenced). If a new title is given here, it must be enclosed in double quotes. To continue the above example, you want to display the database name in a field of 4 characters under a heading of "Name". The field definition would now look like: DATABASE(4,7).4 "Name". When the format is used with an Index command, the result would appear as:

Name
----
ATOM

If the information passed from the database keyword to the display field is longer than the width, it will be truncated and a '+' (plus) character appended to the name when it is displayed. This is true for any display field. In the above example, if the field definition was DATABASE.4 "Name" then the result would be:

Name
----
SU-A+

Note that because the from and to parameters were not used in the above example, the full database name was passed from the keyword to the display field. You may also justify information in the display by using the just parameter. The just parameter has the format:

---

L   Left Justified
R   Right Justified
C   Centered
R0  Right Justified with leading zeros

---

For example, you want to define your own display format and include in it the database name and the document number. The database name should be in a field of 8 characters and have the title "DB Names" while the document number, a field of 6 characters and have the title "Doc#". Both of the titles should be centered while the actual database name should be displayed left justified and the document number, right justified and packed with leading zeros. The format definition would look like:

FORMAT MYFMT: DATABASE.8L "DB Names"C #.6R0 "Doc#"C

The DATABASE and # keywords provide the database name and document number information. The result of an Index MYFMT command would be:

DB Names  Doc#
--------  ----
SU-ATOMS 000103
CHEM-L   000089

Note that the R0 justification parameter can be used only for fields that hold numeric information and never for heading definitions.

 

List

This command can be used to display information on the documents you have selected (through a Search command) in a temporary format you define in the List command parameters. It is similar in function to an Index command that is called with the name of a display format you have previously defined in a Format command. However, it differs in the sense that the display format you choose with the List command is temporary and must be redefined every time it is used (the Format command saves the definition under a given name which may be used repeatedly). The List command is most useful for displaying information about selected documents that would not normally be shown with an Index command and without having to first define a whole new display with the Format command. The format of the List command is:

---

List  format

---

Where format can be a series of parameters describing the display fields to be used (identical to those used in the Format command), or the name of a previously defined display format (either one you have given in a Format command or the default display name of INDEX). Alternatively, it can be a combination of the above. This makes the List command very flexible. For example, you have a number of documents selected and now wish to be shown a list of their senders. If the document sender is not given in the default display of the Index command, the following List command will supply this information:

LIST SENDER.10 "Written by"

The senders of all selected documents will be displayed in a field of 10 characters under the title of "Written by". However, only the document senders will be displayed for each selected document, and no other information. You may, at this point, decide to continue defining each consecutive field for the display (as in the Format command) or display the sender information in conjunction with another, already defined, format:

LIST SENDER.10 "Written by" fmt-name

Where fmt-name is the name you have assigned to a display format previously defined with a Format command or is the default name INDEX (which gives the standard information for the type of database you are searching). Using these parameters, the List command will display each document sender followed by the information normally displayed with the fmt-name format.

 

QUIT

This command is used to leave an interactive database session. It has no meaning in a batch database session.