Internet Info 1997 December/Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso/infoguide/advanced/sysadmin/listserv-owner-tips

Text File | 1997-12-01 | 72KB | 1,569 lines

BITNET Network Information Center LISTMGT HELP
EDUCOM, Suite 600, 1112 16th Street, NW, Washington, DC 20036, USA,
202-872-4200

List Management Tips for LISTSERV Postmasters and List Owners

Version (1) 12-5-91
Lisa M. Covi
Systems Support Professional
[e-mail], COVI@BITNIC
@ Copyright CREN 1991. May be reproduced with credit.

Table of Contents
------------------------
0 Introduction
1 Prerequisites
2 Setting up LISTSERV
2.1 Who has privileges?
2.2 Issuing LISTSERV commands
2.3 Shutting down LISTSERV
3 What lists already exist?
3.1 Directory of LISTSERVs
3.2 Directory of LISTSERV lists
3.3 Tools for Parsing Lists of Lists
3.4 Directory of Electronic Journals
3.5 New List Announcements
4 Adding and Deleting users from existing lists
4.1 Checking subscriptions
4.2 Adding and Deleting subscriptions
4.3 Unsubscribing a user from all BITNET lists
4.4 Deleting Lists
5 Setting up New Lists
5.1 Introduction
5.2 The Cookie Cutter Method
5.3 Modifying the configuration (keyword headers) of lists
5.4 Adding a group of users to a closed list
5.5 List Keyword Defaults
5.6 List-Keyword Recommendations
5.7 Keyword Options for Small Lists
5.8 Formatting REVIEW output
5.9 Aliasing List Names
5.10 System Tuning
5.11 Maintenance Updates
5.12 Maximum size of a message to a list
5.13 Daily Maximum number of messages
5.14 Suppressing Subscription/Unsubscription Announcements
6 Individual List Subscriber Option Flags
6.1 Tired of /Want more Extra Messages from LISTSERV?
6.2 Going on vacation?
6.3 Want to restrict a user from sending files to a list?
6.4 Want to get a copy of your mail to a list?
6.5 Suppressing the names on mail from LISTSERV
6.6 How does LISTSERV track subscriptions?
6.7 Want an unlisted address?
7 Edited Lists
8 Subscription Renewal (the RENEWAL= list header)
9 Large Lists and Peering
10 Archives (List Notebooks or Logs)
11 Troubleshooting - Miscellaneous problems
11.1 Are one or more lists not sending mail?
11.2 Are you getting no LISTSERV response?
11.3 Is LISTSERV misplacing your PUT's?
11.4 Are your requests to DELETE a file from a file list result in
requests getting forwarded to some LISTSERV POSTMASTER?
11.5 Are you running up against the 256K daily limit on getting files
from LISTSERV?
11.6 Are you puzzled why mail is bouncing?
11.7 Need to get rid of mail that violates BITNET usage rules (i.e.
broadcast messages or files)?
12 Customized List Messages - Mailforms
13 List gateways to Usenet Newsgroups
14 File Server Functions
14.1 Obtaining files from the LISTSERV File Servers
14.2 Adding files to an Existing FILELIST
14.3 Deleting a file from an existing FILELIST
14.4 Creating your own FILELIST
14.5 Peered FILELISTs
14.6 Maximum file length
14.7 Troubleshooting - only getting the header of your FILELIST request?
14.8 Packages - Sending out a group of files with one GET command
14.9 Automatic File Subscription
15 Searching LISTSERV Files
16 Acknowledgements
------------------------

0 Introduction

This document will outline the procedures necessary for managing and
supporting the popular electronic mailing list management software
LISTSERV. Before you read this document, you should be familiar with the
basic use of LISTSERV outlined in the document BITNET INTRO (1) and how
to use your local mail software. The purpose of the document is to get
you started in becoming the local LISTSERV expert or provide a reference
for those who may already have experience managing LISTSERV or owning
lists. Other good sources of information are the lists LSTSRV-L@UGA and
LSTOWN-L@INDYCMS. This document will not discuss details of installation
and maintenance of the LISTSERV software itself (LSTSRV-M@SEARN is a
good reference for those topics). If you want to skip to instructions on
how to look up topics on these lists, look in Section 15 Searching
LISTSERV Files.

I hope that you will enjoy exploring and making use of these LISTSERV
functions as much as I have. Although it is often frustrating to use
voluntarily written and maintained software (mostly due to lack of
documentation), LISTSERV has been so well-written and utility-oriented
that its usefulness greatly outweighs initial frustration. Please feel
free to make suggestions for contributions to this document by sending
mail to me at covi@bitnic. This document has grown out of my own
learning process (making mistakes is the ultimate learning experience)
and I'm sure there are many gaps (and much more to learn).

1 Prerequisites

The more you know about your mailers and editing your mail, the more
productive you will be in managing LISTSERV. If you have not had the
opportunity to use LISTSERV before being thrust into your current
predicament, please subscribe to LSTSRV-L or another list that interests
you (see Section 3.2 Directory of LISTSERV lists) as an exercise.
The list of documentation that is provided with LISTSERV can be obtained
by sending your nearest LISTSERV (try LISTSERV@BITNIC if you don't know)
the command INFO. Be forewarned that the standard LISTSERV documents are
not complete and should be used in conjunction with other resources
mentioned in this document.

2 Setting up LISTSERV

LISTSERV is a VM/CMS based software package available free of charge to
BITNET members that offers interactive subscription, unsubscription and
file server capabilities on BITNET and, by way of mail gateways (2)
from the Internet.

In order to set up a LISTSERV, one of the BITNET registered contacts
(anybody from your node listed in the BITEARN NODES or the MAINT account
should send mail to ERIC@SEARN (Eric Thomas, the author of LISTSERV) who
will send him/her the code. Be forewarned that this is not a commercial
product and that Eric is not available for a great deal of direct
support and will tell you so.

2.1 Who has privileges?

There are only two levels of "privileges" on LISTSERV: POSTMASTER,
who can shutdown or stop LISTSERV and has full ownership authority
over all lists on that LISTSERV, and LIST OWNER, who has full ownership
authority only to a particular list. There is a file called LOCAL
SYSVARS on LISTSERV's 191 disk which contains LISTSERV definitions such
as who has POSTMASTER privileges. LIST OWNERS are designated in the
file that contains the mailing list or file list itself.

The LOCAL SYSVARS file also contains creation, store and installation
passwords for LISTSERV which are required to create new lists, store
files on LISTSERV and install updates to the LISTSERV software. It is
strongly recommended that each list be assigned an optional password
created and maintained by the list owner that can control access to the
way the list and files associated with that list can be accessed and
modified. See the discussion about setting up new lists below for more
information on list passwords. Personal passwords which are associated
with specific user IDs, can be used for LISTSERV's Automatic File
Distribution features mentioned in section 14.9.

2.2 Issuing LISTSERV commands

There are two ways of issuing LISTSERV commands: interactively and by
mail). This document will give examples of the interactive commands. To
issue the the commands by mail, just send a message to LISTSERV@listnode
(where listnode is the node where the LISTSERV resides) and put the comm
and (the part after "TELL LISTSERV") into the message text. Note that
LISTSERV ignores the subject heading. This document also assumes that
the LISTSERV you are using is local. If you are using a LISTSERV at
another node, the interactive command should include AT listnode, i.e.
     TELL LISTSERV AT listnode

If you send an interactive command, you will receive an interactive
response on your screen and information you request from LISTSERV will
be spooled to your reader. If you are sending mail messages, your
responses and data will return by mail.

If you are a POSTMASTER for LISTSERV, you may issue user commands as if
the command came from a different user. For example to subscribe someone
(user@node) to a list, type:
     TELL LISTSERV FOR user@node SUB listname firstname lastname
If the list is not public, this command may cause the subscription to be
forwarded to the list owner, which you may or may not want. FOR is
meant to be used more for debugging problems (See Section 11.6 Are you
puzzled why mail is bouncing?) than for routine list management. I
recommend encouraging your users to become LISTSERV-literate and learn
to make full use of LISTSERV themselves.

2.3 Shutting down LISTSERV

Occasionally a POSTMASTER may be required to shutdown the LISTSERV
server for system maintenance (i.e. adding disks to LISTSERV). To
perform this task, type:
     TELL LISTSERV SHUTDOWN
Then query LISTSERV to make sure it is not logged on (it is normally
disconnected -DSC):
     Q LISTSERV
You may then login to the LISTSERV ID, if required, to perform your
maintenance task. When you are ready to bring LISTSERV up, the system
administrator should login to a user ID with AUTOLOG authority and type:
     AUTOLOG LISTSERV
If you have logged in to LISTSERV interactively, you can also start it
by typing:
     LSVPROF

3 What lists already exist?

3.1 Directory of LISTSERVs

There is a complete directory of sites running LISTSERV on
LISTSERV@BITNIC in the file LISTSERV SITES. If you need to get in touch
with a LISTSERV site's maintainer, that information is there too.


3.2 Directory of LISTSERV lists

To get a list of all the existing, publicly available lists on LISTSERV,
type:
     TELL LISTSERV LIST GLOBAL
You will receive a file with over 2800 records (lines) which has been
generated by LISTSERV and thus includes all instances of a list
including its peers (see Section 9 on Large Lists and Peered Lists for
more information). If you don't want all this information, you may get a
listing based on a search string. For example, to find all lists that
have something to do with Chemistry, you could try:
     TELL LISTSERV LIST GLOBAL /CHEM

There is also a list of lists on the Internet that contains both
BITNET lists and Internet interest groups:
     Internet: anonymous ftp to ftp.nisc.sri.com in the file
netinfo/interest-groups
     BITNET: send mail to [e-mail] with the message text
send netinfo/interest-groups

3.3 Tools for Parsing Lists of Lists

There is a LISTSERV database called LISTS which can be searched with
LISTSERV database searching utilities. See Section 15 Searching
LISTSERV Files for more information.

Dartmouth makes a list of lists available that includes an abridged
(no duplicate entries or local lists) version of the "official" list of
Internet interest groups. This list is updated monthly and has
information in the form of tab-delimited fields: category list name,
mailing address, subscription/command address, one line description of
the list, address of list owner, long description (< 450 characters) of
the list. Also available is a Macintosh Hypercard application package
containing the files:
     LISTLIST HQX - 7 MB stack of the List of Lists
     LISTSERV LISTS - 5 MB file from with the above was built
     LISTSTUB HQX - one card of the LISTLIST stack
     LISTTUTR HQX - Tutorial stack on mailing lists
     READ ME - complete information on the Dartmouth list of lists
You can get these files by requesting them from:
     Internet: anonymous ftp to dartcms1.dartmouth.edu in the file
siglists/filename.filetype
     BITNET: TELL LISTSERV AT DARTCMS1 SEND filename filetype

A VAX RDB/VMS software package is available on the Internet only from
vax.muskingum.edu and requires BASIC. The directory dartmouth contains
the files:
     *.EXE
     *.RDB
     *.SNP
     DARTMOUTH.DOC
You may contact Lewis Dreblow ([e-mail]) for more
information.

See the information below in Section 14.9 Automatic File Subscription to
find out how to subscribe to updates of these files.

3.4 Directory of Electronic Journals

There is a Directory of Electronic Journals and Newsletters available
from ARL. To obtain a printed version of the directory for a small fee,
contact:
Office of Scientific & Academic Publishing
Association of Research Libraries
1527 New Hampshire Avenue, NW
Washington, DC 20036 USA
ARLHQ@UMDC
202-232-2466 (voice)
202-462-7849 (fax)
An online version is available from University of Ottawa by typing:
     TELL LISTSERV AT UOTTAWA GET EJOURNL1 DIRECTRY
     TELL LISTSERV AT UOTTAWA GET EJOURNL2 DIRECTRY

3.5 New List Announcements (3)

Most people who keep and compile local copies of Lists of Lists
subscribe to the NEW-LIST LISTSERV list at NDSUVM1 (vm1.nodak.edu on the
Internet). NEW-LIST is a moderated list (See Section 7 Edited Lists) for
new list announcements, old list deletions and major list changes (i.e.
if you move a list to another host or node). You can get a copy of a
sample announcement by typing:
   TELL LISTSERV AT NDSUVM1 GET NEW-LIST FORMAT
You should announce a list only after it is well-tested.

If you are interested in subscribing to NEW-LIST yourself, type:
    TELL LISTSERV AT NDSUVM1 SUB NEW-LIST yourfirstname yourlastname

Some additional hints on how to search for additional lists are kept in
the file "LISTSOF LISTS" (note the two plurals). You can get it by
typing:
     TELL LISTSERV AT NDSUVM1 GET LISTSOF LISTS

4 Adding and Deleting users from existing lists

Before I explain how to set up a new list from scratch, here are some
useful, commonly-asked commands about how to work with existing lists.
In order to work with an existing list, make sure you have the listname
and the node name. If you aren't sure and it's a public list, do a
string search of the List of Lists mentioned in Section 3.2 Directory of
LISTSERV lists.

4.1 Checking subscriptions

As a LISTSERV manager or list owner, you will find that the users on
your lists are not always vigilant about keeping their lists
subscriptions up to date. In fact, you may find that sometimes users are
not even aware of all the lists to which they are subscribed (I confess,
neither am I).

If they don't already know this command, teach your users the following
command to find out who is currently subscribed to a given list:
     TELL LISTSERV REVIEW listname

If you want to find what lists to which a user (user@usernode) is
subscribed at a particular LISTSERV type:
     TELL LISTSERV QUERY * FOR user@usernode

4.2 Adding and Deleting subscriptions

As a list owner and/or a list manager, I would encourage you to take
full advantage of LISTSERV's user capabilities by setting up lists (see
Section 5.5 List Keyword Defaults) to have self-subscription and
unsubscription and setting up lists to have automatic renewal to cut
down on the management tasks you will have to perform. However, even if
you have automatic subscription/unsubscription, you may be required
to alter users' subscriptions, i.e. if a subscriber's From: address
changes and s/he can no longer communicate with the list. You will also
have to manually subscribe and unsubscribe (add and delete ) users if
you maintain closed subscription lists.

When you change a subscription, LISTSERV automatically sends a message
to the user explaining the change. However, if the address no longer
exists, or there is an important reason you want to bypass this
notification message, you can use the QUIET option (examples below).

In order to delete a user from a list with no notification, type:
     TELL LISTSERV QUIET DELETE listname user@node
In order to add a user to a local list with no notification, type:
     TELL LISTSERV QUIET ADD list name user@node firstname lastname
In order to unsubscribe all users from a local list with no
notification, type:
     TELL LISTSERV QUIET DELETE listname *@*

4.3 Unsubscribing a user from all BITNET lists

When a node or user has disappeared, and you wish to unsubscribe a user
or set of users from all LISTSERV lists across BITNET, the BITNET node
administrator (the person listed in the nodes file as :useradm)
should submit a command job by sending mail to LISTSERV
with the message text (remember that the subject line is ignored):

     //USUB JOB
     DELETE * DD=names (NETWIDE
     //names DD *
     user1@node
     user2@node
     ...
      /*
Note that LISTEARN, the EARN network's version of LISTSERV, does not
support wildcards in name specifications * (as in *@node).

4.4 Deleting Lists

When you are ready to delete a list, both the List Owner and the
LISTSERV Postmaster have responsibilities. List Owners should:

1. make the decision to delete the list
2. inform any existing subscribers of the situation,
3. archive any material they wish to keep (files and logs - see below)
4. Notify the LISTSERV Postmaster and/or the system administrator

The LISTSERV Postmaster will then:

1. Erase the list by typing:
     TELL LISTSERV CMS ERASE listname LIST
2. Have the system administrator delete the user ID for the list.
3. Erase the associated files (archives, cache, FILELIST, etc.) by
typing:
     TELL LISTSERV CMS ERASE filename filetype
for each file.
4. If you had a dedicated minidisk for the list archives, you may want
to remove that minidisk from the LOCAL SYSVARS "mdisk" list and remove
it from LISTSERV. Check with your systems administrator.

5 Setting up New Lists

5.1 Introduction

Before you add new lists or new files to your LISTSERV, it would be wise
to familiarize yourself with the way disks are allocated for LISTSERV.
On all LISTSERV's the A disk contains the LISTSERV system files.
LISTSERV notebook archives (See Section 5.5 List Keyword Defaults), and
data files indexed in FILELISTs (See Section 14 File Server Functions)
should not be stored on the A disk because it could fill up unexpectedly
causing bad things to happen to LISTSERV (see Section 11.1 Are one or
more lists not sending mail?). There is some basic information on how
LISTSERV uses its disks in the LISTSERV SYSVARS A disk file (which you
should not edit - local changes should go in LOCAL SYSVARS A). Another
consideration if the LISTSERV node is connected to the Internet, is
whether you want to allow anonymous ftp to a LISTSERV disk. If you are
going to allow anonymous users to access a disk, you will be unable to
control by file what data they can access. Therefore you must separate
public files from private files by disk. Don't use filemodes C or D;
LISTSERV's C disk is reserved for future use and LISTSERV's D disk is a
work disk which is automatically erased periodically. There is a helpful
discussion of how to allocate disks for LISTSERV in Ben Chi's FSV GUIDE
available from LISTSERV@ALBANY and LISTSERV@BITNIC.

5.2 The Cookie Cutter Method

Many novices and experts alike use what's called the cookie cutter
method to copy an existing template (i.e. a currently used list) to set
up new lists. If you are positive that a list you want to create should
be pretty identical to an existing list, by all means copy it. However,
the difference between novices and experts is that the experts know what
the list settings mean. Be sure to check the settings and familiarize
yourself with them (see Section 5.5 List Keyword Defaults). Here's the
"cookie cutter" method:

1. Get a copy of the list you want to imitate by typing:
     TELL LISTSERV REVIEW similarlist
2. Edit the file to reflect the desired subscriptions, list description
and any list keywords, i.e. list password.
3. Save your file as the new listname "newlistname LIST A". Consult the
list of list (see Section 3.2 Directory of LISTSERV lists) to find a
unique name if your list will be public. Also consult your LISTSERV
Postmaster to choose a unique name if the list will be private and
check with your System Administrator to make sure that you can use
this name as a user ID.
4. Consult your LISTSERV POSTMASTER or System Administrator to create a
new ID for your list.
5. Have your LISTSERV POSTMASTER submit your new list to LISTSERV by
using the LSVPUT command. (4)
     LSVPUT newlistname LIST A (CREATE
You should be prompted for the password for the list - use the one that
is stored in the keywords of the list. You may need the assistance of
the LISTSERV POSTMASTER (see above - Privileges) if you do not have the
privileges to create a new list. LSVPUT may also ask if you want to
record your password to disk. If you select yes, the password for your
list will be stored in GLOBALV LASTING A. You will get a message
announcing that newlistname was successfully started. Don't forget to
TELL LISTSERV REV newlistname to check it.
6. After your list is created and tested, if it is a public list, check
Section 3.5 New List Announcements to find out how to announce your
list's availability on the network.

If you are not managing the list from the machine where LISTSERV
resides, instead of LSVPUT, send a message containing your list to
LISTSERV@listnode with the message text before the actual keywords:
     PUT listname LIST PW=list_password

5.3 Modifying the configuration (keyword headers) of lists

If you want to modify the way an existing list works, you must gain a
deeper understanding of the list header or keywords from which you may
choose. First you must obtain a copy of the list keyword headers:
     TELL LISTSERV GET listname (HEADER
Note that this does not work for LISTEARN (EARN's version of LISTSERV).
In that case you will have to get the whole file by omiting (HEADER
(HEADER delivers only the headers of the file, not the subscription
list and continues to process messages to the list under the old
header (keyword) settings.

The list will then be locked which means that no administrative
maintenance (i.e. adding or deleting subscriptions, changing options)
can be performed. If you decide instead, to abandon the changes, be sure
to unlock the mailing list by issuing the command:
     TELL LISTSERV UNLOCK listname
The request to unlock will be confirmed by a response.

See the next section, 5.5 List Keyword Defaults, for information about
the keywords you may modify or add to the header. When you have finished
editing the header file, save it and update LISTSERV by typing:
     LSVPUT listname LIST A (PUT NEWPW
You will be prompted for the password (see Section 5.6 List-Keyword
Recommendations) for the list.

5.4 Adding a group of users to a closed list

If you own a closed list and you want to add a group of users, instead
of interactively typing each name in a mail message or in the TELL
command, you may use the method above, omitting (HEADER and editing
the subscriber list directly. However, the subscribers you add will
not be notified of their subscription automatically. You should also
avoid duplicating lines in this file because the user options are
stored in colums 81-100 and can easily be overlooked (see Section 6
Individual List Subscriber Option Flags).

5.5 List Keyword Defaults

The file, LISTKEYW MEMO (available from any LISTSERV) describes the list
header keywords and their default settings. This is required reading for
someone interpreting a current lists keywords (especially when you are
copying an existing list). Below is a quick reference of the default
settings, but these are not always recommended (see list keyword
suggestions below):

ACK= YES * Acknowledgement messages will be sent to list senders when a
     message from their ID has been successfully sent to the list.
CONFIDENTIAL= NO * The list will be included in the LISTSERV list of
     all lists generated by the LIST GLOBAL command.
ERRORS-TO= POSTMASTER * LISTSERV errors are sent only the the LISTSERV
     Postmaster.
FILES= YES * Files can be sent to the list
FORMCHECK= NO * Files to be sent to the list do not have a FORM of
     REDIST to be accepted.
LANGUAGE= ENGLISH * LISTSERV generated mail and messages to the list
     subscribers will be provided in English.
MAIL-VIA= DIRECT * List mail is processed on the LISTSERV node and sent
     directly to each user.
NOTEBOOK= NO,A,SINGLE,PRIVATE * An automatic log or list archive is NOt
     kept on LISTSERV's A disk, putting every message in a SINGLE
     notebook accessible only to the members of the list. Of course,
     every setting after NO is meaningless since you aren't keeping a
     NOTEBOOK. However if you change this, read Section 5.1
     Introduction to find out why it is a bad idea to store NOTEBOOK
     archives on LISTSERV's A disk.
NOTIFY= YES * the list owner receives notifications of new subscriptions
     and deletions.
REPLY-TO= LIST,RESPECT * when a user replies to a message from the list,
     the reply will be sent to the list, unless the sender specifies
     a different Reply-to mail header in which case the original
     Reply-to header is kept intact.
REVIEW= PUBLIC * anyone can review the list of subscribers.
SEND= PUBLIC * anyone can send mail (and if FILES= YES, files) to the
     list.
STATS= NORMAL,PRIVATE * Elementary statistics on number of mailings,
     etc. are stored (as listname STATS) for access by the members of
     the list only.
VALIDATE= STORE ONLY * a password is not required for users to
     unsubscribe from the list.
X-TAGS= YES * Include X-To: and X-cc headers in the list mail (these are
     not required BITNET mail headers).

WARNING: There must be *no* spaces between commas separating multiple
options of a single keyword (i.e. REPLY-TO=LIST,RESPECT).

Required keywords for which there is no default:

OWNER= USER@NODE * This is the List Owner.
SUBSCRIPTION= OPEN, BY_OWNER, or CLOSED * Whether subscription is by the
     user (anybody), subscription is closed but requests to subscribe
     are automatically forwarded to the list owner, or subscription is
     by the owner only and all requests to subscribe are ignored.

5.6 List-Keyword Recommendations

Unless otherwise specified, the following recommendations apply to all
kinds of lists including Peered and Edited (see Section 7 Edited Lists
and Section 9 Large Lists and Peering for more information).

PW=
Be sure to assign Passwords to all your lists. If you aren't already
aware, it is fairly easy to forge mail (set the from address to a list
owner) and therefore change the keywords (behavior) of a list. To be
completely secure, use the
     VALIDATE= ALL COMMANDS
keyword. The VALIDATE= STORE ONLY checks the password only when you are
PUTing the list on LISTSERV (See Section 5.2 The Cookie Cutter Method
for more information).

To use the password for commands such as DEL indicate it after the
command:
     TELL LISTSERV DEL listname user@node PW=password
WARNING: Unfortunately, VALIDATE=ALL COMMANDS prevents remote users from
signing off a list. If, on the other hand, you want to restrict who can
sign up for a list, yet allow users to unsubscribe, use VALIDATE= STORE
ONLY in conjunction with SUBSCRIPTION= BY_OWNER.

ERRORS-TO= OWNER
Many LISTSERV POSTMASTERS may appreciate your taking responsibility for
handling bounced mail and other errors on your list.

FILES=NO
This will prevent senders from distributing Trojan horse programs, such
as CHRISTMA EXEC to list subscribers. The disadvantages are two: sites
without mail software will not be able to send to your list using
SENDFILE utilities (there are BITNET sites without mail software), and
files you want to distribute to the list (i.e. object code) must either
be embedded in a mail message or be made available via the File Serving
utilities mentioned in Section 14 File Server Functions.

FORMCHECK= REDIST
This would be used in conjunction with FILES=YES (not recommended) which
is the default. If you do allow files in the list, you can require that
the user set the file form to be REDIST:
     CP SP D FORM REDIST
(in the VM/CMS environment) before it is sent to the list . This is
provided as an intermediate step between FILES=YES and FILES=NO to
prevent broken mail software from submitting files to the list unless
they are intentionally modified in this way.

MAIL-VIA= DIST
There are only two values: DIST and DIRECT. You may see DIST, DIST1 and
DIST2 but they are all the same as DIST. The DIST setting sends mail
along the LISTSERV backbone, with the DIST2 protocol to be dropped off
along the way (5). The DIRECT setting sends mail directly to each
destination site. DIST is almost always much more efficient for lists
with significant numbers of non-local subscribers.

NOTEBOOK= YES,X,MONTHLY,PRIVATE
If you don't need a log of all messages, don't set one up needlessly.
However, if you do want to log your traffic, be sure to get permission
from the POSTMASTER or System Administrator and fill in the X with the
LISTSERV filemode s/he wants you to use. See LISTKEYW MEMO for more
information on intervals and privileges.

For CONFIDENTIAL=NO lists, it is recommended that you define a
service area for your list and use the keyword settings:
     CONFIDENTIAL= SERVICE
     REVIEW= SERVICE
     SEND= SERVICE
     NOTEBOOK= <other settings>...,SERVICE
This will help to cut down on the listings in the BITNET list of lists.
Here are the two keywords that limit the service areas.

LOCAL= (default is the same as the LOCAL variable in the LOCAL SYSVARS
file)
The LOCAL keyword allows more than one node to be considered LOCAL for
the purposes of the SERVICE tag (see immediately below).

SERVICE= (area1),(area2)...
This keyword indicates the area outside of which subscription requests
must not be accepted. Valid values for this keyword include LOCAL (see
above keyword), any BITNET node name or Internet host name, or the name
of any country or network. You can use a NOT or a minus sign (-) in
front of a keyword to indicate sites which should be excluded.

5.7 Keyword Options for Small Lists

If you are running a small list and want to notify all list users when
someone makes a subscription, use the keyword NOTIFY= listname@node

If you only want to have one address on the To: mail header, instead of
the list name, use MAIL-VIA= DIRECT and set LOCAL= all the recipient
nodes. Because of the difficulty in maintaining this, this setting is
not useful for SUBSCRIPTION=OPEN lists.

5.8 Formatting REVIEW output

INDENT= (default value 40)
This keyword controls number of columns allowed for list addresses in
the response to the REVIEW command.

5.9 Aliasing List Names

LIST-ID= (default value user ID of list)
This allows users to refer to a list with a name other than the real
name of the list. This is useful for peered or gated lists with names
larger than eight characters (see Section 9 Large Lists and Peering and
Section 13 List gateways to Usenet Newsgroups for more information).

5.10 System Tuning

LOOPCHECK= (default value FULL)
This controls which of the loop-detecting heuristics are used for this
list. The important ones are FULL and NONE. Send mail to LSTSRV-L@UGA
for more information and do not use this unless you have a thorough
understanding of what you are doing.

PRIME= (default value YES)
This controls whether mail for the list is processed during "prime time"
(which is initially defined in LISTSERV SYSVARS, but can be modified in
LOCAL SYSVARS) or waits for "non-prime time". This can be useful for
controlling the load placed on your system by LISTSERV's handling of the
list during periods of heavy local use. Also useful for large lists (see
Section 9 Large Lists and Peering for more information).

SENDER= (default value LIST)
"This controls what value (if any) is placed in the Sender: header field
of messages from the list. This is one of the most controversial 'knobs'
in LISTSERV. If you leave it at the default value LIST, error
messages will be sent back to the list (by properly operating mail
systems).

Usually, LISTSERV's heuristics will catch the messages and send them to
the ERRORS-TO= address(es) for the list. Unfortunately, due to the
endless inventiveness of mail system authors, some error messages may be
missed by the heuristics and sent back to the list, including the
address which caused the error, thereby causing another error, another
missed error message to the list, and a mailing loop which is visible to
every subscriber. When that happens, the Internet purists point out that
the rules say that Sender: should always point to a human who can fix
the problem, not to an automated process like a list.

On the other hand, if you set SENDER= (and thus Sender:) to some other
value, you will alienate the many users of Rice MAIL/MAILBOOK (and quite
probably other mail reading systems) who may be relying on Sender: to
determine which list sent the mail (and perhaps where to save it)". (6)
Common practice within the BITNET community is to use the default, sinc
there is not yet an accepted alternative for indicating the list which
is sending the mail. For small, closed lists you can use the suggestion
in Section 5.7 Keyword Options for Small Lists to limit the Sender
mail header.

5.11 Maintenance Updates

LISTSERV fixes which have been applied are listed on LISTSERV's 191 disk
in the file:
     LFIX LOG

For more information on the LFIX procedure and a list of fixes for your
current release, type:
     TELL LISTSERV AT SEARN GET LFIX MEMO
     TELL LISTSERV AT SEARN GET Vnnn FIXLIST
(i.e. for LISTSERV Version 1.7a use GET V17A FIXLIST). The GET Vnnn
FIXLIST will subscribe you to future additions of the file. LFIX MEMO
will include more information on actually obtaining and installing the
fixes. Even seemingly minor fixes may make a big difference in how well
your local LISTSERV runs.

You may also check to see which fixes are installed on remote LISTSERVs
by typing:
     TELL LISTSERV AT hostnode SHOW FIXES

5.12 Maximum size of a message to a list

If users receive notification that their message was too large to be
sent to a list, you may want to examine the SIZELIM variable to evaluate
whether it is adequate for users on your LISTSERV. In the interests of
network resource economy, you should first evaluate the user's need to
send a large file and suggest sending the file in two parts if sending a
large file is only an occasional requirement.

SIZELIM= (default value taken from LOCAL SYSVARS variable MAILMAXL)
This keyword controls the maximum number of lines for an incoming mail
message to the list. You can raise it above MAILMAXL, but it cannot
exceed the LOCAL SYSVARS variable FILEMAXL. If this is a PEERED LIST,
make sure that you check with the PEERs' POSTMASTERS before changing
this.

5.13 Daily Maximum number of messages

DAILY-THRESHOLD= (default value 50)
This tag sets a limit on the number of messages that may be sent to each
list during a single day (by all users combined). It can be useful if a
list gets into a loop, or just to cut down on the volume of messages.
When that limit is reached, the list goes on HOLD (stops sending mail).
See Section 11.1 Are one or more lists not sending mail? for more
information on HOLD.

5.14 Suppressing Subscription/Unsubscription Announcements

To make sure the owners don't receive all the routing subscription and
unsubscription announcements, add
     NOTIFY= NO

6 Individual List Subscriber Option Flags

The following section (up to Section 7 Edited Lists) is internal
documentation that is subject to change in future LISTSERV releases and
contains information about the internal characteristics of how LISTSERV
lists work. Caveat emptor.

Flags are settings that apply to specific users on a list and can be
altered by the user, usually even if VALIDATE= ALL COMMANDS (since these
settings do not alter the behavior of the entire list). You may include
a default setting for users on a list, by adding to the header of a list
the keyword:
     DEFAULT-OPTIONS= option1,option2,...
For Example:
     DEFAULT-OPTIONS= REPRO,NOFILES

If you add this header to an existing list, the current subscribers will
be assigned a setting automatically. The list owner should judge how to
handle the existing subscriptions. For example, the list owner could
announce the addition of the default option to the list and tell
subscribers how to set it:
     TELL LISTSERV SET listname option
On the other hand, if the list subscribers would prefer to have all
existing subscribers get the new option setting, the list owner can set
the options of users already subscribed by typing:
If you add this header to an existing list you can set the options of
users already subscribed (using the wildcard *@*) by typing:
     TELL LISTSERV QUIET SET listname option FOR *@*

These options are stored in columns 81-100 after the user's name
in either the file "listname LIST" or the file "listname OLDLIST" where
listname is the name of the list. You will only see them when you do a
GET as is described in Section 5.4 Adding a group of users to a closed
list Here is a full list of flags with their column numbers and what
they mean. The default setting (even without Default-options) is listed
first.

6.1 Tired of /Want more Extra Messages from LISTSERV?
Column 81 ACK (A), NOACK (a), MSGACK (M)

These settings control whether users receive interactive acknowledgement
(A), no acknowledgement (a) or a mail message acknowledgement (M) when
mail from their user ID has been successfully sent to the list. By
providing an option flag, subscribers can override the list keyword
setting. People who don't set this option, will have mail
acknowledgement default to the ACK= list keyword setting.

6.2 Going on vacation?
Column 82 MAIL (M), NOMAIL (m)

To temporarily stop mail from a mailing list from filling up your spool,
set the NOMAIL option, or for all lists, send to each LISTSERV node
(listnode):
     TELL LISTSERV AT listnode SET * NOMAIL
Don't forget to turn it back on when you return by typing:
     TELL LISTSERV AT listnode SET listname (or *) MAIL

6.3 Want to restrict a user from sending files to a list?
Column 83 FILES (F), NOFILES (f)

This is similar to MAIL/NOMAIL, but for files. See Section 5.6 List-
Keyword Recommendations under FILES= for more information on the issue
of whether to allow files to be sent to a list.

6.4 Want to get a copy of your mail to a list?
Column 84 NOREPRO ( ), REPRO (R)

By default LISTSERV does not send a copy of mail to a list to its
sender, even if the sender is subscribed to the list. To change this
default, SET listname REPRO or for all users on a list,
     TELL LISTSERV AT listnode SET listname REPRO FOR *@*

6.5 Suppressing the names on mail from LISTSERV
Column 85 SHORTHDR(), FULLHDR(F), FULLBSMTP(S), SHORTBSMTP(s),
IETFHDR(I)

This option controls what the header on your mail messages will look
like. There are three types of headers:

1. Short header, with a minimum number of fields. This is the default
and the most compact. Depending on the mail delivery software, use
either SHORTHDR or SHORTBSMTP.
2. Full header with a number of other fields, plus any header field
unknown to LISTSERV. Depending on the mail delivery software use either
FULLHDR or FULLBSMTP.
3. IETF headers - specified by the Internet Engineering Task Force in
RFC1211 and RFC1123. Use IETFHDR (new in LISTSERV 1.7b).

Consult the code or send a message to LSTSRV-L@UGA for more information.

To make LISTSERV mail look like mail is coming from the list,
     SET listname SHORTBSMTP FOR *@*

6.6 How does LISTSERV track subscriptions?
Columns 86-87 subscription year (yy) or deletion year (yy)
What determines whether it is subscription or deletion year

Columns 88-90 subscription day (ddd) or deletion day (ddd)
This is what day of the year (1-366) that the user subscribed.

Column 91 normal ( ), deletion pending (D), confirmation waived (W)
Confirmation is waived by SET listname NORENEW

These three option flags work in the following manner: When a user
subscribes to a list, columns 86-90 are set to the subscription date and
column 91 is set to normal( ) or the default (DEFAULT-OPTION= NORENEW).
When a user subscribes to a list that includes the RENEWAL= keyword (see
Subscription Renewal below), the date in columns 86-90 is set to the
subscription or confirmation date. When the list is up for renewal,
columns 86-90 are checked against the current date less the renewal
period. If it finds a subscription that will expire soon, it sends a
warning (see Subscription Renewal below), sets 86-90 to the date at
which the subscription will be deleted (if not confirmed) and sets
column 91 to D. If the user sends back a confirm, 91 is set to blank and
86-90 is set to the date of the confirmation.

6.7 Want an unlisted address?
Column 92 NOCONCEAL ( ), CONCEAL (C)

This option flag will conceal your subscription address when the list is
REVEWed (see above).

7 Edited Lists

Lists can be set up so that all mail is sent first to a person, called
the list editor. That person could summarize, spell-check, proofread,
etc. items before they are distributed across the network. No one except
the editor would send mail directly to the list members. This facility
is useful for electronic journals, digests, newsletters and moderated
discussions.

To set up an edited list, use the list keyword EDITOR= (net-
address1),(net-address2).... and the SEND= EDITOR. All mail sent to the
list will then be automatically forwarded to the first person listed in
the EDITOR keyword list. Only the editors (not the owners) are allowed
to mail directly to the list subscribers. Any editor can send to the
list, but only the first listed editor will receive submissions. Editors
receive submissions in mail messages. Make sure the Editor address is
NOT a file server, list server, mailer,etc. - that may result in a
mailing loop.

If you need more than one editor to receive all submissions, you may
create a separate (non-edited) list with just the editors subscribed.
then you can use this small list, editlist in the EDITOR keyword of the
edited list as follows:
     EDITOR=editlist,(editlist)

You may also use the keyword: EDITOR-HEADER= (default value YES) to
control whether mail sent to the editor includes some explanatory
prose preceding the message. This preface includes the ID of the
original sender and notifies the editor that s/he can forward the
submission to the list and the preface will automatically be removed.
If the list is merely moderated, you probably want this heading prose.
If it is digested, you probably don't.

Another suggestion for Edited lists is to log all requests for
subscriptions. If you don't do Subscription Renewal (see Section 8
Subscription Renewal), or don't care to keep track of the subscription
flags above, this can be an easy way to cut down on bounced mail and
subscription patterns. (7)

8 Subscription Renewal (the RENEWAL= list header)

You can set up a list so that the subscriptions will be regularly
expired and renewed. The renewal keyword is in the form:
     RENEWAL= NONE | item1<,item2<,...>>
where an item can be:
a) an interval: MONTHLY, YEARLY, WEEKLY, BI-MONTHLY,BI-YEARLY, BI-
WEEKLY, or another numeric division such as 3-MONTHLY (every 3 months -
quarterly).
b) an absolute date yy/mm/dd (once on this day), mm/dd (every year on
this day), dd (every month on this day)
c) the delay: DELAY(n) in days between when users are asked to confirm
their subscription and when the user is removed from the list. The
default is 7 days

Where there is more than one interval specified (i.e. the default) the
smallest one is used.

For each user and list, the date of the last subscription/change in the
subscription (SET) is kept (for more information see Section 6.6 How
does LISTSERV track subscriptions?). An internal LISTSERV procedure,
LSVEXPIR, will check all these values once a week against the
RENEWAL= keyword in the list headers. (8)

When the user's subscription is up for renewal, a message is sent (this
is customizable - see Section 12 Customized List Messages - Mailforms)
to ask them to send a message:
     CONFIRM listname
or they will be removed from the list after the delay period. The list
owner is also sent mail telling them when users are asked to confirm and
when they are removed. The date before the subscriber is removed from
the list also depends on when the LSVEXPIR procedure runs to actually
removes the subscriber.

A common problem with subscription renewal is that some lists
subscribers have a different FROM address than their list subscription
due to aliases, redistribution of the list (see Section 13 List Gateways
to Usenet below) or other system settings. A list owner can confirm a
subscription for a user, but I recommend asking the user resubscribed to
keep the most up-to-date addresses for list subscribers, especially if
the list is open. In the case of redistribution, you should waive list
renewal for redistlist@node by typing:
     SET listname NORENEW for rdistlist@node
See Section 6.6 How does LISTSERV track subscriptions? for more
information on NORENEW and see Section 11.6 Are you puzzled why mail is
bouncing? for more information about invalid addresses.

9 Large Lists and Peering

Large lists (i.e. 2000+) can be a drain on the LISTSERV node's CPU and
you may need to increase virtual storage to improve performance. You can
also alleviate some of the strain, by using the MAIL-VIA: DIST and
considering using Peered lists which break large LISTSERV lists into
smaller distributed ones (geographically located at other LISTSERV
sites).

To set up a peered list, consult the instructions in LISTOWN MEMO. You
must coordinate with the LISTSERV sites where your list will be Peered
to set up lists with similar keywords. It is strongly recommended, but
not required, that these lists have identical names and passwords. To
find LISTSERV sites to peer your list, send a message asking for
volunteers to your list, LSTSRV-L@UGA, and/or the POSTMASTER at a
LISTSERV site found in LISTSERV SITES (available from LISTSERV@BITNIC).
You will be adding a list keyword PEERS=(peer1),(peer2)... . If you
are splitting an existing list, you will be using the MOVE command to
move your users from one peer (your original node) to another
interactively or by mail.

A lot of Peered lists are set up so that the keywords reside in a
separate file (named listname KEYWORDS) from the list subscriptions,
list name header and password keyword PW=. To direct LISTSERV to the
listname KEYWORDS file, the listname LIST must have a keyword named .IK
(insert keywords). The listname KEYWORDS file can also reference another
keyword file with the keyword .IK filename (insert the file named
filename KEYWORDS) and so on. Some lists include a topology (listname
TOPOLOGY) file by means of a keyword named .IT filename. In order to
update keywords, you may have to GET and PUT the listname KEYWORDS file
instead of the listname LIST file (or the appropriate keywords or
topology file). Also, when you GET a peered list, the remote peered list
are returned to you as LISTNAME HOSTNODE instead of as LISTNAME LIST.

Most peered lists need different keyword files because of different
settings such as what disk the NOTEBOOK is stored on (see Section 5.6
List-Keyword Recommendations under NOTEBOOK=). If you use the .IK method
and have a peered filelist (see instructions in Section 14.5 Peered
FILELISTs), when a list owner changes the keywords of a peered list (by
changing his/her local copy only), the changes will be propagated out
automatically after the local copy is updated. However changes must be
made by the list owner. The LISTSERV POSTMASTER is not authorized to
change the offsite peers.

You may want to use the keyword LIST-ID= (default value user ID of list)
when setting up Peered lists especially when they are gated (See List
Gateways below). This allows users to refer to a list with a name other
than the real name of the list. This is useful for peered or gated lists
with names larger than eight characters (see Large Lists - Peered Lists
and List Gateways topics below). For example, there is a group of peer
lists redistributing the Internet list Info-IBMPC. Most of the peer
lists are named IBMPC-L, but the peer is named $$INFOPC (for historical
reasons). All carry the List-ID INFO-IBMPC, so a potential subscriber
may send SIGNUP INFO-IBMPC to any LISTSERV and have the request sent to
the appropriate LISTSERV even though a list literally named INFO-IBMPC
could not exist on any VM/CMS system (since it's over 8 characters).(9)

Large lists may also have trouble if they have both keywords
SUBSCRIPTION= OPEN and NOTIFY=YES. Since LISTSERV may get tied up
while users unsubscribe, if you want the owner to be notified, consider
setting SUBSCRIPTION= BY_OWNER. Also, consider using the PRIME= NO
option to process list requests at off hours. See Section 5.6 List-
Keyword Recommendations for more information on PRIME.

10 Archives (List Notebooks or Logs)

The NOTEBOOK= YES keyword creates a file of all messages sent to the
list. However, if the POSTMASTER moves or changes the name of a list,
here are some things to watch out for:

If you have to change the names of archives that are sequentially
numbered, make sure to do a
     TELL LISTSERV DATABASE REFRESH listname

When you are rebuilding/renaming archive files, don't forget to delete
the associated DBINDEX and DBNAMES files to regenerate the lists for the
index and automatic numbering commands by typing:
     TELL LISTSERV CMS ERASE listname DBINDEX filemode
     TELL LISTSERV CMS ERASE listname DBNAMES filemode

If you want to set up the Notebook files based on volume number and year
(like a newsletter), you must edit the listname COUNTER file to restart
numbering at the beginning of each year.

To move archives from one list to another, rename the files and use
XEDIT to
     c/oldname@jhuvm/newname@jhuvm
The DBINDEX and DBNAMES files should be erased. Only rename the archive
files and the COUNTER file if you use a separate file per posting
(NOTEBOOK=SEPARATE).

11 Troubleshooting - Miscellaneous problems

11.1 Are one or more lists not sending mail?

Check to make sure that LISTSERV is disconnected (NOT not logged in) by
typing
     Q LISTSERV.
If one of your LISTSERV disks fill up, lists which are active go into a
hold state and postpone all new mail. When your POSTMASTER or System
Administrator has cleaned up the disk or enlarged it you must
specifically take the list out of the hold state by typing:
     TELL LISTSERV FREE listname

To find out what lists are held,
     TELL LISTSERV LIST
and look for the line "* Note: This list is on hold" immediately
following any held lists.

See Section 5.13 Daily Maximum number of messages for information on
other list limitations.

POSTMASTERS may be interested in the LISTSERV Line Monitor described in
LMONUSER MEMO available from LISTSERV@SEARN (you must be a registered
LISTSERV contact to request it). The line monitor can help you
manage your spool area, control your BITNET lines and keep statistics.

11.2 Are you getting no LISTSERV response?

If you make more than 10 errors consecutively, LISTSERV will disable
your ID by suspending LISTSERV services from you ("served off").
LISTSERV will send you a message informing you of your predicament and
how to resolve it, but if you miss the information, here's how to get
out of your state. Simply have another user type:
     TELL LISTSERV SERVE yourid
The person doesn't even need to be the POSTMASTER. This feature of
LISTSERV is important for non-human generated errors so don't take it
personally if you get served off.

11.3 Is LISTSERV misplacing your PUT's?

If you find that your PUT requests result in the files being sent to
your reader, your LASTING GLOBALV may have been corrupted. Try using
using the option TO in LSVPUT such as:
     LSVPUT listname FILELIST A (PUT TO listnode
Please contact your system administrator or look in LSVPUT EXEC for more
info.

11.4 Are your requests to DELETE a file from a file list result in
requests getting forwarded to some LISTSERV POSTMASTER?

You may have a problem with the FILEID for that file (see Section 14
File Server Functions). The LISTSERV POSTMASTER should identify the disk
mode where the file is stored (for instance, monitor the LISTSERV
console and send a TELL LISTSERV CMS LISTF filename filetype *) to it.
Then you can identify the disk in a TELL LISTSERV CMS ERASE filename
filetype filemode.

11.5 Are you running up against the 256K daily limit on getting files
from LISTSERV?

The LISTSERV POSTMASTER can add you to the GETQWAIVE variable in the
LOCAL SYSVARS file (or create the variable if it doesn't exist yet).
Alternatively, the postmaster can write some REXX code into the LSV$GETQ
exit to bypass the limit for log files for list owners.

11.6 Are you puzzled why mail is bouncing?

Here is why some list addresses bounce:

1) Someone has moved from the address to which they were subscribed on
the list, but friendly systems folks made the old address work anyway.
Now someone is doing some housecleaning and deleted the old alias. The
subscriber has been receiving the mail fine, not knowing there was a
problem and if you summarily delete them, they might well be upset.

2) There is a software problem at the receiving site (or a gateway
servicing that site). The problem is likely to be solved in the next
couple of days - especially if you let someone know about the problem.

3) There is software at the subscriber's site which is refusing to
deliver the mail because disk space has been exceeded or some other such
temporary problem.

The easiest thing for a list owner to do is to delete a subscriber as
soon as mail to them is bounced. This may or may not be appropriate
depending on your judgement on what level of service you can/want to
provide for the list. There may be a significant investment of time
needed to figure out why the mail bounced and there are not any good
tools to make it easy to do a good job. (10)

11.7 Need to get rid of mail that violates BITNET usage rules (i.e.
broadcast messages or files)?

To see what LISTSERV jobs are waiting to be processed POSTMASTERS or
users with the correct privileges (see your System Administrator) can
type:
     Q RDR LISTSERV ALL

To remove bogos jobs from the LISTSERV Reader, the POSTMASTER should
1) get the job number by typing:
     Q RDR LISTSERV ALL
2) Check the file by typing
     CP TRAN LISTSERV RDR #### *
     PEEK ####
3) If it is not the file you want to get rid of, return it to LISTSERV
by typing:
     CP TRAN RDR #### LISTSERV
and then get rid of the file from the POSTMASTER's reader (user ID)
     PURGE RDR ####

12 Customized List Messages - Mailforms

You can customize (by list) the messages that LISTSERV sends to users
upon completion of a command. You will be working with a LISTSERV file
called $DEFAULT MAILFORM.

1. To create a mailform, get a copy of $DEFAULT MAILFORM for the
templates to see what the default messages are. Copy the form/s you
want to customize for a list and put them in a file named listname
MAILFORM (i.e. :ADD and :SIGNUP for subscriptions). The forms you don't
customize will be taken from the $DEFAULT MAILFORM file.

2. Create the information you want to send out in the listname MAILFORM
file. Keep in mind that LISTSERV will try to concatenate consecutive
lines as long as they start from the first column. You can get around
this by using .FO OFF (to turn off formatting) at the beginning of a
block of text you don't want formatted and then .FO ON to turn it back
on.

3. The text after the :formtag (i.e. :ADD :SIGNUP) is automatically
enclosed in the subject line. You may customize this to your
satisfaction.

4. If you have text to go in multiple forms, create a dummy form (i.e.
:$SIGNUP) and use the .IM command (i.e. .IM $SIGNUP) to enclose the text
in the multiple mailforms.

5. Make sure that no lines begin with . (you can move it to the second
column if you really need to use a period).

6. Don't use single quotes. Double quotes are okay. If you really need
single quotes, use them back-to-back. Single quotes in MAILFORM files
are used to enclose expressions (i.e. variables or function calls) which
are evaluated at the time the mailform is used.

7. In order to put your mailform on LISTSERV's A disk, the LISTSERV
postmaster must use the PUTC command. For example,
     LSVPUT listname MAILFORM A (PUTC

13 List gateways to Usenet Newsgroups

There is a list of LISTSERV lists that are gated to Usenet Newsgroups
available from American University. To get it type:
     TELL LISTSERV AT AUVM GET NETGATE GATELIST
You should also GET NETGATE POLICY for an introduction to lists,
Newsgroups and how gateways are established. You can also obtain
information about the gateway software by typing:
     TELL LISTSERV AT PSUVM GET NETNEWS PACKAGE

If your list is gated, you may want to set the name of the list which
will be used by Usenet using the keyword NEWSGROUPS= (default value
bit.LISTSERV.userid of list).

There is some information about other links to LISTSERV in the file
LISTLINK MEMO available from any LISTSERV.

14 File Server Functions

LISTSERV provides features to store and distribute files in conjunction
with, or independently of the list management features. The LISTSERV
file server functions was designed based on those of NETSERV, which is a
package that is used to distribute BITNET network routing information
each month. (11) On LISTSERV, files are organized in groups by topics or
lists called FILELISTs. The index to all FILELISTs is the LISTSERV
FILELIST.

The FILELISTs have a special syntax which include whether a file is a
FILELIST (/F/), File Access Codes (FAC's) that control who can modify
FILELISTs and files, and updated information on the format, description
and modify time for each file. Get LISTSERV's LISTFILE MEMO for a
complete description.

Also, be aware that LISTSERV does not necessarily use the filename
listed in the FILELIST to store it on LISTSERV's disks. There is a
special file associated with each FILELIST with the same filename as the
FILELIST and the filetype FILEID (i.e. LISTSERV FILEID) that contains
LISTSERV's internal name for the file. This file should not normally be
modified.

14.1 Obtaining files from the LISTSERV File Servers

LISTSERV stores files the same way it stores list archives and the help
files. If you want to obtain the LISTSERV FILELIST, you can get it
interactively (or by mail - see Section 2.2 Issuing LISTSERV Commands):
     TELL LISTSERV GET LISTSERV FILELIST

14.2 Adding files to an Existing FILELIST

Before you add new files to your LISTSERV, please familiarize yourself
with the disk allocation of your LISTSERV files. See the note above in
Section 5 Setting up New Lists for a description of special
considerations.

As a LISTSERV maintainer or owner of a FILELIST, please note the PUT
File Access Code (FAC) on the FILELISTs in LISTSERV FILELIST. Do not
modify the CONTROL, INFO or TOOLS FILELISTs because they are updated by
the LISTSERV Master Coordinator (FAC=LMC), Eric Thomas. For information
on adding your own FACs, see the discussion in LSV GUIDE

1. Get a copy of the FILELIST (i.e. netinfo) to which you wish to add
the new file in order to create an entry for the new file (see step 6
for information on updating a list or FILELIST by mail):
     TELL LISTSERV GET netinfo FILELIST (CTL
When you obtain this file, the FILELIST will go into a locked state.
This behaves similarly to a GET request for a mailing list (see
Section 5.3 Modifying the configuration (keyword headers) of lists).

2. When you edit the copy of the FILELIST, note whether it has been
organized by a table of contents or includes sub-FILELISTs (by using /F/
in the first column) and choose the appropriate place to add your new
file.

3. If you want to copy the line preceding the place where you want to
insert the entry of the newfile (in XEDIT use " in the prefix area),
make sure you change the filename, filetype, GET and PUT FAC's (check
the top of the file for locally defined FAC's) and the file format.
LISTSERV will automatically fill in the rest of the fields until the
description if after the file format, you type five periods separated by
one space each followed by the description:
     . . . . . This is the description of the file.
Also if you will be regularly adding a file with the same filename or
filetype (i.e. listname *), you may use an entry with > in the first
column and the wildcard character * in the first column of the filename
or filetype field. When you add the file, a new entry will be created
using this line's FACs as default.

4. When you save a copy of the FILELIST on your A disk (for example),
return it to LISTSERV interactively using the LSVPUT EXEC (distributed
with LISTSERV):
     LSVPUT netinfo FILELIST a (PUT
You will be prompted for the LISTSERV store password (see Section 2.1
Who has privileges?).

5. You will receive a confirmation message from LISTSERV that the
FILELIST had been refreshed, noting that the file entry you added does
not exist yet.

6. Use LSVPUT to add the new file to LISTSERV:
     LSVPUT filename filetype a (PUT

or send it by mail by sending mail to LISTSERV@listnode with the
message text:
     PUT filename filetype filelist "TITLE=description..." PW=password
                                                                    (12)
When issues by mail, the PUT line MUST fit within 80 bytes (columns) of
ONE record! If it doesn't you may accidentally have your password
"folded" onto the next line where it is treated as part of the file and
will be seen by anyone who GETs the file! On the line after this PUT
command, the actual file should be included. Do not include a signature
at the end because it will be interpreted as part of the file.

7.You should receive a confirmation message from LISTSERV that your file
has been stored.

14.3 Deleting a file from an existing FILELIST

To delete a file you can type:
     LSVPUT filename filetype (DELETE

To delete the file by mail, send a message to LISTSERV with the
following as the ONLY line in the body of the text of the mail:
     PUT filename filetype filelist PW=password

If your system adds a blank line or anything else after the text of the
mail, then this will NOT delete the file, but instead replace it with
whatever is there (i.e. a blank line).

You will have to GET the FILELIST (see above step 1) to remove the
reference to the now-defunct file. You may have to specify an additional
option (FILELIST filelistname) if there are two LISTSERV files with the
same name on different FILELISTs. See the LSVPUT EXEC for details.

14.4 Creating your own FILELIST

1. Add the new name to the LISTSERV FILELIST (steps 1-5 above) to add a
reference to your new FILELIST. Don't forget to precede the name with
/F/ in the first column.

2. Create the new file newname FILEID (you may want to copy an existing
FILEID file to make sure you have RECFM=F and LRECL=80). Edit the file
so only the following line appears
     1
 Check FSV GUIDE for more information on allocating disks dynamically.
The FILEID file is the translation between LISTSERV's internal name for
the file and the name recorded on the FILELIST (see the discussion
in Section 14 File Server Functions).
     LSVPUT newname FILEID A (PUTC

3. Create the newname FILELIST - as I suggested above in Section 5
Setting up New Lists, you may want to copy and edit an existing FILELIST
to use as a guide. You may even use LISTSERV FILELIST. Make sure you
delete all the non-comment lines and create entries only for the files
you want this list to contain and that non-FILELIST files are not
preceded by /F/.
     LSVPUT newname FILELIST A (PUT

4. LSVPUT newfile filetype A (PUT

14.5 Peered FILELISTs

Just as you can make distributed mailing lists, you can also create
distributed FILELISTs. Review the items in Section 9 Large Lists and
Peering to get the general idea. After you have a list of the peers,
include a PEERS= (peer1),(peer2)... keyword in the comments section at
the top of the FILELIST. When a non-local file is PUT to the FILELIST at
any of the peered sites, the file will automatically be sent to all the
sites included in the PEERS= keyword.

The file entries that contain local files must include the /...L/ flag
in column 1. This flag indicates that this file is not available on
the other peered filelists (or, if available, the contents are not the
same), and PUT commands should not be redistributed to other peers.

14.6 Maximum file length

If you want to alter the maximum length of a file a user may retrieve,
change the variable MAXGETK in LOCAL SYSVARS. Any user is allowed to
retrieve one file exceeding his/her quota on any given day, but then
s/he can't order anything else that day. Other similar settings are
documented in LISTSERV SYSVARS. The code is contained in LSV$GETQ EXEC.

14.7 Troubleshooting - only getting the header of your FILELIST request?

If you are only receiving the header when you request a FILELIST, check
the "parent" FILELIST (where the entry for the requested FILELIST is
contained i.e. LISTSERV FILELIST). This message usually means that there
is no file code /F/ in column one.

14.8 Packages - Sending out a group of files with one GET command

Packages are special files that group a set of files in a FILELIST
together (they can still be accessed individually).

1. Follow the instructions for adding files to an existing FILELIST
creating entries for all the files you want to group together. Also, add
an entry for the file:
     packname $PACKAGE
where packname is the name you have chosen for the grouping.

2. Create a file named "packname $PACKAGE" that looks something like:
     * PACKNAME $PACKAGE:
     * Shipping list for PACKNAME package
     *
     * other comments here such as electronic mail address
     *
     * filename filetype filelist
     *==========================
     packname $package packlist
     utility   exec     packlist
     second   exec     packlist

3. LSVPUT all these files on the packlist FILELIST including packname
$package. When they are available, users will be able to
     TELL LISTSERV GET packname PACKAGE
and all files will be sent. Note that the $ is not included on the GET
command.

14.9 Automatic File Subscription

There are two types of functions LISTSERV offers to users who want to
"subscribe" to a file so they can be notified when the copy changes and
automatically be sent updates. Automatic File Distribution (AFD)
automatically ships an updated file to a list of users and File Update
Information (FUI) notifies a list of users when a file has been updated
(but does not actually send the file).

To subscribe to File Update Information for a file (i.e. FSV GUIDE
available from LISTSERV@ALBANY), type:
     TELL LISTSERV AT albany FUI ADD fsv guide PW=newpsswd
To sign up for an Automatic File Distribution:
     TELL LISTSERV AT albany AFD ADD fsv guide PW=newpsswd
To get off either FUI or AFD, substitute the command DEL for ADD.

A password may be used to secure the subscription from potential
"crackers" if desired.  A password can be defined for each user.
LISTSERV POSTMASTERs can disable or restrict the passwords.
For a user to set a password type:
     TELL LISTSERV AT albany PW ADD newpsswd
To remove it, substitute DEL for ADD
If users forget their password, the local LISTSERV POSTMASTER can find
the password for them:
     TELL LISTSERV PWC QUERY user@usernode
However, you must contact a remote LISTSERV's POSTMASTER to find a
forgotten password on his/her LISTSERV.

For more information on how to control password access to your LISTSERV,
check LSV$PW EXEC. For more information see the LISTAFD MEMO available
from any LISTSERV.

15 Searching LISTSERV Files

LISTSERV provides some limited database functions for searching for a
string in a specified database (i.e. list archives). To find out what
databases are available on a particular LISTSERV type:
     TELL LISTSERV database list

There are two ways you can search on a database: interactively using
LDBASE and by mail sending a command file. To use LDBASE, you must
first GET LDBASE EXEC and GET LSVIUCV MODULE unless they are available
on your local applications disk (see your systems administrator for more
information).

Here are two examples of a search of the string 'confirm' on the
database LSTSRV-L which is located on the LISTSERV at UGA:

To query a remote database (i.e. at UGA), type:
     LDBASE uga
     SEARCH 'confirm' IN LSTSRV-L
     SENDBACK PRINT
     QUIT

To query as an mail command job, the following commands into a file
named thisfile text a :
SENDFILE thisfile text a LISTSERV AT uga
     //ListSrch JOB Echo=No,Reply-via=msg
     Database Search DD=Rules
     //Rules DD *
     SEARCH 'confirm' IN listname
     PRINT
     /*

Another useful database to search is the LISTS database which
contains the List of Lists. First, to find the closest LISTS database
which resides on some, but not all LISTSERV backbone servers, query
the local LISTSERV PEERS names file:
     LDBASE bitnic
     SEARCH ':BACKBONE.YES LISTDB(YES)' IN PEERS
     SENDBACK PRINT
     QUIT
This will give you all nodes that contain the LISTS database.
Choosing your nearest node, you can search the LISTS based on
keywords:
     LDBASE RUTVM1
     SELECT * in LISTS where subscription=open and title contains EDUCOM
     SENDBACK PRINT
     QUIT

For more information on searching, GET LISTDB MEMO from LISTSERV. For
more information on the format of an mail command job, GET LISTJOB MEM
from LISTSERV. There is also a list named LDBASE-L at UKANVM concerned
with searching strategies.

16 Acknowledgements:

Many thanks to the following people without which I would still be
completely in the dark:
Ben Chi for writing the "File Server Bible" the LSV Guide available from
LISTSERV@ALBANY
Diane Kovacs for her helpful overview of list ownership for non LISTSERV
guru-wannabees (Kovacs PRV2N1 available from LISTSERV@BITNIC)
David@dartcms1 for the List-of-Lists Readme file.
Marty Hoag for help with Internet access to LISTSERV
Jim McIntosh for information about List-news gateways.
Helpful members of the LSTSRV-L list for their friendly (and quick!)
responses especially Herb Huston and Mark Williamson.
Larry Snodgrass, my office-mate for putting up with my incessant
questions.
Eric Thomas for providing us with such a useful program to write about!

Footnotes
---------
(1) To obtain this document, send mail to LISTSERV@BITNIC with the
message text (the subject line is ignored): GET BITNET INTRO.
(2) Internet addresses generally look like [e-mail]
and BITNET addresses look like user@nodename (or, in some cases,
[e-mail]). Since LISTSERV resides on BITNET, Internet
subscriptions may appear in their BITNET accessible form, i.e.
user%host.domain.xxx@gatenode. In the examples, although the user names
are given in BITNET format, you may substitute the "%hack" Internet
addresses in the command line. Check the file BITNET GATES from
LISTSERV@BITNIC to find Internet-BITNET gateways in your area.
(3) Contributed by Marty Hoag
(4) The LSVPUT exec is provided with the LISTSERV distribution. Contact
your LISTSERV POSTMASTER if it is not available on your public disks.
(5) DIST2 is implemented as a command job as described in the LISTSERV
documentation LISTJOB MEMO and LISTDIST MEMO.
(6) Keyword information courtesy of Mark Williamson, LSTSRV-L LOG9110
([e-mail])
(7) Suggested by John Unsworth, PMC@NCSUVM - editor of Postmodern
Culture list.
(8) Eric Thomas, LSTSRV-L LOG8705 available from LISTSERV@UGA.
(9) Information courtesy of Mark Williamson, LSTSRV-L LOG9110
([e-mail]
(10) From LSTSRV-L, 9 Oct 91 J. Philip Miller ([e-mail]).
(11) To get more information on NETSERV, first you must find which
NETSERV "serves" your area:
     TELL NETSERV AT BITNIC QUERY SERVICE
Note that, like LISTSERV you can send a mail message instead of an
interactive message by sending the message text (subject line is
ignored):
     QUERY SERVICE
to the address NETSERV@BITNIC. Once you have the node MYNODE that hosts
the NETSERV in your service area, you can get the helpfile by typing:
     TELL NETSERV AT mynode GET NETSERV HELPFILE
(12) Note that without the cooperation of the list manager who can
update the FILELIST to add a remote user to the FAC list and a file
entry to the FILELIST, remote users cannot add files(instructions
courtesy of Marty Hoag).