The list archive consists of all of the notebook logs for your list. (If your list is coded "
Notebook= No", then it does not have a list archive, of course.) Users can find out what notebook logs are available for a specific list by sending the command
INDex listname to the appropriate LISTSERV host.
If your list is coded "Notebook= No", you should consult your LISTSERV maintainer to change the keyword to create list archive notebooks. The LISTSERV maintainer is the only one who can change this setting and specify where the notebook should be kept. Also, depending on local policies, you may or may not be allowed to archive your list, or keep more than a few months' or weeks' worth of archives available at a given time.
If your list is set to Notebook=Yes, you may occasionally need to delete archive notebook files to conserve disk space or to prevent access to out-of-date information.
To delete an archive notebook file, simply execute a PUT operation for the notebook in question without sending any other text along with the
PUT command line (turn off automatic signatures, and do not use a mail service that automatically adds text to every message sent). For instance, send an email message with the following text as the only content in the body of the message:
|
•
|
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 pointers to where further information may be obtained.
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.
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
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 16.2.4
The listname.CATALOG System on non-VM Systems to register files and store them on the server.
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.
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:
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.
"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.
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:
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.
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.
|
•
|
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 16.2.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.
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.
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.
|
2.
|
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").
|
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.
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):
|
1.
|
Send a GET MY.CATALOG command to LISTSERV (or, if the catalog is brand new, start from an empty file).
|
|
3.
|
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.
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:
MY.FILE C:\FILES\XYZ\MY.FILE JOE@XYZ.EDU,JACK@XYZ.EDU,PRIVATE(XYZ-L) CTL
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:
MY.FILE
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
*
XYZ.AGENDA
XYZ.BUDGET
XYZ.PROPOSAL-1
XYZ.PROPOSAL-2
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.
(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.
|
•
|
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.
|
|
5.
|
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.
|
|
6.
|
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.
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.
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.:
* MYLIST $PACKAGE* Packing list for MYLIST PACKAGE
*
* You can make other comments here, such as
* the contact email address.
*
* filename filetype filelist
*==========================
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.
