LISTSERV historical documentation, release 1.5m ----------------------------------------------- Copyright Eric Thomas 1986,1987 +-----------------------------------------------------+ | Revised LISTSERV: Automatic File Distribution | +-----------------------------------------------------+ | | | Document number: U01-006b-0 (October 17th, 1987) | | | | Document fileid: "LISTAFD MEMO" (from "Info AFD") | +-----------------------------------------------------+ Preface This manual is an introductory guide to the file-server functions of LISTSERV that are available to general users. It applies solely to the Revised LISTSERV software (also known as FRECP11-LISTSERV). In particular, the functions described in this document do not neces- sarily apply to the NETSERV software unless otherwise specified. This document is designed to be used in conjunction with the Revised LISTSERV: User's Guide, (Document Number U01-001) and assumes basic knowledge of the LISTSERV functions available to general users. File owners should refer to the Revised LISTSERV: File Maintainer's Guide (Document number M01-008) for a more technical discussion of the internal format of filelist entries and a description of the privi- leged file-maintenance commands available to file owners. Conventions ----------- The following typographical conventions have been made in this docu- ment to improve its readability: | o Recent changes in the publication are indicated by a vertical bar | in the left margin. ! o Intermediate changes between two releases of the document ("Pre- ! releases") are flagged with an exclamation point in the left ! margin. Features described in this fashion should be considered ! as not documented and not officially supported until the exclama- ! tion point is removed. > o Temporary restrictions or circumventions are marked with a > "greater than" sign in the left margin. This sign may also be used > to signal obsolete features for which support will be dropped in > the next release. o This manual duplicates some parts of the Revised LISTSERV: User's Guide (Document Number U01-001) for easier reference. Those excerpts are delimited by runs of ">>>" and "<<<" signs. + + Paragraphs marked with a '+' sign in the left margin contain detailed + explanations for experienced users and can be skipped at first + reading. + ************************** * Background Information * ************************** Introduction ------------ Experience has shown that offering automatic distribution of updated files was the best way to reduce the load caused by users who period- ically order files they already have "just to see if it has changed". An index (directory) with date/time stamps is not sufficient since users will normally not keep those large files for a long time and will therefore not be able to compare the new time stamps against the old ones. Also, automatic distribution of updated files will relieve the file maintainer of the burden of keeping and maintaining a list of people who want to receive updated copies of the file, and will make this distribution more efficient whenever more than one server make the file available to users. There are other obvious advantages to this automatic distribution of updated files which led to the decision that LISTSERV should provide such a facility along with its file server functions. There are basically three types of automatic update distribution: o Shipment of the new updated version of the file. o Shipment of an update file (also called "delta" file). o Shipment of a short notice informing the user that the file has been updated. This last type of information is best suited to people who want to be kept informed about the file but do not know in advance whether they will need a copy of the new updated file immediately or not. LISTSERV only provides automatic update shipment of the first and third types, henceforth referred to as "Automatic File Distribution" process for the first type and "File Update Information" for the third type (NETSERV terminology). LISTSERV passwords ------------------ One of the main purposes of automated file distribution is to shift the burden of maintaining the "file-recipients" list from the main- tainer of the file to the subscribers themselves. The file-recipients must therefore be able to subscribe and unsubscribe to a file without any intervention from the list owner. However, the very concept of the RSCS (NJE) network makes it possible for authorized personnel to fake network addresses by a process that will not be described here for obvious reasons. Those people could send a message "from" any network address and subscribe a thousand people to a hundred files each, with obvious undesirable results. They could also unsubscribe people from several files or packages or play similar unwanted tricks. Last, but not least, the LISTSERV management at some nodes might not want to allow remote users to subscribe to files on their server due to the resulting load on their network lines. It was therefore decided that the use of the Automatic File Distrib- ution feature be subjected to the obtention of a LISTSERV password for the host server. Provision has been made to allow any network user to define himself such a password, within the regulations imposed by the local LISTSERV management. As soon as a password has been assigned to the user, he is able to subscribe to files without any intervention by the file maintainer or LISTSERV operation staff. Note: The person to be contacted in case you forget your password is the local LISTSERV manager. The file owner does NOT have authority to query LISTSERV passwords, even if he is also one of the managers of another LISTSERV. File Subscription lists ----------------------- LISTSERV will maintain two separate "subscription lists" for each user: the AFD and FUI subscription lists. They are completely inde- pendent and are maintained and processed separately by means of two similar commands: FUI and AFD. Subscription lists are local to each server, which makes it possible for a user to be subscribed to the same file from two different servers. It is solely the user's responsibility to ensure that his subscription lists do not overlap each other and that each file is being obtained from the nearest possible server. ********************************* * Obtaining a LISTSERV password * ********************************* To define yourself a password for LISTSERV, you must use the PW ADD command described below: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> PW ADD new_password CHange old_password new_password DELete old_password This command allows you to define yourself a password for use with LISTSERV, change that password, or delete it if you no longer need it. Note that the PW ADD function may have been disabled or restricted to a certain category of people by the local LISTSERV management. Please contact the local LISTSERV management, not the author, if you find yourself unable to use the PW ADD and think you ought to be able to define yourself a password. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< The syntax is fully compatible with the NETSERV one for the CHANGE option. The ADD and DELETE options are not because their function is completely different from that of their NETSERV counterparts. Note that you can also use the conventional LISTSERV syntax for the CHANGE command: PW CHANGE new-password PW=old-password Any user can change his password or delete it, regardless of it being added by a PW ADD command from the user or by the LISTSERV management. ********************************************* * The File Update Information (FUI) command * ********************************************* File Update Information (FUI) refers to the notification of an update in the file without any actual shipment of the updated file. It can be established by means of the FUI command as described below: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> FUI ADD filename filetype PW=password ! REP filename filetype PW=password DELete filename filetype PW=password GET filename filetype <(options> List Query ! FOR userid@node function This command allows you to subscribe to a file or package which you are normally authorized to retrieve from the server by means of a GET command (qqv). FUI DELete will remove your subscription to one or more files/packages (wildcard characters are accepted), while FUI List or Query will list the files/packages to which you have subscribed. The GET option allows file owners to request a list of people who have ! subscribed to their files. The FOR option allows NADs ! and LISTSERV postmasters to effect a FUI command on ! behalf of another user or series of users (wildcard ! characters are accepted for the LIST and DELETE ! functions). ! Available options for the GET subcommand are: ! Fileid Displays the fileid of the files. ! Useful in conjunction with wildcard ! characters. ! NOFileid Does not display the fileid. This is ! the default if no wildcard character ! appears in the parameter list. ! FROM user Shows files in the FUI-list of the ! specified user only. ! FOR user Synonym for FROM. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< The rules for filename, filetype and filelist-name are the same as for the GET command. Only a single information note will be sent for all the files that have been updated on a given day. This note will contain the updated FILELIST entries of all the files that have been changed on that day and are in the recipient's FUI subscription-list, and nothing else. Note that these filelist entries might span several records consid- ering the network-standard limit of 80 characters per record. However, the filelist owner might have requested that an immediate FUI note be sent out as soon as the file is updated, instead of waiting until the scheduled FUI broadcasting processing takes place (usually around midnight). In that case you would receive a separate FUI note for the corresponding file, and for this file only. ************************************************* * The Automatic File Distribution (AFD) command * ************************************************* Automatic File Distribution (AFD) refers to automatic distribution of the new updated file without any other form of notification. It can be established by means of the AFD command as described below: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> AFD ADD filename filetype > <"prologtext"> ! REP filename filetype > ! <"prologtext"> DELete filename filetype GET filename filetype <(options> ! List <(options> ! Query <(options> ! FOR userid@node function This command allows you to subscribe to a file or package which you are normally authorized to retrieve from the server by means of a GET command (qqv). The ! LISTSERV-standard "file-format" (F=fformat) and ! "file-class" (CLASS=fclass) keywords are honoured by ! the AFD command. AFD DELete will remove your subscription to one or more files/packages (wildcard characters are accepted), while AFD List or Query will list the files/packages to which you have subscribed. The GET option allows file owners to request a list of ! people who have subscribed to their files. The FOR ! option allows NADs and LISTSERV postmasters to effect ! an AFD command on behalf of another user or series of ! users (wildcard characters are accepted for the LIST ! and DELETE functions). The ADD and DELete options require a "PW=password" keyword to be specified. ! Available options for the GET subcommand are: ! Fileid Displays the fileid of the files. ! Useful in conjunction with wildcard ! characters. ! NOFileid Does not display the fileid. This is ! the default if no wildcard character ! appears in the parameter list. ! PRologtext Displays prologtexts (restricted to ! postmasters). This is the default. ! NOPrologtext Hides prologtexts. ! FROM user Shows files in the AFD-list of the ! specified user only. ! FOR user Synonym for FROM. ! Available options for the LIST subcommand are: ! PRologtext Displays the "prologtext" of each of ! the files. ! Format Displays the file format and class that ! have been associated with each of the ! files. ! FFormat Synonym of FORMAT. ! CLass Synonym of FORMAT. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< The rules for filename, filetype and filelist-name are the same as for the GET command. The only difference in syntax between AFD and FUI is the optional prologtext operand of the AFD command. It refers to an optional text that is to be inserted on top of the file before it is sent out to the user (ie it will be in record 1 of the file, with the actual contents starting in record 2). It can be specified either after the filel- ist-name operand or immediately after the filetype, in which case it must have been enclosed within double quotes. The default for AFD is to send out the revised copy of the file as soon as it is updated (this process is referred to as "immediate AFD"), except for FILELISTs which are sent out after FUI notification at midnight (or any other time chosen by the installation). Filelist owners can change this setting if they deem it necessary, of course. + + You may indicate a specific file-format and/or file-class along with + your AFD command. This specification will be recorded by LISTSERV and + used when sending a new version of the file. You can query the + format/class values recorded for the files you have subscribed to by + sending an AFD LIST (FORMAT command to LISTSERV. + LISTSERV will try to send new versions of AFD files as a DISTRIBUTE + job whenever possible, so as to minimize the network load caused by + this distribution. This means that you may receive the file from a + different LISTSERV server than the one you have sent the AFD command + to. However, if you have specified a prologtext in your AFD command, + you will always receive the file directly from the server you have + sent the AFD command to. + ************************************* * Appendix A. The LISTSERV Library * ************************************* o User's guide . . . . . . . . . . . . . . . . . . . . (U01-001) o List Manager's guide . . . . . . . . . . . . . . . . (M01-002) o Installation guide . . . . . . . . . . . . . . . . . (S01-003) o Application Programmer's guide . . . . . . . . . . . (A01-004) o Maintenance guide . . . . . . . . . . . . . . . . . . (S01-005) --> o File Server Functions . . . . . . . . . . . . . . . . (U01-006) o Listserv-Punch Implementation . . . . . . . . . . . . (R01-007) o File Maintainer's guide . . . . . . . . . . . . . . . (M01-008) o BITNET-Oriented Presentation . . . . . . . . . . . . (P01-009) o Public Utilities Reference . . . . . . . . . . . . . (A01-010) o Licensed Utilities Reference . . . . . . . . . . . . (S01-011) o Database Functions . . . . . . . . . . . . . . . . . (U01-012) LISTSERV Document Numbers ------------------------- U 01 - 006 - 0 _ __ ___ _ | | | | Document Class -----------+ | | | | | | | | | | | | Product Number --------------+ | | | | | | | | Publication Number -------------------+ | | | | Revision Number ------------------------+ Document Class The Document Class indicates for which category of persons the publi- cation was written. The current classes are: A Documents intended for Application Programmers. These publica- tions are usually very technical. M Documents intended for Software Managers, i.e. operators, "list owners", "file maintainers", et al. P General Presentation documents intended for persons who do not have any particular knowledge in the product. These are gener- ally non-technical documents. R Reference documents defining protocols used by the product. These documents are very technical and are intended for people who have to write interfaces for the product or attempt to port it to an operating system or environment for which it was not originally written. S Documents intended for Systems Programmers, i.e. the persons responsible for the installation and operation of the product. U Documents intended for General Users. Product Number The Product Number is a unique number associated with the product to which the publication relates. Number 01 refers to LISTSERV, number 02 corresponds to the NETINFO sub-product, etc. Publication Number This is a unique number associated with the publication. Publication Numbers are assigned sequentially, disregarding the Document Class. There is a different set of Publication Numbers for each product. Revision Number This number is incremented at every release change in the publication. Fractional numbers indicate intermediate changes between two releases.