
                                ECHOLIST
                      The EchoMail Conference List
                              USERS GUIDE

01 Dec 96                                                   ELMOD612.TXT

   This Users' Guide is intended as a brief description of the EchoList,
   a summary of how to submit updates to the database, and how to obtain
   information on the status of an echo from the Echolist.

   Changes since the last issue are highlighted in the left margin with
   the pipe symbol '|'.

FILE CONTENTS
=============

   Table of Contents of this file:

                       FILE CONTENTS
                       DISTRIBUTION
                       CURRENT ELIST STATUS
                       PURPOSE OF THE ECHOLIST
                       EXPIRY OF ELIST ENTRIES
                       ACKNOWLEDGEMENTS OF UPDATES
                       SENDING AN ADDITION OR UPDATE
                       DELETING AN ECHO
                       SENDING A RULES FILE
                       SENDING A QUERY REQUEST
                       OBTAINING INDIVIDUAL RULES
                       AUTOMATING THE UPDATES
                       HOW ECHOLIST PROCESSES MESSAGES
                       CONCLUSION

DISTRIBUTION
============

   A new ELMODnnn.ZIP (User's Guide) is distributed monthly, and each
   issue replaces all previous versions of ELMOD.  The 'nnn' is replaced
   by 3 numbers representing the last digit of the year followed by two
   digits of the month number - eg July 1995 is 507.

   This file is distributed monthly in the ECHOLIST file echo, and is
   also available on the Internet at the following Web page:

             http://www.portal.ca/~awalker/elist.htm

   In addition, the file is constantly updated to reflect changes in the
   Echolist software, or to improve the explanations, and the current
   draft version of the file is published weekly in the ECHOLIST message
   echo, distributed by Fidonet's North American Backbone.

CURRENT ELIST STATUS
====================

   In the weeks following 02 June 1995, the Echolist software was
   completely rewritten to permit its use on a different platform and to
   allow fully automated operation.  Most former features and formats
   were retained, but since the rewriting of the software necessitated
   some changes, moderators are encouraged to read this file carefully
   for details of the current Elist operation.

PURPOSE OF THE ECHOLIST
=======================

   The EchoList is a monthly publication sponsored by the Fidonet Zone 1
   Echomail Coordinator, and produced by 1:1/201.  It provides a place
   for Moderators to advertise their conferences regardless of
   distribution system or network, both to people who would like to
   participate, and to those who route echo traffic.  It is also a
   reference for distribution systems wishing to contact the Moderator
   of an echo, or wishing information about an echo's topics.  The
   Echolist is independent of all echomail distribution systems and
   their rules.

   Only one restriction exists on the acceptance of entries.  We reserve
   the right to decline to accept a requested entry if in our opinion
   the listing of an entry appears intended to cause harm to an
   individual, promotes illegal activities, or is likely to affect
   adversely those involved in distribution of the Echolist or the echo.

   The listings in the EchoList are maintained by the Moderators and
   Robot software, not by the Echolist Coordinator.  Additions and
   updates to the database are done by submitting NetMail messages
   addressed to a special name and node address.  The Subject of the
   message indicates what is to be done, and the body of the message has
   the data for the database entry.  The format of the message body
   requires that each line have one keyword and its accompanying data.
   Since the process is automated, correct formatting of both the
   address and the message body is essential to having your data
   recognized by the program.

EXPIRY OF ELIST ENTRIES
=======================

   To ensure that the Echolist contains only up-to-date information:

   ***********************************************************************
   ALL ENTRIES EXPIRE SIX MONTHS AFTER THE MODERATOR'S LAST UPDATE IS SENT
   ***********************************************************************

   This means that a Moderator must send an update by netmail or
   Internet email at least once every six months to maintain the
   EchoList entry. Moderators and Co-Moderators should work together to
   ensure that this is done.  It is suggested that the process be
   automated, and many moderators send their updates monthly.

   5 months after an entry was last updated, a netmail or Internet email
   advisory is sent to the person who last updated the entry, at the
   node number or Internet address on record.  At the same time the
   Elist entry is flagged with the following warning immediately under
   the tag in the Elist:

                         !!! DELETE WARNING !!!

   6 months after an entry was last updated, if the entry is still not
   updated, it is deleted from the Elist distribution files.

   7 months after an entry was last updated, it is completely purged
   from the database, and all password protection of the tag is lost.

        NOTE:

        Warning, expiry and purging are performed when the Elist is
        published on the first of each month, so for calculation
        purposes the software assumes that an echo was updated on
        the first of the month following the actual update.

ACKNOWLEDGEMENTS OF UPDATES
===========================

   Acknowledgements of receipt of update netmail messages are sent via
   Fidonet's echomail-routed netmail, unless the hold option is
   specified.  Update Internet email messages are acknowledged by return
   Internet email. Acknowledgements to non-Fidonet nodes are available
   only if the hold option is specified.  Please note that packet-header
   format prevents holding mail addressed to points - it will be
   necessary for points to call in as .0 to pick up such mail.
   Automated expiry warning netmail is all routed.

   The Elist software is run each time inbound mail is received. Netmail
   is processed immediately regardless of whether it arrives via a
   passworded or an insecure session, and email is processed immediately
   as well.  As a result, updates usually are processed within 60
   seconds of their arrival.  Some delay is inevitable if the system is
   in the middle of processing a major mail dump.  To allow for that, if
   you have requested that an acknowledgment to be placed on hold, it is
   suggested that you wait for one hour after delivering an update
   before polling again.  Email responses are sent to the Internet
   immediately after being written.

   Successful updates are also posted daily in the ECHOLIST echo.

SENDING AN ADDITION OR UPDATE
=============================

   To add or update an EchoList entry, submit either a

         1.  NetMail message addressed to "ECHOLIST" at 1:1/201, or
         2.  Internet email message addressed to awalker@portal.ca

         NOTE:  The return Internet email name@address MUST be 35
         characters or less since Fidonet *.msg format is used by the
         Robot for creating return messages.

   A separate message is required for each echo being updated.  The
   message subject for both netmail and Internet email must be
   "MODerator UPDate" which may also be abbreviated to "MOD UPD".  The
   message header thus looks like this:

         Correct:     [Netmail]            [Internet email]

         To:          ECHOLIST             awalker@portal.ca
         At:          1:1/201              [n/a]
         Subject:     MOD UPD              MOD UPD

         Wrong:

         To:          Adrian Walker
         At:          1:1/201
         Subject:     MOD UPD

   Note:  The Echolist software will take your return address from the
         MSGID, if present.  If your message originates in a Fidonet or
         FTN-format network, the MSGID is expected to show an address in
         a form which constitutes a valid return address for the
         originating network.  An Internet-format MSGID address will
         result in an error in recording of the return address.

   MESSAGE BODY FORMAT
   -------------------

      The body of the message text has the data for the database entry,
      formatted so that every line starts with a special keyword that
      identifies the field name as detailed below, followed by at least
      one space, followed by the data to be put in that field.

      The required fields for new entries are TAG, TITLE, DESCRIPTION,
      MODERATOR and PASSWORD.  The other lines are optional, and if you
      do not wish to supply data for a given field, omit that line.

      Similarly, if you wish to delete the contents of a data line, just
      include the keyword with no text after it, and the 'empty string'
      will replace whatever is in the database for that keyword.

      If the echo is already in the current Elist, only the TAG and
      PASSword fields need to be included in an update message, since
      the software will supply the remaining information from the
      existing Elist entry.

      NOTE 1:  If an abbreviated update is sent, the netmail response
               from the Robot will only contain the data provided in the
               update.  All previous data in the database is left
               intact, but is not shown in the netmail.  To see a copy
               of the complete entry, the QUERY function described below
               may be used.

      NOTE 2:  Although an abbreviated update is accepted, the public
               posts of updates in the ECHOLIST echo similarly contain
               only the data from the update message.  Since these posts
               form a useful advertising medium for an echo, a moderator
               may wish to include all data in every update to assist
               users reading these public posts.

      NOTE 3:  If the echo has already been deleted from the Elist, you
               can not submit an abbreviated update, since the missing
               data is no longer on file, and only the tag and password
               are kept until the 7-month purge date.

      Each line may appear only once, the two exceptions being DESC and
      MOD lines, of which there may be as many as necessary up to the
      limit shown below.  If multiple copies of other lines are
      included, only the last one will be recognized by the software.

      The first data line MUST be TAG.  After that, all other lines can
      come in any order.  The keyword starts at the left margin of the
      line, and may be abbreviated, but the CAPITALIZED part of the
      keyword is the minimum abbreviation you can use.  Put at least one
      space between the keyword and the text of the line.  The To-name,
      subject, keywords and passwords are NOT case sensitive.  The <>
      and [] in the following lines are used here only for clarity and
      should be omitted.

      In the body of the message:

      Mandatory:

      TAGname       <echo area name>                     [max 19 characters]
                AREA is also accepted for backward compatibility.
      TITle         <brief description of the echo>      [max 58 characters]
      DESCription   <full description of the echo>       [max 25 lines]
      MODerator     <moderator name>, <moderator node>   [max 6 lines]
      PASSword      <current password>, <new password>

      Optional:

      ORIGin        <originating node of the distribution>
      DISTribution  <distribution systems or regions>
      GATEway       <gateways to other zones & networks crossed>
      RESTrictions  </SYS /MOD /MEM /REA /ACC /RUL>
      TOTalnodes    <number of nodes carrying this echo>
      VOLume        <number of messages>/<Month, Day or Week>
      RULEfile      <filename of rules file in ELRULnnn.ZIP>
      OPTION        <HOLD>                               [no abbreviations]

      Note:

      1.  Passwords and descriptions are now mandatory.
      2.  Fields such as SEEN-BY and PATH are no longer recognized or recorded.
      3.  Packet-header format prevents holding mail addressed to points -
          points should call in as .0 to pick up such mail.

   SAMPLE ENTRY
   ------------

      TAG  ECHOLIST
      PASS YOURGUESS
      TIT  EchoList Access Conference
      DESC The EchoList, or Elist, is published at the beginning of each
      DESC month and is a listing of EchoMail Conferences as described
      DESC and submitted by each conference's moderator.  Successful echo
      DESC update requests are posted in this echo in addition to being
      DESC sent in netmail to moderators.  This provides public
      DESC information on updates between the monthly Elist file
      DESC distribution dates. This echo also provides access to the
      DESC Elist's author for questions about the database which are not
      DESC answered by the ELMOD and ELFAQ help files.  For availability
      DESC of files and routine questions about update formatting,
      DESC participants should first contact their NEC or REC.  Discussion
      DESC of echomail links and distribution systems is off topic.
      ORIG 1:1/201
      DIST Z1-Backbone
      VOL  300/Week
      RULE ECHOLIST.RUL
      MOD  Adrian Walker, 1:1/201

   KEYWORD EXPLANATIONS
   --------------------

                            <MANDATORY KEYWORDS>

      TAG is the one-word name used in distributing the echo, and is
      also called the area name or group name.  Since the tag is used by
      areas control programs to create subdirectories, is formatted into
      the echo listings of distribution systems, and is processed by
      various mail processing software, the following guidelines for
      tags are provided:

         - No longer than 19 characters.
         - The first 8 characters should not duplicate those of other tags.
         - Characters should be between ASCII 33 and ASCII 126 inclusive.
         - The following characters should be avoided, because the
           software indicated below is known to restrict their use in
           tags.  Any use of these characters in a tag name, therefore,
           may cause distribution problems for the echo when passing
           through systems using such software:

            *    (Imail, Fastecho)
            ?    (Imail, Fastecho)
            [    (Imail, Fastecho)
            ]    (Imail, Fastecho)
            .    (Can not be used in Tag-name-based filenames/subdirectories)

         - The first character should not be any of the above, or:

            -    (Imail, Fastecho)
            +    (Imail, Fastecho)
            &    (Imail, Fastecho)
            ~    (Imail, Fastecho)
            #    (Imail, Fastecho)
            %    (Imail, Fastecho)
            =    (Imail, Fastecho)

      The Echolist does not accept duplicate tag names.

      TITLE should be a one-line title for the conference, preferably 58
      chars or less.  Since the title is also imported from the Elist
      directly into the echolists of various distribution systems,
      titles longer than 58 characters are likely to be truncated.

      DESCRIPTION is a mandatory field, and allows for a more detailed
      description of the conference, since you can supply multiple DESC
      lines.  In the Elist all DESC lines are combined into a single
      paragraph.  Make sure that you have the keyword DESC in front of
      *every* line of description text, or the Elist software will not
      recognize what type of line they each are.

         Correct:

         DESC The EchoList, or Elist, is published at the beginning of each
         DESC month and is a listing of EchoMail Conferences as described
         DESC and submitted by each conference's moderator.

         Wrong:

         DESC The EchoList, or Elist, is published at the beginning of each
              month and is a listing of EchoMail Conferences as described
              and submitted by each conference's moderator.

      MODERATOR, for the purpose of the Echolist, is normally defined as
      the person(s) with authority over the distribution and policies of
      a conference.  For those echoes not requiring such a single
      authority, the listing refers instead to the person designated as
      contact person or liaison on behalf of the echo.

         There MUST be at least one Moderator listed in order to have a
         valid EchoList entry.  Each Moderator line consists of a first
         and last name (no initials or middle names) followed by a
         comma, and then the Moderator's node address.  Only one name
         and address is permitted per MOD line.

         Node addresses should provide the method of contact with the
         Moderator, and since the Echolist is produced within Fidonet,
         this should be an address, or a point off an address, which is
         listed in a commonly available nodelist and is thus accessible
         from Fidonet.  There should be no spaces in the address field.

         Correct:

            MOD  Adrian Walker, 1:153/752
            MOD  Adrian Walker, 1:153/752.0
            MOD  Adrian Walker, awalker@portal.ca

         Wrong:

            MOD  Adrian Walker 1:153/752         [no comma]

      PASSWORD is a mandatory field.  It may protect your entry from
      modification by someone else.  There are two password fields on
      the PASSWORD line.  The first is for the current password.  The
      second is optional and is for the new password to change it to, if
      you want to change it.  Here are the formats:

            PASS  SOMEWORD                       [existing password]
            PASS  SOMEWORD, NEWWORD              [change passwords]

            PASS  NEWWORD                        [add password if none]
                 or
            PASS  , NEWWORD                      [add password if none]

         Please note that the use of  "PASS , NEWWORD"  to update an
         entry causes the Robot to expect the current password to be
         non-existent (nothing before the comma), and to be replaced by
         the new password provided.  If there actually *IS* a password
         on record, such a format will cause the update to be bounced
         for an incorrect password.

                            <OPTIONAL KEYWORDS>

      ORIGIN, DISTRIBUTION and GATEWAYS are just an organized set of
      text fields which you can use to describe sources and contacts
      that control links to the conference.  Use any of them which you
      need.  If you are on a formal distribution backbone of some kind,
      don't just say BACKBONE - there are lots of them.  Specifically
      say "Zone 1 Backbone" or "Zone-3 Backbone" or "EchoNet
      Backbone"...

      RESTRICTIONS is a shorthand reference to rules applied by the
      Moderator concerning admission to the conference.

         /ACC - access is limited to Read-Only status.
         /MEM - you must be validated as a member of some organization.
         /MOD - you may not link in without specific approval of the Moderator.
         /REA - only real names are permitted - no aliases.
         /RUL - a rules file is included in ELRULnnn.ZIP.
         /SYS - only Sysops are allowed to participate.

         The letters following the '/'  must be in upper case.  If more
         than one is needed these should be separated by a space.  A
         free form Restrictions line is permitted, but ONLY if the line
         does not contain the preceding '/' character.  Acceptable
         formats include:

              REST /SYS
              REST /MOD /SYS
              REST Startrek Fans only

      TOTALNODES is for providing an estimate of the number of systems
      participating in your conference.  It must be a single integer
      number such as 6, 21, 190, etc..

      VOLUME is for providing an estimate of the volume of messages to
      be expected by those who link-in.  It must be a single integer
      number followed by a slash followed by either MONTH, WEEK or DAY
      to identify the time period in which that number of messages flow.

      RULEFILE allows you to specify the name of the rules file, or
      other information file or FAQ about the echo, which you submitted
      for inclusion in the ELRUL archive.  Please note, this keyword is
      only used to display the NAME of the rules/FAQ file in the Elist
      entry - to submit the rules/FAQ FILE itself, you must use a
      separate message following the format detailed in "SENDING A RULES
      FILE" below. All rules/FAQ files have the extension of *.RUL.
      After the keyword "RULE" you should ONLY put the rulefile name on
      this line - no other text:

         Correct:

            RULE  WHATEVER.RUL
            RULEfile  WHATEVER.RUL

         Wrong:

            RULE WHATEVER.RUL is the file.       [extra words]

      OPTION allows you to specify the way in which your update message
      should be handled by the Echolist software.  At present the only
      option is HOLD which causes the acknowledgement message to be held
      for you to pickup, instead of being sent to you via routed
      netmail.  Allow 12 hours before polling for pickup.  The HOLD
      option is ignored for Internet email responses.

DELETING AN ECHO
================

   There is at present no automated routine for deleting an echo from
   the Elist.

   To have a complete entry deleted, please send netmail addressed to
   Adrian Walker at 1:1/201 or 1:153/752, giving the echo tag, your
   password, and requesting that the entry be deleted from the Elist
   database.

   On receipt, the entire entry and its password will be removed from
   the Elist.  This also removes all protection for the echo tag, thus
   allowing others to make use of it.

SENDING A RULES FILE
====================

   To submit an echo rules/FAQ file to the Echolist for inclusion in
   ELRUL###.ZIP, the monthly collection of current echo rules/FAQs,
   submit either:

         1.  NetMail message to "ECHOLIST" at 1:1/201, or
         2.  Internet email message to awalker@portal.ca.

   In order to submit a Rules/FAQ File the EchoList entry must already
   have been added to the Elist with a MOD UPD message.  Rules File
   messages can not be used for adding or updating Elist entries.

   Depending on whether it is done by netmail or Internet email, the
   rules/FAQs may be submitted using either of the following methods.

   1.  As a file attach message (only applicable to Fidonet direct Netmail):

         To:       ECHOLIST
         At:       1:1/201
         Subject:  <attached rules/FAQ file name (xxxxxxxx.RUL)>

         NOTE:  The file being attached must be a plain language text
         file in ASCII format.  Use of extended ASCII is permitted.  The
         file must NOT be a compressed file, since this poses problems
         on some systems when the ELRUL archive is decompressed.

         In the body of the message:

         TAGname       <symbolic area name>
         PASSword      <current password>
         ---

   2.  Included in the text of the message (Netmail or Internet email):

             [Netmail]                           [Internet email]
         To:       ECHOLIST                   To:       awalker@portal.ca
         At:       1:1/201                    At:       [n/a]
         Subject:  MOD RUL                    Subject:  MOD RUL

         In the body of the message:

         TAGname       <symbolic area name>
         PASSword      <current password>
         RULEtext      <Full Title of rule/FAQ file - one line only>
         [insert freeform rules file into message here]
         ---

         The format for the password is the same as shown in the Update
         message format, above.

   Note that in both cases the 3-character string "RUL" appears as part
   of the subject line, and this is the cue for the Elist software to
   process the message as a Rules/FAQ submission.  All rules/FAQ
   messages must end with a 3-dash tear line.

       *************************************************************
       ALL RULE/FAQ FILES EXPIRE AND ARE DELETED WHEN SIX MONTHS OLD
       *************************************************************

   As with database echo description entries, to ensure currency,
   rule/FAQ files are removed from the archive when more than 6 months
   old, and Moderators wishing their rules/FAQs to appear in ELRULnnn.ZIP
   should resubmit their echo's rules/FAQs at least once every 6 months.
   They are not retained in the database after this time.

   All rules/FAQ files are stamped with the date of arrival at 1:1/201,
   regardless of the original file date, so as long as a Moderator
   submits a rule/FAQ file every 6 months, it is not essential that the
   file have a recent file date.

SENDING A QUERY REQUEST
=======================

   To obtain a list of echoes and the date of their last update, file
   request ELTAG from 1:1/201 or 1:153/751, and the current ELTAGnnn.TXT
   will be sent (approx 110 kb).  This file is updated every time an
   update arrives so it will contain up-to-the-minute information.

   To query the EchoList database, submit a NetMail message to
   "ECHOLIST" at 1:1/201.  The message subject must be "ECHO QUERY" (no
   abbreviation). The body of the message text has the arguments for the
   request.

   Only a single Query parameter is currently available with the new
   Elist software, and only a single echo may be queried in a given
   query message:

   /MODUPD       <Echo area name>

   This produces an updated copy of the echo's complete Elist entry
   formatted as it appears in the monthly ELIST###.TXT file.  Thus the
   message will look like the following:

   To:          ECHOLIST
   At:          1:1/201
   Subject:     ECHO QUERY

   /MODUPD SOMEECHO
   ---

   It should be noted that some options for message forwarding, and
   string searches other than a complete tag name are not implemented at
   present.

OBTAINING INDIVIDUAL RULES
==========================

   To obtain a list of the most current rules files on record, file
   request the magic name RULES from 1:1/201.  From that list you can
   then file request specific rules which may be more current than those
   in the last ELRULnnn.ZIP distribution file.

AUTOMATING THE UPDATES
======================

   You can automate the process of sending update messages with a batch
   file like the following.  The programs I use (and there are many
   others) are DOM100.ZIP (Day of the Month), and MESSGN19.ZIP (Message
   Generator) and/or MKMSG21.ZIP (Makemsg).  This extract is from my
   Mailer's batch file:

   :MIDNIGHT
           call c:\batch\midnight.bat
           dom                         {see it it is the first of the month}
           if errorlevel 2 goto M2
           if errorlevel 1 goto M1
   :M2
           goto start
   :M1
           c:
           cd\bink\mailchek            {post policies into the echo}
           copy z1_back.hdr messgn.ctl
           messgn c:\max\policies\z1_back.pcy c:\msgs\z1back 153 752 All

                                       {post Elist entry into netmail}
                                       {this is all one line}
           makemsg -Cc:\elist\echo.upd -Dc:\msgs\netmail\ -S1:153/752
              -F"Adrian Walker" -R1:1/201 -T"Echolist" -J"MOD UPD" -P
              -O"Your Origin Line, Vancouver BC "

                                       {post Elist rules into netmail}
                                       {again all one line}
           makemsg -Cc:\elist\echo.rul -Dc:\msgs\netmail\ -S1:153/752
           -F"Adrian Walker" -R1:1/201 -T"Echolist" -J"MOD RUL" -P
           -O"Your Origin Line, Vancouver BC "

           goto start

HOW ECHOLIST PROCESSES MESSAGES
===============================

   Echolist is a group of programs each performing part of the function
   of processing update messages and updating the database.  This group
   of programs runs after every inbound mail packet is processed.  The
   editing of help files, preparation of the distribution archives, and
   hatching of these archives each month is performed manually.

   After mail tossing is complete, the following series of actions takes
   place:

   1.  ECHOLIST.EXE runs.  This is the main Elist program, and does 3
       things - it manages the password file, extracts data from
       messages to a temporary update file, and it prepares netmail
       responses based on the information received.  It also processes
       ECHO QUERY messages based on information as it showed in the
       database immediately prior to the program running.

   2.  ESORT.EXE runs.  It sorts the extracted data in the newly-created
       update file in preparation for merging into the main database.

   2.  EMERGE.EXE runs.  It runs through the database looking in turn
       for each echo noted in the update file.  When it finds the
       matching database entry, it merges the 2 files segments.  This is
       done by replacing any field which has been updated and retaining
       any field which has not been updated.  Thus a new one line
       description field will replace an entire previously multi-line
       description field, a new title line will replace a previous title
       line, and so on.

CONCLUSION
==========

   Frequently-asked questions are discussed in ELFAQnnn.TXT contained in
   the distribution Elist archive.

   If you have a problem, you should consult the ELFAQ file, this ELMOD
   file, and finally your NEC and REC for assistance.

                              ---ooo000ooo---
