LISTSERV historical documentation, release 1.5d ----------------------------------------------- Copyright Eric Thomas 1986 ************************************************************ * * * A description of the Relayed File Distribution feature * * * ************************************************************ **************** * Introduction * **************** The Relayed File Distribution feature was developped in an attempt to provide an efficient and network-resources-saving means whereby files and mail can be distributed to a large number of persons on the network by ANY network user, without having to resort to predefined distribu- tion lists (which have other advantages but are basically static). This information guide is composed of two independent sections. The first one is a description of the distribution algorithm used by Relay- ed File Distribution. It is general enough to be accessible to inexpert computer users, but does not explain how to send a Relayed File Distri- bution Request (RFDR) to LISTSERV. The second section gives a detailed technical description of RFDRs and assumes the reader is familiar with the basic concepts of the Command Job Language Interpreter (CJLI). More information about CJLI can be obtained by sending an "INFO JOB" command to LISTSERV. *************************************************** * Section 1 -- What is Relayed File Distribution? * *************************************************** Relayed File Distribution is a service provided by the (growing) network of Revised LISTSERVs to all the users connected to BITNET, EARN or NetNorth and allowed to send and receive files (messages are not needed). The user desiring to send the file (which we will call the 'sender') provides its nearest Revised LISTSERV host with a copy of the file to be distributed and the list of persons who are to receive it. He can optionally indicate the full name of these persons as well as his own full name, and they will be used in information messages and mail headers as appropriate. The LISTSERVs will then relay the file to each other as explained below and distribute the file to all the indicated recipients in the most efficient way they could 'manage'. The server that initially receives the file from the sender will first distribute the file to the (possible) recipients of its local node, which does not generate any network traffic. It will then examine the list of non-local recipients and determine, for each of them, which of the Revised LISTSERV servers is nearest. Everytime it finds itself to be the nearest server, it distributes the file directly, and removes the recipient from the list. It then uses a rather complex algorithm to "route" the remaining recipients through its nearest servers, and transmits the request to them. This will be best illustrated by an example. User X@FRECP11 sends a file distribution request for the following list of people: Y@FRECP11,X@CEARN,Y@CEARN,X@CZHRZU1A,X@NEUVM1,X@IBACSATA, X@EARNET, X@PSUVM We will assume that a Revised LISTSERV has been installed at the following sites: FRECP11, CEARN, DEARN, DKEARN, EARNET Finally we will assume the following topology, which will not necessa rily reflect the actual network topology at the time you read this memo (it has been simplified and nodes which do not participate in the transfer have been removed) CZHRZU1A | | V FRECP11 --> FRORS31 --> FRHEC11 --> CEARN --> DEARN --> DKEARN --> NEUVM1 | | | | | V | GWUVM --> PSUVM V EARNET --> IBACSATA The file is distributed by LISTSERV@FRECP11 to Y@FRECP11, and then forwarded to LISTSERV@CEARN, which will distribute to the two CEARN recipients and to X@CZHRZU1A. LISTSERV@CEARN then forwards one copy of the file to LISTSERV@DEARN and one to LISTSERV@EARNET, with the appro- priate list of recipients. LISTSERV@EARNET distributes to the EARNET recipient and to X@IBACSATA. LISTSERV@DEARN distributes to X@PSUVM, and also to X@NEUVM1. LISTSERV@DKEARN does not receive anything because it would have served only a unique recipient, and in that case a direct send can only be better. The file has therefore crossed a total of 11 links. If it had been sent the normal way from FRECP11, it would have had to cross 32 links, ie thrice more. The reduction is very important because we assumed that a server is installed at all the central nodes in the network, which is not necessarily the case in practice. ******************************************************************** * Section 2 -- A description of Relayed File Distribution Requests * ******************************************************************** Relayed File Distribution Requests (RFDR) must imperatively be trans- mitted as a commands-job file. It is recommended that you obtain the commands-job description memo from LISTSERV ("Info JOB" command) and read it if you are not familiar with the basic concepts of CJLI. The job sent to the server must contain: - A JOB card with the "Echo=No" option to avoid tracing the unique command to the job output. The "Reply-via=" keyword can be set to "Message" if so desired, although this is not recommended. The job name can be anything you want, eg filename.filetype - A DISTRIBUTE command with the appropriate arguments: DISTribute < > > ! All the keywords can be omitted, but must be specified in the indica- ! ted order. The "PRIOR" and "INFORM" keywords are indepedent from the ! others and can appear anywhere in the command line. A description of ! the keywords follows: * MAIL indicates that the file to be distributed is a mailfile, to be sent to the MAILER at the destination node. The contents of the file are proofread and the "mail origin" is verified so that users cannot send forged mail. MAIL-type distribution is 100% transparent to the mail recipient, which is not the case with file distribution -- a file would come from the LISTSERV userid instead of the sender's userid. The mailfile must contain a blank "To:" line where the actual name and network address of each recipient will be automatically inserted as the file is distributed to him. * DD=ddname is the ddname corresponding to the data to be transmit- ted (ie the file or mailfile). The default is "DD=DATA" * FROM=xxxx indicates either the network address of the file sender or the name of a dataset of which the first line indicates the network address and full name of the file sender, eg FROM=DD=XXX and //XXX DD "JPB@BIGNODE John P. Brown". The default is FROM= your-userid. You are not allowed to specify an origin different from your own network address, of course, so you should not use that option unless you want to specify your full name. You do not have to indicate your name when distributing MAIL-type files -- put your name in the "From:"/"Sender:"/whatever field, as appro- priate. * ACK= indicates the amount of acknowledgement you want to get. The default is NOne and indicates you do not want to receive messages as the file is distributed. MAIL indicates mail acknowledgements while MSG indicate interactive messages. * TO indicates the list of recipients for the file or mailfile. It can either be a list of network addresses ("TO u@n1 u@n2...."), which must not cause the physical command line to exceed 255 characters (use continuation cards in that case), or a ddname of which each line is a "userid@node " pair. The former is best suited to file distribution while the latter should be preferred for MAIL-type distribution since the recipient's full name will be inserted in the "To:" field of the mail file. The ! default is "TO DD=TO". Note that distributing a file to a LIST- ! SERV userid will cause it to be interpreted as a command job for ! execution or a PUT request, as appropriate. Releases 1.5b and ! earlier did not accept such a destination for DISTRIBUTEd files ! and ignored the recipient. ! * PRIOR is the network transmission priority you want to assign to ! the file. If specified, it can be either "*" or an integer number ! between 0 and 99, inclusive. "*" indicates that the file priority ! is left up to LISTSERV, which will use an internal algorithm to ! assign a reasonable priority to the file according to its number ! of records. ! * INFORM specifies the media by which you want users to be informed ! of the arrival of the file. The default is MSG for interactive ! messages -- specify MAIL if you want LISTSERV to notify reci- ! pients via mail. Note that this option is ignored when MAIL dis- ! tribution has been selected. ! --> Note about the PRIOR and INFORM keywords: these two options are ! not supported by servers whose release number is lower than 1.5d ! and would result in an error message if sent to such a server. ! However, those servers which can accept the keyword are able to ! identify the "older" servers and will suppress the option when ! forwarding the file to distribution to such a server. There ! should therefore be no compatibility problem. - A dataset for the "FROM=DD=" keyword, if specified -- the DD "text" syntax is recommended since the dataset will contain only a single line of data. - A dataset for the "TO DD=" keyword, if specified -- the DD * syntax is best suited to this dataset. - Finally, a dataset for the "DD=" keyword, to contain the file. This should be the last dataset in the file and the DD *,EOF syntax should be used to ensure that the dataset is not prematurely ended by a pos- ! sible "/*" card in the data. Also, for storage space saving and per- ! formance considerations, the "Res=Disk" option should be specified on ! that DD card, ie: DD *,EOF,Res=Disk. Statistics have shown that this ! decreases the CPU time required to process the request by a factor of ! six... Mail-type RFDR must IMPERATIVELY use raw-image (PUNCH) format for the mail dataset, since the header will be scanned and modified by the server. File-type RFDRs can use any type of network filke format -- the contents of the "data" dataset will be sent "as is" to the recipients, without anything added on top or bottom of it. The only difference will be the RSCS file origin -- the file will come from the LISTSERV userid instead of the sender's userid. The file class, spool fileid and DIST- code are preserved, but the FORM is changed to QU-DIST to trigger the "quiet file transfer" feature installed in some RSCSs in the network. Non-BITNET addresses: non-BITNET recipients are routed to their gate- way, as determined by the DOMAIN NAMES file. The first server in the chain that finds itself unable to determine the gateway distributes the file directly. Whenever non-mail file is distributed to a non-BITNET user, LISTSERV generates a sample mail enveloppe with the current date, sender's name and address, recipient's address and transfers it to the mailer. Any possible rejection mail will be sent directly to the sender by the mailing system (and not to the LISTSERV userid). ************************ * Sample mail RFDR job * ************************ //V22.5y JOB Echo=No DISTRIBUTE MAIL //TO DD * USER1@NODE1 Howard P. Craftlove USER2@NODE2 June Guiness USER3@NODE3 . . USERn@NODEn Sarah Crawford /* //DATA DD *,EOF,Res=Disk Date: Sun, 5 Oct 1986 22:51:20 SET From: O. Roger Simpson '31' Subject: Version 22.5y of the WONDERful conferencing system To: Dear colleagues, Version 22.5y of the WONDER conferencing system is now ready. I am sen- ding it now via the new DISTRIBUTE command of Revised LISTSERV. You should receive three files, WONDER PKG1, WONDER PKG2 and WONDER INSTL225. Don't forget to issue a GIMME CANCER command to the server after instal- ling the new version, so that you receive an up-to-date version of the CANCER full-screen interface. Those of you that are confined to teletype terminals may still use the old FRAIL interface -- I didn't change it in this release. Happy WONDERing... /Roger ************************ * Sample file RFDR job * ************************ //V22.5y JOB Echo=No DISTRIBUTE FROM=DD=ME ACK=MSG TO USER1@NODE1 USER2@NODE2 ... USERn@NODEn //ME DD "ORS@BIGVM O. Roger Simpson" //DATA DD *,EOF,Res=Disk :CARD WONDMAG1MODULE S2VÈ83 c &bbÈÈ  \i <ËfŒESDe bZ000002 i" ŸÈŒŽ} í¦0¦jÿâA ¦Ÿ{KA&KAצA«KA«Bº¨0 Ñâ×AKA«B”¨” N×Bqâ×{-o BbKA«B:¦A«Ë ºÿâ×A¨AšKA—K"AtKAÚj Bbâ{{¦×¦øB/¦ŒAA0A¦×¦øB|¦ŒAæ0Ak/A¿3A] k AÄâ0{2¦×¦øB|¦ŒAæ0Ak/A¿KA]k AĦצøB¨¦ŒAA0Aâ0Aj BbâA¨‹K Aùmâ 0AK AùKABh¦AËKABŒ¦A˨\} q }§KŒø£Œ×ÿa ESTATEA*-*D *-*DA1eWRBUFBFNAMEBFTYPEBA1bŒb &F *ÿÿ§/C:C ::FSTLKPA E STATEASTATEBeWRBUFBFINISBDSKÄÄÄÄŒ.á.°«.Ù.ç .ä :CARD WONDMAG2MODULE S2VÈ83 c ¦Ÿ{KA&KAצA«KA«Bº¨0 Ñâ×AKA«B”¨” N×Bqâ×{-o BbKA«B:¦A«Ë STATEASTATEBeWRBUFBFINISBDSKÄÄÄÄŒ.á.°«.Ù.ç .ä ºÿâ×A¨AšKA—K"AtKAÚj Bbâ{{¦×¦øB/¦ŒAA0A¦×¦øB|¦ŒAæ0Ak/A¿3A] k AÄâ0{2¦×¦øB|¦ŒAæ0Ak/A¿KA]k AĦצøB¨¦ŒAA0Aâ0Aj BbâA¨‹K Aùmâ &bbÈÈ  \i <ËfŒESDe bZ000002 i" ŸÈŒŽ} í¦0¦jÿâA 0AK AùKABh¦AËKABŒ¦A˨\} q }§KŒø£Œ×ÿa ESTATEA*-*D