[LISTSERV logo] [Online documentation]

L-Soft international, Inc.
Site Manager's Operations Manual
LISTSERV®, version 1.8c
April 8, 1997
Revision 1

The reference number of this document is 9704-UD-03.

[next chapter] [previous chapter] [table of contents]

Appendix E: LISTSERV Database Functions


The information in  this appendix applies primarily to the  VM version of
LISTSERV.  Certain parts  of  it  (including the  section  on the  SEARCH
command and its various options) may be helpful in dealing with the "new"
database functions available in the non-VM ports of LISTSERV 1.8c. DO NOT
LIST  RESIDES  ON A  VM  SERVER.  This section  will  be  updated as  new
functionality is introduced.

Document number: U01-012-0 (September 3rd, 1988)

Document fileid: "LISTDB MEMO" (from "Info DATABase")

  This chapter is an introduction to the LISTSERV database functions. It
  is  intended  to be a reference document for general users with little
  or no knowledge of database systems.  It does not  contain  any  tech-
  nical  information  that general users do not need to worry about.  In
  particular, the interactive database access protocols  are  not  docu-
  mented  in  this  manual;  they can be found in the "Revised LISTSERV:
  Application Programmer's Guide" , document number A01-004.
This document will discuss the syntax and operational characteristics of 
the LISTSERV database subsystem. It is assumed that the reader is familiar
enough with the the "LISTSERV Command Job Language Interpreter" to build
up a simple job and send it to LISTSERV for execution. A sample job 
"skeleton" is described later on.

Note that all references to LISTSERV's interactive database functions has
been removed, as the number of sites with NJE connectivity required for 
the old LDBASE client is shrinking rapidly and fewer and fewer users are 
actually using LDBASE to search LISTSERV archives.  In any case, LDBASE 
cannot be used with non-NJE-connected hosts.
  * E.1. Introduction *
  The  LISTSERV  database functions have been developed in an attempt to
  make it possible for users to extract relevant information  from  list
  archives  without  having to retrieve a large "notebook" file and scan
  it locally.  Users will send commands to LISTSERV,  requesting  it  to
  perform  search  operations  locally and to send out only the selected
  items from the list archives.  The following goals have been  kept  in
  mind all throughout the development of the new facilities:
  o   The  functionalities  provided must be general enough to allow for
      databases other than list archives (i.e. electronic  mail)  to  be
      used if needed.
  o   Users with little or not database experience must be able to learn
      how to use the LISTSERV database in a few minutes.
  o   The  syntax  should  be as close to "natural english" as possible,
      and should be easy to remember.
  o   The commands must be powerful enough to be  functional,  but  they
      should not be overly complex so as not to discourage beginners.
  o   Interactive  access to the database through the network is primor-
      dial.  Once the search has been carried out, the user should  have
      the option to retrieve the results in a file rather than as inter-
      active output.
  Because  their  main application is the scanning of list archives, the
  LISTSERV database functions are document-oriented and therefore  quite
  different from "usual" commercial database systems.
  E.1.1. Accessing the database
  When accessing the database, you must construct a CJLI job  which  you
  must  then  submit  to  the appropriate  server  for  execution.  This
  means that you must know in advance what you want  to do  exactly.  If
  you  are  not  familiar with CJLI, you can use the following "job 
  skeleton" to build up your database search job:
  | //      JOB  Echo=No                                               |
  | Database Search DD=Rules                                           |
  | //Rules DD   *                                                     |
  | command 1                                                          |
  | command 2                                                          |
  | ...                                                                |
  | /*                                                                 |
  |                                                                    |
  | Figure E.1.  Sample database job skeleton                          |
  You will then receive a "DATABASE OUTPUT" file containing the  results
  of your search.  This file might look like this:
  | > Select * in TEST-L                                               |
  | --> Database TEST-L, 4 hits.                                       |
  |                                                                    |
  | > Index                                                            |
  | Item #   Date   Time  Recs   Subject                               |
  | ------   ----   ----  ----   -------                               |
  | 000001 87/10/18 13:09   12   This is a test looking for upcasing   |
  | 000002 87/08/24 09:18    9                                         |
  | 000003 87/10/18 13:09    8   Test - please acknowledge receipt     |
  | 000004 87/10/18 13:09    7   Does Reply-To=Both work correctly?    |
  |                                                                    |
  | Figure E.2.  Sample  DATABASE  OUTPUT: Each of the commands in the |
  |            original job is  echoed  in  the  output  file  (unless |
  |            specifically disabled).                                 |
  If  you realize that the items you were interested in are number 1 and
  3, you will have to submit a new job to ask for a copy  of  them.
  E.1.2. Organization of the chapter
  The  next section of this chapter will introduce the concepts required
  to understand the LISTSERV database  system.    The  various  database
  commands  will  then  be  explained, starting with the simplest syntax
  forms.  For each command, there will be a  short  tutorial  describing
  the  most  important  forms  of  the  syntax,  followed by a detailed,
  exacting description of the command.  The last chapter  will  describe
  the  more advanced functions like changing the CPU limit, output lines
  limit, etc.
  * E.2. Concepts *
  This chapter introduces the various concepts  required  to  understand
  the LISTSERV database system.
  E.2.1. What is a database?
  A  database is a collection of items of homogeneous type, which can be
  stored in computerized form.  For example, a telephone directory,  the
  archives  of  a  distribution  list,  a  list  of employees can all be
  considered to be databases.  Database items will often be referred  to
  as documents since they will, in most cases, be just that.
  The  actual  "physical"  structure  of  the  database is usually quite
  complex, but it is completely transparent to  the  end-user  who  sees
  only a series of documents.
  Finally, to each database is associated a database type.  Databases of
  the  same  type  can  be  expected to contain roughly the same type of
  documents.  For example, all list archives have  a  database  type  of
  "Notebook".  The user does not have to specifically know the type of a
  database in order to access it.  However, the keywords (see definition
  below) that can be searched will normally depend on the database type.
  For  example,  you can search a list-archives database for a "Subject"
  of "Comments on the minutes of the last meeting", but not for a "Diam-
  eter" of "1/10th" (which might be valid for  a  database  of  electric
  E.2.2. What are the attributes of a document?
  Attributes common to all database types
  Each  document  is  assigned  a  document  number, which is unique all
  throughout the database and can therefore be used to identify it.
  The structure of the LISTSERV database system does not guarantee  that
  document  numbers  will not change from one session to the other.  If,
  for example, a list archive file is  edited  to  add  or  remove  some
  entries,  other documents might be renumbered and assigned a different
  document number.
  In addition, to each document is associated a date/time  field,  whose
  exact  meaning  will  depend  on  the  type of the database.   It will
  usually be either the document creation date or the date of  the  last
  change made to it.
  Other attributes
  Document keywords
  Depending on the type of database, one or more keyword might have been
  defined  for  the  documents.   Each of these keywords is a name/value
  pair, such as "REFCODE 2378237"  or  "SENDER  WIZARD@TOWER.FaerieNet".
  Abbreviations  or  synonyms  might  have  been defined for the keyword
  name.  For example, you might be able to specify "Author"  instead  of
  "Sender" when performing a search operation.
  Document portions
  In any case, these "keywords" contain information which is external to
  the  document,  in  much  the  same  way  as a label sticked on a book
  contains information (e.g. the price of  the  book)  which  cannot  be
  found inside the book itself.
  A  document  portions,  on  the  contrary,  is a name that refers to a
  subset of the contents of the documents, like "Foreword" or "Epilogue"
  in our book example above.   There is  a  built-in  document  portion,
  "ALL"  ,  which is common to all the database types and corresponds to
  the complete document.
  E.2.3. What are the attributes of NOTEBOOK databases?
  The following "keywords" are  available  for  list-archives  databases
  (shortest abbreviation is Capitalized):
  o   Subject corresponds to the contents of the "Subject:" field of the
      mail header (case is preserved).
  o   SEnder  or  From  identify the RFC822 address of the originator of
      the mailfile (case is preserved).  You should note that "FROM" may
      be a reserved database keyword, depending on the context in  which
      it  appears.  You should therefore avoid to refer to the mail-ori-
      ginator keyword as "FROM", unless you use an abbreviated form.
  The following "document portions" have been defined for  list-archives
  databases (shortest abbreviation is Capitalized):
  o   Header and HDR both identify the RFC822 header of the mailfile.
  o   Body  and  Text  correspond  to the contents of the mailfile, i.e.
      anything which appears after the header.
  o   And of course, ALL corresponds to the  complete  mailfile,  header
      and body.
  E.2.4. What is a hit?
  Before  you  are  able to display anything, you will have to perform a
  search on the database (if you have nothing to search  in  particular,
  there  is  a  special form of the search command which lets you select
  all the items from the database).  You will specify a series of search
  rules, which will be applied to all  the  documents  in  the  selected
  database.    Each document that matches these search rules is called a
  hit and is considered to have been selected  for  further  processing.
  Most  database  commands will, by default, be applied to all the docu-
  ments that have been "hit" in the  last  search  you  have  performed.
  This  means  that if your previous search did not yield any "hit", you
  will not be able  to  do  anything  until  you  issue  another  search
  E.2.5. How can I get a list of existing databases?
  Although  there is no global list of all the available databases, each
  LISTSERV can send you a list of all the databases that it keeps.    If
  you  are not allowed to access a given database, it will (usually) not
  be listed so that you do not waste your time trying to search it.   To
  get  this  list,  simply  send  a DATABASE LIST command to the desired
  | Database  Description                                              |
  | --------  -----------                                              |
  | APPPRG-L  Archives of "ADMCSC Application Programmers list"        |
  | BITEARN   Information on all the BITNET/EARN/NetNorth nodes        |
  | LISTS     Information on all the network-wide LISTSERV lists       |
  | MANUALS   Information about IBM manuals in the ADMCSC library      |
  | PEERS     Information on all the LISTSERV servers in the network   |
  | SYSPRG-L  Archives of "ADMCSC Systems Programmers list"            |
  | SUPPORT   LISTSERV software support database                       |
  |                                                                    |
  | Figure E.3.  Sample DATABASE LIST command                          |
  * E.3. The SEARCH command *
  This chapter will introduce you to the SEARCH command.   This  minimum
  abbreviation  of  this  command  is  just "S", and there also exists a
  synonym of SELECT with a minimum abbreviation of "SEL".
  The syntax of this command is a bit complex, and  will  be  introduced
  step by step.
  E.3.1. Basic search functions
  The  two  most important things you have to indicate when you search a
  database are:
  1.  The name of the database you want to search.
  2.  What you want to search the individual documents for.
  The name of the database to be searched is specified after  the  words
  or  phrases  to  be  sought  and  is prefixed with an IN keyword.  For
  example, we might do this:
                        Search Rosemary in MOVIES
  This would select all the entries from  database  "MOVIES"  containing
  the string "ROSEMARY".
  Now  if  you just wanted to see the list of all the movies you can see
  this week, you could have used  an  asterisk  as  search  argument  to
  select all the entries in the database:
                            Search * in MOVIES
  Note  that  the  database name doesn't have to be uppercased.  This is
  merely done to make the examples look better.
  If you want to "narrow" your previous search, i.e. perform  additional
  tests  on  the  documents that have been previously selected, you must
  omit the IN keyword.  In that case, the search will be applied to  the
  previous "hits" and will create a new "hit list".
  But  in  most  cases, we will want to search for something longer than
  one word, for example part of a "key" sentence.
             Search Hardware problem with a 4381 in IBMFORUM
  Another problem is that we  might  not  remember  the  exact  original
  This is not very important, since LISTSERV will search each word indi-
  vidually:    in  the above example, any entry that contained the words
  "hardware", "problem", "with", "a" and "4381" would have  matched  the
  search, even if the words appeared in a different order.
  But  what  if  the  original  document had "4381-13" in it, instead of
  This is again no problem, as LISTSERV does not require the word to  be
  surrounded  by  blanks  to  find  a match.   Case is also ignored when
  performing the search operation.  That is, "problem" would have  found
  a  match  on  "problems"...    and  "with" would have found a match on
  "without" or "withstand"!  This may sound like inconsistent behaviour,
  but you should keep in mind that it  is  always  possible  to  "narrow
  down"  a search operation.  However, once a document has been excluded
  from the list of "hits", it is very difficult to bring it back.
  Now what if I want to search for an exact string?  For example,  I  am
  interested  in  the  string  "in C".   It is very likely that just any
  document in the database will contain both a "in" and  the  letter  C.
  But  what  I  am  interested  in is things which have been written, or
  programmed, or implemented, "in C".
  In that case, it is possible to force LISTSERV to group words together
  by quoting them, as in:
                         Search 'in C' in UTILITY
  This method can also be used to insert extra blanks between or  before
  words:    leading  and  trailing  blanks are normally removed automat-
  ically, but they are preserved inside quoted  strings.    Please  note
  that  quotes  must be doubled when specified inside quoted strings, as
                   Search 'Rosemary''s baby' in MOVIES
  The search for 'in C' resulted in over fifty hits, because a match was
  erroneously found against "in clear", "in core", etc.   However, I  do
  not  want  to  search for 'in C ' because there might be hits with "in
  C." or "in C," in the database and I don't want to miss them.
  If the search respected the capital C, it would  no  longer  find  all
  those  irrelevant  hits.    To  do  this, you must enclose your search
  string in double-quotes instead of single quotes, for example:
                         Search "in C" in UTILITY
  Note that single quotes should not  be  doubled  inside  double-quoted
  strings, and vice-versa.  Only quotes of the same type than the string
  should be doubled.
  It  is important to understand the difference between the two types of
  quoting.  If you request a search for 'TEXT', you will find a match on
  "TEXT", "Text", "text" or even "teXt".  This is the same behaviour  as
  unquoted  text.   However, if you request a search for "TEXT", it will
  only find a match on "TEXT", not on "text" nor "Text".

  Quoting is also the only way to search for  a  reserved  keyword  like
  "IN":  if you tried "Search in in UTILITY", LISTSERV would report that
  database  "IN"  does  not exist and would reject the command.  This is
  because the keyword IN indicates the end of your search arguments.  If
  you quote it, however, it will not be recognized and will be  searched
  as  you  wanted  it  done.    Similarly,  if you want to search for an
  asterisk, you will have to quote it since "Search  *"  indicates  that
  all entries should be selected.
  Now the problem is that there may be sentences starting with a capital
  I,  e.g.  "In  C, it would be coded this way:".  How can I catch these
  Actually, you have been using "complex search  expressions"  from  the
  beginning without even being aware of it.  When you specified a search
  on  "Hardware  problem with a 4381", you had in fact been asking LIST-
  SERV for:  "Hardware AND problem AND with AND a AND 4381".  The  "AND"
  is implicit, but it may be overriden.  You may even use parenthesis if
             Search ("in C" or "In C") and program in UTILITY
  The "AND" can still be implied, as in:
  | Search wooden chair (blue or green) in CHAIRS                      |
  | Search (wooden chair) or (plastic chair) in CHAIRS                 |
  | Search plastic chair (blue or green but not streaked) in CHAIRS    |
  |                                                                    |
  | The following commands are strictly equivalent:                    |
  |  Search (wooden chair) or (plastic chair not blue) in CHAIRS       |
  |  Search chair (wooden or (plastic not blue)) in CHAIRS             |
  |  Search chair (wooden or (plastic but not blue)) in CHAIRS         |
  |  Search chair AND (wooden OR (plastic AND NOT blue)) in CHAIRS     |
  |                                                                    |
  | Figure E.4.  Sample SEARCH commands  using complex document search |
  |            arguments                                               |
  E.3.2. Date specifications
  Since each document has been  assigned  a  "date/time"  field,  it  is
  possible to select documents based on this date field.  This is accom-
  plished  by appending "date search rules" to the search expression, as
  | Search problem (serious or severe) in BBOARD since july            |
  | Search problem in BBOARD since oct 85                              |
  | Search symptom in BBOARD since 12/28                               |
  | Search error report from 12 january to august in BBOARD            |
  | Search user complaint until 18 sept in BBOARD                      |
  | Search data check since today 11:53 in EREP                        |
  |                                                                    |
  | Figure E.5.  Sample SEARCH commands using date search arguments    |
  The default values for omitted arguments are always chosen  so  as  to
  exclude as little entries as possible.  For example, "July" would mean
  "1  July 00:00:00" in a SINCE specification, and "31 July 23:59:59" in
  an UNTIL clause.  The only exception is the year field,  which  always
  defaults to the current year.
  E.3.3. Keyword search specifications
  The  last  thing  you  may wish to search is the "keywords" list.  For
  example, you might want to select those plastic chairs which cost less
  than 50 dollars.  It is assumed that the price will vary often  (maybe
  almost daily), and that it is therefore kept externally from the docu-
  ment  describing  the  chair.   Thus, you would have a "Price" keyword
  which you could search in the following way:
             Search plastic chair in CHAIRS where price < 50
  You may of course use complex expressions (with  parenthesis)  in  the
  WHERE  clause.   There are new comparison operators available for this
  clause, like IS, CONTAINS, all the usual arithmetical comparison oper-
  ators, and some more.    However,  the  AND  operation  is  no  longer
  implied, but it can still be specified explicitly of course:
       Search plastic chair in CHAIR where price < 50 and avail > 4
  The  problem  now is that, as the search commands become more and more
  complex, they will no longer fit in a single  line.    To  solve  this
  problem,  it  has  been  decided that any database command ending in a
  dash indicates that more is to follow on the next line.  This  process
  can be repeated several times if desired.  
  | Search chair (wooden or (blue or green but not streaked)) -        |
  |        in CHAIRS -                                                 |
  |        where price < 50 & avail > 4                                |
  |                                                                    |
  | Search chair (wooden or (blue or green but not streaked)) -        |
  | in CHAIRS where price < 50 & avail > 4                             |
  |                                                                    |
  | Search chair (wooden or ( -                                        |
  | blue or green but not streaked) -                                  |
  | ) -                                                                |
  | in CHAIRS where price < 50 & avail > 4                             |
  |                                                                    |
  | Figure E.6. Sample SEARCH  commands  with continuation lines:  All |
  |            these commands are  strictly  identical,  although  the |
  |            first one is obviously more legible.                    |
  The  only  "trick"  about  this continuation line business is that you
  should always keep quoted strings on a single line.   The  process  of
  identifying  continuation  lines and concatenating them afterwards may
  cause unwanted blanks to be inserted in the command line, which is  no
  problem  outside  a  quoted string since blanks are ignored, but might
  cause erroneous results in a quoted string.
  If you want to search for several possible values in a given  keyword,
  you do not have to repeat the keyword name and operator:
  | > Search * in BBOARD where -                                       |
  | > subject contains (PC or (Personal and computer))                 |
  |                                                                    |
  | is strictly equivalent to:                                         |
  |                                                                    |
  | > Search * in BBOARD where -                                       |
  | > subject contains PC or -                                         |
  | > (subject contains Personal and subject contains computer)        |
  |                                                                    |
  | Figure E.7.  Sample use of "factorization"                         |
  However,  it  should  be  noted that this "factorization" is performed
  according to the rules of logic, which may not necessarily match those
  of english grammar.  This removes any possible  ambiguity  as  to  the
  meaning of these clauses.  Let's consider the following example:
                  machine does not contain (IBM and DEC)
  This clause will get translated into:
      machine does not contain IBM and machine does not contain DEC
  In  english  you  would probably say "machine contains neither IBM nor
  DEC" .  This is how LISTSERV will understand it.  However, if you read
  the clause aloud, you will probably not pronounce the parenthesis  and
  will  end  up  saying "machine does not contain IBM and DEC", in other
  words, "machine does not contain both  IBM  and  DEC"  ,  which  is  a
  totally  different  thing  (and  would  most  probably be true all the
  time).  The "english meaning" could be  obtained  with  the  following
                   not (machine contains (IBM and DEC))
  In  the  former  case,  the  negative  "does  not contain" operator is
  inserted inside the parenthesis.  In the latter,  only  "contains"  is
  moved, and the negation remains outside.
  | > Search gateway problem -                                         |
  | > in BBOARD -                                                      |
  | > since sept 86 -                                                  |
  | > where sender contains (john or paul but not mick) -              |
  | > and subject does not contain lost                                |
  | --> Database BBOARD, 5 hits.                                       |
  |                                                                    |
  | > Index                                                            |
  | Item #   Date   Time  Recs   Subject                               |
  | ------   ----   ----  ----   -------                               |
  | 000012 87/10/18 13:09   12   The gateway has stopped working       |
  | 000017 87/08/24 09:18    9   Glory glory alleluja! Again!!!        |
  | 000018 87/10/18 13:09    8   You know what? It WORKS!!!            |
  | 000024 87/10/18 13:09    7   Guess what happened today?            |
  | 000205 87/10/04 16:59    9   Who's going to babysit it today?      |
  |                                                                    |
  |                                                                    |
  | You  might now wish to narrow your search down to exclude postings |
  | whose subject contains "work".  You can do this  by  specifying  a |
  | new WHERE clause with no associated IN.                            |
  |                                                                    |
  | > Search * where subject does not contain work                     |
  | --> Database BBOARD, 3 hits.                                       |
  |                                                                    |
  | > Index                                                            |
  | Item #   Date   Time  Recs   Subject                               |
  | ------   ----   ----  ----   -------                               |
  | 000017 87/08/24 09:18    9   Glory glory alleluja! Again!!!        |
  | 000024 87/10/18 13:09    7   Guess what happened today?            |
  | 000205 87/10/04 16:59    9   Who's going to babysit it today?      |
  |                                                                    |
  | Figure E.8.  Sample SEARCH commands with keyword search clauses    |
  Finally,  the  reason why the database name appears in each reply from
  LISTSERV is that you can specify several database in the IN clause:
  | > Search user complaint in BBOARD1 BBOARD2 -                       |
  | > since august -                                                   |
  | > where sender is charles                                          |
  | --> Database BBOARD1, 2 hits.                                      |
  | --> Database BBOARD2, 8 hits.                                      |
  |                                                                    |
  |                                                                    |
  | Figure E.9.  Sample SEARCH commands involving several databases    |
  Phonetic search
  There may be cases where you are looking for  a  certain  value  of  a
  keyword,  the  exact  spelling of which you cannot remember.  In these
  cases, it may be useful to try a phonetic search.   A phonetic  search
  will yield a match for anything that "sounds like" your search string,
  as  dictated by a predefined algorithm which is of course not perfect.
  It may give a hit for something which does  not  actually  sound  like
  your  search  string,  or, more rarely, omit a keyword which did sound
  like what you entered.  The main reasons for this are that  the  algo-
  rithm  must  be  fast  to execute on the machine and therefore not too
  sophisticated, and that the way a given word is pronounced depends  on
  the  idiom in which the word was written.  For example, the phonetical
  transcription of the  name  "Landau"  will  be  different  in  French,
  English, German and Russian.  Thus, it is impossible to decide whether
  a  word  sounds  like  another  if the language in which the words are
  pronounced is not known (and of  course  LISTSERV  does  not  have,  a
  priori, any way to know it).
  Phonetic searches are performed through the use of the SOUNDS LIKE and
  DOES  NOT  SOUND  LIKE  operators,  which are syntactically similar to
  CONTAINS and DOES NOT CONTAIN.  That is, you could do something like:
            Select * in PHONEBOOK where NAME sounds like WOLF
  There is a little trick with the SOUNDS LIKE operator that you  should
  be  aware of.   If your search string (WOLF in our above example) is a
  single word, it will be compared individually to all the words in  the
  reference  string  (i.e.  the  data  from  the  database), and will be
  considered a hit if it "sounds like" any of the words in the reference
  string.   Thus, the search word  "Ekohl"  sounds  like  the  reference
  string  "Ecole  Normale Superieure" because it matches the first word.
  If the search string contains more  than  one  word,  the  search  and
  reference strings will be compared phonetically as a whole (and "Ekohl
  Dzentrahll"  will  therefore  not  match  "Ecole Normale Superieure").
  Note that any search string containing more than a single word must be
  quoted, as explained in the previous sections of this chapter.
  | > Select * in BITEARN where site sounds like (COHRNEAL and LAPORRAD|
  | RY)                                                                |
  | --> Database BITEARN, 3 hits.                                      |
  |                                                                    |
  | > Index                                                            |
  | Ref# Conn  Nodeid   Site name                                      |
  | ---- ----  ------   ---------                                      |
  | 0292 87/03 CRNLASSP Cornell University Cornell Laboratory of Atomic|
  | 0301 87/03 CRNLION  Cornell University Cornell Laboratory of Plasma|
  | 0307 87/06 CRNLNUC  Cornell University Laboratory of Nuclear Studes|
  |                                                                    |
  | > Select * in BITEARN where SITE sounds like HOPTIKK               |
  | --> Database BITEARN, 2 hits.                                      |
  |                                                                    |
  | > Index                                                            |
  | Ref# Conn  Nodeid   Site name                                      |
  | ---- ----  ------   ---------                                      |
  | 0751 87/09 FRIHAP31 Assistance Publique - Hopitaux de Paris        |
  | 2120 87/04 UOROPT   University of Rochester The Institute of Optics|
  |                                                                    |
  | > Select * in BITEARN where SITE sounds like SCHIKAGO              |
  | --> Database BITEARN, 1 hit.                                       |
  |                                                                    |
  | > Index                                                            |
  | Ref# Conn  Nodeid   Site name                                      |
  | ---- ----  ------   ---------                                      |
  | 0140 86/03 BMLSCK11 Studiecentrum voor Kernenergie (SCK/CEN), Mol, |
  |                                                                    |
  | Figure E.10. Sample SEARCH commands involving phonetic match:  The |
  |             first  command  shows  an example of accurate phonetic |
  |             match, where the  result  is  exactly  what  the  user |
  |             expected.   In the second example, the user found what |
  |             he was  looking  for  ("Optics"),  but  an  additional |
  |             unwanted  entry was selected.  This is by far the most |
  |             common case.  The last command is a typical example of |
  |             phonetic clash, where the algorithm did not  translate |
  |             the  search string into phonetics as the user expected |
  |             it, with the result that the desired name  ("Chicago") |
  |             was  not  found and that completely irrelevant entries |
  |             were presented instead.                                |
  The phonetic matching algorithm used by LISTSERV is a  slightly  modi-
  fied  version  of  SOUNDEX  --  a  well-known  algorithm that provides
  reasonably accurate matches at a very low CPU cost.  Although it gives
  best results with the English language, for which  it  was  originally
  designed, it is not too strongly tied to it and can still be used with
  other  languages.    It is of course absolutely impossible to write an
  program that would work for all the languages in the  world,  or  even
  for  the most widley used ones, since their interpretation of the most
  common combinations of letters are completely incompatible.
  E.3.5 Exact syntax description
  This section describes the exact syntax of  the  "SEARCH"  command  in
  technical  terms.    You  can  skip  it  if  you are not interested in
  learning about the details of this command.
  General syntax
  |        |                                                           |
  | Search |  search-rules                             |
  | SELect |                                                           |
  |        |                                                           |
  |        |  Optional rules are:                                      |
  |        |                                                           |
  |        |    date-rules                                             |
  |        |    keyword-rules                                          |
  |        |    db-list                                                |
  The optional "date-rules", "keyword-rules" and "db-list" arguments may
  appear in any order.
  Database list specification
  For each SEARCH command, you may specify a list  of  databases  to  be
  searched.  The default is to narrow the search, i.e. to use the result
  of the previous search as input for the new search.  This is of course
  possible only if the previous search yielded one or more "hits".
  The syntax of the "db-list" specification is the following:
               db-list:  IN <(> dbspec1 > <)>
  The parenthesis are optional.  If they are omitted, database names may
  not be reserved keywords like SINCE or WHERE.
  Finally, the syntax of "dbspec" is the following:
           db-spec:  db-name<.<(>range1<,><...>><)>>
  where  "db-name"  is  the  name  of  the  database to be searched, and
  "ranges" 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 may be either enclosed in parenthesis and separated by blanks, or
  separated by commas, in which case the parenthesis are optional.
  | IN (BBOARD1 BBOARD2)                                               |
  | IN BBOARD1.12-40 BBOARD2 MGMT.(30-35 200-)                         |
  | IN REXXBB.200-,12-13 VMSTAFF.(61 80-100 12)                        |
  |                                                                    |
  | Figure E.11.  Sample IN clauses                                      |
  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
  different ways date/time specifications are usually expressed:
    dd mm
<->monthname<-> mm/yy mm-yy yy/mm/dd yy-mm-dd Month names can be abbreviated to any length. If there is an ambi- guity, the first month in chronological order is retained. For example, "J" would mean "January", "JU" would be "June" and "JUL" would unambiguously select "July". The format of a "time-spec" is simply >. +--------------------------------------------------------------------+ | FROM 14 july TO oct 87 | | SINCE 86 | | UNTIL 23-JUN-87 | | SINCE today 11:30 | | | | Figure E.12. Sample date clauses | +--------------------------------------------------------------------+ NOTE: Case is irrelevant in date specifications. The keywords (SINCE, UNTIL, etc) have been capitalized only for better legibility, and can be entered in lower case if desired. Keyword rules specification You may request the actual document search to take place only for those entries which match a set of "keyword comparison" rules. The syntax is the following: WHERE kwd-expression WITH "kwd-expression" is, generally speaking, an mathematical expression of keyword/value comparisons, possibly bound by logical operators. Comparison operators have a higher precedence than logical operators, that is, "A>10 AND B=20" is interpreted as "(A>10) AND (B=20)". The available comparison operators are listed below. All the operators appearing on a given line are synonyms. +--------------------------------------------------------------------+ | = IS | | ^= <> IS NOT | | > | | < | | >= | | <= | | CONTAINS | | DOES NOT CONTAIN | | SOUNDS LIKE | | DOES NOT SOUND LIKE | | | | Figure E.13. Comparison operators for WHERE clauses | +--------------------------------------------------------------------+ All these operators are self-explanatory, except the last two which allow you to search the keyword value for a given "substring". That is, "Sender contains jeff" would be true if the value of the "Sender" keyword was "Jeff Smith" or "Jeffrey Donaldson". The case is ignored during the comparison unless the search operand is double-quoted. If no valid comparison operator is specified between two arguments, "IS" (identity) is assumed. The available logical operators are: +--------------------------------------------------------------------+ | ^ NOT | | & AND BUT | | | / OR | | | | Figure E.14. Logical (boolean) operators | +--------------------------------------------------------------------+ Finally, keywords and operators can be "factorized" when the same comparison is to be applied to a given keyword and a series of compa- rands. For example, you might enter: Search * where sender contains ('CS Dept' and (Jack or Phil)) This is internally expanded to: SEARCH * WHERE sender CONTAINS 'CS Dept' AND - (sender CONTAINS Jack OR sender CONTAINS Phil) Please note that the expression must always be enclosed in paren- thesis, even if it is a simple one: Search * where sender contains (Joe or Morris) This stems from the fact that comparison operators have a higher priority than logical (boolean) ones. +--------------------------------------------------------------------+ | WHERE Sender is "Arthur Dent" - | | and Subject does not contain tea | | | | WITH Refcode 8467272 and Location Roubaix | | | | WITH (QTY > 100 | PRICE > 1000) & MAT = COPPER | | | | Where Sender is (Atiaran@Land or Elena@Land) - | | and Subject contains ('Be true' but not Ur-Lord) | | | | Figure E.15. Sample WHERE clauses | +--------------------------------------------------------------------+ 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 (e.g. if you are only selecting known items from the database), you can specify an asterisk as a placeholder to waive the search. Otherwise you must specify a mathematical expression where arguments are search strings, possibly bound by logical operators (see Figure 14for a comprehensive 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 (not necessarily in the same line). +--------------------------------------------------------------------+ | Search * | | | | Search 'I/O' Error | | | | Select Interpret (performance or tips - | | but not (bug or question)) | | | | Figure E.16. Sample document-search clauses | +--------------------------------------------------------------------+ Reserved words and quoting When to quote strings Keyword names and search arguments need not be quoted, unless: o They are formed of more than one word (search arguments only). o They contain leading or trailing blanks (search arguments only). o Their name matches one of the "reserved keywords" of the LISTSERV database system, and appears in a context where it can be mistaken for such. The "reserved keywords" are: FROM, IN, SINCE, TO, UNTIL, WHERE, WITH. o They contain a parenthesis, logical operator or comparison oper- ator symbol. More generally, you should quote any string that contains one of the following characters: ( ) < > = | & ^ / Any non-quoted word will be stripped of leading and trailing blanks and converted to uppercase before the search. Single-quoted strings Strings quoted in single-quotes (') are converted to upper case and cause case to be ignored during the search. That is, they behave in the same manner as un-quoted strings as far as the search algorithm is concerned. As a rule of thumb, any string can be single-quoted if desired, even if it does not have to. Single quotes must be doubled inside single-quoted strings, but double quotes should not: Search '"T''amo, ripetilo, si caro accento' in OPERA Double-quoted strings Strings quoted in double-quotes (") are not converted to upper case. They result in a case-sensitive search, which means that you should never double-quote a string unless you want case to be respected during the search. Double quotes must be doubled inside double-quoted strings, but single quotes should not: Search """T'amo, ripetilo, si caro accento" in OPERA ************************** * E.4. The INDEX command * ************************** If you have understood everything in the previous chapter, you will have no problem with this one, nor with the following. The SEARCH command is by far the most complex database command you will have to use, and you will find INDEX and PRINT to be quite simplistic as compared to it. E.4.1. Introduction ------------------- The INDEX command can be used to display a list of all the "hits" that your last search resulted in. For each such "hit", a single line of information will be displayed. This information will depend on the type of the database you were searching of course, but it will typi- cally contain the following columns: o Item number and possibly name of the database, although the latter is often suppressed to make room for more useful information. o Date and time the item was created or last modified (the exact meaning depends on the database type). o Number of records or, more generally speaking, some indication on the size of the document. o Any other information relevant to the type of database you are searching. To each database type is associated a unique, predefined index format. You will learn later how to define your own "formats" to produce customized index displays. This knowledge is not necessary to perform normal searches on the database. E.4.2. Syntax ------------- The syntax of the INDEX command is simply INDEX with no argument (minimum abbreviation is "I"). You will learn later that this is a lie, and that you can specify a flurry of horrendous parameters on the INDEX command, but for now you are better off without this knowledge. So, let's the syntax be simply INDEX for now. E.4.3. Examples --------------- Since the index format is the same for all databases of the same type, we will simply give an example of "Notebook" index, and another example for a fancy database type of "Opera" which we will use exten- sively in the following chapters. +--------------------------------------------------------------------+ | > Select * IN EARNTECH where Sender contains HEARN | | --> Database EARNTECH, 6 hits. | | | | > Index | | Item # Date Time Recs Subject | | ------ ---- ---- ---- ------- | | 000013 87/06/20 13:04 13 Re: Prior 1 files from mailers | | 000046 87/07/09 11:32 10 phone number change | | 000079 87/07/28 15:30 17 Re: HW/SW at nodes | | 000172 87/10/07 10:02 16 portugal meeting ? | | 000173 87/10/12 08:58 16 again errors in xmailer names | | 000187 87/10/15 10:06 18 SNA - VTAM help needed. | | | | Figure E.17. Sample INDEX for a "Notebook" database | +--------------------------------------------------------------------+ We will assume that the "Opera" database type is designed to process opera libretti, and defines the following keywords and document portions: AUTHOR The name of the composer (keyword). FROM The name of the opera from which the tune is extracted (keyword). SINGERS The name of the singers in "my own official preferred best record" (keyword). NAME The "name" generally given to the tune (keyword). TUNE A few lines out of the text, which are supposed to help the reader remember what it is exactly (portion). CHARACTERS The name of the character(s) singing the tune (portion). We could then have an index looking like this: +--------------------------------------------------------------------+ | > Select felice IN OPERA.250- where Singer is Bergonzi | | --> Database OPERA, 2 hits. | | | | > Index | | Item # From Singer Recs Name | | ------ ---- ------ ---- ---- | | 000254 Rigoletto Bergonzi 27 La donna e mobile | | 000259 La Traviata Bergonzi 34 Di quell'amor che palpito | | | | Figure E.18. Sample INDEX for a (fancy) Opera database | +--------------------------------------------------------------------+ ************************** * E.5. The PRINT command * ************************** E.5.1. Tutorial --------------- The PRINT command (minimum abbreviation "P") can be used to display the contents of documents which have been previously selected. Where INDEX displayed only one line of information, PRINT will typically display one or more pages. You should therefore be careful to not PRINT documents that you are not interested in, as this may generate a lot of unwanted output. The PRINT command will, by default, apply to any and all selected documents. That is, it is assumed that everything you have selected is of interest to you. It is also assumed that, by default, you want the entire contents of the selected documents printed out (which will usually be the case anyway). You can, however, request only specific document portions to be printed. This is done by listing the name of the "portions" after the PRINT command, as in: Print Characters Tune A separator will be printed between each document portion (see exam- ples below). You can also request to print only specific documents among the ones that have been selected. To do this, simply specify the document numbers after the PRINT keyword. If you also wish to specify portion names, these must appear before the document numbers and may optionally be followed by an OF keyword: Print Tune OF 127 232 841 For your convenience, it has also been made possible to PRINT the contents of keywords associated with the selected documents. This will cause each keyword value to be displayed as if it were a one-line document portion. The output therefore takes three lines per entry (separator, keyword value and one blank line), and the INDEX command should obviously be preferred. However, there may be cases where you want to display the value of a particular keyword in a particular entry, which was not listed in the index because there is usually not enough room to display all keywords in a single 80-characters line: Print Author OF 254 You could also get this information through the use of the "LIST" command, which will be explained later on. However, this command would produce an output similar to the index, with one line per selected entry. This would most likely be longer than the PRINT output if you were interested in a few entries only. Finally, you can indicate several print specifications on a single PRINT command by separating them with commas: Print Author of 254, Tune of 220 226-230 E.5.2. Examples --------------- In the examples that will follow, we will assume that the following search has been executed prior to issuing the PRINT command: +--------------------------------------------------------------------+ | > Select fleur or diletto or belleza IN OPERA.100-150 - | | > where singer is not Domingo | | --> Database OPERA, 5 hits. | | | | > Index | | Item # From Singer Recs Name | | ------ ---- ------ ---- ---- | | 000103 Carmen Carreras 41 La fleur que tu m'avais jete| | 000118 Don Giovanni Sciepi 23 La ci darem la mano | | 000121 Rigoletto Fisher-Die+ 37 Veglia o donna | | 000127 Aida Moll 25 Mortal, diletto ai Numi | | 000142 La Traviata Bergonzi 52 Brindisi | | | | Figure E.19. Search/Index upon which the sample PRINT commands are | | based | +--------------------------------------------------------------------+ The meaning of the "+" sign appearing after the truncated "Fisher- Dieskau" will be explained later. Let's first see what happens when you print document portions. To avoid making the example too long, we will print only the "Tune" portion which is not very large. +--------------------------------------------------------------------+ | > Print Tune | | >>> Item number 103, dated 87/10/18 13:09:30 -- TUNE | | La fleur que tu m'avais jetee | | Dans ma prison m'etait restee | | | | >>> Item number 118, dated 87/10/18 16:29:12 -- TUNE | | La ci darem la mano, | | La mi dirai di si... | | Vedi non e lontano, | | Partiam ben mio da qui. | | | | >>> Item number 121, dated 87/08/15 09:23:45 -- TUNE | | Ah, veglia o donna questo fior | | Che a te puro confidai | | | | >>> Item number 127, dated 87/02/12 19:26:02 -- TUNE | | Mortal, diletto ai Numi | | A te fidate son d'Egitto le sorti | | | | >>> Item number 142, dated 87/11/29 13:52:10 -- TUNE | | Libiamo, libiamo nell' lieti calici | | Che la belleza infiora | | | | Figure E.20. Sample PRINT of a document portion | +--------------------------------------------------------------------+ The name of the singer of "Veglia o donna" has been truncated in the INDEX output, and you would like to see it in full, as well as the name of the character singing the tune. You also don't remember who is the author of "Carmen", and you would like it printed. Finally, you would like to print the whole of tune number 127. +--------------------------------------------------------------------+ | > Print singer character of 121, author of 103, all of 127 | | >>> Item number 121, dated 87/08/15 09:23:45 -- SINGER | | Fisher-Dieskau, Dietrich | | | | >>> Item number 121, dated 87/08/15 09:23:45 -- CHARACTERS | | Rigoletto | | | | >>> Item number 103, dated 87/10/18 13:09:30 -- AUTHOR | | Georges Bizet | | | | >>> Item number 127, dated 87/02/12 19:26:02 -- ALL | | Ramfis (a Radames) | | | | Mortal, diletto ai Numi | | A te fidate son d'Egitto le sorti | | Il sacro brando dal Dio temprato | | Per tua man diventi ai nemici | | Terror, Folgore, Morte! | | | | Figure E.21. Sample PRINT of both document keywords and portions | +--------------------------------------------------------------------+ E.5.3. Syntax ------------- This section will describe the exact syntax of the PRINT command. You may skip it if you are not interested in details. The syntax of the PRINT command is: +--------------------------------------------------------------------+ | Print <,print-spec2<,...>> | | | | Each "print-spec" | | has the following form: | | >> >> | | | | Figure E.22. Syntax of the PRINT command | +--------------------------------------------------------------------+ Each "part" must be a valid "document portion" or "keyword" for the database against which the PRINT command is being 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 previ- ously selected by means of a SEARCH command. Finally, you may place more than one set of print specifications on the command line, provided you separate them with commas. *************************** * E.6. The FORMAT command * *************************** The next two chapters will deal with the definition of "index formats", which allow you to view indexes different from the default ones. You may wish to skip them if you are not interested in details. You should now know enough about the database commands to be able to perform most kind of searches. E.6.1. Introduction ------------------- The FORMAT command lets you define a named index format. An "index format" is a series of specifications which define one or more columns of output. For each column, you must specify the name of the keyword which is to be listed, along with some information like the number of characters (width) of the column, whether it must be left-justified, right-justified or centered, and optionally a title for the column. The default title is the (upper case) name of the keyword associated with the column. Please note that the FORMAT command itself does not cause any informa- tion to be displayed. This is done by the LIST command, which will be explained in the next chapter. E.6.2. Syntax ------------- The exact syntax of the FORMAT command (minimum abbreviation "F") is: +--------------------------------------------------------------------+ | Format fmtname<:> fmtspec1 > | | | | Each "fmtspec" defines a column in the output chart, using the | | following syntax: | | | | fieldname<(<,end>)><. cols> <"heading"> | | | | Figure E.24. Syntax of the FORMAT command | +--------------------------------------------------------------------+ This will create a column in the table, under the specified heading, where a substring (start,end) of the specified keyword (fieldname) will be displayed. The default values for start and end are 1 and 255, respectively. The width of the column 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, whilst the header is justified as indicated by hd-just. Both justification parameters default to L, but can be any of the following: +--------------------------------------------------------------------+ | 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. | | | | Figure E.25.Justification keywords for use with the FORMAT command | +--------------------------------------------------------------------+ If the data does not fit entirely in the column space you have provided ("cols" parameter), i.e. if characters other than blanks (or leading zeroes for numeric fields) had to be removed in order for the keyword substring to fit into the column, a "+" sign will be placed in the following inter-column gap. This merely informs you that more data is available, but could not be displayed with the format you specified. It is also possible to specify a previously defined format name in lieu of column definition. This will insert the complete format spec- ification that had been recorded when the format was defined. Each "fieldname" must be a valid "keyword" name for the database against which the format will be used. No verification is made during the definition of the format. 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 | | | | Figure E.26. Reserved keywords for use with the FORMAT command | +--------------------------------------------------------------------+ E.6.3. Example -------------- We will assume that you want to create a new index format for the "Opera" database, because you are not satisfied with the default one. You would want to see the name of the character singing the tune, not the "Singer" name which is what the person who keyed-in the database entries considers to be the best singer for the tune -- something which you might not agree about and don't want to see in the index. You also want to reduces the "Recs" column to 2 characters, since tunes are rarely longer than 99 lines. Finally, you want to change the heading of the "For" column to say "Excerpted from". The first thing to do is to prepare the "Item #" column, which you don't want to change. The "keyword" associated with the item number is #, the contents are numeric, must be right-justified with leading zeroes and there are 6 characters. Just to practise, we will change the header to "Nb" instead of "Item #", and will cause it to be centered in the column. The resulting specification is: #.6R0 "Nb"c For the second column, we only want to change the title. There were 13 characters displayed, left-justified (which is the default) and the title must now be "Excerpted from". Since the title is 14 characters long, we will make the field 14 characters long too: From.14 "Excerpted from" The "Recs" column must be shortened to 2 characters. The title must therefore be shortened too, and we will use "Sz". This is numeric data, so we want it right-justified but without leading zeroes: #Recs.2R "Sz" Now we want to create a new column for the character name. This could be up to, say, 12 characters, left-justified and with a title of "Character": Characters.12 "Character" Finally, we must prepare the "Name" column. We want it to take all the remaining room in the output display. The simplest way to do this is to assign it a length of 80, and let LISTSERV truncate the resulting output lines to 80 by itself: Name.80 "Name of the tune" Assuming we want to call this new format "MYINDEX", we would use the following command: +--------------------------------------------------------------------+ | > Format MYINDEX: #.6R0 "Item #" - | | > From.14 "Excerpted from" #Recs.2R "Sz" - | | > Characters.12 "Character" - | | > Name.80 "Name of the tune" | | | | > Select fleur or diletto or belleza IN OPERA.100-150 - | | > where singer is not Domingo | | --> Database OPERA, 5 hits. | | | | > Index MYINDEX | | Nb Excerpted from Sz Name of the tune | | -- -------------- -- ---------------- | | 000103 Carmen 41 La fleur que tu m'avais jetee | | 000118 Don Giovanni 23 La ci darem la mano | | 000121 Rigoletto 37 Veglia o donna | | 000127 Aida 25 Mortal, diletto ai Numi | | 000142 La Traviata 52 Brindisi | | | | Figure E.27. Sample FORMAT command | +--------------------------------------------------------------------+ For your information, the default format provided for "Notebook" data- bases is the following: +--------------------------------------------------------------------+ | > Format INDEX: #.6R0 "Item #" Date.8L "Date"c - | | > Time(1,5).5 "Time" #Recs.4R "Recs" - | | > #.0 "" Subject.80 "Subject" | | | | Figure E.28. Default format provided for "Notebook" databases | +--------------------------------------------------------------------+ ************************* * E.7. The LIST command * ************************* E.7.1. Introduction ------------------- The purpose of the LIST command is to allow you to produce output indexes similar to those obtained through the use of the INDEX command, but with different fields. The syntax of the LIST command is a bit complex, but there is a very simple form when you are using a "format" which you have previously defined: List format-name The minimum abbreviation for the LIST command is "L". In fact, the INDEX command is nothing but a synonym for the LIST command. The default "format" is the index provided with the database type definition. E.7.2. Syntax and examples -------------------------- In fact, the syntax of the LIST command is very similar to that of the FORMAT command. It allows you to specify column definitions directly if you so desire, without having to define an explicit format. That is, if you do not plan to re-use a given format in the same session, you can specify it directly on the LIST command. For example, let's assume that you have selected a few tunes out of the "Opera" database, displayed an index, and that you realize that you also want to display the name of the author of the opera. You could do this with the following command: List Author "Author" However, this would produce only a list of authors, without anything else. What you want is whatever was on the previous index, plus the "Author" field. To do this, you can simply append INDEX to your LIST command, to cause the default index specifications to be appended to yours. ---------------------------------------------------------------------- > List Author.15 "Author" Index Author Item # From Singer Recs Name ------ ------ ---- ------ ---- ---- Georges Bizet 000103 Carmen Carreras 41 La fleur que + W.A. Mozart 000118 Don Giovanni Sciepi 23 La ci darem l+ Giuseppe Verdi 000121 Rigoletto Fisher-Die+ 37 Veglia o donn+ Vincenzo Bellin+000143 Norma Callas 25 Casta Diva W.A. Mozart 000187 Le Nozze di F+Fisher-Die+ 12 Se vuol balla+ G. Rossini 000203 Il Barbiere d+Kiri te Ka+ 38 Una voce poco+ Figure E.29. Sample LIST command ---------------------------------------------------------------------- Note the plus sign after "La fleur que". The full title is "La fleur que tu m'avais jetee", and without the plus sign you might not have realized that some words were missing since the last displayed word was not truncated. *************************** * E.8. Advanced functions * *************************** This chapter contains information about "advanced" database functions. You should not read it until you have acquired a good knowledge of the basic database functions. You might in fact never need to use the functions described herein, althought database application programmers would certainly need to. E.8.1. Syntax of the DATABASE SEARCH command -------------------------------------------- When performing database searchs in "batch" mode, you submit a job to LISTSERV containing a DATABASE SEARCH command and an inline dataset containing the search commands to be executed. The name of this dataset is specified through the use of a DD= keyword. There are, however, some additional keywords that may be specified on the DATA- BASE SEARCH command. The ECHO keyword The ECHO= keyword lets you choose whether you want search commands echoed in the job output or not. Echoed commands are preceded by a "greater than" sign in the job output. The default is to echo all commands, but this may be overriden by specifying an ECHO=NO keyword on the DATABASE SEARCH command: Database Search DD=Rules Echo=No Specifying a value other than YES or NO causes the search to be aborted with an error. The CPULIM keyword The amount of CPU time that a database search job may use is, by default, limited to 60 seconds. The amount of work that can be done in this time depends on the CPU model of course. You can raise or lower this limit by means of the CPULIM= keyword, whose exact syntax is: CPULIM=ss The search job is aborted (with a partial output being returned to you) if this limit is exceeded. The OUTLIM keyword The number of output lines that can be generated by database search jobs has been limited, by default, to 2000 lines. This is to avoid generating huge output because of an error in the search criteria (for example, an "AND" clause being inadvertently replaced with an "OR"). This default value may be overriden through the use of an OUTLIM=nnnn keyword. If the maximum number of output lines is exceeded, the job is imme- diately aborted and its output is returned to you. E.8.2. Limiting the output of a given command --------------------------------------------- General description There might be cases where you want to limit the output of a partic- ular database command. For example, you might want to display the beginning of an index or document which you know to be quite large. This can be achieved by specifying an OUTLIM=nnnn keyword at the end of your command. This keyword can appear anywhere after the last quoted string in the command. This restriction allows you to perform a search on a string containing "OUTLIM=" by just quoting it, without changing the the maximum number of output lines. The keyword may not appear before the command verb itself. +--------------------------------------------------------------------+ | Examples of valid use of the "OUTLIM=" keyword: | | | | Print body of 220 outlim=30 | | Print outlim=100 all of 340-362 | | List Sender.17L "Sender"c Index Outlim= 20 | | List Sender.17L "Sender"c OUTLIM=20 index | | List Sender.17L "Sender outlim=10"c index | | | | Examples of invalid use of the "OUTLIM=" keyword: | | | | OUTLIM=20 Print all | | --> The command verb (PRINT) must appear before the keyword. | | | | List Sender.17L "Sender outlim=10"c index | | --> Here the keyword will be considered part of the heading. | | | | List Sender.17L outlim=20 "Sender"c Index | | --> There is a quoted string after the keyword. | | | | Figure E.30.Example of valid and invalid use of the OUTLIM keyword | +--------------------------------------------------------------------+ If the maximum number of output lines is exceeded, an error message is issued (in the job output) and all output lines subsequently generated by the command are discarded. However, the job itself is not aborted, and following commands will continue to execute normally. +--------------------------------------------------------------------+ | > Select * in TEST-L | | --> Database TEST-L, 21 hits. | | | | > Print header Outlim=10 | | >>> Item number 1, dated 87/10/18 13:09:30 -- ALL | | Date: 29 Jun 1987, 10:00:00 | | Reply-To: Revised LISTSERV -- test list | | Sender: Revised LISTSERV -- test list | | Comments: Warning -- original Sender: tag was TEST-L@UGA | | From: PHIL@UIUCVMD | | Subject: this is a test looking for upcasing | | | | --> Maximum number of output lines reached, remaining command | | output flushed. | | | | > Search debugging | | --> No hit. | | | | Figure E.31. Example of the use of the OUTLIM keyword | +--------------------------------------------------------------------+ In batch mode, there are in fact two OUTLIM keywords: the "global" one, which is defined in the DATABASE SEARCH command, and the "local" one, which applies only to the individual command with which it has been specified. In batch mode, the default value of the local OUTLIM keyword is "infi- nite", i.e. it is internally equated to the value of the global keyword. The local OUTLIM keyword cannot be used to override the limitations set by the global keyword. That is, if the global keyword indicates that the job is to be aborted as soon as it generates more than 2000 lines, you cannot allow a particular command to generate 3000 lines of output by appending an "OUTLIM=3000" keyword to it. However, if the command would have generated 3000 lines and you had set a local "OUTLIM=100" keyword, only 100 lines would be actually generated and the job would not be aborted. E.8.3. Limiting the CPU time available to a given command --------------------------------------------------------- General description There might be cases where you want to limit the amount of CPU time which may be spent on a particular command. This can be done by spec- ifying a CPULIM=ss keyword at the end of your command. It is similar to the "OUTLIM=" keyword in that it may appear anywhere after the last quoted string in your command, but may not appear before the command verb itself. If the CPU limit you have specified is exceeded, the job is aborted with an error message, and the (incomplete) job output is returned to you. There are two CPULIM keywords, a global one and a local one. This is exactly the same as with the "OUTLIM" keyword. The default value of the local CPULIM keyword is "infinite". The local CPULIM keyword cannot be used to override the limitations set by the global keyword. E.8.4. Performance considerations --------------------------------- Search clauses LISTSERV tries to process search clauses in such a way as to minimize the number of I/O operations to the database. Each search operation is done in three steps: 1. The "date" clause is compared against the date of the database item, which is present in the database index and immediately available to LISTSERV at no extra cost. 2. The "WHERE" clause is executed against the document "keywords", which are available to LISTSERV at no I/O cost. 3. The document is read in from the database, and the actual search operation takes place. This step is waived if no search argument was specified, of course. It is therefore best to specify "date" or "WHERE" clauses which you know to be true for the items you are searching and false for "most" other items. This will not constitute extra work for LISTSERV, as one might first have thought. Response time You should always keep in mind that LISTSERV is not a multi-tasking system, and may only serve a single user at a time. There are two consequences to this: o Other users will have to wait for your database search to be completed before they can be served. You should therefore avoid sending database jobs that are likely to require more than one minute of wall-clock time to execute. It is always best to send several smaller jobs, especially since the output will be smaller and will therefore reach you faster. o You may have to wait for other users' commands to complete before you are served. This means you should be prepared to wait longer if you are addressing a server on a "hub" node with a lot of traffic. You should also remember that the "work unit" is the job when in batch mode, and the command when in interactive mode. If you have five different and independent search operations in a given job, they will all be executed sequentially before the next user is served. In interactive mode, LISTSERV will switch to the next user after each search command.

[next chapter] [previous chapter] [table of contents]