Table of Contents Previous Next Index

Section 8 File Archives

Section 8 File Archives
There are three file server systems currently in use by various versions of LISTSERV:
The VM (mainframe) version of LISTSERV continues to support the "traditional" file server system. While it is very powerful, this file server system dates back to 1986 and suffers from a few annoying limitations. In addition, it is written in a non portable language. This will be replaced eventually with the "new" file server system, currently under development.
The non-VM versions of LISTSERV 1.8d enhanced further the new file server system introduced in non-VM 1.8c, which included most of the functionality of the "traditional" file system. Notably, GIVE and file "packages" became available. Most end user commands continue to work as before. However, there is no guarantee that the internal data files manipulated by the file server functions will remain as before. Note that SITE.CATALOG files from versions 1.8a through 1.8c are still supported and will not need to be changed in order to work with 1.8d and later.
The non-VM versions of LISTSERV 1.8a and 1.8b supported a "temporary" file server system, to provide an interim solution while the new system was being developed. This temporary system supports only a subset of the functions of the traditional system. This system is no longer supported by L-Soft as it has been superseded by the new non-VM file server referenced above.
In general, the three systems are compatible, with the understanding that the temporary system does not include all the possible options. However, the mechanism for registering files (defining them to the file server system) is different.
Since the first and third systems will eventually be replaced by the second system, rather than providing an exhaustive section detailing all filelist aspects from the management side, we have provided only a basic overview of the two systems currently in the field with 15.0, with pointers to where further information may be obtained.
8.1 What is the File Archive?
The file archive consists of all files other than notebook logs that have been stored on the LISTSERV host for your list. Users can find out what files are available for a specific list by sending the command INDex listname to the appropriate LISTSERV host.
8.2 Starting a File Archive for your List
8.2.1 On VM Systems ONLY
With the traditional system (running on the VM servers), the LISTSERV maintainer creates files called "xxxx FILELIST", which contain definitions for all the files belonging to a particular archive. These FILELIST files must be created by the LISTSERV maintainer at the site before they can be edited by the list owner.1
8.2.2 On Workstation and PC Systems
The LISTSERV maintainer creates a definition for your listname.CATALOG in a system-global file called SITE.CATALOG. The list owner then follows the instructions in Section 8.4 The listname.CATALOG System on non-VM Systems to register files and store them on the server.
Note: The instructions in Section 8.3 Filelist Maintenance (VM Systems Only) and the instructions in Section 8.4 The listname.CATALOG System on non-VM Systems are not interchangeable. If you are not sure which system your list is running on, then you can send the command RELEASE to the server to find out.
8.3 Filelist Maintenance (VM Systems Only)
If your list is running on LISTSERV under unix, Windows, or VMS, please skip this section as it does not pertain in any way to your implementation of LISTSERV.
Maintaining the filelist for your archive is not difficult. It requires only that you have a working knowledge of VM XEDIT (or your local system's editor) and understand how to send files via email.
8.3.1 Retrieving the Filelist
To retrieve your filelist in an editable format, send the command
to the LISTSERV host where the filelist is stored. The (CTL switch causes LISTSERV to lock the filelist until you store it again or explicitly unlock it with an UNLOCK listname FILELIST command. (If you don't want to lock the filelist, use (CTL NOLOCK instead.) If your mail account is not located on the same host as LISTSERV, you will need to provide your personal password (same as your password for getting and putting your lists).
A filelist retrieved with the (CTL option does not look like the filelist you get with an INDEX command. A sample (CTL option filelist appears below:
Figure 8-1 Sample Filelist Retrieved with (CTL Option
* Files associated with MYLIST and available to subscribers:
* rec last - change
* filename filetype GET PUT -fm lrecl nrecs date time Remarks
* -------- -------- --- --- --- ----- ----- -------- -------- --------
MYLIST POLICY ALL OWN V 79 45 94/03/16 12:04:23 Mission Statement
MYLIST BOOKLIST ALL OWN V 79 177 94/04/19 16:24:57 Books of interest
MYLIST QUARTER ALL OWN V 73 113 95/03/11 08:57:04 Quarterly posting
* Listowner's files (not public)
MYLIST FAREWELL OWN OWN V 78 9 95/03/11 08:53:41 Goodbye memo
MYLIST WELCOME OWN OWN V 73 105 95/03/11 09:14:38 Hello memo
Note: The filelist does not include the comment lines you would normally see at the top of an INDEX filelist; nor does it include any notebook archives. LISTSERV creates these lines dynamically at the time the INDEX command is received from a user. If the filelist you have retrieved has any of this kind of material in it, either (a) you have not retrieved the filelist correctly, or (b) you or someone else has stored the filelist previously with this material included. If you did a GET with (CTL, you should be able to remove these extraneous lines by simply deleting them.
If you do an INDEX of your archive and it has (for instance) two sets of comment lines or duplicate notebook archive listings, then you should GET the filelist with (CTL and edit out the offending lines. While the extra lines will not affect the operation of the file server, they are a source of potential confusion for your users.
8.3.2 Adding File Descriptors to the Filelist
"Adding a file to a filelist" is not exactly accurate terminology, although it is a widely-used phrase. Adding files to file archives is a two-step process. First, add a file descriptor to the appropriate filelist and store the filelist on the server. Second, store the file itself on the server.
To add a file descriptor, start a line with a space and then type in your file's name, access codes, five dots (periods) and a short description, each separated by a space. For example:
MYLIST FAQ ALL OWN . . . . . Frequently-Asked Questions for MYLIST
Note: The line must begin with a space. Also, you must place five dots separated by spaces between the PUT file access code (here it is OWN) and the short description. These dots are place holders for the record format (recfm), longest record length (lrecl), number of records (nrecs), and the date and time of the last update. If these dots are not present, LISTSERV will return an error message when you try to store the filelist.
You will note that the line you have just added does not look like the other lines in the filelist. Ignore the "pretty" formatting. LISTSERV will reformat the information for you. After adding the line, your filelist should look like this:
Figure 8-2 Adding a File Descriptor to the Filelist
* Files associated with MYLIST and available to subscribers:
* rec last - change
* filename filetype GET PUT -fm lrecl nrecs date time Remarks
* -------- -------- --- --- --- ----- ----- -------- -------- --------
MYLIST POLICY ALL OWN V 79 45 94/03/16 12:04:23 Mission Statement
MYLIST BOOKLIST ALL OWN V 79 177 94/04/19 16:24:57 Books of interest
MYLIST QUARTER ALL OWN V 73 113 95/03/11 08:57:04 Quarterly posting
MYLIST FAQ ALL OWN . . . . . Frequently-Asked Questions for MYLIST
* Listowner's files (not public)
MYLIST FAREWELL OWN OWN V 78 9 95/03/11 08:53:41 Goodbye memo
MYLIST WELCOME OWN OWN V 73 105 95/03/11 09:14:38 Hello memo
Note: You can add comment lines to the filelist by placing an asterisk in the left-most column instead of a space. Comment lines can act as indexes, descriptions, or pointers to other resources.
Once you are finished adding file descriptors, save the filelist to disk.
8.3.3 File Access Codes (FAC) for User Access
FACs define which users have access to files in the file archive. The FAC for GET indicates who may retrieve the files, and the FAC for PUT indicates who may store the files on the server.
Note: Some special FACs exist for "superusers" such as the LISTSERV maintainer(s) and the LISTSERV Master Coordinator, who may GET and PUT any file regardless of its GET/PUT permissions.
The basic FAC codes that are always available for the VM server are:
ALL – Universal access.
PRV – Only members of the associated mailing list have access.
OWN – Only the owners of the associated mailing list have access.
Notes: The FAC codes PRV and OWN work only on the VM filelist system. They do not work on the non-VM catalog system. See Section 8.4 The listname.CATALOG System on non-VM Systems if you are configuring the non-VM systems.

This assumes the name of the filelist is identical to the name of the associated mailing list – for instance, MYLIST@FOO.BAR.EDU would have a MYLIST LIST file and a MYLIST FILELIST file. Ask your LISTSERV maintainer for assistance if this is not the case or if you need special FACs added for special user access to files.
8.3.4 Deleting File Descriptors from the Filelist
Note: Before you delete file descriptors from the filelist, you should delete the files themselves from LISTSERV's archive disk. See Section 8.6 Deleting Files from the Host Machine for instructions.
If this step is not followed, LISTSERV may not be able to find the file you want to delete after you edit the filelist and store it.
8.3.5 Storing the Filelist
Create a mail message to LISTSERV at the appropriate host. (Sending a filelist to LISTSERV@LISTSERV.NET will not work. The filelist must be sent to the host it resides on.)
Include the filelist file as plain text in the body of the mail message. Do not attach it with MIME or another encoding scheme, as LISTSERV does not translate encoded messages.
Make sure that your mail client does not automatically add a signature file to the bottom of your mail. If it does, your signature file will be treated as part of the filelist and will be stored along with it.
where XXXXXXXX is your personal password for LISTSERV on that host. Note that this is similar to the PUT command used when storing the list file.
Once LISTSERV acknowledges the receipt and storage of the filelist, you can send the files that correspond to the file descriptors in your filelist. See Section 8.5 Storing Files on the Host Machine for instructions.
8.4 The listname.CATALOG System on non-VM Systems
List-level file catalogs are not available in LISTSERV LITE; you must register files in the SITE.CATALOG file per the instructions in the installation guide.
LISTSERV running on non-VM systems has a file archive registration system similar to (but differing in important respects from) the old VM FILELIST system.
This "sub-catalog" enhancement allows the LISTSERV administrator to delegate file management authority in a controlled and secure manner. Multiple list owners can be given the authority to maintain their own sub-catalog in a predefined directory.
From a list owner's point of view, the procedure works as follows:
Ask the LISTSERV administrator to create the sub-catalog for your list. You will need to provide the email addresses of the person(s) who will be in charge of managing it ("catalog owners").
The catalog owners use the GET and PUT commands to update their catalog and register new files in their directory. Each file has the usual GET and PUT file access codes, allowing the catalog owners to further delegate the management of individual files to third parties ("file owners").
The file owners manage the files in question using the GET and PUT commands. Authorized users can retrieve the files using the GET command.
If your list is being migrated from VM to one of the non-VM versions of LISTSERV, please note that it is not necessary to create entries in your sub-catalog for WELCOME, FAREWELL, and MAILTPL files. If entries for these files are not created, they simply do not appear in the output of an INDEX command. However, if desired, you can force them to appear by defining them in your sub-catalog.
8.4.1 Updating the Sub-Catalog
Once the sub-catalog is created, the catalog owner(s) can register new files using the following procedure (in this example, it will be assumed that the sub-catalog is called MY.CATALOG):
Send a GET MY.CATALOG command to LISTSERV (or, if the catalog is brand new, start from an empty file).
Use the PUT MY.CATALOG PW=XXXXX command to store the updated catalog.
Alternatively, if the catalog owner has an account on the LISTSERV host system and write access to the directory associated with the sub-catalog, the file can be edited directly. Note however that, in that case, the LISTSERV-ISP quota system will be inoperative as it has no control over disk accesses which do not go through LISTSERV itself.
The format of sub-catalogs is similar to that of SITE.CATALOG:
(1) (2) (3) (4)
Notes: (1) This defines the name of the file as seen by LISTSERV users. That is, the command to retrieve the file will be GET MY.FILE.

(2) This defines the name of the actual disk file where the contents of MY.FILE will be stored. Normally, you should specify the same as (1), or just an equal sign (LISTSERV will then substitute the name you provided for (1)). However, in some cases you may want to make a particular file available under multiple names. This can be done by registering multiple files (i.e. multiple values for (1)), and using the same (2) value every time.

(3) This file access code determines who can order the file through a GET command. The following file access codes are available:

ALL – universal access.
PRIVATE(xxx) – Only members of the xxx list have access.
OWNER(xxx) – Only the owners of the xxx list have access.
SERVICE(xxx) – Only users in the service area of the xxx list have access.
NOTEBOOK(xxx) – Same access as the archives of the xxx list.
user@host – The user in question is granted access.

Except for ALL, which must occur on its own, multiple file access code entries can be specified, separated by a comma with no intervening space. For instance:


defines a file that Joe, Jack and the subscribers of the XYZ-L list can order via the GET command, but that only the LISTSERV administrator can update.

(4) This file access code determines who can update the file with the PUT command. See note (3), above, for more information on FAC codes.

(2) defaults to the value of (1), and (3) and (4) default to the GET and PUT access codes of the sub-catalog itself, respectively. So, in most cases a sub-catalog entry will be as simple as:


Additionally, comment lines (starting with an asterisk) or blank lines can be interspersed with file definitions. These comments will be echoed when the sub-catalog is indexed (see below), in sequence with the file definitions. For instance, your catalog could read:

* Files for the XYZ sub-project
8.4.2 Indexing the Sub-Catalog
If MY.CATALOG is defined as:
MY.CATALOG /home/lists/xyz/my.catalog xxx JOE@XYZ.COM
then any user who matches the 'xxx' file access code is authorized to issue an INDEX MY command to get a formatted version of the catalog. For compatibility with older versions of LISTSERV, GET MY.FILELIST will produce the same results. If there is a mailing list called MY, a list of the archive files will be appended automatically.
8.5 Storing Files on the Host Machine
To store a file on any LISTSERV host, first ensure that it has been registered with an entry in a filelist or catalog. Then follow these instructions:
Be sure that you have defined a "personal password" to LISTSERV with the PW ADD command before you PUT the new or edited file. If you have done this but can't remember the password, send a PW RESET command to LISTSERV, then a new PW ADD command.
PUT filename extension [filelist|catalogname] PW=XXXXXXXX
(This line will not appear to people who GET the file from LISTSERV.) Replace XXXXXXXX with your personal password. If you specify the filelist or catalog name, do not put the square brackets around the name.
There are a couple of issues that need to be noted here:
If the file you are going to store is registered in a sub-catalog or filelist other than the sitewide one, you may have to specify the name of the sub-catalog or filelist in order to be able to store the file. This is because it is entirely possible that two lower-level filelists or catalogs may have files registered with the same name (for instance, README TXT). If LISTSERV has two sub-catalogs registered (for instance, MYLIST CATALOG and HISLIST CATALOG) that both have a file called README TXT registered, then a PUT README TXT command will tell LISTSERV to try and store the file in the first catalog it comes to in the hierarchy. If MYLIST CATALOG is registered before HISLIST CATALOG in SITE CATALOG, LISTSERV will try to store the file as if it belonged to MYLIST (which we assume is what you want). However, if HISLIST CATALOG is registered before MYLIST CATALOG (and many sites like to keep things in alphabetical order, so this is a most likely scenario), LISTSERV will try to store the file as if it belonged to HISLIST, and you will get an error stating that you aren't allowed to store the file.
8.6 Deleting Files from the Host Machine
To delete a registered file on any LISTSERV host:
Be sure that you have defined a "personal password" to LISTSERV with the PW ADD command before you PUT the delete job. If you have done this but can't remember the password, send a PW RESET command to LISTSERV, then a new PW ADD command.
PUT filename extension [filelist|catalogname] PW=XXXXXXXX
(Replace XXXXXXXX with your personal password.) The same issues noted in Section 8.5 Storing Files on the Host Machine regarding the filelist/catalog name are operative here.
For VM Systems ONLY: GET the listname FILELIST for your list and delete the line for the file you’ve just deleted. PUT the listname FILELIST back on the server.
For Workstation and PC Systems ONLY: Get the listname.CATALOG for your list and delete the line for the file you've just deleted. PUT the listname.CATALOG back on the server. (This is not necessarily required since under non-VM, if the physical file does not exist, LISTSERV will not include it in the output of an INDEX command. This is primarily a housekeeping measure.)
Note: Number 5 and number 6 are not necessary when you are deleting notebook archives. LISTSERV generates the notebook archives index "on the fly" when needed.
8.7 Automatic File Distribution (AFD) and File Update Information (FUI)
If your list is running on LISTSERV under unix, Windows, or VMS, please skip the rest of this section as it does not currently pertain in any way to your implementation of LISTSERV.
AFD and FUI have not yet been ported to the workstation and PC environments. However, this feature is supported on VM and will be supported in the near future on the other platforms.
These two features are similar in their command syntax, but do different things. AFD provides a method whereby users may subscribe to specific files, which will be sent to them any time the files are updated. For instance, if you have a FAQ file that is updated monthly, a user could send an AFD subscription to that FAQ file and LISTSERV would send it to the user every time you updated and stored the FAQ.
FUI, on the other hand, is a method whereby a user subscribes to a file but receives only a notification that the file has been updated. The user can then GET the file at his own discretion.
AFD and FUI can be password-protected to protect users from network hackers who might forge mail from the user subscribing him to large or frequently-updated files. If a password is not provided in an AFD or FUI ADD command, LISTSERV warns the user that it would be a good idea to password protect the subscription.
8.8 File "Packages"
You can define a group of files as a "package" that can be retrieved by users with a single GET command. First, ensure that all the files in the package are defined in the appropriate filelist and stored on the server as detailed above.
Next, create a file descriptor in the appropriate filelist or catalog for a file called filename $PACKAGE (or filename.$PACKAGE for non-VM), where filename is the name you have chosen for the group of files. Be sure that the filetype or extension is $PACKAGE, with a leading $ sign, and store your filelist.
Now create the actual filename $PACKAGE file. At the top of the file you can insert comment lines beginning with asterisks, e.g.:
* Packing list for MYLIST PACKAGE
* You can make other comments here, such as
* the contact email address.
* filename filetype filelist
Following these comment lines, you insert lines for each of the files contained in the package. There are two ways to format entries in your $PACKAGE file:
A "compatibility" mode that works on all platforms, and which is identical to the original method used on VM (and which VM servers still must use). In the compatibility mode the basic format for the entries is
filename filetype filelist <optional_comments>
for example,
filename.extension <optional_comments>
for example,
MYLIST.$PACKAGE The packing list
INTEREST.FILE Interest groups
NETIQUET.FILE How to behave
Note: Anything that is not the name of a file in the package must be commented out with an asterisk in the leftmost column of the line. It is possible to create a package file without any comment lines at all, but this is not preferable in practice. Often users will get the package file itself just to see what is in it. You should include a reference to the package file itself so that the user will get a copy of the "packing list" to check against the files he receives from LISTSERV.
The final step is to send the package file to LISTSERV like any other file.
Now users can do one of two things:
They may get the entire package of files sent to them by sending LISTSERV the command GET filename PACKAGE (without the $ sign); or
They may request that LISTSERV send only the package file itself by sending LISTSERV the command GET filename $PACKAGE (with the $ sign).
Packages may be subscribed to with the AFD and FUI commands (VM only).
8.9 Where to Find More information on File Archives
LISTSERV maintainers can also find more information in the Site Manager’s Operations Manual for LISTSERV.

If you are interested in the mechanics of starting a VM-type filelist, the best reference is "Setting Up the LISTSERV File Server--A Beginner's Guide" by Ben Chi ( This publication is available from LISTSERV@ALBANY.EDU as FSV GUIDE.