Table of Contents Previous Next Index

Section 18 File and Notebook Archives

Section 18 File and Notebook 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 16.0, with pointers to where further information may be obtained.
18.1 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.
18.2 Starting a file archive for your list
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
On Workstation and PC Systems
The LISTSERV maintainer stores "root-level" file definitions in a file called SITE.CATALOG, which should be placed in the same directory with the SYSTEM.CATALOG file.2 The LISTSERV maintainer can also define "sub-catalogs" which in turn can define further files. You should be aware of the differences between VM and workstation file server functions as many people are using and will continue to use the VM file server with different conventions, and may give you incorrect advice. Non-VM sites should skip section 8.3, and use the information below in section 8.4 to maintain their file archives.
18.3 Filelist Maintenance (VM Systems Only)
If you are running 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 e-mail.
18.3.1 Creating a Filelist (VM Systems Only)
Please see FSV GUIDE (available at ftp://ftp.lsoft.com/documents/fsv.guide) for details.
18.3.2 Adding FAC Codes (VM Systems Only)
Please see FSV GUIDE (available at ftp://ftp.lsoft.com/documents/fsv.guide) for details.
18.3.3 Retrieving the Filelist (VM Systems Only)
To retrieve your filelist in an editable format, send the command
GET listname FILELIST PW=XXXXXXXX (CTL
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 18-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
* -------- -------- --- --- --- ----- ----- -------- ------ ---------
Notes: 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.
18.3.4 Adding File Descriptors to the Filelist (VM Systems Only)
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 then 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), logical 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.
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 18-2 Adding a File Descriptor to the Filelist
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.
18.3.5 File Access Codes (FAC) for User Access (VM Systems Only)
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 that 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 VM servers 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.
(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 18.4 The listname.CATALOG System on Non-VM Systems if you are configuring the non-VM systems.)
Note: 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.)
18.3.6 Deleting File Descriptors from the Filelist (VM Systems Only)
Warning: Before you delete file descriptors from the filelist, you should delete the files themselves from LISTSERV's archive disk. See Section 18.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.
18.3.7 Storing the Filelist (VM Systems Only)
1.
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.)
2.
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.
3.
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.
4.
PUT filename FILELIST PW=XXXXXXXX
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.
5.
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 18.5 Storing Files on the Host Machine for instructions.
18.4 The listname.CATALOG System on Non-VM Systems
Documented Restriction: The hierarchical listname.catalog system documented below is not available under LISTSERV Lite. You may store files on a Lite server for people to retrieve, but the files must be registered in the site.catalog file and must reside in the same directory with the *.list files so that LISTSERV can find them.
LISTSERV version 1.8c and later uses a file archive registration system similar to (but differing in important respects from) the old VM FILELIST system. This system is available on the VMS, unix, and Windows ports only. VM sites will continue to use the old FILELIST system indefinitely as it still offers more functionality than the new system.
Files to be made generally available to users (e.g., not specific to any one list on your server) should still be registered in the site.catalog file as before.
Prior to 1.8c, entries in site.catalog were written like this:
MY.FILE my.file./home/lists/xyz ALL JOE@XYZ.COM
In 1.8c a new "native" format for these entries was introduced, and the new format is used in all of the examples below. The old format remains supported for compatibility. However, note that you MUST use the old format if any of the directories in the path contains a period.
Documented Restriction: All files manipulated by LISTSERV must be accessible through LISTSERV's OS-independent file access methods. This means that files whose name contains spaces or control characters (or, under unix, upper case characters) cannot be accessed. Similarly, files whose name does not contain a period cannot be manipulated by LISTSERV. There is no limit on the length of the file name, only on its contents. Note that these "system filenames" are not visible to the end users, who refer to the files by the names assigned in the catalog.
18.4.1 Adding Files to the SITE.CATALOG
This is the most basic way to add files to LISTSERV's file archive system so they can be made available to users via the GET command.
To register a new file to the server on workstation systems, the LISTSERV maintainer adds a line to the SITE.CATALOG file. If SITE.CATALOG does not already exist (it is not shipped with the installation kits), simply open a new ASCII text file named site.catalog in the same directory as system.catalog and add entries to it as shown below. (Do not just add entries to system.catalog as this file will always be overwritten during a software update.)
Here is what a typical SITE.CATALOG entry looks like under Windows NT:
MY.FILE C:\FILES\XYZ\MY.FILE XXX YYY
And the same entry under Unix would look like this:
MY.FILE /files/xyz/my.file XXX YYY
Note: Under Unix, LISTSERV does not observe case-sensitivity internally. Therefore you cannot define two different files with the same non-case-sensitive filename. In other words, LISTSERV will not differentiate between MY.FILE and my.file, or even My.File. But note carefully that the physical files you store must be named in lower-case; in other words, the output of an 'ls' command must show my.file, not MY.FILE or My.File. LISTSERV will handle this issue automatically when you PUT the files, but be forewarned if you store the files on the server via ftp or the Unix file system.)
Finally, here is an OpenVMS example:
MY.FILE XYZ:[FILES]MY.FILE XXX YYY
The first item, MY.FILE, is the name by which the file is known to LISTSERV. That is, the users will use GET MY.FILE to order a copy of that file. The name should contain only one period.
The second item, for instance C:\FILES\XYZ\MY.FILE, is the name LISTSERV will use for the actual disk file, in native OS format. Note that the directory must be created before you register the file. For security reasons, LISTSERV will not create the directory (or set the protections) for you. (LISTSERV will normally need full access to these files.)
The third and fourth items are "File Access Codes" (FACs). The first is for read accesses, and the second for writing. The following file access codes are available for non-VM servers (for VM FAC codes, see Section 18.3.5 File Access Codes (FAC) for User Access (VM Systems Only)):
ALL – Universal access.
CTL – Only the LISTSERV maintainers have 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.
Important: These "file access codes" apply to LISTSERV commands (GET, PUT, INDEX) only, and not to the workstation or PC's file security system. It is your responsibility to protect the actual disk file by setting the file protections for the directory in which they are created.
18.4.2 Delegating File Management Authority
The 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. With the LISTSERV-ISP add on (under development), a quota can be imposed on the directory in question.
The procedure works as follows:
1.
The LISTSERV administrator creates the sub-catalog and identifies the directory where the files will be stored, and the person(s) who will be in charge of managing it ("catalog owners").
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").
3.
The file owners manage the files in question using the GET and PUT commands. Authorized users can retrieve the files using the GET command.
Note: This functionality is available in the VM version, using a different syntax. See Section 18.3 Filelist Maintenance (VM Systems Only) for information on managing the VM file archive system.
If you are migrating from VM to one of the non-VM versions of LISTSERV, please note that it is not necessary to create a subcatalog file for WELCOME, FAREWELL and MAILTPL files. If a subcatalog for these files is not created, they do not appear in the output of an INDEX command. However, there are two ways to force them to appear:
As the result of an INDEX command without qualifier: simply define the file in SITE.CATALOG.
As the result of an INDEX listname command: simply define the file in the listname.CATALOG.
18.4.3 Creating a Sub-Catalog
To create a sub-catalog, the LISTSERV administrator edits the file called SITE.CATALOG (or site.catalog under unix) in LISTSERV's main directory (the directory where SYSTEM.CATALOG/system.catalog is located). A sub-catalog is defined as follows:
MY.CATALOG /home/lists/xyz/my.catalog ALL JOE@XYZ.COM
(1) (2) (3) (4) (5)
Notes: The name must end in '.CATALOG', but otherwise it can be anything. In particular, there does not need to be a list by that name.

The directory specification indicated for the catalog file (e.g., /home/lists/xyz) is where ALL the files defined in the sub-catalog will be stored. DO NOT USE LISTSERV'S MAIN (A) DIRECTORY FOR THIS PURPOSE! The catalog owner will be given FULL ACCESS to all the files in this directory, so make sure to create a new, empty directory. If the sub-catalog is being set up for a list owner, it may be a good idea to put the list archives and the sub-catalog in the same directory.

A file name must be provided for the sub-catalog file itself. This name, however, does not need to match.

This file access code controls the authority to INDEX the sub-catalog. This will also be the default GET access code for all the files registered in the sub-catalog.

This file access code defines the catalog owner(s) and default file owner(s) for all the files in the sub-catalog.

There is no need to reboot LISTSERV after updating the SITE.CATALOG file. Also, bear in mind that you are responsible for the OS-level security of the directory you create for the catalog. The file access codes in SITE.CATALOG only affect operations that go through LISTSERV; it is your responsibility to make sure that other users of the computer are given the appropriate access level to any directory you create for LISTSERV's purposes.
18.4.4 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):
1.
2.
3.
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:
MY.FILE my.file ALL JOE@XYZ.COM
(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 (ie 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. See Section 18.4.1 Adding Files to the SITE.CATALOG for more information on FAC codes.

(4) This file access code determines who can update the file with the PUT command. See section 18.4.1Adding Files to the SITE.CATALOG 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
18.4.5 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.
18.5 Storing Files on the Host Machine
Note: LISTSERV does not currently recognize "attachments" created by many popular mail clients as files to be stored with the PUT command. Such files must be part of the body of the message that contains the PUT command. This means that binary files must be stored either in 7-bit format (uuencoded, etc.) or ftp’d to the server and placed in the appropriate directory by the LISTSERV maintainer or other privileged user.
If you store binary-format files on the server, you should be careful to note in the file catalog or filelist that users who want to GET the files will need to use an F= modifier (e.g., GET BINARY.FILE F=MIME/APPL) when ordering them by email.
To store a file on any LISTSERV host, first ensure that it has been registered with an entry in a filelist or the site catalog. Then mail the file to LISTSERV with a single line at the top of the document. Follow the directions below:
1.
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.
You MUST turn off your signature file (if one is enabled in your mail client) in order to successfully store files. If you do not, LISTSERV will store your signature file at the end of the file.
2.
3.
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.
4.
18.6 Deleting Files from the Host Machine
To delete a registered file on any LISTSERV host:
1.
PUT filename extension [filelist|catalogname] PW=XXXXXXXX
(Replace XXXXXXXX with your personal password.) The same issues noted in Section 18.5 Storing Files on the Host Machine regarding the filelist/catalog name are operative here.
You MUST turn off your signature file (if one is enabled in your mail client) in order to successfully delete files. If you do not, LISTSERV will store your signature file in place of the file you are trying to delete instead of deleting the file.
2.
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.
3.
4.
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. Note that 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.
18.7 Automatic File Distribution (AFD) and File Update Information (FUI)
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.
Note: If you are running LISTSERV under unix, Windows, or VMS, please skip the rest of this section as it does not pertain in any way to your implementation of LISTSERV.
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 when applicable.
AFD and FUI can be password-protected to protect users from network hackers who might forge mail from the user subscribing to large or frequently-updated files. If a password is not provided in an AFD ADD or FUI ADD command, LISTSERV warns the user that it would be a good idea to password protect the subscription.
18.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 file type 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, for example:
* MYLIST $PACKAGE
* 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,

MYLIST $PACKAGE MYLIST The packing list
INTEREST FILE MYLIST Interest groups
NETIQUET FILE MYLIST How to behave
ANOTHER FILE MYLIST No comment
In the second (new) mode for non-VM servers only, the entries are formatted like this:

filename.extension <optional_comments>

for example,

MYLIST.$PACKAGE The packing list
INTEREST.FILE Interest groups
NETIQUET.FILE How to behave
ANOTHER.FILE No comment
Note: Anything that is not the name of a file in the package must be commented out with an asterisk in the left-most 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:
1.
They may get the entire package of files sent to them by sending LISTSERV the command GET filename PACKAGE (without the $ sign); or
2.
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).
18.9 Finding More Information on File Archives
Other guides that refer to File Archive setup and maintenance are found at:
http://www.lsoft.com/resources/manuals.asp.
18.10 Notebook Archives
Notebook archives are files in which postings to the list are stored (assuming that notebooks are enabled for the particular list). In general, they are managed automatically by LISTSERV, with certain functions left to the list owner(s). For instance, there is no need to register notebook archives in the listname.FILELIST or listname.CATALOG; this is taken care of automatically.
18.10.1 Setting Up Notebook Archives for a List
Setting up notebook archives requires only a few steps:
1.
Make sure that you have disk space for the notebook archives and that the directory in which they will reside has been created with appropriate security privileges. LISTSERV needs read and write access to any directory it uses for notebooks. Note that, for security reasons, LISTSERV will not create the directory if it does not exist.
2.
Add the Notebook= keyword to the list header with appropriate settings. (If you are not the LISTSERV maintainer, you will have to ask the LISTSERV maintainer to do this for you.)
3.
For instance, let's assume you have a list called MYLIST running on a unix server and you wish to store its archives in a directory called /usr/listserv/home/mylist-archive. Notebooks are to be kept on a monthly basis and are to be available to anyone. Your Notebook= keyword would look like this:
* Notebook= Yes,/usr/listserv/home/mylist-archive,Monthly,Public
Note: Only the LISTSERV maintainer may change the location of Notebook archives (or change Notebook= No to Notebook= Yes). Anyone else attempting to PUT the list header after changing these values will result in the following message being sent in response:
The following problems have been detected in the list header:
* Notebook= ...
Error: The first two parameters of the "Notebook=" keyword may only be updated by the LISTSERV administrator.
Please refer to the list keyword documentation (available via the "INFO KEYWORDS" command) for more information about keyword syntax.
PUT operation rejected, old list remains unchanged.
Note: This output will appear either if an attempt is made to change "Notebook= No" to "Notebook= Yes", or if an attempt is made to change the location where notebook archives are stored on the server, by anyone who is not a LISTSERV maintainer.
Similar restrictions also apply to the Digest= keyword. See the List Keyword Reference document for details.
18.10.2 Migrating Old Notebook Archives to a New Site (LISTSERV to LISTSERV)
If migrating old notebook archives from one LISTSERV site to another, you can simply ftp (in TEXT mode) the notebooks from the old host to the new host, put them in the directory reference in the Notebook= keyword settings, and LISTSERV will immediately recognize their presence. You can also migrate the notebooks with GET and PUT.
18.10.3 Migrating Old Notebook Archives (Non-LISTSERV to LISTSERV)
LISTSERV notebooks follow a modified VM MailBook format, which is as follows:
A line of 73 "=" signs (ASCII 0x3D)
RFC822 headers, starting with the Date: header3
Blank line (actually part of RFC822 headers)
Message body
For instance:
======================================================================
Date: Fri, 6 Mar 1998 17:05:01 -0500
Sender: Test list <TEST@XXXXXX.NET>
From: Nathan Brindle <nathan@XXXXXX.NET>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
 
This is a test.
======================================================================
Date: Thu, 12 Mar 1998 13:23:07 -0500
Sender: Test list <TEST@XXXXXX.NET>
From: Nathan Brindle <nathan@XXXXXX.NET>
Subject: Test
 
This is another test
======================================================================
Date: Thu, 12 Mar 1998 13:24:58 -0500
Sender: Test list <TEST@XXXXXX.NET>
From: Nathan Brindle <nathan@XXXXXX.NET>
Subject: Test 3
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
 
Yet another test.
======================================================================
The last message in the archive is not followed by a separator line (in other words, the separator line is found at the beginning of each message, not at the end of each message).
If you can reformat your non-LISTSERV archives this way then you can rename them using standard LISTSERV filenames:
For monthly archives: listname.logyymm
For weekly archives: listname.logyymmw
For yearly archives: listname.logyy
(where yy = 2 digit year, mm = 2 digit month, w = letter A-F denoting the week of the month), place them in the directory pointed to by the Notebook= keyword for the list, and LISTSERV will index them and make them available via the web archive interface and so on.4 In order for the web archive interface to notice new notebook files you must either GET and PUT the list header or restart LISTSERV.
If a list owner is planning to store archive files via the PUT method, the LISTSERV maintainer must first make dummy files with the same filenames in the list's notebook directory so that LISTSERV will not say that the file does not exist and reject the PUT operation. However please note that you should not make entries for the notebooks in listname.catalog (if one exists). LISTSERV makes its list of notebooks "on the fly" every time an INDEX command is issued for the list.
If your old archives have lines at the beginning of each message like this:
From userid@host.com Thu Feb 2 15:27:02 1995
you should delete them; this is the message separator used by sendmail. LISTSERV does not use it and it may in fact cause problems with indexing if left in.
18.10.4 Deleting Old Notebook Archives
The LISTSERV maintainer may delete old notebook archives that are no longer needed in one of two ways:
Use standard file system commands from the console prompt to delete the files. On VM, use CMS ERASE; on Unix, rm; on VMS, DEL; on Windows systems, DEL or ERASE.
Send a PUT command by itself (in essence, you are storing a zero-length file) via mail to LISTSERV. For instance:
PUT MYLIST LOG9607 PW=mypersonalpw
by itself would delete the file MYLIST LOG9607.
Two important issues:
This command MUST be issued by email. It cannot be issued via the "Execute a LISTSERV command" facility of the web management interface.
You MUST turn off your signature file (if one is enabled in your mail client) in order to successfully delete files. If you do not, then LISTSERV will store your signature file in place of the file you are trying to delete instead of deleting the file.
18.10.5 Indexing existing notebook archives
LISTSERV creates the notebook archive index "on the fly" as required. If there is an existing listname.FILELIST or listname.CATALOG, it appends the index of notebook archives to the end of the index of other files. Otherwise, the index of notebooks is generated and sent by itself. The user simply issues the command INDEX listname to receive the index of available files and notebooks.
 
 

1
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 (bec@albany.edu). This publication is available from LISTSERV@LISTSERV.NET as FSV GUIDE, or at ftp://ftp.lsoft.com/documents/fsv.guide.

2
Under unix, all files accessed by LISTSERV must be named in lower case (i.e., 'ls' must show site.catalog, not SITE.CATALOG or Site.Catalog). Internally LISTSERV does not care about case since it translates everything to lower case for the purpose of accessing the unix file system, and you may use upper or mixed case within the catalog file itself.

3
Note that by default, LISTSERV requires that the RFC822 Date: header be the first header in the message. If some other header or headers come before Date:, LISTSERV will not properly delimit the messages in the notebook.
You can work around this restriction for archives migrated from non-LISTSERV systems by using the list header keyword "Notebook-Header= Full"; however you must still remove unix mailbox separator lines like the one shown at the end of this section or LISTSERV will not be able to correctly index the notebook.
It should also be noted that lists with "Notebook-Header= Full" consume more disk space for very little gain, which is why the default is "Notebook-Header= Short", and why we suggest reformatting such migrated archives to the LISTSERV "short" header format.
Note also that the proper formatting of the Date: field is critical. If the format is incorrect, the web archive interface will be unable to index and display the messages. Therefore, the Date: header in all messages contained in the archive file MUST conform to the standard format as described in
RFC822/RFC2822. For example:
CORRECT: Date: Wed, 30 Jan 2008 03:01:00 -0500
INCORRECT: Date: Wednesday, January 30, 2008 03:01 EST
In addition, all other RFC822/RFC2822 headers in the message SHOULD conform to their standard formats.

4
If your old archives are from Majordomo or ListProc you might want to look at an unsupported Perl script found at ftp://ftp.lsoft.com/CONTRIB/notebook-conv.pl which converts sendmail-style notebooks to LISTSERV format. This is really ListProc-specific but it would probably work with Majordomo archives. In any case this user-contributed script is not supported in any way by L-Soft, so please direct any questions about it to its authors.


L-Soft international, Inc.
1-800-399-5449