Organization: Computing Center, Virginia Tech.
Newsgroups: bit.listserv.lstsrv-l
Date:         Thu, 16 Apr 1992 12:38:29 EDT
From:         Greg Kroll <USDGK@VTVM1.BITNET>
Subject:      Maintaining a FILELIST via e-mail
              15 Apr 1992 12:26:30 EST from <COTRSSM@SEA04VM.NAVSEA.NAVY.MIL>

On Wed, 15 Apr 1992 12:26:30 EST Scott Mattes said:
>...deleted...
>
>  How do I use the PUT command?  I want to take a file on my disk,
>transmit it via TCPIP to a list I am now part 'owner' of and stash it so
>that others on the list can retreive it.
>

Scott,

  I hope this isn't overkill, but I wrote the following for someone using
our LISTSERV here at Virginia Tech.  I welcome comments and criticisms
from all.  Hope you find it useful.

--Greg Kroll

+++++++++++++++++++++++++++++++++ cut here ++++++++++++++++++++++++++++++

Updating a LISTSERV FILELIST via electronic mail (e-mail)



By:  Gregory Kroll
     Senior Programmer/Analyst
     Virginia Tech
     Blacksburg, Va. 24060

     USDGK@VTVM1, usdgk@vtvm1.cc.vt.edu



Preface
_______


LISTSERV users on non-VM hosts can maintain a FILELIST file via e-mail with the
following restrictions.

o   E-mail  necessarily limits the record length of any stored file to 80 char-
    acters or less.

o   You must include a PUT command in the body of the e-mail.  It will be  used
    to  store  the  file.   The entire PUT command must fit on one 80-character
    line; no line wrapping is allowed.



Introduction
____________


I will assume you have at least scanned the LISTSERV document File Server Func-
tions, to familiarize yourself with LISTSERV FILELIST's.  If not, you  can  ob-
tain this document, from any handy LISTSERV, with the command "INFO FILES".

The  only  significant  problem  in maintaining a LISTSERV FILELIST file from a
non-VM host is handling records greater than 80 characters.    This  limitation
means the amount of text used to describe the contents of the file (i.e., which
appears  in  the "File description..." area of the FILELIST file) is limited to
as many characters as are left on the line after all required PUT keywords  are
entered.    With  this procedure you are limited to approximately 30 characters
for any file description.  However, the benefit of remote updating (i.e.,  from
a  non-VM  host)  is that LISTSERV does all the work; you simply send it e-mail
and LISTSERV does the rest.

You begin by entering a LISTSERV PUT command as the first line of  your  e-mail
message.   The PUT command names the file to be stored, identifies the FILELIST
file with which it is associated, secures the transaction with a password,  and
gives  a  brief description of the file contents.  The remainder of your e-mail
becomes the contents of your stored file.  Upon receiving this e-mail  LISTSERV
extracts  the PUT command and creates a CMS file with the name given in the PUT
command.  LISTSERV then automagically updates the FILELIST  creating  an  entry
for this new file.



Preliminaries
_____________


The  LISTSERV  administrator at the site hosting the list (e.g., Virginia Tech)
must set up a FILELIST template with an agreed on file  naming  convention  for
all  stored files.   The file naming convention is a character pattern match on
the filename or filetype, or any portion thereof.   Although use  of  "generic"
entries  (a  FILELIST template) is not mandatory, their use is strongly encour-
aged as it makes the update process much easier.  More on this later.

You must tell the LISTSERV administrator the e-mail address of everyone author-
ized to store files to the FILELIST.  Authorized userids can be different  from
the owner's of the list.

You  must  use  a LISTSERV password for authentication of the PUT command.  Use
your LISTSERV "personal password" (established with the PW ADD command), or the
password of the associated LIST,  or  a  separate  one  created  just  for  the
FILELIST.



Procedure
_________


1.  Send e-mail to LISTSERV@<node>
    e.g., LISTSERV@VTVM1 or LISTSERV@VTVM1.CC.VT.EDU

2.  The first line of e-mail text (body) must be the required PUT command.  The
    syntax is:

    PUT filename filetype filelist PW=password "TITLE=...file description..."

    where:

    o   "filename" and "filetype" can be up to 8 characters long, consisting of
        letters  (A-Z), and numbers (0-9).  Some special characters are allowed
        ($,#,@,+,-,_) but I would avoid using any of them except for the hyphen
        (-).  The filename and filetype (or both) must conform to the character
        pattern defined in the FILELIST.

        For example, let's say the FILELIST template is defined as follows:

        > *XYZ*  *  PRV OWN .  .  0 ........ ........ Template, not a real file.

        This means the filename of the stored file must contain the  characters
        XYZ,  in that order, anywhere in the name.  The filetype, designated by
        an asterisk, can be anything desired.  Examples of valid  PUT  commands
        could be:

        -   PUT XYZ MEMO ...
        -   PUT MYXYZ FILE ...
        -   PUT XYZ9112 SCRIPT ...
        -   PUT ABCXYZ35 PASCAL ...

        As another example:

        > *   EXEC  PRV OWN .  .  0 ........ ........ Template, not a real file.

        Files  stored  for this FILELIST can have any filename, but must have a
        filetype of EXEC.  Examples of valid PUT commands could be:

        -   PUT A2E EXEC ...
        -   PUT LOOKSEE EXEC ...
        -   PUT DOITALL EXEC ...

    o   "filelist" is the FILELIST name.

    o   "password" is one of the password's noted above.

    o   "...file description..." is the text used to describe the file.

    NOTE: You must enclose in double quotes, as shown, the  TITLE  keyword  and
    associated  text.    The amount of text allowed for the file description is
    whatever will fit on the remainder of the line.  DO NOT WRAP THIS  TEXT  TO
    THE NEXT LINE.

3.  Follow  the  PUT  command  IMMEDIATELY  with the text to be stored.   There
    should be no blank lines between the PUT command  and  the  first  line  of
    text.

    NOTE: ALL lines following the PUT to the end of the mail become part of the
    file,  including  your signature.  Unless you want your signature to appear
    as part of the stored file, remember to turn off  any  automatic  signature
    feature of your mail software.

4.  Send the file and await confirmation mail from LISTSERV similar to:

    File "<filename> EXEC" has been successfully stored.

5.  You  may confirm that the file was stored and the FILELIST properly updated
    by sending the following commands as the body of an e-mail message.

    GET <filename> <filetype>
    (e.g., to get a copy of the file, use: GET LOOKSEE EXEC)

    INDEX <filelist>  (or, GET <filelist> FILELIST)
    (e.g., to get an updated copy of the FILELIST, use: INDEX TEST-L)



Replacing files
_______________


To replace (overwrite) a file, enter the filename and filetype on the PUT  com-
mand  so  it  matches an existing file in the FILELIST.  When LISTSERV receives
this e-mail it will replace the existing file and update the  FILELIST  to  re-
flect the new file characteristics.



Deleting files
______________


To delete a file (this procedure can also delete NOTEBOOKS), send a PUT command
as  the  ONLY  line  of  text in your e-mail message.  Include the filename and
filetype of the file to delete, the filelist name, and your password  (you  can
omit  the  TITLE keyword).   Be sure this is the ONLY line of text in the file.
If anything appears after the PUT command, LISTSERV will replace the file  with
the  remaining  contents  of  your e-mail message, even if this is a blank line
(put there by you or your mail software).  Remember to turn off  any  automatic
signature feature.

Upon receiving this e-mail LISTSERV will:

o   Erase the file.

o   Update the FILELIST and remove the line referencing this file.  A very nice
    feature,  meaning  you do not have to GET the FILELIST and remove this line
    yourself (which is the usual way of doing it on VM).



WARNING to the host LISTSERV site regarding FILELIST templates
______________________________________________________________


The remainder of this document  is  intended  for  the  LISTSERV  administrator
(e.g.,  POSTMASTER  or  NAD)  of the site hosting the LIST.  It is included for
completeness and taken from my own experience with LISTSERV FILELIST templates.

Because of the tree structure of LISTSERV FILELISTs and the  sequential  nature
in which they are searched, it is possible for an authorized person to:

o   be prevented from saving files to a FILELIST.
o   be unable to GET a saved file.

Three conditions must be met for this to happen.

1.  The  user DOES NOT explicitly name the FILELIST on a PUT or GET command, or
    as an option when using the LSVPUT exec.

2.  The FILELIST with a template defined must appear in the  LISTSERV  FILELIST
    file BEFORE the target FILELIST, i.e., appears first in sequential order.

3.  The CMS filename or filetype of the desired file, happens to match the tem-
    plate defined in another FILELIST.

An example will clarify.

UserA  is  the  owner  of list LIST-A, at node NodeX.  UserA maintains his list
(and FILELIST) from a remote VAX host.  The LIST-A FILELIST has  the  following
template defined:

> *  *I*  ALL OWN .  .  0 ........ ........ Template, not a real file.

This means UserA can create any file as long as an "I" appears somewhere in the
filetype (e.g., MYLIST DIRECTRY, in CMS terms).

Now  NodeX  also  has  many  local list owners with their own FILELISTs.  Local
user, UserB, maintains a FILELIST for his list called  LIST-B.    Today,  UserB
wishes  to  save  a file called "920312 FASTLINE" to his FILELIST.  Following a
well established procedure, UserB retrieves the  LIST-B  FILELIST,  creates  an
entry  for  the new file, then sends the FILELIST back to LISTSERV for storage.
UserB then attempts to save the file by placing the following  PUT  command  in
the file and sending it to LISTSERV for storage.

PUT 920312 FASTLINE PW=<UserB_password>

Notice  that  UserB does not explicitly name his FILELIST and that the filetype
of the file contains an "I" (i.e., FASTL*I*NE).

Now suppose further that UserA's and UserB's FILELIST entries appear as follows
in the LISTSERV FILELIST file.

/F/  LIST-A   FILELIST   ALL OWN V      79    63 92/03/11 16:45:22 ...
/F/  LIST-B   FILELIST   ALL OWN V     122    82 92/03/10 08:45:43 ...

With this setup, when UserB saves the file, he will receive the  message  (from
LISTSERV)

You are not authorized to store file "920312 FASTLINE".

It  appears  as if LISTSERV searches its LISTSERV FILELIST file, finds the tem-
plate defined for UserA's FILELIST, because it comes to it first  sequentially,
and  rightfully  tells  UserB he cannot store files in this FILELIST.  LISTSERV
never gets to LIST-B FILELIST.

Let's now suppose that UserB finally gets the file stored, all other conditions
above remain as described.  Someone wishing to retrieve this  file  enters  the
following GET command:

GET 920312 FASTLINE

LISTSERV responds with:

File "920312 FASTLINE" is not yet available.



Again,  LISTSERV  apparently  finds  the  template  entry  for  UserA's  LIST-A
FILELIST, does not find the indicated file and responds with the not yet avail-
able message.

There are several solutions to this predicament.

1.  Try  to  make  the  character  pattern match in the template (the "generic"
    entry) something unique that cannot  easily  be  used  in  other  filenames
    (i.e.,  probably  never  make  it one character as the above example illus-
    trates).

2.  Switch the order of the FILELIST definitions in the LISTSERV FILELIST file.
    That is, always make sure a FILELIST with a template defined  appears  last
    (sequentially) in the LISTSERV FILELIST file.

3.  Make  sure  everyone always names the target FILELIST explicitly in GET and
    PUT commands, and when using the LSVPUT exec.  For example:

    GET filename filetype filelist

    and

    PUT filename filetype filelist PW=password

    and

    LSVPUT filename filetype (FILELIST filelist

    In practice, this is very hard to implement and enforce.


--Greg Kroll
Comments: Gated by NETNEWS@AUVM.AMERICAN.EDU