Relayed File Distribution Requests ("RFDR Jobs") must imperatively be transmitted as a commands-job file. It is recommended that you read Section 2 Commands-Job Feature and CJLI Interpreter if you are not familiar with the basic concepts of CJLI.

By default DISTRIBUTE may only be executed by a LISTSERV maintainer (defined in the POSTMASTER= variable in the site configuration file) or a "trusted" user (identified in LISTSERV's site configuration file in the DIST_ALLOWED_USERS= variable) and requires a password (the invoker's personal LISTSERV password).

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, e.g. filename.filetype
    • A DISTRIBUTE command with the appropriate arguments:

DISTribute <type> <source> <dest> <options> PW=<password> 


Options for <type>:

      • MAIL – Data is a mail message and recipients are defined by ‘<dest>’.
      • MAIL-MERGE – Data is a mail-merge message.
      • POST – (non-z/VM only) Used to send pre-approved messages to moderated (Send=Editor) mailing lists. Typically, this is used only by automated scripts and LISTSERV Maestro. For more information, see Section 9.4.2 Sending Pre-Approved Messages to Moderated Lists.
      • FILE – (z/VM only) Data is not mail, recipients are defined by ‘<dest>’.
      • RFC822 – Data is mail, recipients are defined by the RFC822 To:/cc: fields.

<source> is:

      • DD=ddname – Name of a Ddname holding the data to distribute 
        (default: ‘DD=DATA’)

<dest> can be one of the following:

      • <TO> user1 <user2 <...>> – List of recipients.
      • <TO> DD=ddname – One recipient per line in a provided DD.

Available <options> are:

      • ACK=NONE|MAIL|MSG – Acknowledgement level (default: ACK=NONE).
      • CANON=YES – ‘TO’ list in canonical form.
      • DEBUG=YES – Do not actually perform the distribution; returns debug path information.
      • INFORM=MAIL – Send file delivery message to recipients via mail.
      • TRACE=YES – Similar to DEBUG=YES, but the mail or file is actually distributed.
      • AV=YES[,FORCE] – Check the message for viruses. The FORCE option overrides any maximum message size limit that is set.
      • DKIM=YES | NO – Sign (or don’t sign) the message with a DomainKeys signature. Default is DKIM=NO.
      • PRIO=* | NN – Set a network transmission priority level for the file.
      • INFORM=MSG | MAIL – For non-mail DISTRIBUTE only, specify how to inform users that they have received the file. Effective on z/VM only.

<options> that require postmaster-level privileges:

      • FROM=user – File originator (RFC821 MAIL FROM:).
      • FROM=DD=ddname – One line:’address name’.
      • PRE-APPROVED=YES – Pre-approve message (with DISTRIBUTE POST only).

All the keywords (except PW=) can be omitted, but must be specified in the indicated order. The "PRIOR" and "INFORM" keywords are independent from the others and can appear anywhere in the command line. The DISTRIBUTE command requires a password (PW=password, above) for validation purposes. A description of the keywords follows:

      • A "type" of DISTRIBUTE must be defined as the first parameter to the DISTRIBUTE command. Specifying MAIL indicates that the file to be distributed is a mail file, 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 mail file 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.

        Other DISTRIBUTE "types" are MAIL-MERGE (described in the chapter below on DBMS and mail-merge), POST (a method used when messages are "pre-approved", typically by LISTSERV Maestro), FILE (obsolete except for z/VM servers), and RFC822 (where the data is mail and the recipients are defined by the RFC822 To: and cc: fields found in the data). 

        All DISTRIBUTE jobs sent from non-z/VM servers will be MAIL-type DISTRIBUTE jobs. Non-MAIL DISTRIBUTE is available only on z/VM.
      • DD=ddname is the ddname corresponding to the data to be transmitted (i.e. the file or mail file). 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, e.g. FROM=DD=XXX and //XXX DD "JPB@BIGNODE John P. Brown". The default is FROM= your-userid. 

        This field contains the address you want bounces to go to (the RFC821 MAIL FROM: address) and it can be used to redirect bounces that should not normally go to the user invoking DISTRIBUTE--e.g., it can be set to a special address set up specifically to handle errors for this particular DISTRIBUTE job.

        You do not have to indicate your name when distributing MAIL-type files -- put your name in the "From:"/"Sender:"/whatever field, as appropriate.
      • 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 mail file. 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 <full name>" 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 LISTSERV 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 (effective on z/VM only) 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 recipients via mail. Note that this option is ignored when MAIL distribution has been selected.
      • Finally, a password is required to validate the command invoker. This is a standard LISTSERV personal password, set with the PW ADD command. 
    • 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. This dataset contains network addresses (imperatively) and per-address options, one address/options per line. The per-address options are a real-name field and the keywords BSMTP or PROBE (BSMTP and PROBE are mutually-exclusive; only one can be specified per address). For instance a TO dataset could contain lines like

janecustomer@abc.com
jacktechie@def.edu Jack Techie
johndoe@ghi.org BSMTP
joe@example.com PROBE
sue@example.edu Sue User BSMTP
petergunn@example.edu Pete Gunn PROBE


When the BSMTP option is specified, LISTSERV will combine the address along with any other addresses for which BSMTP is specified into a multi-recipient BSMTP envelope (which is much more efficient, since not using BSMTP tells LISTSERV to create a separate SMTP envelope for each address). For general DISTRIBUTE jobs (i.e., non-mail-merge jobs), it is probably most efficient to specify BSMTP for all addresses in the job.

When the PROBE option is specified, LISTSERV will process the address as a PROBE. This is most useful when using a backend list or a changelog file for error processing (see the section on "Advanced LISTSERV applications using DISTRIBUTE", below, for more information on these features; also see the sections on LISTSERV's address probing in the Site Manager's Operations Manual and/or in the List Owner's Manual). PROBE should not be used on one-off DISTRIBUTE jobs which do not require specialized error processing, as it has no particular usefulness otherwise.

Again, BSMTP and PROBE are mutually-exclusive; you may specify one or the other but not both.

    • Finally, a dataset for the "DD=" keyword, to contain the mail message or 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 possible "/*" card in the data. On VM, for storage space saving and performance considerations, the "Res=Disk" option should be specified on that DD card, i.e. 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 under z/VM 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 file 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 recipients are routed to their gateway, 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 standard mail envelope 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).