The Best of Windows 95.com 1996 September

home *** CD-ROM | disk | FTP | other *** search

/ The Best of Windows 95.com 1996 September / WIN95_09961.iso / mailsrv / LSV95.ZIP / win95.z / listfile.memo < prev next >

Wrap

Text File | 1995-05-24 | 26KB | 607 lines

LISTSERV historical documentation, release 1.5m ----------------------------------------------- Copyright Eric Thomas 1986,1987 +---------------------------------------------------------+ | Revised LISTSERV: File Server Functions | +---------------------------------------------------------+ | | | Document number: U01-006a-0 (October 17th, 1987) | | | | Document fileid: "LISTFILE MEMO" (from "Info FILEs") | +---------------------------------------------------------+ 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. + **************** * Introduction * **************** Although the primary function of LISTSERV is to distribute mail and files to predefined distribution lists, it may often be desired to provide the subscribers of the list with a set of data or program files to be periodically maintained by a particular person or set of persons. Apart from the obvious example of list "notebooks" (archives), working groups might want to provide minutes of internal meetings held by some of the subscribers, technical groups might want to share application programs related to some software they are all using, etc. It was decided that the most convenient way of meeting these needs was to provide basic, non-specialized file-server functions along with the mail-processing functions of LISTSERV. Those functions would have to provide powerful yet list-based file access control and remote file updating facilities, under the control of both the list owner and the LISTSERV management. Automatic distribution of updated materials to subscribers was another major concern since it makes this distribution more efficient whenever the list is supported by more than one peer server, and relieves the file maintainer of the burden of preparing the list of subscribers - the users request such distribution directly from the server without any intervention from the file maintainer. It was decided that LISTSERV should conform to the well-implemented and well-accepted standard command set of the NETSERV file-server developped by Berthold Pasch <PASCH@DHDIBM1> for EARN. Commands should be similar enough so as not to confuse unexperienced users who switch from one type of server to the other, with additional commands or parameters being provided if needed. The LISTSERV commands should conform to the general LISTSERV conventions whenever there is a conflict between the LISTSERV and NETSERV commands, the best solution being of course to support both conventions to allow for application programs written for NETSERV to operate with LISTSERV with a minimal amount of changes. A presentation of the set of commands that were retained will follow. You should note that a significant number of these commands have the same syntax for LISTSERV and NETSERV and yet operate very differently on the two servers (the best example being the PW command). ************* * FILELISTs * ************* Several "file directories" (FILELISTs) were required to allow each list to have its own set of files, independently from the other lists, and to make it possible to hide the very existence of private files from those users who are not supposed to retrieve them. LISTSERV maintains a number of FILELISTs which can be nested in each other if needed. The "root" filelist is called LISTSERV FILELIST and is always maintained by the LISTSERV management. In UNIX terms, a FILELIST is a "directory"which can contain sub-directories (any level of nesting is allowed) and is defined upwards in the tree structure with the root being LISTSERV FILELIST. To review the contents of a filelist, you can either request it to be sent to you by means of the usual GET command (see later on) or use the special command INDEX as follows: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> ! INDex <filelist_name> <F=fformat> <CLASS=fclass> Sends you the specified filelist (defaults to LISTSERV FILELIST). This command is strictly equivalent to "GET filelist_name FILELIST" and has been made available for compatibility with other file servers on the network. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< LISTSERV filelists are almost fully compatible with the ones you may obtain from NETSERV. The header of the filelist will provide informa- tion about the contents of the filelist directory and a list of File Access Codes (FACs) which will be used later in the body of the filelist to identify who is authorized to retrieve the files or store them into the server. This FAC list is included between "banners" made of an asterisk, a blank and a full line of colons, and will usually have been commented by the maintainer of the filelist to provide more information as to whom the FACs refer to. The body of the filelist will contain file declarations, possibly interspersed with comment lines. Comment lines start with an asterisk in column one. The format of the file-declaration lines is as follows (column numbers have been given for easier reference by application programmers): +--------------------------------------------------------------------+ | 1 3 12 23 26 31 35 | | | | | | | | | | | filename filetype get put rfm lrecl | | SAMPLE FILE ALL CTL VP 106 | | | | 41 47 56 65 | | | | | | | | nrecs date time description | | 85 86/11/12 19:50:14 Dummy file | | | | Figure 1. File-definition line format | +--------------------------------------------------------------------+ filename is the 'name' of the file as it should appear in a GET command. filetype is the 'type' of the file as it should appear in a GET command. get is the FAC that controls read access to the file. That is, people who do not "meet" that FAC will not be able to issue GET commands for the file. put is the FAC that controls write access to the file. Usually points to the file maintainers. rfm is the record-format of the file. The first letter is either "V" for "Variable length records" or "F" for "Fixed length records", while the second letter will be set to "P" for "Packed format files" or left blank for non-packed files. Note that packed files will be automatically unpacked prior to being sent to you as a result of a GET command or Automatic File Distribution process; however, if you obtain a direct LINK to the disk on which they are stored, you will find them to be in packed format. nrecs is the number of records in the file. Files flagged with nrecs = 0 and dots in the other fields are not yet available but can be subscribed to or stored by their maintainer. date/time is the date the file was last updated, in yy/mm/dd format (this makes it easier to sort the filelist by date). Note that the process of updating the "date" field in a filelist causes the filelist itself to be flagged as changed and the corresponding date/time in its entry up the tree structure to be modified accordingly. ********************** * Ordering the files * ********************** The GET command --------------- >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> ! GET fn ft <filelist_name> <F=fformat> <CLASS=fclass> Sends you the requested file provided you are authorized to retrieve it. Synonyms have been defined for the GETND, GETDD, ! GETPP, GETLP and GET80 commands of Netserv. "GETND xxxx" is translated to "GET xxxx F=Netdata", etc. Note that in this implementation, GETPP and GET80 are strictly equivalents and will cause the file to be sent in Listserv-Punch format if its logical record length is greater than 80. Send an "Info LPUNch" command to LISTSERV for more information about Listserv-Punch format. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< You can use the GET command, or its synonym SENDme, to request a file to be sent to you. You must specify the filename and filetype of the file as their appear in the filelist, and you may optionally append a third parameter to the command to indicate from which filelist you want the search for the file to start. This parameter is normally not required unless there is more than one file available from LISTSERV with the filename and filetype you are requesting. Application programs which issue GET commands to LISTSERV and know the filelist name should specify it since it speeds up the filelist search. The default is to start at the root filelist, of course. + + For security reasons, files with a filetype of "FILELIST" are always + sought from the root filelist, regardless of the filelist parameter + specified on the command. + ! The LISTSERV-standard "file-format"(F=fformat) and "file-class" ! (CLASS=fclass) keywords are supported on this command. Additionally, synonyms have been defined for the NETSERV GETxx (e.g. GETND, GETDD) commands. Note that the NETSERV GET80 format is not supported by LISTSERV; LISTSERV-Punch (refer to the "Revised LISTSERV: LISTSERV-Punch Implementation Guide" - Document Number R01-007 - for more details) format is substituted. The LISTSERV GET command is compatible with the NETSERV one, with the exception of: o The GET80 format restriction. ! o The addition of the optional file-format and file-class keywords. o The addition of the optional filelist-name parameter. > o The "prologtext" feature of NETSERV, which is not implemented in > the LISTSERV GET command. The GETALL command ------------------ ! >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> ! GETALL fn ft <filelist> <F=fformat> <CLASS=fclass> ! Sends you the requested file provided that you are ! either authorized to GET it (refer to the description ! of the GET command for more details), or you are ! authorized to PUT the filelist that defines it or any ! other filelist in the same branch up the tree ! structure. ! <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ! The GETALL command allows filelist owners to retrieve files defined in ! a filelist that they can PUT, but which they are not allowed to access ! via the GET command because their File Access Codes prevent it. That ! is, whenever the command originator would be able to change the File ! Access Code that prevents him from retrieving the file by modifying ! the filelist in which it is defined, he is allowed to obtain the file ! directly by means of a GETALL command. + + o It should be noted that the GETALL command can be used in all + instances where the GET command would be accepted. Since the + syntax is identical, it can be systematically substituted to GET + whenever desired. You should note, however, that it takes a + significantly higher amount of processor time to LISTSERV to + process a GETALL command. You should therefore avoid using the + GETALL command on a regular basis, and give yourself GET authority + on all the files you plan to retrieve regularly. + o The GETALL command will only bypass the File Access Code access + restriction. If any File Access Verification Exit has been estab- + lished for the file, it will still receive control and might still + deny access to the file. + o The LISTSERV operation staff normally has PUT access over the root + filelist, LISTSERV FILELIST. This implies having GETALL access + over all the files stored on the local server. + The GIVE command ---------------- >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> GIVE fn ft <filelist> <TO> userid@node <F=fformat> ! <CLASS=fclass> Sends the requested file to the specified userid, provided you would be authorized to retrieve it yourself by means of a GET command. The destination userid will receive a mail message saying that you requested the file to be sent to him. You will get a copy of all messages sent to him so that you are informed if some error occurs while sending the file. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ! The GIVE command allows you to request LISTSERV to send a file or ! package to another network user. This is very useful when you want to ! send a file to some user who is not authorized to retrieve it but who ! is topologically nearer to the server than to you. It also allows you ! to order files for people who are not able to issue the requests them- ! selves, for example people behind a one-way gateway which allows mail ! to be received but not sent out to LISTSERV. + + o The filelist maintainer has the option to disable the GIVE command + on a file-per-file basis. This will usually have been done for + confidential files or large files which should not leave the + server's node. + o For technical reasons, it is not possible to GIVE a LIST file: the + present inter-server command protocol does not allow a destination + address different from the command origin address, which would + make it impossible to consistently forward the GIVE request to + other servers. + ************ * Packages * ************ The term "package" refers to a set of program or data files which are supposed to be retrieved together under normal conditions. Provision has been made to allow users to retrieve those packages with a single command, and to subscribe to it as a whole with updated versions of only the individual changed files being sent out. The package exists independently of its individual components which can still be refer- enced separately. With each package is associated a dummy file and a definition file. The dummy file has a fileid of "package-name PACKAGE" and does not really exist. However, ordering this dummy file will cause the whole set of files to be sent to you. Similarly, subscribing to this single dummy file will result in a global subscription for all the components of the package. As a rule of thumb, the dummy file should be used whenever reference is made to the package as a whole. The definition file has a fileid of "package-name $PACKAGE" and lists the set of files that are contained in the package. Unlike the dummy file, it really exists and can be retrieved as any other normal file. It will usually list itself as the first file of the package so that you get a copy of it and you can check you have received all required files before starting to use the package. It may reference another package which is required for the package you ordered to be used (any level of nesting is allowed). If you subscribe to a package via Auto- matic File Distribution (qqv), you will automatically receive updated versions of all the corresponding sub-packages if they are updated. Similarly, ordering the package will cause all sub-packages to be sent to you. + + Application programmers wishing to parse the contents of a package + file should use the following algorithm: + o Blank lines and lines starting with an asterisk are comment lines + and should be ignored. + o Each non-comment line describes a file which belongs to the + package. The first two words of the line are the (mandatory) + filename and filetype, the third word is the optional filelist, + and all remaining words are optional comments which should be + ignored. The program should be able to handle any number of + blanks between words as well as before the first word in the line. + ************* * Notebooks * ************* LISTSERV is able to automatically keep notebooks for a list if the list owner so desires. Those notebooks are listed in a special filelist called "NOTEBOOK FILELIST", which is automatically maintained by the server according to the parameters specified in the headers of ! its various lists. They will also be automatically appended to the ! corresponding "listname FILELIST"(if it exists) so as to make it ! possible to get a listing of all archive files kept for a particular ! list without having to retrieve the whole NOTEBOOK FILELIST. If no ! "listname FILELIST" has been prepared by the list owner, LISTSERV will ! automatically create a dummy one with no file-definition entries other ! than the ones for the notebook files kept for the list. This dummy ! filelist can be retrieved or subscribed to (via the AFD and FUI ! commands) as if it were a normal filelist. ! The NOTEBOOK FILELIST can be subscribed to via FUI, but its retrieval ! has been restricted to registered Node Administrators (NADs) as it is ! usually a very large file prone to generate significant network ! traffic. The files listed in the NOTEBOOK filelist are just like normal files and can be retrieved as indicated by their GET File Access Code. They can be subscribed to as normal files, and can even be modified or deleted by their owners, as indicated by their PUT FAC (which usually points to the list owners). However, once such a file has been deleted, it will disappear permanently from the filelist, unlike a normal file which would be forced to nrecs = 0 but would remain listed. + + Any archive file can be ordered either as "filename filetype listname" + or as "filename filetype NOTEBOOK". The two syntaxes will produce + strictly equivalent results, regardless of whether the NOTEBOOK + filelist has been made available to general users by the local LIST- + SERV management or not. However, it is recommended that the latter + form be preferred in application programs as it will result in better + response time from the server: the NOTEBOOK filelist always denotes + list archive files whereas the listname filelist might contain other + files, which makes it impossible to optimize the search algorithm. + ************************************* * 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.