home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Spezial / SPEZIAL2_97.zip / SPEZIAL2_97.iso / ANWEND / ONLINE / VSOUP128 / VSOUP128.ZIP / vsoup.INF (.txt) < prev    next >
OS/2 Help File  |  1997-04-20  |  93KB  |  2,567 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. 1 Introduction to VSoup ΓòÉΓòÉΓòÉ
  3.  
  4.  VSoup1.2.8  19-Apr-1997
  5.  
  6.  The multithreaded Souper for OS/2
  7.  
  8.  Copyright (c) 1996-1997 by Hardy Griech 
  9.  
  10.  VSoup1.2.8 is a multithreaded network mail and news client program for OS/2 
  11.  Warp with TCP/IP (or the Internet Access Kit) installed.  It transfers mail 
  12.  and news fetched from a POP3 server and NNTP server respectively to packets in 
  13.  SOUP format.  It can also send messages in SOUP reply packets to NNTP / SMTP 
  14.  servers. 
  15.  
  16.  VSoup is especially designed to work with Yarn, but it is probable that VSoup 
  17.  will work with most offline newsreaders which expect SOUP as their input and 
  18.  output. 
  19.  
  20.  The program requires the emx run-time DLLs.  You can get these from e.g. 
  21.  
  22.      ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/emxrt.zip 
  23.  
  24.  The emx09c run-times or newer are required.  emxrev should show at least 
  25.  revision 50 for the DLLs.  VSoup may work with an earlier version such as 
  26.  emx09b, but keep in mind that there were many changes in the DLLs concerning 
  27.  multithreading / sockets since emx09a. 
  28.  
  29.  
  30.  !!!!! MAKE SURE THAT YOU ARE USING THE CORRECT EMX DLL-VERSIONS !!!!!
  31.  
  32.  
  33. ΓòÉΓòÉΓòÉ 2. 2 Legal Issues ΓòÉΓòÉΓòÉ
  34.  
  35.  This program is heavily based on ideas and modules from Chin Huangs 
  36.  (cthuang@io.org) Souper15.  Thanks to him for both Souper and Yarn. 
  37.  
  38.  Please note that bug reports and everything else concerning VSoup should be 
  39.  directed to Hardy Griech (rgriech@swol.de), not to Chin Huang! 
  40.  
  41.  Standard Disclaimer 
  42.  
  43.  VSoup is free software; you can redistribute it and/or modify it under the 
  44.  terms of the GNU General Public License (GPL) as published by the Free 
  45.  Software Foundation; either version 2, or (at your option) any later version. 
  46.  For more details about the GPL see the file COPYING contained in this archive. 
  47.  
  48.  VSoup is distributed in the hope that it will be useful, but without any 
  49.  warranty; without even the implied warranty of merchantability or fitness for 
  50.  a particular purpose.  See the GNU General Public License for more details. 
  51.  
  52.  Warning 
  53.  
  54.  Some news sites might see VSoup as a news sucking utility and might feel 
  55.  offended by its use. 
  56.  
  57.  The intention is that VSoup is to be used to receive news for your personal 
  58.  use from a reasonable number of newsgroups. 
  59.  
  60.  Misuse of this program could conceivably result in a general ban on the use of 
  61.  this or similar programs to the detriment of responsible VSoup users who 
  62.  certainly don't want a general ban of VSoup. 
  63.  
  64.  
  65. ΓòÉΓòÉΓòÉ 3. 3 Features ΓòÉΓòÉΓòÉ
  66.  
  67.      Multithreaded news receiving is supported, anything between 1 and 10 
  68.       threads can be started (default 4), and in addition there are several 
  69.       possible strategies for fine tuning. 
  70.  
  71.       Multithreading gives a speed gain of 200%-500% depending on the overall 
  72.       speed of the connection and the number of threads; on the other hand 
  73.       multiple connections have a communication overhead (i.e. the connections 
  74.       must be established, the groups selected).  Estimated loss is around 
  75.       5%... 
  76.  
  77.      all the packets are exchanged in SOUP format files, i.e. offline readers 
  78.       expecting as input format either SOUP or USENET batch format can be used 
  79.       together with VSoup. 
  80.  
  81.      VSoup generates a status message as incoming mail.  (this is not in the 
  82.       SOUP standard, but is recognized by Yarn).  Normally this message is only 
  83.       generated in case of failure (eg., cannot select newsgroup) or when 
  84.       special events occur (eg., when new newsgroups are added), but the 
  85.       generation can be forced to always occur by means of a command line 
  86.       option. 
  87.  
  88.      VSoup will show some statistic information about data transfer. 
  89.  
  90.      Specification of the required servers is easy by using URLs on the 
  91.       command line. 
  92.  
  93.      It is possible to filter articles by header lines before retrieving the 
  94.       body text, see score file handling.  VSoup allows regular expression for 
  95.       both group and header patterns, article length is treated special. 
  96.  
  97.      VSoup detects too low throughput or stuck connections. 
  98.  
  99.      VSoup knows about NNTP authentication. 
  100.  
  101.      YarnIo, a script to do VSoup operation safely (without risk of message 
  102.       loss etc.)  is included in the archive.  YarnIo is capable of 
  103.       simultaneously receiving news from up to nine separate NNTP news servers, 
  104.       posting news to NNTP, receiving mail from up to nine POP3 servers and 
  105.       sending mail to SMTP. 
  106.  
  107.      Other utilities included are 
  108.  
  109.       OwnSoup      This, with the help of the Yarn import program, redirects 
  110.                    news articles matching a specific pattern into a separate 
  111.                    mail folder which will show up when you read your mail with 
  112.                    Yarn. 
  113.  
  114.                    For example you can search newsgroups for any mention of 
  115.                    your name or any mention of a program you are interested in. 
  116.  
  117.       QSoup        This appends mail and news messages to the Yarn reply packet 
  118.                    file for transmission by VSoup. 
  119.  
  120.       ConvSoup     This transforms all articles from binary SOUP format to 
  121.                    mailbox/USENET format. 
  122.  
  123.      FAQ included. 
  124.  
  125.      source code included. 
  126.  
  127.      freeware according to GPL (without any warranty for correct function 
  128.       etc.). 
  129.  
  130.  
  131. ΓòÉΓòÉΓòÉ 4. 4 Installation ΓòÉΓòÉΓòÉ
  132.  
  133.  This section describes the installation of VSoup on a step by step basis. 
  134.  Steps (1)-(4) are for preparation to ensure that you have a system 
  135.  configuration which can run VSoup1.2.8. 
  136.  
  137.  The installation instructions assume that you intend to run VSoup with the 
  138.  help of YarnIo.  If you wish to use VSoup on its own for example to benefit 
  139.  from multithreaded news reception, but do not need YarnIo, simply skip the 
  140.  steps (7)-(11) and parts of (6). 
  141.  
  142.  Anyway you can use YARNIO.CMD as an example. 
  143.  
  144.  If you experience any problems take a look at the troubleshooting section. 
  145.  
  146.  If you are upgrading an older VSoup version, you should have a look at the 
  147.  history section for hints on important changes. 
  148.  
  149.  
  150.    1. your system must be one of the following: 
  151.  
  152.           OS/2 2.x with TCP/IP (not tested but should work) 
  153.  
  154.           OS/2 3.0 (Warp) with the 'Internet Access Kit' installed 
  155.  
  156.           OS/2 3.0 (Warp Connect) with TCP/IP installed 
  157.  
  158.           anything above 
  159.  
  160.    2. get the latest version of the emx runtime library and install it or check 
  161.       your current installation with emxrev.  This should show a revision level 
  162.       higher than or equal to '50'.  If you are not intending to use YarnIo, 
  163.       then add an environment setting of SET EMXOPT=-h40 to your CONFIG.SYS as 
  164.       noted in the environment settings section below. 
  165.  
  166.    3. check your environment variables according to the environment settings 
  167.       section below. 
  168.  
  169.    4. check your %ETC%\SERVICES file to ensure that it contains the following 
  170.       lines: 
  171.  
  172.               smtp         25/tcp mail          #Simple Mail Transfer
  173.               smtp         25/udp mail          #Simple Mail Transfer
  174.               pop3        110/tcp               #Post Office Protocol - Version 3
  175.               pop3        110/udp               #Post Office Protocol - Version 3
  176.               nntp        119/tcp readnews untp #Network News Transfer Protocol
  177.               nntp        119/udp readnews untp #Network News Transfer Protocol
  178.  
  179.       Most probably the %ETC%\SERVICES file is located either in x:\TCPIP\ETC 
  180.       or x:\MPTN\ETC.  If you need to specify non-standard port numbers, you 
  181.       should do that in the command line.  Check the URL specification. 
  182.  
  183.    5. unzip the VSOUP127.ZIP archive in a temporary file directory (%TMP% is a 
  184.       good place). 
  185.  
  186.    6. copy the following files into a subdirectory of your choice (using a 
  187.       subdirectory contained in the PATH statement is always a good choice): 
  188.  
  189.           VSOUP.EXE, the VSoup executable 
  190.  
  191.           YARNIO.CMD, the YarnIo script 
  192.  
  193.           YARNIO.SET, the YarnIo configuration file 
  194.  
  195.            Note:        YARNIO.CMD & YARNIO.SET must reside in the same 
  196.                         subdirectory and must have the same filename, except 
  197.                         the extension... 
  198.  
  199.           If you want YarnIo dial automatically, then you should also copy 
  200.            LOGINISP.CMD and LOGOUTISP.CMD as templates for your own 
  201.            connect/disconnect scripts. 
  202.  
  203.           OWNSOUP.EXE and/or QSOUP.EXE and/or CONVSOUP.EXE should be copied if 
  204.            required. 
  205.  
  206.           If you want to have help available, then copy also the 
  207.            documentation: either VSOUP.INF or VSOUP.TXT (both have the same 
  208.            content but different format). 
  209.  
  210.           If you are interested in the source code, move it also to a specific 
  211.            subdirectory. 
  212.  
  213.    7. review the Command Line Options section below and edit the YARNIO.SET 
  214.       configuration file according to your specific needs.  Also read the 
  215.       comments in YARNIO.SET. 
  216.  
  217.       Note:        the setup of YARNIO.SET is required only once.  In future, 
  218.                    updates will be made by amending YARNIO.CMD. 
  219.  
  220.    8. If you wish YARNIO.CMD to dial for you, you must also setup the scripts 
  221.       LOGINISP.CMD and LOGOUTISP.CMD to reflect your needs. 
  222.  
  223.       Another option is to use your dialer to call your ISP (provider) and 
  224.       start YarnIo after the connection has been established.  The disadvantage 
  225.       of doing it this way is that after completion of YarnIo the dialer will 
  226.       not hang up immediately. 
  227.  
  228.       Note:        If you have only FAT drives you have to rename LOGOUTISP.CMD 
  229.                    to something else.  Therefor you have to change the 
  230.                    hangupISP setting in YARNIO.SET too. 
  231.  
  232.    9. setup the directory structure for YarnIo: 
  233.  
  234.               %HOME%ΓöÇΓöÇ yarn             - subdirectory containing Yarn config file
  235.                        :
  236.                        Γö£ΓöÇΓöÇ in           - root of YarnIo input subdirectories
  237.                        Γöé   Γö£ΓöÇΓöÇ mail     - primary     subdir for EMail reception
  238.                        Γöé   Γö£ΓöÇΓöÇ mail2    - optional #2 subdir for EMail reception
  239.                        Γöé   Γö£ΓöÇΓöÇ :                          :
  240.                        Γöé   Γö£ΓöÇΓöÇ mail9    - optional #9 subdir for EMail reception
  241.                        Γöé   Γöé
  242.                        Γöé   Γö£ΓöÇΓöÇ news     - primary     subdir for news reception
  243.                        Γöé   Γö£ΓöÇΓöÇ news2    - optional #2 subdir for news reception
  244.                        Γöé   Γö£ΓöÇΓöÇ :                          :
  245.                        Γöé   ΓööΓöÇΓöÇ news9    - optional #9 subdir for news reception
  246.                        Γö£ΓöÇΓöÇ out          - subdirectory for EMail&news transmission
  247.                        :
  248.  
  249.       In each of the NEWS subdirectories you will need to create an appropriate 
  250.       NEWSRC file as detailed in the Newsrc File section. 
  251.  
  252.       The ..MAIL, ..MAIL2 until ..MAIL9 subdirectories have to be created only. 
  253.       They should be left empty. 
  254.  
  255.       The number of subdirectories depend on the number of servers you wish to 
  256.       poll. 
  257.  
  258.   10. change the following line in the Yarn-config file (%HOME%\YARN\CONFIG): 
  259.  
  260.               reply-packet=%HOME%\yarn\out\reply.zip
  261.  
  262.       If this is omitted or is incorrect then transmission of replies will not 
  263.       be possible, because Yarn will move its output to a place where VSoup 
  264.       does not expect it!  Of course %HOME% should be replaced by the actual 
  265.       value of HOME. 
  266.  
  267.   11. if you have setup LOGINISP.CMD and LOGOUTISP.CMD, start YarnIo directly. 
  268.       Otherwise first dial-in to your ISP and then start YarnIo. 
  269.  
  270.  When you first start using VSoup I recommend that you add the -M option to 
  271.  each call of VSoup (e.g. in YARNIO.SET) to force generation of the status 
  272.  mail.  This can be a good debugging aid... 
  273.  
  274.  
  275. ΓòÉΓòÉΓòÉ 4.1. 4.1 Environment Settings ΓòÉΓòÉΓòÉ
  276.  
  277.  Environment variables are set in your CONFIG.SYS by lines such as: 
  278.  
  279.     SET ETC=D:\TCPIP\ETC
  280.  
  281.  Also they can be set in a dedicated script, which calls VSoup1.2.8. 
  282.  
  283.  EMXOPT  This are the settings for the emx runtime DLLs.  Recommended setting 
  284.          of this variable should contain -h40 to allow 40 file handles (not 
  285.          required, if you are calling VSoup through YarnIo). 
  286.  
  287.  ETC     This is needed for accessing the TCP/IP configuration contained in the 
  288.          file %ETC%\TCPOS2.INI.  If -i is specified in the command line, ETC is 
  289.          not required. 
  290.  
  291.  HOME    your home directory (can also be specified on the command line).  If 
  292.          HOME is not defined, it defaults to the current directory. 
  293.  
  294.  MAILER  command for transmitting EMails (the EMail is piped into the stdin of 
  295.          MAILER).  If VSoup should do the job, MAILER must be undefined. 
  296.  
  297.  NNTPSERVER hostname of the nntp server (can also be specified in the command 
  298.          line).  This variable is, in my opinion, obsolete and remains only to 
  299.          avoid compatibility problems. 
  300.  
  301.  POSTER  command for transmitting news (the article is piped into the stdin of 
  302.          POSTER).  If VSoup should do the job, POSTER must be undefined. 
  303.  
  304.  TMP     points to the subdirectory which holds temporary files (VSoup 
  305.          generates soupxxxx.tmp as temporaries, with xxxx being a number 
  306.          between 0000 and 9999).  If TMP does not exist, the temporaries will 
  307.          be generated in the current subdirectory. 
  308.  
  309.  TZ      setting of your time zone (e.g. mine is MET-1MES).  Due to a bug in 
  310.          the emx runtime, the setting of this variable is critical for correct 
  311.          functioning of the emx C library revision 50.  Check the emx runtime 
  312.          documentation for the syntax of the TZ settings. 
  313.  
  314.          An incorrect setting of TZ can also cause errors if you appear to be 
  315.          getting mail before it was sent. 
  316.  
  317.  
  318. ΓòÉΓòÉΓòÉ 4.2. 4.2 VSoup And YarnIo Troubleshooting ΓòÉΓòÉΓòÉ
  319.  
  320.  some simple checks can be carried out: 
  321.  
  322.      read the FAQ section. 
  323.  
  324.      if VSoup does not run at all, initiate VSoup with VSOUP -?.  This should 
  325.       output the usage information to the screen.  If it does not, you have to 
  326.       check your system configuration.  Otherwise you should try to call VSoup 
  327.       in its different modes directly from the command line to check all your 
  328.       command line options. 
  329.  
  330.      generate the VSoup status mail with -M and check if it tells you the 
  331.       expected file locations and server names. 
  332.  
  333.      is the configuration file YARNIO.SET correct and in the same directory as 
  334.       YARNIO.CMD? 
  335.  
  336.      is the subdirectory setup correct for YarnIo? 
  337.  
  338.      does the pingHost command work as expected?  Issue the program via 
  339.       REXXTRY to check the return values in connected/disconnected case. 
  340.  
  341.      if you have a setup including LOGINISP.CMD and LOGOUTISP.CMD you can also 
  342.       check if they work.  Run LOGINISP.CMD from a command line - login should 
  343.       be performed.  Then run LOGOUTISP.CMD - logout should be performed.  Now 
  344.       also the YarnIo auto-dial/hangup should work... 
  345.  
  346.      connect to your ISP and try YARNIO -RCVMAIL -SEND -RCVNEWS2.  This will 
  347.       start only the YarnIo RCVNEWS window (hit ctrl-ESC and open it).  News 
  348.       reception should be performed as expected, at the end import to yarn will 
  349.       be initiated (after that 30s pause). 
  350.  
  351.       You can check all single YarnIo modes this way. 
  352.  
  353.      is VSoup called in each window started by YarnIo? 
  354.  
  355.  
  356. ΓòÉΓòÉΓòÉ 5. 5 Command Line Options ΓòÉΓòÉΓòÉ
  357.  
  358.  This section describes the VSoup command line options in detail.  An example 
  359.  is presented first. 
  360.  
  361.  Example 
  362.  
  363.     VSoup -m -h d:\yourHomedir nntp://your.news.server
  364.  
  365.  This would start VSoup telling it not to fetch mail (i.e. to collect news 
  366.  only) using a home directory called d:\yourHomedir from a news server named 
  367.  your.news.server.  The loginid and password would by default be taken from 
  368.  your TCP/IP configuration. 
  369.  
  370.   Global Options
  371.   News Receiving Options
  372.   Mail Receiving Option(s)
  373.   URLs
  374.   News Reception
  375.  
  376.  
  377. ΓòÉΓòÉΓòÉ 5.1. 5.1 Global Options ΓòÉΓòÉΓòÉ
  378.  
  379.  -hdir   sets the home directory for the VSoup operation.  You can also specify 
  380.          your home directory through the environment variable HOME. 
  381.  
  382.  -i      ignore the settings of the TCP/IP configuration. 
  383.  
  384.  -m      do not fetch mail. 
  385.  
  386.  -M      generate the VSoup status mail .\STSMAIL.MSG in any case.  Default is 
  387.          to generate the message in case of error only. 
  388.  
  389.  -n      do not fetch news. 
  390.  
  391.  -r      read only mode.  Only the .\AREAS, .\00*.MSG, .\00*.IDX files are 
  392.          written (e.g. %HOME%\NEWSTIME, %HOME%\NEWSRC are not written).  Also 
  393.          the EMails are not deleted from the POP3 server.  Main purpose for 
  394.          this option is debugging. 
  395.  
  396.  -s      send replies.  Do not use this option in combination with -m or -n, if 
  397.          you do it will be ignored. 
  398.  
  399.  -Tn     throughput must be higher than n, otherwise transfer will be aborted. 
  400.          Throughput is checked against the limit n every 10s after data 
  401.          transfer has begun.  If 6 samples show not enough throughput, VSoup 
  402.          will be aborted.  Default is '0 bytes/s', i.e. it will be checked for 
  403.          a stuck connection.  Use -T-n to check your throughput conditions. 
  404.          Special case is -T-1, which disables throughput check. 
  405.  
  406.  
  407. ΓòÉΓòÉΓòÉ 5.2. 5.2 News Receiving Options ΓòÉΓòÉΓòÉ
  408.  
  409.  -a      add new newsgroups to the %HOME%\NEWSRC file.  If there are any new 
  410.          groups on the server, the generation of the status message will be 
  411.          forced.  The new newsgroups will be added in the unsubscribed state. 
  412.  
  413.  -c[n]   catchup: mark every article as read except for the last n (default is 
  414.          10). 
  415.  
  416.  -kn     set maximum news packet size to n KBytes (default is no limit).  n 
  417.          indicates the total amount of received messages, not the size of a 
  418.          single message (this can be done through scoring). 
  419.  
  420.  -Kfile  set the name of the score file (see note below concerning -K/-N 
  421.          options). 
  422.  
  423.  -Nfile  set the name of the NEWSRC file (see note below regarding -K/-N 
  424.          options). 
  425.  
  426.  -Sn     receiving strategy (n=0..2).  Speed increases (at least it should) in 
  427.          the direction 0 to 2, danger of receiving crossposted articles 
  428.          increases also from 0 to 2.  The default of 1 is ok for most cases, 
  429.          but this parameter is an issue of fine tuning! 
  430.  
  431.          How the strategy parameter operates: 
  432.  
  433.          -S0          groups are read sequentially, i.e. all threads are 
  434.                       fetching articles from only one group. 
  435.  
  436.          -S1          if one thread goes into waiting state the next group will 
  437.                       be accessed - only small modification of the above. 
  438.  
  439.          -S2          VSoup tries to keep all threads busy.  I.e.  each thread 
  440.                       accesses one dedicated group, groups are read in parallel 
  441.                       (if there are no more groups to access, the waiting 
  442.                       threads are used for parallel reading from one group). 
  443.  
  444.          Recommendation: 
  445.  
  446.              If you have a lot of groups with small amount of articles per 
  447.               fetch and only a little bit cross-posting, -S2 will be the best 
  448.               option for you.  If you allow reception of crossposted articles 
  449.               (see option -x), -S2 will be best for you in any case. 
  450.  
  451.              if you are accessing groups with large articles (i.e. cost of 
  452.               double reception of crossposted articles is high), -S0 will be 
  453.               the best for you. 
  454.  
  455.  -tn     receive the news with n threads, i.e. connect to the NNTP server n 
  456.          times (limits are 1-10, default 4). 
  457.  
  458.  -u      create news summary.  Output can be found in the .\00*.IDX files.  Be 
  459.          aware that the summarized articles are marked as read (one way to get 
  460.          out of this, is to call VSoup with -r). 
  461.  
  462.  -x      do not process news Xref headers, i.e. allow reception of crossposted 
  463.          articles. 
  464.  
  465.  
  466. ΓòÉΓòÉΓòÉ 5.2.1. 5.2.1 Note Concerning The -K And -N Options ΓòÉΓòÉΓòÉ
  467.  
  468.  If you are using the -h option then use of either of the options -K or -N is 
  469.  not recommended, because behavior is not very transparent. 
  470.  
  471.  If the -h option is placed behind the -K / -N options the result will not be 
  472.  as expected - VSoup (and Souper) will revert to SCORE and NEWSRC in the new 
  473.  specified home directory. 
  474.  
  475.  If -K / -N options are placed behind the -h option and do not contain absolute 
  476.  paths, they will not be located in the home directory specified by -h. 
  477.  
  478.  This is confusing and will be fixed in a future release. 
  479.  
  480.  It is better and cleaner to use -h and setup the special SCORE/NEWSRC files in 
  481.  that subdirectory! 
  482.  
  483.  
  484. ΓòÉΓòÉΓòÉ 5.3. 5.3 Mail Receiving Option(s) ΓòÉΓòÉΓòÉ
  485.  
  486.  -D      If specified, VSoup will logout and login after reception of each 
  487.          EMail, thus effectively forcing deletion of the letter on the POP3 
  488.          server.  This is useful, if your connection to the POP3 server is 
  489.          aborted often and your mailbox is full.  Normal behaviour is to 
  490.          retrieve EMail without disconnecting/connecting. 
  491.  
  492.  
  493. ΓòÉΓòÉΓòÉ 5.4. 5.4 URLs ΓòÉΓòÉΓòÉ
  494.  
  495.  The addresses of the hosts are given in Unified Resource Locator (URL) form. 
  496.  These do not fully conform to the standard, so a short explanation follows: 
  497.  
  498.      nntp://[UserId[:Password]@]nntp-host[:port] defines the address of your 
  499.       NNTP server (i.e. news server).  UserId and Password can be given if 
  500.       required for AUTHINFO. 
  501.  
  502.      pop3://[UserId[:Password]@]pop3-host[:port] defines the address of your 
  503.       POP3 server.  UserId and Password are usually required. 
  504.  
  505.      smtp://[UserId[:password]@]smtp-gateway[:port] defines your SMTP gateway. 
  506.       UserId and Password are not required, in fact they are ignored by 
  507.       VSoup1.2.8! 
  508.  
  509.  The URL-feature makes VSoup different to Souper16, which wants to see a 
  510.  %HOME%\NEWSAUTH file for NNTP authorization. 
  511.  
  512.  Notes: 
  513.  
  514.    1. It is not intended to implement other protocols like http or so. 
  515.  
  516.    2. If port is not specified, the actual port number is taken from the 
  517.       %ETC%\SERVICES file.  This is the recommended way of port number 
  518.       handling. 
  519.  
  520.  
  521. ΓòÉΓòÉΓòÉ 5.4.1. 5.4.1 Brief Description Of NNTP/POP3/SMTP ΓòÉΓòÉΓòÉ
  522.  
  523.  Mail can be compared to the postal service, just like a letter. 
  524.  EMail-reception is handled through POP3 server (pop3:// prefix), transmission 
  525.  through SMTP gateways (smtp:// prefix). 
  526.  
  527.  News messages are more like broadcasting, everybody will 'hear' your message. 
  528.  News messages are transmitted and received via NNTP servers (nntp:// prefix). 
  529.  
  530.  Perhaps it is a little bit confusing, that you can also deliver news via EMail 
  531.  service (just like the Yarn list).  The other way around is not possible... 
  532.  
  533.  Anyway, please don't mix up news and EMail (your EMail might be news, but in 
  534.  these terms they remain EMails). 
  535.  
  536.  
  537. ΓòÉΓòÉΓòÉ 5.4.2. 5.4.2 Evaluation Order Of URLs ΓòÉΓòÉΓòÉ
  538.  
  539.  VSoup evaluates URLs in the following order: 
  540.  
  541.    1. take all information from the 'Internet Connection for OS/2' notebook 
  542.       settings 
  543.  
  544.    2. check the NNTPSERVER environment settings 
  545.  
  546.       Note1:       NNTPSERVER is a URL without leading nntp:// 
  547.  
  548.       Note2:       there are no environment variables for the SMTP / POP3 
  549.                    setup. 
  550.  
  551.    3. command line options 
  552.  
  553.  If you specify only e.g. nntp://your.news.server in the command line (without 
  554.  userid/password), the userid and password from the TCP/IP configuration are 
  555.  taken as a standard value. 
  556.  
  557.  
  558. ΓòÉΓòÉΓòÉ 5.5. 5.5 News Reception ΓòÉΓòÉΓòÉ
  559.  
  560.  For news reception you have the following options (which cannot combined): 
  561.  
  562.      either process .\COMMANDS (.\COMMANDS exists), 
  563.  
  564.      or catch-up the newsgroups (-c option), 
  565.  
  566.      or create newsgroups summary (-u option), 
  567.  
  568.      or receive the news in the standard way (no specific option). 
  569.  
  570.  New newsgroups are added to the %HOME%\NEWSRC file, when news is received in 
  571.  the standard way and the command line option -a is given. 
  572.  
  573.  
  574. ΓòÉΓòÉΓòÉ 6. 6 Diagnostics ΓòÉΓòÉΓòÉ
  575.  
  576.  VSoup returns with an exit code of 1, if any operation failed.  Otherwise 
  577.  return code will be 0. 
  578.  
  579.  Failing operations are: 
  580.  
  581.      bad command line options, 
  582.  
  583.      bad setup (e.g. no ETC set, but 'Internet Connection' settings 
  584.       requested), 
  585.  
  586.      bad OS (e.g. D*┬░@!S), 
  587.  
  588.      user hit ^C or ^BREAK, 
  589.  
  590.      throughput check failed (e.g. connection broken), 
  591.  
  592.      could not setup connection (e.g. server not defined, server does not 
  593.       exist, server is down, etc.), 
  594.  
  595.      there was no .\REPLIES file and you have requested -s, 
  596.  
  597.      .\REPLIES contains an illegal entry, 
  598.  
  599.      .\MAIL.MSG or .\NEWS.MSG is malformed, 
  600.  
  601.      could not deliver news article, e.g. NNTP server did not allow it, 
  602.  
  603.      could not deliver mail, e.g. POP3 authentication failed, 
  604.  
  605.      MAILER / POSTER contains illegal value, 
  606.  
  607.      there is no NEWSRC file, 
  608.  
  609.  .\STSMAIL.MSG 
  610.  
  611.  In case of an error condition the status message .\STSMAIL.MSG will be 
  612.  generated.  Under the following additional cases .\STSMAIL.MSG will be 
  613.  generated too: 
  614.  
  615.      VSoup was called with the -M option (force .\STSMAIL.MSG generation), 
  616.  
  617.      VSoup was called with -a and there were new newsgroups on your NNTP 
  618.       server, 
  619.  
  620.      VSoup could not select a newsgroup specified in NEWSRC, 
  621.  
  622.      VSoup could not select a newsgroup specified in .\COMMANDS, 
  623.  
  624.      a newsgroup specified in .\COMMANDS was not contained in NEWSRC, 
  625.  
  626.      there was another command than sendme contained in .\COMMANDS, 
  627.  
  628.      a specified (-Kfile) score file does not exist. 
  629.  
  630.      .\REPLIES contained an illegal (i.e. not understood by VSoup1.2.8) reply 
  631.       type.  Legal reply types are 'b' and 'B', 
  632.  
  633.      .\REPLIES contained an illegal (i.e. not understood by VSoup1.2.8) reply 
  634.       kind.  Legal reply kinds are "mail" and "news". 
  635.  
  636.  Future extensions 
  637.  
  638.  The following failing operations are NOT yet implemented fully: 
  639.  
  640.      there was no EMail in your POP3 mailbox, 
  641.  
  642.      there were no new news, 
  643.  
  644.      you have requested -s, but a message file is missing (VSoup deletes 
  645.       message files immediately after successful delivery.  Note that if you 
  646.       need two runs to deliver all your messages e.g. one file will be missing 
  647.       on the second attempt.  This is considered ok). 
  648.  
  649.  It is possible, that diagnostics code will change in the future.  Return codes 
  650.  with a cleared bit 0 (like 0,2,4,...)  will indicate a non-fatal condition, 
  651.  return codes with a set bit 0 will indicate fatal conditions. 
  652.  
  653.  
  654. ΓòÉΓòÉΓòÉ 7. 7 Utilities ΓòÉΓòÉΓòÉ
  655.  
  656.  This section describes the several utilities contained in VSOUP127.ZIP archive 
  657.  in more detail.  For most users only the YarnIo files will be of interest. 
  658.  
  659.   YarnIo
  660.   OwnSoup
  661.   QSoup
  662.   ConvSoup
  663.   ModifyEmxH
  664.   RmHigh
  665.  
  666.  
  667. ΓòÉΓòÉΓòÉ 7.1. 7.1 YarnIo ΓòÉΓòÉΓòÉ
  668.  
  669.  As stated before YarnIo - actually consisting of YARNIO.CMD, YARNIO.SET and 
  670.  optionally of LOGINISP.CMD and LOGOUTISP.CMD - is responsible for safe VSoup 
  671.  I/O operations.  The script(s) handle(s) the complete I/O between Yarn and the 
  672.  internet world.  Newsgroups are read from up to nine NNTP servers, mail/news 
  673.  packets are transmitted and mail is received again from up to nine POP3 
  674.  servers - all simultaneously.  Actions can be disabled individually (type 
  675.  YARNIO ? for more information). 
  676.  
  677.  The script should be started directly after the connection has been 
  678.  established.  It is also possible to let YarnIo dial out to establish the 
  679.  connection.  To do this you must provide the two scripts LOGINISP.CMD and 
  680.  LOGOUTISP.CMD (see the installation section). 
  681.  
  682.  Most items of the user configuration are in a file called YARNIO.SET.  It 
  683.  contains the settings for the initialization of the external programs 
  684.  including VSoup, import ...  calls. 
  685.  
  686.      You WILL need to amend the details in the YARNIO.SET file. 
  687.  
  688.  Sorry, but the directory structure must be set up manually!  You should follow 
  689.  the structure given above in the installation section. 
  690.  
  691.  
  692. ΓòÉΓòÉΓòÉ 7.1.1. 7.1.1 YarnIo.Set ΓòÉΓòÉΓòÉ
  693.  
  694.  For configuration of YarnIo, YARNIO.SET is required.  YARNIO.SET must reside 
  695.  in the same directory as YARNIO.CMD and must have the same filename prefix 
  696.  (i.e. YARNIO). 
  697.  
  698.  YARNIO.SET contains the statements which determine how YARNIO.CMD is to call 
  699.  the several commands. 
  700.  
  701.  To give you an idea what must be configured in YARNIO.SET, an example follows. 
  702.  There is a YARNIO.SET contained in the archive, which includes more comments. 
  703.  
  704.     :
  705.   '@SET NNTPSERVER='
  706.  
  707.   preImportProg = 'ownsoup -q rgriech stuff4me OwnTemp'
  708.   importProg    = 'import.exe -u'
  709.   soupProg      = 'vsoup.exe'
  710.   soupSend      = soupProg '-s nntp://xmt.nntp.server'
  711.   soupRcvNews   = soupProg '-mai' '-h' rcvNewsDir 'nntp://1st.nntp.server'
  712.   soupRcvNews2  = soupProg '-mai' '-h' rcvNews2Dir 'nntp://2nd.nntp.server'
  713.   soupRcvMail   = soupProg '-n'
  714.   pingHost      = 'slipwait 2 2>&1 > nul'
  715.   connectISP    = 'cmd /c loginisp.cmd NOWAIT'
  716.   hangupISP     = 'cmd /c logoutisp.cmd'
  717.   unzipProg     = 'unzip.exe -oq'
  718.   zipProg       = 'zip -0mq'
  719.     :
  720.  
  721.  Remarks 
  722.  
  723.      Instead of slipwait you could also use the command 'ping x.y.z 1 2>&1 > 
  724.       nul'.  The host x.y.z in pingHost must not be contained in the 
  725.       %ETC%\HOSTS, because otherwise pingHost will return unexpected results. 
  726.  
  727.      Do not remove the option '-h' rcvNewsDir from the soupRcvNews line or the 
  728.       option '-h' rcvNews2Dir from the soupRcvNews2 line. 
  729.  
  730.      If you are not interested in a service (e.g. soupRcvNews2), set the 
  731.       corresponding variable to '' (empty string). 
  732.  
  733.      If required, you can change the environment settings in YARNIO.SET, e.g. 
  734.       the above '@SET NNTPSERVER=' clears an existing NNTPSERVER environment 
  735.       variable. 
  736.  
  737.      To enable news server #3..#9, you have to add soupRcvNews3..soupRcvNews9 
  738.       lines into YARNIO.SET.  Use soupRcvNews2 as a template.  Of course you 
  739.       have to set up the corresponding Newsrc Files in the respective 
  740.       subdirectories. 
  741.  
  742.       For POP3 server #2..#9 you have to set up soupRcvMail2..soupRcvMail9. 
  743.       You have to create the corresponding subdirectories manually. 
  744.  
  745.       For setting up the correct subdirectory structure see also the 
  746.       Installation section. 
  747.  
  748.  
  749. ΓòÉΓòÉΓòÉ 7.1.2. 7.1.2 LoginIsp ΓòÉΓòÉΓòÉ
  750.  
  751.  LOGINISP.CMD is an optional script, which allows YarnIo to dial in to your 
  752.  ISP.  The following example script will connect using the internet dialer.  If 
  753.  you are a customer of Advantis the script will work for you without any 
  754.  changes - of course you have to insert the correct account user passwd 
  755.  information. 
  756.  
  757.   /*
  758.     LoginIsp  -  rg211096
  759.  
  760.     Login to your ISP.  If Option NOWAIT is given, the command will not wait
  761.     until connection has been established.
  762.  
  763.     You have to do the following configuration:
  764.     -  the line '...logoutisp...' must show the effective logoff script
  765.     -  the line '...start...' must show the effective call of the dialer
  766.     -  the line '...ping...' must show a pinger to check connection
  767.    */
  768.  
  769.   call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
  770.   call SysLoadFuncs
  771.  
  772.   TRACE('')
  773.  
  774.   option = ARG(1)
  775.  
  776.   DO FOREVER
  777.       '@cmd /c logoutisp.cmd'
  778.       '@start dialer.exe account user passwd '-m'
  779.       IF option = 'NOWAIT' THEN
  780.           LEAVE
  781.  
  782.       DO j = 1 TO 20
  783.           rc = SysSleep(3)
  784.           '@ping www.cdrom.com 2>&1 > nul'
  785.           IF rc = 0 THEN
  786.               EXIT
  787.       END j
  788.   END
  789.  
  790.   EXIT
  791.  
  792.  Note1:  You will find an almost identical LOGINISP.CMD in the VSOUP127.ZIP 
  793.          archive. 
  794.  
  795.  Note2:  This LOGINISP.CMD requires a working LOGOUTISP.CMD. 
  796.  
  797.  
  798. ΓòÉΓòÉΓòÉ 7.1.3. 7.1.3 LogoutIsp ΓòÉΓòÉΓòÉ
  799.  
  800.  LOGOUTISP.CMD is an optional script, which allows YarnIo to disconnect from 
  801.  your ISP.  The following example script will disconnect using the internet 
  802.  dialer.  If you are a customer of Advantis the script will work for you 
  803.  without any changes - other than maybe changing dialer and comPort. 
  804.  
  805.  This script is a little bit more complicated than LOGINISP.CMD, because it 
  806.  will 
  807.  
  808.    1. block itself to avoid multiple instances of itself 
  809.  
  810.    2. wait until the dialer has been closed 
  811.  
  812.    3. force a disconnect of the modem through switching DTR 
  813.  
  814.  An almost identical version of the script is contained in the VSOUP127.ZIP 
  815.  archive. 
  816.  
  817.   /*
  818.     LogoutIsp  -  rg211096
  819.  
  820.     Logoff from your ISP.
  821.  
  822.     The lines dialer/dialerClose,comPort must be configured
  823.   */
  824.  
  825.   call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
  826.   call SysLoadFuncs
  827.  
  828.   dialer      = 'c:\tcpip\bin\dialer.exe'
  829.   dialerClose = dialer '-c'
  830.   comPort     = 'com3'
  831.  
  832.   TRACE('')
  833.  
  834.   parse source . . compCmdName
  835.   cmdName = filespec('name',compCmdName)
  836.   tmpDir  = value('tmp',,'os2environment')
  837.  
  838.   lockFile = ''
  839.   IF tmpDir = '' THEN
  840.       SAY 'please define %TMP% for locking' CmdName
  841.   ELSE DO
  842.       lockFile = tmpDir || '\logout.sem'
  843.       if stream( lockFile,'c','open write') \= 'READY:' then DO
  844.           SAY CmdName 'already active...'
  845.           EXIT
  846.       END
  847.   END
  848.  
  849.  
  850.   if isActive(dialer) then do
  851.       SAY 'logging off...'
  852.      '@start /min' dialerClose
  853.  
  854.      rc = SysSleep( 2 )
  855.      DO FOREVER
  856.          IF \isActive(dialer) THEN
  857.              LEAVE
  858.          call HangupNow
  859.          rc = SysSleep( 2 )
  860.      END
  861.   end
  862.   call HangupNow
  863.  
  864.   IF lockFile \= '' THEN DO
  865.       rc = stream( lockFile,'c','close' )
  866.       rc = SysFileDelete( lockFile )
  867.   END
  868.  
  869.   EXIT
  870.  
  871.  
  872.   HangupNow:
  873.   '@mode' comPort || ',dtr=on  > nul'
  874.   '@mode' comPort || ',dtr=off > nul'
  875.   '@mode' comPort || ',dtr=on  > nul'
  876.   RETURN
  877.  
  878.  
  879.   isActive: PROCEDURE
  880.   prog = ARG(1)
  881.  
  882.   '@pstat /c | RXQUEUE'
  883.  
  884.   prog = TRANSLATE(prog)
  885.   found = 0
  886.   DO ii = 1 TO queued()
  887.       PULL line
  888.       IF POS(prog,TRANSLATE(line)) \= 0 THEN do
  889.           found = 1
  890.           LEAVE
  891.       END
  892.   END
  893.   RETURN found
  894.  
  895.  
  896. ΓòÉΓòÉΓòÉ 7.2. 7.2 OwnSoup ΓòÉΓòÉΓòÉ
  897.  
  898.  OwnSoup, with the help of the Yarn import program, redirects news articles 
  899.  matching a specific pattern into a mail folder.  OwnSoup can be seen as a 
  900.  notification program to allow easy tracking of news threads you are involved 
  901.  in. 
  902.  
  903.  Syntax 
  904.  
  905.  ownsoup [-h] [-b] [-q] pattern groupname outputfile 
  906.  
  907.  where 
  908.  
  909.  [-h]    search for pattern in header of article only, 
  910.  
  911.  [-b]    search for pattern in body of article only.  The subject line of the 
  912.          header is considered to be part of header and body. 
  913.  
  914.          If -h or -b is not specified the default is to search the complete 
  915.          article, 
  916.  
  917.  [-q]    be quiet.  Only the number of matches found will be displayed, 
  918.  
  919.  pattern is your search pattern which should be defined according to the 
  920.          regular expression syntax, 
  921.  
  922.  groupname is a dummy groupname to allow easy filtering.  All the matching 
  923.          articles will contain the header line X-ownsoup: groupname, 
  924.  
  925.  outputfile is the name of the temporary outputfile (the .MSG-extension will be 
  926.          added by OwnSoup). 
  927.  
  928.  The generated outputfile will be registered in the .\AREAS file, thus import 
  929.  will also find the outputfile.  Note that the outputfile will be deleted after 
  930.  the import so that the actual name you choose is almost unimportant. 
  931.  
  932.  
  933.  Example Setup of OwnSoup 
  934.  
  935.      Assuming a script is used when importing news, directly before import is 
  936.       called, a line calling OwnSoup is placed in the script.  This would be 
  937.       something like: 
  938.  
  939.               ownsoup rgriech stuff4me OwnTemp
  940.  
  941.       This example would search for "rgriech" in the header and body sections 
  942.       of each message, writing matching messages to an output file called 
  943.       OwnTemp after marking them with 
  944.  
  945.               X-ownsoup: stuff4me
  946.  
  947.       The Yarn import can now easily filter out any such news articles and put 
  948.       them in a mail folder which in this example we will call "Personal". 
  949.  
  950.       The search pattern here is "rgriech" but a more complex pattern could be 
  951.       used, for example I could search on a pattern of "rgriech|hardy.griech" 
  952.       which would find either my EMail name or my full name.  The '.' wildcard 
  953.       is used in place of a space.  The pattern must be in quotes because of 
  954.       the '|' character. 
  955.  
  956.       Note that because no -h or -b parameter is set, OwnSoup will search both 
  957.       the header and the body of all messages. 
  958.  
  959.       If you are using YarnIo, OwnSoup would be called by setting the 
  960.       preImportProg line in YARNIO.SET.  Our example would require the 
  961.       following: 
  962.  
  963.               preImportProg = 'ownsoup rgriech stuff4me OwnTemp'
  964.  
  965.      To setup a Yarn filter which moves all the messages matching the pattern 
  966.       "X-ownsoup: stuff4me" into the mail folder "Personal" you would do the 
  967.       following: 
  968.  
  969.       Set up a filter using the Yarn FILTER.EXE program.  When run, this shows 
  970.       a box for details, which you would complete as follows: 
  971.  
  972.             Γöî Mail Rule ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  973.             Γöé                                                                          Γöé
  974.             Γöé  Rule name: MentionsMe                                                   Γöé
  975.             Γöé                                                                          Γöé
  976.             Γöé  Search in: ( ) From                                                     Γöé
  977.             Γöé             ( ) To                                                       Γöé
  978.             Γöé             ( ) Subject                                                  Γöé
  979.             Γöé             (*) Header                                                   Γöé
  980.             Γöé             ( ) Body                                                     Γöé
  981.             Γöé             ( ) Header and body                                          Γöé
  982.             Γöé                                                                          Γöé
  983.             Γöé Search for: X-ownsoup: stuff4me                                          Γöé
  984.             Γöé Match case: No                                                           Γöé
  985.             Γöé                                                                          Γöé
  986.             Γöé     Action: (*) Move to folder/newsgroup: Personal                       Γöé
  987.             Γöé             ( ) Delete                                                   Γöé
  988.             Γöé                                                                          Γöé
  989.             ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  990.  
  991.       In the "Search for" line above, "X-ownsoup: stuff4me" represents the 
  992.       string you wish to search for, i.e. the string that OwnSoup puts in when 
  993.       it finds a match on its own search and "Personal" represents the name you 
  994.       wish the new mail folder to have. 
  995.  
  996.       Note that Yarn's filter now only needs to search the header as it is only 
  997.       looking for the "X-ownsoup: stuff4me" line. 
  998.  
  999.       After this preparation all incoming news articles will be checked for 
  1000.       pattern as set in OwnSoup (in this case "rgriech"), and matching articles 
  1001.       will be moved into the "Personal" mail folder. 
  1002.  
  1003.      Of course, you can set up more than one filter and if you wish you could 
  1004.       put the output in different mail folders. 
  1005.  
  1006.  Restriction 
  1007.  
  1008.  Do not set up "Personal" as a newsgroup, because Yarn would skip the filtered 
  1009.  articles in this case due to the Message-ID:. 
  1010.  
  1011.  Others 
  1012.  
  1013.      Articles filtered to "Personal" can be replied and followed up. 
  1014.  
  1015.      OwnSoup scans all files contained in .\AREAS matching the SOUP formats 
  1016.       "b" and "u", i.e. files containing news articles.  The generated file has 
  1017.       the binary 8-bit clean mail SOUP format ("bn"). 
  1018.  
  1019.  
  1020. ΓòÉΓòÉΓòÉ 7.3. 7.3 QSoup ΓòÉΓòÉΓòÉ
  1021.  
  1022.  QSoup (pronounce 'queue soup') appends mail and news messages to the Yarn 
  1023.  reply packet file for transmission by VSoup.  The messages must contain all 
  1024.  required header fields, i.e. QSoup does not manipulate the content of the 
  1025.  message, except that it does '\r' stripping and interpretes ^Z as end of 
  1026.  message. 
  1027.  
  1028.  Syntax 
  1029.  
  1030.  qsoup [-m] [-v] [-i] [-hdir] [-lfile] [inputfile] 
  1031.  
  1032.  where 
  1033.  
  1034.  [-m]    the message input to QSoup is a mail, default is news, 
  1035.  
  1036.  [-v]    be verbose, 
  1037.  
  1038.  [-i]    ignore all options coming behind the -i.  This is useful, if the 
  1039.          calling program appends command line arguments which are not known by 
  1040.          QSoup, 
  1041.  
  1042.  [-rfile] set the name of the reply packet to file.  Default is to read the 
  1043.          name of the reply packet from %HOME%\YARN\CONFIG in the line 
  1044.          reply-packet, 
  1045.  
  1046.  [-lfile] use file as the lock file for access control to the reply packet. 
  1047.          Default is to use %YARN%\HISTORY.PAG, 
  1048.  
  1049.  [inputfile] is the name of the message file.  If omitted, the message will be 
  1050.          read from stdin, thus allowing to connect the message provider and 
  1051.          QSoup through a pipe. 
  1052.  
  1053.  
  1054.  Example Setup Of QSoup And Sendmail 
  1055.  
  1056.  Using sendmail has several advantages.  First, it is a standard tool which is 
  1057.  used by many programs for mail delivery (e.g. Lynx).  Second, it is very 
  1058.  flexible and allows routing of messages depending on their recipients address. 
  1059.  The second point is also the weakest point of sendmail: it is hard to 
  1060.  configure. 
  1061.  
  1062.  This example shows my setup of sendmail.  But be warned: I am no sendmail 
  1063.  expert and to get this configuration running was a lot of fiddling! 
  1064.  
  1065.  
  1066.  My changes to the standard configuration were as follows: 
  1067.  
  1068.      take the original sendmail.uml from Warp Connect and copy it to 
  1069.       %ETC%\sendmail.cf, 
  1070.  
  1071.      insert the following two lines in the very beginning of sendmail.cf: 
  1072.  
  1073.               Cwworkstationname.domain
  1074.               Dwworkstationname.domain
  1075.  
  1076.      change the OQ setting so it reflects the subdirectory of your mail queue 
  1077.       (which in fact should not be required, because the mails are received by 
  1078.       QSoup immediately), 
  1079.  
  1080.      set the H?F?From: field to your EMail address.  This will be the default 
  1081.       address, if nothing else is specified in the From:-header of the message, 
  1082.  
  1083.      in the Ruleset 0 at the end of the first section specify the rule 
  1084.  
  1085.               R$+<@$+>              $#local $:$1
  1086.  
  1087.       This will instruct sendmail to direct all mails to the local mailer 
  1088.       program.  Note that the blanks between the > and the $ have to be tabs, 
  1089.  
  1090.      change the local mailer program, so that it shows the following: 
  1091.  
  1092.               Mlocal, P=d:\b\32\qsoup.exe , F=lmnDFM, S=10, R=0, A=-m -i $u
  1093.  
  1094.       You have to replace the d:\b\32 with the actual QSoup path.  If this path 
  1095.       is not correct, sendmail will not deliver the mails! 
  1096.  
  1097.  After you have done the setup, you should check it with a dummy mail.  Type in 
  1098.  the following: 
  1099.  
  1100.     sendmail -t
  1101.     --->IBM OS/2 SENDMAIL VERSION 1.3.17
  1102.     --->reading ...\sendmail.cf 10
  1103.     to: dummy@x.y.z
  1104.     subject: sendmail/qsoup testing
  1105.  
  1106.     Hello
  1107.     ^Z                    (this is a ctrl-Z!)
  1108.     --->11/09/96 19:01:03 mail delivered from:  YourName
  1109.  
  1110.  Now you can check the successful delivery with the command unzip -Cp -aa 
  1111.  reply-packet mail.msg.  The output should be something like that: 
  1112.  
  1113.     Received: by ibm.net (IBM OS/2 SENDMAIL VERSION 1.3.17/2.12um) id AA3986; ...
  1114.     Date: Sat, 09 Nov 96 18:59:40 +0100
  1115.     From: YourName
  1116.     Message-Id: <9611091759.AA3986@ibm.net>
  1117.     To: dummy@x.y.z
  1118.     Subject: sendmail/qsoup testing
  1119.  
  1120.     Hello
  1121.  
  1122.  Note, that sendmail inserted the missing Date:, From: and Message-Id: header 
  1123.  lines (the redundant header Received: too).  YourName should show the correct 
  1124.  settings. 
  1125.  
  1126.  After successful test you should delete the reply packet file.  For the actual 
  1127.  'diff' of my sendmail.cf and sendmail.umf see also the FAQ. 
  1128.  
  1129.  
  1130.  Miscellaneous 
  1131.  
  1132.      If you are using QSoup as a sendmail mailer program you can not setup 
  1133.       sendmail as the MAILER of VSoup (see environment settings). 
  1134.  
  1135.       First, this would result in a deadlock during transmit action of VSoup, 
  1136.       because the invoked sendmail would invoke an instance of QSoup, which 
  1137.       could not proceed, because the Yarn reply packet would be held by the 
  1138.       transmitting VSoup. 
  1139.  
  1140.       Second, this would not be a meaningful configuration, because the mail 
  1141.       would loop endlessly in your computer without being ever transmitted to 
  1142.       the external world. 
  1143.  
  1144.       If other programs require the MAILER environment variable pointing to 
  1145.       sendmail and if sendmail is configured to deliver mails to QSoup, one 
  1146.       should clear MAILER prior to the "VSoup -s" call.  For YarnIo operation 
  1147.       this could be done in YARNIO.SET. 
  1148.  
  1149.      Because QSoup has to unzip/zip the reply packet, do not expect fast 
  1150.       operation.  Anyway appending a message to the reply packet will be much 
  1151.       faster than the actual delivery to the network. 
  1152.  
  1153.      If QSoup is copied to an executable with the name sendmail (SENDMAIL.EXE) 
  1154.       and is invoked as sendmail, QSoup mode defaults to 'get a mail from 
  1155.       stdin'.  If QSoup is copied to an executable with the name inews 
  1156.       (INEWS.EXE) and is invoked as inews, QSoup mode defaults to 'get a news 
  1157.       article from stdin'. 
  1158.  
  1159.       All command line options will be ignored in either case.  Keep in mind, 
  1160.       that the messages must contain all required header fields. 
  1161.  
  1162.      The exact access criteria for reply packet access are as follows: 
  1163.  
  1164.         1. Set %YARN%\HISTORY.PAG to writable without access sharing.  This 
  1165.            operation must be accomplished successfully.  %YARN%\REPLIES is the 
  1166.            default lock file which can be overridden by the -lfile option. 
  1167.  
  1168.         2. The REPLIES file in the reply packet subdirectory must not exist. 
  1169.  
  1170.       Criterion (1) blocks QSoup, if Yarn is active.  Also this works like a 
  1171.       semaphor and prevents multiple instances of QSoup to access the reply 
  1172.       packet.  Criterion (2) prevents QSoup from accessing the reply packet if 
  1173.       it is unzipped, e.g. during "VSoup -s". 
  1174.  
  1175.       Don't forget that an open Yarn or an active "VSoup -s" blocks QSoup. 
  1176.       This means, as long as another application accesses either the lockfile 
  1177.       or the Yarn reply packet, QSoup can not perform the requested operation. 
  1178.  
  1179.  
  1180. ΓòÉΓòÉΓòÉ 7.4. 7.4 ConvSoup ΓòÉΓòÉΓòÉ
  1181.  
  1182.  ConvSoup is a small program which converts the VSoup SOUP output files, which 
  1183.  are in binary format ("bn" & "Bn") into UNIX mailbox format ("mn") and USENET 
  1184.  batch format ("un") respectively.  The output files are written with '\n' as 
  1185.  line separator. 
  1186.  
  1187.  ConvSoup must be started in the subdirectory that contains the .\AREAS and the 
  1188.  .\*.MSG files. 
  1189.  
  1190.  ConvSoup is useful for people who wants to use VSoup with offline newsreader 
  1191.  which do not recognize VSoup's packet format directly.  Although VSoup 
  1192.  complies to SOUP, some readers only know about UNIX mailbox and USENET batch 
  1193.  format.  E.g.  Changi's RNews expects USENET batch format on its input. 
  1194.  
  1195.  
  1196. ΓòÉΓòÉΓòÉ 7.5. 7.5 ModifyEmxH ΓòÉΓòÉΓòÉ
  1197.  
  1198.  This script is of interest for people who wants to compile VSoup on their own. 
  1199.  MODIFYEMXH.CMD is required for multiple inclusion of the os2.h and os2emx.h 
  1200.  header files. 
  1201.  
  1202.  MODIFYEMXH.CMD reads form stdin and copies to stdout.  Keep in mind, that 
  1203.  multiple inclusion of the above mentioned headers is not standard.  It is just 
  1204.  for my convenience. 
  1205.  
  1206.  
  1207. ΓòÉΓòÉΓòÉ 7.6. 7.6 RmHigh ΓòÉΓòÉΓòÉ
  1208.  
  1209.  RMHIGH.CMD removes the highlighting from VSOUP.TXT.  This is useful for people 
  1210.  who wants to read the documentation in text mode and have no pager or editor 
  1211.  available which understands the poor (wo)mans highlighting used in VSOUP.TXT. 
  1212.  
  1213.  GNUs Less is an example of a pager that handles the distributed VSOUP.TXT 
  1214.  correctly. 
  1215.  
  1216.  
  1217. ΓòÉΓòÉΓòÉ 8. 8 Files ΓòÉΓòÉΓòÉ
  1218.  
  1219.  This section describes all the input and output files used and generated by 
  1220.  VSoup in detail.  Under normal circumstances %HOME%\NEWSRC and %HOME%\SCORE 
  1221.  are the only files of interest.  For description of YarnIo files, see the 
  1222.  YarnIo section. 
  1223.  
  1224.   The Newsrc File
  1225.   The Score File
  1226.   Other Files
  1227.  
  1228.  
  1229. ΓòÉΓòÉΓòÉ 8.1. 8.1 The Newsrc File ΓòÉΓòÉΓòÉ
  1230.  
  1231.  %HOME%\NEWSRC contains the list of newsgroups. 
  1232.  
  1233.  ':'     behind the name indicates subscribed group, 
  1234.  
  1235.  '!'     indicates an unsubscribed one. 
  1236.  
  1237.  The list of newsgroups can be obtained from the news server by using the -a 
  1238.  option of VSoup (see FAQ) or can be prepared with a text editor as follows: 
  1239.  
  1240.  List the newsgroups you want to receive, one per line, and end each line with 
  1241.  a colon.  For example: 
  1242.  
  1243.     comp.answers:
  1244.     news.answers:
  1245.     rec.humor.funny:
  1246.  
  1247.  VSoup will keep track of fetched articles by recording the article numbers in 
  1248.  this file. 
  1249.  
  1250.  
  1251.  Syntax 
  1252.  
  1253.  For anyone who really wants to know, the syntax of the file is as follows: 
  1254.  
  1255.  %HOME%\NEWSRC ::= lines 
  1256.  
  1257.  lines ::= line lines | empty 
  1258.  
  1259.  line ::= groupname sep article-ranges "\n" 
  1260.  
  1261.  sep ::= "!" | ":" 
  1262.  
  1263.  article-ranges ::= article-ranges "," art-range | art-range 
  1264.  
  1265.  art-range ::= " " art-num | " " art-num "-" art-num 
  1266.  
  1267.  groupname is the name of a group, art-num is a long integer.  article-ranges 
  1268.  must be sorted in ascending order to be recognized correctly.  Blanks are only 
  1269.  allowed at the indicated positions. 
  1270.  
  1271.  Under normal circumstances, only the sep is important to the user for 
  1272.  subscribing and unsubscribing groups. 
  1273.  
  1274.  
  1275. ΓòÉΓòÉΓòÉ 8.2. 8.2 The Score File ΓòÉΓòÉΓòÉ
  1276.  
  1277.  The score file specifies criteria used to exclude articles from the VSoup 
  1278.  packet.  You can kill articles that have a specific subject, are from a 
  1279.  specific poster, or contain a particular string anywhere in the header.  Even 
  1280.  killing of articles which do not contain a specific pattern in their header is 
  1281.  possible with scoring. 
  1282.  
  1283.  %HOME%\SCORE is the default score file.  The name and subdirectory of the 
  1284.  score file can be configured by specifying the -Kscorefile command line 
  1285.  option.  This allows one single score file for all news servers you wish to 
  1286.  access. 
  1287.  
  1288.  An entry in the score file, also called score-section, has the format: 
  1289.  
  1290.  score-group "{" 
  1291.    score-rule 
  1292.        ... 
  1293.  "}" 
  1294.  
  1295.  with score-rule being one of the following alternatives: 
  1296.  
  1297.    1. score "lines" ">" number 
  1298.  
  1299.    2. score "lines" "<" number 
  1300.  
  1301.    3. score "pattern" "header" reg-exp 
  1302.  
  1303.    4. score "pattern" where reg-exp 
  1304.  
  1305.    5. score "header" string 
  1306.  
  1307.    6. score where string 
  1308.  
  1309.  score-rules 1. and 2. are for scoring of the article length, 3.  and 4. are 
  1310.  both working with regular expressions (reg-exp), 5. and 6. are working with 
  1311.  literal strings (string).  3. and 5. are scanning the complete header for the 
  1312.  corresponding patterns, 4. and 6.  are matching its pattern only in the 
  1313.  corresponding header line where. 
  1314.  
  1315.  
  1316.  Description of the score-section elements 
  1317.  
  1318.  score-group score-group is a regular expression.  The contained score-rules 
  1319.          are applied to newsgroups which are matched by the score-group regular 
  1320.          expression completely.  If score-group is the string "all", the 
  1321.          score-rules are applied to all newsgroups. 
  1322.  
  1323.  score-rule see above. 
  1324.  
  1325.  score   is the score which has been assigned to the score-rule.  All scores of 
  1326.          score-rules matching an articles header are added up and then compared 
  1327.          to the kill-threshold.  If the total score is less than the 
  1328.          kill-threshold, the article is killed. 
  1329.  
  1330.  where   specifies where to search in the header.  from searches the From: 
  1331.          line, subject searches the Subject: line and so on.  The special 
  1332.          where-pattern "header" searches all the lines in the header of the 
  1333.          article. 
  1334.  
  1335.  reg-exp is the string in form of a regular expression to search for. 
  1336.  
  1337.  string  is the literal string to search for. 
  1338.  
  1339.  number  is a line number to which the actual article length is compared. 
  1340.  
  1341.  
  1342.  Special score-sections 
  1343.  
  1344.  There are two special score-sections: 
  1345.  
  1346.  "quit"  stops reading of the score file immedialtely. 
  1347.  
  1348.  "killthreshold" kill-threshold sets the threshold for killing articles, i.e. 
  1349.          the lowest limit articles should fulfill to not being killed.  The 
  1350.          threshold is global (i.e. applies to all groups and rules) and the 
  1351.          last occurance of "killthreshold" counts. 
  1352.  
  1353.  Lines beginning with a '#' in the first non-blank position are treated as 
  1354.  comments. 
  1355.  
  1356.  
  1357.  Remarks 
  1358.  
  1359.      All fields are case-insensitive. 
  1360.  
  1361.      After "header" and where a colon (":") is allowed. 
  1362.  
  1363.      News transmission speed decreases if a score file is used, because an 
  1364.       article is fetched then in two steps: HEAD <num>, then BODY <num>. 
  1365.       Otherwise an article will be fetched in only one single step: ARTICLE 
  1366.       <num>.  Offline-Scoring of Yarn is also more flexible than this 
  1367.       online-scoring because you can change your mind about the scores after 
  1368.       reception of the articles! 
  1369.  
  1370.      It is pretty legal to break the scoring criteria of several score-groups 
  1371.       in several score-sections. 
  1372.  
  1373.      If "header"-score-rules are applied, the pattern is searched for in the 
  1374.       complete header, i.e. one can also match specific header fields. 
  1375.  
  1376.      The score-group "all" is transformed to the regular expression ".*". 
  1377.  
  1378.      Although the "."s in newsgroup names are meta characters of regular 
  1379.       expressions this should not do any harm to 'normal' group matching.  E.g. 
  1380.       the score-group expression "comp.os.os2.programmer.misc" will match only 
  1381.       one group in real life. 
  1382.  
  1383.      The score file works on news only. 
  1384.  
  1385.      Check the FAQ for example score files. 
  1386.  
  1387.  
  1388.  Syntax 
  1389.  
  1390.  The exact syntax of the score file is as follows: 
  1391.  
  1392.  %HOME%\SCORE ::= {line "\n"}* 
  1393.  
  1394.  line ::= '#' text | score-section 
  1395.  
  1396.      Lines beginning with a '#' indicates a comment, text indicates literal 
  1397.      strings. 
  1398.  
  1399.  score-section ::= "all" "{" score-rules "}" 
  1400.           | score-group "{" score-rules "}" 
  1401.           | "killthreshold" number 
  1402.           | "quit" 
  1403.  
  1404.      "all" indicates, that the following score-rules is valid for all 
  1405.      newsgroups, The regular expression score-group limits the score-rules to 
  1406.      specific newsgroups. 
  1407.  
  1408.  score-rules ::= score-rule "\n" {score-rules} 
  1409.  
  1410.  score-rule  ::= score "lines" ">" number 
  1411.        | score "lines" "<" number 
  1412.        | score "pattern" "header" reg-exp 
  1413.        | score "pattern" where reg-exp 
  1414.        | score "header" string 
  1415.        | score where string 
  1416.  
  1417.      score is a number (the score!), number too, , reg-exp is a regular 
  1418.      expression, where and string are literal strings. 
  1419.  
  1420.  
  1421.  Note:   "\n" is the newline character.  It is mandatory! 
  1422.  
  1423.  
  1424. ΓòÉΓòÉΓòÉ 8.2.1. 8.2.1 Regular expression syntax ΓòÉΓòÉΓòÉ
  1425.  
  1426.  The following description has been taken from the man regexp pages (BSD 
  1427.  experimental). 
  1428.  
  1429.  A regular expression is zero or more branches, separated by |.  It matches 
  1430.  anything that matches one of the branches. 
  1431.  
  1432.  A branch is zero or more pieces, concatenated.  It matches a match for the 
  1433.  first, followed by a match for the second, etc. 
  1434.  
  1435.  A piece is an atom possibly followed by *, +, or ?.  An atom followed by * 
  1436.  matches a sequence of 0 or more matches of the atom.  An atom followed by + 
  1437.  matches a sequence of 1 or more matches of the atom.  An atom followed by ? 
  1438.  matches a match of the atom, or the null string. 
  1439.  
  1440.  An atom is a regular expression in parentheses (matching a match for the 
  1441.  regular expression), a range (see below), .  (matching any single character), 
  1442.  ^ (matching the null string at the beginning of the input string), $ (matching 
  1443.  the null string at the end of the input string), a \ followed by a single 
  1444.  character (matching that character), or a single character with no other 
  1445.  significance (matching that character). 
  1446.  
  1447.  A range is a sequence of characters enclosed in [].  It normally matches any 
  1448.  single character from the sequence.  If the sequence begins with ^, it matches 
  1449.  any single character not from the rest of the sequence.  If two characters in 
  1450.  the sequence are separated by -, this is shorthand for the full list of ASCII 
  1451.  characters between them (e.g. [0-9] matches any decimal digit).  To include a 
  1452.  literal ] in the sequence, make it the first character (following a possible 
  1453.  ^).  To include a literal -, make it the first or last character. 
  1454.  
  1455.  
  1456. ΓòÉΓòÉΓòÉ 8.3. 8.3 Other Files ΓòÉΓòÉΓòÉ
  1457.  
  1458.  .\COMMANDS 
  1459.  
  1460.  contains lines with the syntax: 'sendme' groupname article-ranges.  .\COMMANDS 
  1461.  is executed instead of standard fetching of news (see also News Reception). 
  1462.  After successful .\COMMANDS processing, the file will be deleted. 
  1463.  
  1464.  Note:   articles which have already been read (marked in %HOME%\NEWSRC) will 
  1465.          be skipped! 
  1466.  
  1467.  %HOME%\NEWSTIME 
  1468.  
  1469.  contains the time of the last NNTP connection.  This is for fetching of new 
  1470.  newsgroups.  If %HOME%\NEWSTIME does not exist, all currently available 
  1471.  newsgroups are fetched from the server when VSoup was called with the -a 
  1472.  option. 
  1473.  
  1474.  %TMP%\SOUP*.TMP 
  1475.  
  1476.  temporary files for received articles.  * will be replaced by a number in the 
  1477.  range 0-9999.  If %TMP% is not defined, %TMP% will be substituted by a '.' 
  1478.  
  1479.  
  1480.  .\00*.MSG 
  1481.  
  1482.  contain the received messages (news articles & EMail).  The files are written 
  1483.  in the following SOUP formats: 
  1484.  
  1485.      Binary 8-bit clean news format ("Bn") for incoming news.  Lines are 
  1486.       delimited by a single '\n', 
  1487.  
  1488.      Binary 8-bit clean mail format ("bn") for incoming mails.  Lines are 
  1489.       delimited by a single '\n'. 
  1490.  
  1491.  Note that the format of the message files can be changed to UNIX mailbox and 
  1492.  USENET batch using ConvSoup. 
  1493.  
  1494.  .\00*.IDX 
  1495.  
  1496.  contain the received newsgroup summaries (-u option).  The files are written 
  1497.  in the SOUP "ic" format. 
  1498.  
  1499.  .\STSMAIL.MSG 
  1500.  
  1501.  contains the status message generated by VSoup1.2.8.  This file is written in 
  1502.  the SOUP UNIX mailbox format ("mn").  Lines are delimited by a single '\n'. 
  1503.  
  1504.  .\AREAS 
  1505.  
  1506.  contains the table of contents of the received .\00*.MSG / .\00*.IDX files (+ 
  1507.  .\STSMAIL.MSG). 
  1508.  
  1509.  
  1510.  .\NEWS.MSG 
  1511.  
  1512.  contains the news messages that should be sent to the NNTP server.  The 
  1513.  following SOUP formats are supported: 
  1514.  
  1515.  "B"     Binary 8-bit clean news format.  The files are read in binary mode but 
  1516.          transferred in text mode to the NNTP host, 
  1517.  
  1518.  "u"     USENET batch format with the area name "news".  The files are read in 
  1519.          binary mode, thus '\r\n' pairs are treated as two characters (this is 
  1520.          not according to RFC1036 but according to Soup12.Html). 
  1521.  
  1522.  .\MAIL.MSG 
  1523.  
  1524.  contains the mail messages that should be sent to the SMTP server.  The 
  1525.  following SOUP formats are supported: 
  1526.  
  1527.  "b"     Binary 8-bit clean mail format.  The files are read in binary mode but 
  1528.          transferred in text mode to the SMTP gateway, 
  1529.  
  1530.  "u"     USENET batch format with the area name "mail".  The files are read in 
  1531.          binary mode, thus '\r\n' pairs are treated as two characters (this is 
  1532.          not according to RFC1036 but according to Soup12.Html). 
  1533.  
  1534.  .\REPLIES 
  1535.  
  1536.  contains the table of contents of the .\NEWS.MSG / .\MAIL.MSG files to be 
  1537.  transmitted.  Instead of the above file names other names could be used too. 
  1538.  
  1539.  
  1540. ΓòÉΓòÉΓòÉ 9. 9 Insufficiencies, Bugs & Plans ΓòÉΓòÉΓòÉ
  1541.  
  1542.  Insufficiencies 
  1543.  
  1544.      some cmd options, some files are not compatible with Souper16 
  1545.  
  1546.      space allocated from the heap is not freed (debugging...) 
  1547.  
  1548.      behaviour for news receiving/posting, mail receiving/posting is not 
  1549.       symmetrical, i.e. there is no multithreading except for news receiving... 
  1550.       This will be (perhaps) fixed in a future version 
  1551.  
  1552.       E.g.  start threads for connecting to the hosts for transmission, start a 
  1553.       thread for overall transmission, start a thread for overall mail 
  1554.       reception.  This all will allow parallel operation of sending/receiving 
  1555.       NNTP/POP3/SMTP stuff with one single VSoup. 
  1556.  
  1557.      only one single version (for OS/2) 
  1558.  
  1559.      it is not clear, how to handle '\r\n' pairs in the SOUP format! 
  1560.       Soup12.Html says '\r' should be treated as data, but '\r\n' must be 
  1561.       avoided.  In Soup12.Html '\r' are counted just like normal data bytes. 
  1562.  
  1563.  Bugs 
  1564.  
  1565.      version of the emx runtime is not checked! 
  1566.  
  1567.  Plans 
  1568.  
  1569.      remove bugs & insufficiencies 
  1570.  
  1571.      more situation dependent return codes 
  1572.  
  1573.      perhaps more status information on the screen 
  1574.  
  1575.      perhaps the servers IP address will be added to status messages 
  1576.  
  1577.      perhaps write Subject: to .\STSMAIL.MSG for mail reception/transmission 
  1578.  
  1579.      real Bcc: implementation for mailing 
  1580.  
  1581.  
  1582. ΓòÉΓòÉΓòÉ 10. 10 Author & Acknowledgements ΓòÉΓòÉΓòÉ
  1583.  
  1584.  Author 
  1585.  
  1586.  Hardy Griech 
  1587.  Ernetstr.  10/1 
  1588.  77933 Lahr 
  1589.  Germany 
  1590.  
  1591.  EMail:  rgriech@swol.de 
  1592.  
  1593.  
  1594.  Acknowledgements 
  1595.  
  1596.      FSF for GCC (2.7.2.1 used), EMACS (19.33.1 used), 
  1597.  
  1598.      Eberhard Mattes for the GCC & EMACS ports to OS/2 and the documentation 
  1599.       utility emxdoc, which made the .INF-file possible, 
  1600.  
  1601.      Chin Huang for Yarn and Souper, 
  1602.  
  1603.      the gamma testers Jim Holcomb, Kay Pyrtek, Phil Crown and Ralph D. 
  1604.       Bednarski, 
  1605.  
  1606.      Barrie Smith for rework on the documentation, for many suggestions about 
  1607.       documentation and a lot of proof reading! 
  1608.  
  1609.      Timo Maier for his excessive help finding the Warp4 related bug which led 
  1610.       to system crashes (see history, VSoup1.2.7). 
  1611.  
  1612.  
  1613. ΓòÉΓòÉΓòÉ 11. 11 History ΓòÉΓòÉΓòÉ
  1614.  
  1615.  Version 1.2.8 (190497) 
  1616.  
  1617.      new features: 
  1618.  
  1619.         -  Scoring introduced, see score file. 
  1620.  
  1621.      obsolete features: 
  1622.  
  1623.         -  The -l and -L command line options are obsoleted by scoring.  These 
  1624.            options allowed length limitations of articles. 
  1625.  
  1626.      bug fixes: 
  1627.  
  1628.         -  Small bug in pop3.cc which led to undefined/sick error messages. 
  1629.  
  1630.      other internal changes: 
  1631.  
  1632.         -  In pop3.cc mails are now no longer blocking the areas-files during 
  1633.            mail reception.  Instead incoming mail is copyied into a temporary 
  1634.            file.  This is a preparation step to allow simultaneous reception of 
  1635.            mail/news. 
  1636.  
  1637.  Version 1.2.7 (120297) 
  1638.  
  1639.      new features: 
  1640.  
  1641.         -  Port specification in URLs is now supported. 
  1642.  
  1643.         -  .\STSMAIL.MSG now contains a Date: header field.  This allows import 
  1644.            of the .\STSMAIL.MSG into a pseudo newsgroup, see also the Yarn 
  1645.            filter program. 
  1646.  
  1647.         -  The Subject: header line of .\STSMAIL.MSG now contains also the 
  1648.            server names which are relevant for the requested operation. 
  1649.  
  1650.         -  The first 40K of temporary files are kept in memory to reduce HDD 
  1651.            access (class TFileTmp). 
  1652.  
  1653.         -  National language support (_nls_tolower()) introduced for kill 
  1654.            expressions, OwnSoup and hashing. 
  1655.  
  1656.         -  newsgroup names in kill files are now regular expressions. 
  1657.  
  1658.         -  new Option -Ln allows specification of minimum article length (see 
  1659.            news receiving options). 
  1660.  
  1661.         -  new Option -D forces deletion of mails on POP3 server after 
  1662.            reception of each mail (see mail receiving options). 
  1663.  
  1664.         -  RmHigh.Cmd added, which removes the highlighting in VSOUP.TXT. 
  1665.  
  1666.      bug fixes: 
  1667.  
  1668.         -  VSoup crashed some Warp4 systems (trap address 0140:7d4c or 
  1669.            0140:7e33).  This was fixed through serializing some C library calls 
  1670.            (remove(), rename(), open(), close(), read(), write(), lseek() and 
  1671.            ftruncate()).  This problem is most likely device driver related, 
  1672.            although nothing specific is known.  Thanks to Timo, Stefan, Nate, 
  1673.            Rodney, Soenke, Tero and Teng Thiam for their help in finding the 
  1674.            problem. 
  1675.  
  1676.         -  Bug in emxlibcm <= 52 (don't know, what will happen later on): 
  1677.            _fd_init() is not threadsafe, i.e. all callers too (open(), 
  1678.            socket(), etc).  Perhaps This is the cause of the trap problem above 
  1679.            (not verified, rg120297) 
  1680.  
  1681.         -  Incomplete packets are now removed from the SOUP output.  Problems 
  1682.            appeared with aborted EMail reception (which writes directly into 
  1683.            the SOUP output and not to a temporary). 
  1684.  
  1685.         -  -T-1 no longer shows throughput info (see global options). 
  1686.  
  1687.         -  Signals were not initialized for mtGetGroup() with option -S2. 
  1688.  
  1689.         -  In SOUP .\REPLIES the types "bn"/"Bn" now override the message kind 
  1690.            "mail"/"news", which is required for type "u". 
  1691.  
  1692.         -  handling of "m" and "u" SOUP format in .\REPLIES corrected (file 
  1693.            positioning was wrong). 
  1694.  
  1695.         -  "ok, we've read enough..." now displays correctly. 
  1696.  
  1697.         -  %-display with -S1 reading strategy now (more) correct. 
  1698.  
  1699.         -  handling of "\r\n" delimited reply files corrected. 
  1700.  
  1701.         -  files are now opened with SH_DENYWR. 
  1702.  
  1703.         -  missing NEWSRC is no longer fatal (useful for initial setup). 
  1704.  
  1705.      other internal changes: 
  1706.  
  1707.         -  The threads are no longer killed through DosKillThread().  Instead, 
  1708.            threads are killing themselves (when they are detecting an abort 
  1709.            condition) through SIGUSR1.  Sockets are being set to O_NONBLOCK to 
  1710.            abort current requests. 
  1711.  
  1712.         -  assert(_heapchk() == _HEAPOK) inserted in some places. 
  1713.  
  1714.         -  nhandles() aborts after checking 150 handles. 
  1715.  
  1716.  Version 1.2.5 (091196) 
  1717.  
  1718.      Improved Documentation, thanks to Barrie Smith. 
  1719.  
  1720.       Documentation now in TXT and INF format available, thanks to emxdoc. 
  1721.  
  1722.      SOUP format for import has been changed: 
  1723.  
  1724.         -  .\STSMAIL.MSG has format "mn" (same as before) 
  1725.  
  1726.         -  from POP3 incoming Mails have format "bn": binary 8-bit clean mail 
  1727.            format.  This allows from headers in the first column of the mail, 
  1728.            i.e. mail handling is now transparent (old was "mn"). 
  1729.  
  1730.         -  news have format "Bn": binary 8-bit clean news format (old was "un") 
  1731.  
  1732.       To allow the conversion to the old format ConvSoup has been added. 
  1733.  
  1734.      Added OwnSoup which filters news articles containing a specific pattern 
  1735.       into a mail folder. 
  1736.  
  1737.      Added QSoup to allow injection of messages into the SOUP reply packet. 
  1738.  
  1739.      YarnIo changes: 
  1740.  
  1741.         -  YarnIo now only zips the SEND packets (this is to allow re-edit of 
  1742.            the replies).  Received messages are imported via import -u.  If you 
  1743.            have an older version of YARNIO.SET it must be updated. 
  1744.  
  1745.         -  YarnIo now supports OwnSoup.  To allow operation of OwnSoup the 
  1746.            entry preImportProg has been added to YARNIO.SET. 
  1747.  
  1748.         -  YarnIo now supports up to nine NNTP servers for news reception and 
  1749.            up to nine POP3 servers for EMail reception. 
  1750.  
  1751.      -T-1 disables throughput check completely. 
  1752.  
  1753.      the kill-section for one group can now be seperated, e.g. the kill file 
  1754.       may now contain several "all" sections. 
  1755.  
  1756.      now article ranges are allowed in the sendme of .\COMMANDS.  This is a 
  1757.       non-standard SOUP extension. 
  1758.  
  1759.      bug fixes: 
  1760.  
  1761.         -  hostname is now fetched through TCP/IP API, no longer from 'internet 
  1762.            settings' 
  1763.  
  1764.         -  it was possible in -S2 that during final catchup of articles the 
  1765.            connections were changing group assignment on each fetched article 
  1766.  
  1767.         -  catchup did not work as expected.  It sets the %HOME%\NEWSRC, so 
  1768.            that in any case 'n' articles were read afterwards.  Display now 
  1769.            shows groupLo & groupHi 
  1770.  
  1771.         -  ^Z was not recognized correctly for %HOME%\NEWSRC & %HOME%\KILL 
  1772.  
  1773.         -  Now again linked dynamically, ths EMX.DLL and EMXLIBCM.DLL are 
  1774.            required 
  1775.  
  1776.         -  Lines containing a single '.' were aborting EMails, even if the '.' 
  1777.            is actually doubled for transfer.  Don't know if this is an SMTP 
  1778.            bug.  Appending a blank behind the '.' helped (i.e. "..  " is 
  1779.            actually transferred to the SMTP server).  For news articles it 
  1780.            works without appending the blank. 
  1781.  
  1782.         -  sockets are now opened in text mode, because all the RFCs requires 
  1783.            \r\n as a line delimiter. 
  1784.  
  1785.  Version 1.2 (061096) 
  1786.  
  1787.      first non-beta release 
  1788.  
  1789.      more detailed README 
  1790.  
  1791.      YarnIo enhanced (autodial, disabling specific actions, configuration 
  1792.       file, ...) 
  1793.  
  1794.      some changes/enhancements/extensions in .\STSMAIL.MSG, e.g. command line 
  1795.       parameters are contain, important server names too...  (useful for 
  1796.       debugging) 
  1797.  
  1798.      if supported by the NNTP server, the XHDRs are retrieved to determine 
  1799.       holes in the article sequence 
  1800.  
  1801.      throughput check (-T option) now replaces the old timeout detection.  It 
  1802.       is now working for all operations. 
  1803.  
  1804.      news reading, strategy parameter: 
  1805.  
  1806.       -S0          groups are read sequentially, i.e. all threads are fetching 
  1807.                    articles from only one group 
  1808.  
  1809.       -S1          the next group will be accessed, if one thread goes into 
  1810.                    waiting state - only small modification of the above 
  1811.  
  1812.       -S2          it is tried, to keep all threads busy.  I.e.  each thread 
  1813.                    accesses one dedicated group, groups are read parallel (if 
  1814.                    there are no more groups to access, the waiting threads are 
  1815.                    used for parallel reading from one group) 
  1816.  
  1817.      more robust (but slower) reading of %HOME%\KILL and %HOME%\NEWSRC. 
  1818.       Because it is slower: clean-up your %HOME%\NEWSRC from time to time, if 
  1819.       you are using the -a option 
  1820.  
  1821.      bug fixes: 
  1822.  
  1823.         -  'internet connection' settings were never ignored (-i did not work) 
  1824.  
  1825.         -  some very minor bug fixes for handling of broken connections 
  1826.  
  1827.         -  under some circumstances broken SMTP connection did not produce an 
  1828.            error condition 
  1829.  
  1830.         -  bug in kill file handling fixed (trailing blanks in line were not 
  1831.            accepted).  Lines in the kill file can now be outcommented through a 
  1832.            '#' as the first non-blank character 
  1833.  
  1834.         -  if getArticle() fails, the according connection will be marked as 
  1835.            failed.  This lets VSoup die gracefully, if single connections are 
  1836.            cancelled (by whom?) 
  1837.  
  1838.         -  signal handling changed: VSoup tries (!) to kill the sub-threads 
  1839.  
  1840.         -  number of file handles provided by emx is now checked 
  1841.  
  1842.         -  now compiled with emx09c.  During this 'port' it became obvious, 
  1843.            that streams are not appropriate.  Thus all file i/o is done 
  1844.            directly via handles (class TFile in mts.cc) 
  1845.  
  1846.  Version 1.1╤ü (010996) 
  1847.  
  1848.      first public beta 
  1849.  
  1850.      if NNTP server knows nothing about DATE command, the internal clock will 
  1851.       be taken as a reference (required for -a cmd option only) 
  1852.  
  1853.      'AUTHINFO USER' / 'AUTHINFO PASS' for nntp server implemented (RFC977 
  1854.       extension).  Call VSoup simply with the nntp-URL 
  1855.       nntp://user:passwd@nntpserver 
  1856.  
  1857.      NNTP NEXT will only be done, if there is a bigger gap between the 
  1858.       articles 
  1859.  
  1860.      bug in socket.cc ((char)0xff == (int)-1 !!!) 
  1861.  
  1862.  Version 1.0╤ü (010896) 
  1863.  
  1864.      Program is now named VSoup.  I am sorry, but the program again requires 
  1865.       the emx DLLs (to my opinion no disadvantage, because most of the people 
  1866.       will have them anyway).  Also there is no support for Win95 (this was not 
  1867.       intended and I am not sorry, but I have no Win95 system - and I am happy 
  1868.       about that ;-) 
  1869.  
  1870.      Program is now multithreaded for news reading.  This gives a speed gain 
  1871.       of 200%-500% depending on the overall speed of the connection and the 
  1872.       number of threads; on the other hand multiple connections have a 
  1873.       communication overhead (i.e. the connections must be established, the 
  1874.       groups selected).  Estimated loss is around 5%... 
  1875.  
  1876.      Return codes are now much more consistent: on failure an EXIT_FAILURE (1) 
  1877.       is returned, on success EXIT_SUCCESS (0) 
  1878.  
  1879.      On failure a status mail is generated.  Most of the console messages are 
  1880.       redirected into this status mail.  The generation of the mail can be 
  1881.       forced thru cmd option -M 
  1882.  
  1883.      If file %HOME%\NEWSTIME does not exist, the complete newsgroup list is 
  1884.       retrieved from the news server (NNTP LIST) 
  1885.  
  1886.      Kill files may have comments ('#' in the first position of a line).  This 
  1887.       is very beta... 
  1888.  
  1889.      Readonly mode is now much more consistent (%HOME%\NEWSTIME is not 
  1890.       updated, also the sent articles are not deleted) 
  1891.  
  1892.      the default maximum packet size has been changed to unlimited 
  1893.  
  1894.      Small bug in %HOME%\NEWSRC handling found (firstUnread was wrong 
  1895.       sometimes) 
  1896.  
  1897.      automatic timeout for NNTP reception 
  1898.  
  1899.  
  1900. ΓòÉΓòÉΓòÉ 12. 12 FAQ ΓòÉΓòÉΓòÉ
  1901.  
  1902.  This sections contains several frequently questions and the corresponding 
  1903.  answers.  The questions are: 
  1904.  
  1905.   Why do I get something like '0000002.msg: Too many open files'?
  1906.   Why is my news reception getting stuck sometimes?
  1907.   Are there any specific problems with the different versions of the emx runtimes?
  1908.   I cannot receive EMail from my POP3 server?
  1909.   I have another EMail program.  Therefor I'd like to disable...
  1910.   Give me sample scripts for simple VSoup IO operation.
  1911.   VSOUP.TXT contains strange characters...
  1912.   Give me an example scorefile!?
  1913.   How to kill heavily crossposted articles...
  1914.   How to convert my old kill file to the new score file format?
  1915.   I have 8 connections requested for news receiving...
  1916.   I am getting mails, which actually seems to be news articles!?
  1917.   How can I setup more than one filter with OwnSoup?
  1918.   How to move the VSoup status mails into a pseudo newsgroup?
  1919.   How do I get a listing of all available newsgroups?
  1920.   How to clean up the NEWSRC file?
  1921.   How to subscribe to a newsgroup?
  1922.   How to unsubscribe and delete a newsgroup?
  1923.   Can I abort VSoup operation safely?
  1924.   Can you show me the 'diff' between your sendmail.cf and...
  1925.   Can I use VSoup together with Changi?
  1926.   Can I use VSoup together with another offline newsreader...
  1927.   Where to obtain more information about SOUP?
  1928.   Where are the internet standards described?
  1929.   Where can I obtain the latest version of VSoup?
  1930.   Where to obtain the latest version of Yarn?
  1931.   How to subscribe to the Yarn mailing list?
  1932.  
  1933.  
  1934. ΓòÉΓòÉΓòÉ 12.1. Why do I get something like '0000002.msg: Too many open files'? ΓòÉΓòÉΓòÉ
  1935.  
  1936.  Why do I get something like '0000002.msg: Too many open files'? 
  1937.  
  1938.  and the related question 
  1939.  
  1940.  I am getting the message '...number of threads cut...'.  What does it mean? 
  1941.  
  1942.  VSoup needs a lot of open file handles.  The YarnIo script provides these 
  1943.  automatically, but if you are not using this script then it is recommended 
  1944.  that you add the following line to your CONFIG.SYS: SET EMXOPT=-h40 -c -n. 
  1945.  This allows 40 open file handles which should be enough. 
  1946.  
  1947.  
  1948. ΓòÉΓòÉΓòÉ 12.2. Why is my news reception getting stuck sometimes? ΓòÉΓòÉΓòÉ
  1949.  
  1950.  Why is my news reception getting stuck sometimes? 
  1951.  
  1952.  One common reason is that you are using the wrong (too old) version of the 
  1953.  emx-runtime-DLLs.  Check them with emxrev (should show revisions >= 50) and 
  1954.  update them if required.  Also you have to avoid a mixture of emx runtime 
  1955.  DLLs. 
  1956.  
  1957.  
  1958. ΓòÉΓòÉΓòÉ 12.3. Are there any specific problems with the different versions of the emx runtimes? ΓòÉΓòÉΓòÉ
  1959.  
  1960.  Are there any specific problems with the different versions of the emx 
  1961.  runtimes? 
  1962.  
  1963.  Unfortunately there are!  The revision of the runtime DLLs can be obtained via 
  1964.  the command emxrev.  Only the revision numbers of emx.dll and emxlibcm.dll are 
  1965.  important for VSoup. 
  1966.  
  1967.  revision < 40 No way, because nothing of the TCP/IP stuff is included in the C 
  1968.          library. 
  1969.  
  1970.  revision < 50, >= 40 This is not recommended, although it should work because 
  1971.          VSoup serializes most of the calls to the C library.  Nevertheless you 
  1972.          should use the newest available revision of the emx09b runtimes, 
  1973.          because there were many changes/bugfixes in the TCP/IP part. 
  1974.  
  1975.  revision = 50 (also > 50) Check the setting of the environment variable TZ. 
  1976.          It should/must contain a value which is acceptable for the emx C 
  1977.          library.  Otherwise you will get an SYS3175. 
  1978.  
  1979.          Revisions > 50 will not crash due to incorrect setting of TZ, anyway 
  1980.          they cannot interprete the variable correctly. 
  1981.  
  1982.  
  1983. ΓòÉΓòÉΓòÉ 12.4. I cannot receive EMail from my POP3 server? ΓòÉΓòÉΓòÉ
  1984.  
  1985.  I cannot receive EMail from my POP3 server? 
  1986.  
  1987.      Check, if your UserId/Password settings are ok 
  1988.  
  1989.      Check, that your %ETC%\SERVICES file contains the following lines (see 
  1990.       also Installation): 
  1991.  
  1992.               pop3        110/tcp       #Post Office Protocol - Version 3
  1993.               pop3        110/udp       #Post Office Protocol - Version 3
  1994.  
  1995.      Alternatively you can insert the port number in the command line POP3 
  1996.       URL. 
  1997.  
  1998.  
  1999. ΓòÉΓòÉΓòÉ 12.5. I have another EMail program.  Therefor I'd like to disable... ΓòÉΓòÉΓòÉ
  2000.  
  2001.  I have another EMail program. Therefor I'd like to disable the RCVMAIL feature 
  2002.  of YarnIO.  How do I do this? 
  2003.  
  2004.  You simply have to set soupRcvMail in YARNIO.SET to '' (the empty string). 
  2005.  
  2006.  
  2007. ΓòÉΓòÉΓòÉ 12.6. Give me sample scripts for simple VSoup IO operation. ΓòÉΓòÉΓòÉ
  2008.  
  2009.  Give me sample scripts for simple VSoup IO operation. 
  2010.  
  2011.  Simple Reception: Because this is a simple approach, NEWSRC & SCORE resides in 
  2012.          the %HOME% directory. 
  2013.  
  2014.              change to a directory for IO operation, e.g. c:\vsoup. 
  2015.  
  2016.              call VSoup, e.g. 
  2017.  
  2018.                             vsoup -M nntp://your.news.server pop3://your.pop3.server
  2019.  
  2020.               The output of the VSoup operation will be in the current 
  2021.               directory, i.e. in c:\vsoup in this example.  If your 'internet 
  2022.               settings' are setup correctly by your dialer, you could omit the 
  2023.               nntp:// and pop3:// specifications in the command line. 
  2024.  
  2025.              feed the received news/EMails and the by VSoup generated status 
  2026.               mail into the database of your newsreader.  For Yarn the import 
  2027.               program will be used (e.g. import -u). 
  2028.  
  2029.          If you are using different programs for handling news/EMails, you 
  2030.          could do two sequential invocations of VSoup: 
  2031.  
  2032.                   vsoup -Mm nntp://your.news.server
  2033.                   handle_news_import
  2034.                   vsoup -Mn pop3://your.pop3.server
  2035.                   handle_mail_import
  2036.  
  2037.          Of course this VSoup instances could also be started parallel through 
  2038.          e.g.: 
  2039.  
  2040.                   start do_news_reception
  2041.                   start do_mail_reception
  2042.  
  2043.          This approach requires a little bit more effort than the sequential 
  2044.          one.  Check YarnIo as an example. 
  2045.  
  2046.  Simple Transmission: 
  2047.  
  2048.              change to the directory where your reply packets (e.g. reply.zip) 
  2049.               reside.  If they are zipped (or packed in another way), you have 
  2050.               to unzip/unpack them before VSoup will be called (e.g. unzip -oq 
  2051.               reply.zip & del reply.zip). 
  2052.  
  2053.              call VSoup, e.g. 
  2054.  
  2055.                             vsoup -Ms nntp://your.news.server smtp://your.mail.gateway
  2056.  
  2057.               Failure of transmission should be handled in a proper way, e.g. 
  2058.               if .\REPLIES still exists, you have to rezip the not transmitted 
  2059.               news/mails (for Yarn IO you have to invoke zip -0m reply.zip 
  2060.               replies news.msg mail.msg).  If your 'internet settings' are 
  2061.               setup correctly by your dialer, you could omit the nntp:// and 
  2062.               smtp:// specifications in the command line. 
  2063.  
  2064.              handle the by VSoup generated status mail (e.g. import -u for 
  2065.               Yarn IO). 
  2066.  
  2067.          If you are using different programs for handling news/mail, you could 
  2068.          do two sequential invocations of VSoup or you could start two VSoup 
  2069.          parallel (see above). 
  2070.  
  2071.  IO for Yarn with simple scripts 
  2072.  
  2073.  We assume, that the IO subdirectory is at c:\vsoup, the news/EMail 
  2074.  reader/writer is Yarn and the server URLs are taken from the 'internet 
  2075.  settings', a status mail is generated by VSoup, the reply packet is stored by 
  2076.  Yarn to c:\vsoup\reply.zip, the NEWSRC & SCORE (if one exists) are located in 
  2077.  %HOME%: 
  2078.  
  2079.  Script for simple reception: 
  2080.  
  2081.                   c:
  2082.                   cd \vsoup
  2083.                   vsoup -M
  2084.                   import -u
  2085.  
  2086.  Script for simple transmission: 
  2087.  
  2088.                   c:
  2089.                   cd \vsoup
  2090.                   unzip -oq reply
  2091.                   del reply.zip
  2092.                   vsoup -Ms
  2093.                   import -u
  2094.                   zip -0m reply replies news.msg mail.msg
  2095.  
  2096.  
  2097. ΓòÉΓòÉΓòÉ 12.7. VSOUP.TXT contains strange characters... ΓòÉΓòÉΓòÉ
  2098.  
  2099.  VSOUP.TXT contains strange characaters.  What's wrong? 
  2100.  
  2101.  VSOUP.TXT uses some kind of poor (wo)mans highlighting.  This is obtained 
  2102.  through backspacing and overwriting in the ASCII file.  Some Viewers or 
  2103.  Editors are not capable of handling such files correctly (GNUs Less can do 
  2104.  it). 
  2105.  
  2106.  Solution is to remove the highlighting with the small script RmHigh. 
  2107.  
  2108.  
  2109. ΓòÉΓòÉΓòÉ 12.8. Give me an example scorefile!? ΓòÉΓòÉΓòÉ
  2110.  
  2111.  Give me an example scorefile!? 
  2112.  
  2113.  Here you are: 
  2114.  
  2115.     # this is a scorefile for VSoup
  2116.     #
  2117.     all {
  2118.        -1 header microsoft
  2119.        -1 pattern from bill.*gates
  2120.     }
  2121.  
  2122.     all {
  2123.        -1 pattern subject make.*money
  2124.        -1 pattern subject \$\$\$
  2125.        -1 x-newsreader forte agent
  2126.     }
  2127.  
  2128.     comp.os.os2.mail-news {
  2129.        -1 subject ultimail
  2130.        -1 subject netscape
  2131.        -1 subject help:
  2132.     }
  2133.  
  2134.     .*binaries.* {
  2135.        -1 lines < 50
  2136.        -1 lines > 3000
  2137.     }
  2138.  
  2139.     comp\..* {
  2140.        -1 lines > 99
  2141.     }
  2142.  
  2143.      First group would kill messages in all newsgroups which have 
  2144.  
  2145.         -  the word microsoft somewhere in the header, 
  2146.  
  2147.         -  or are from a guy with a bill-pattern followed somewhere by a gates 
  2148.            pattern, 
  2149.  
  2150.      Second group would again kill messages in all newsgroups which have 
  2151.  
  2152.         -  make followed by money in the subject, 
  2153.  
  2154.         -  or contain three consecutive $$$ in the subject, 
  2155.  
  2156.         -  or contain forte agent in the x-newsreader header line. 
  2157.  
  2158.      Third group would kill messages in the comp.os.os2.mail-news group which 
  2159.       have subject lines containing the words ultimail, netscape or help:. 
  2160.  
  2161.      Forth group would kill articles in newsgroups matching .*binaries.*, if 
  2162.       they contain less than 50 lines or more than 3000 lines. 
  2163.  
  2164.      Fifth group would kill articles in newsgroups matching comp\..*, if they 
  2165.       contain more than 99 lines.  Note, that the newsgroup 
  2166.       comp.os.os2.mail.news will match both the third and the fifth group! 
  2167.  
  2168.  Also check scorefile explanation and the regular expression syntax. 
  2169.  
  2170.  
  2171. ΓòÉΓòÉΓòÉ 12.9. How to kill heavily crossposted articles... ΓòÉΓòÉΓòÉ
  2172.  
  2173.  How to kill heavily crossposted articles (and thus avoid spams very likely)? 
  2174.  
  2175.  Add the following to your score file: 
  2176.  
  2177.     # this kills articles posted to more then 4 groups
  2178.     #
  2179.     all {
  2180.        -1000 pattern newsgroups ,.*,.*,.*,
  2181.     }
  2182.  
  2183.  
  2184. ΓòÉΓòÉΓòÉ 12.10. How to convert my old kill file to the new score file format? ΓòÉΓòÉΓòÉ
  2185.  
  2186.  How to convert my old kill file to the new score file format? 
  2187.  
  2188.  Two rules (but no script...): 
  2189.  
  2190.      insert "-1" at the beginning of each rule, 
  2191.  
  2192.      if the pattern on the right side contains a regular expression insert 
  2193.       "pattern" behind the "-1". 
  2194.  
  2195.  
  2196. ΓòÉΓòÉΓòÉ 12.11. I have 8 connections requested for news receiving... ΓòÉΓòÉΓòÉ
  2197.  
  2198.  I have 8 connections requested for news receiving (with the -t8 option), but 
  2199.  the status message says that only 3 threads were connected successfully. 
  2200.  What's wrong? 
  2201.  
  2202.  Nothing! Sometimes it takes very long to establish a connection to the news 
  2203.  server which means that VSoup has finished before all requested threads have 
  2204.  been connected.  It is also possible that a news server might restrict the 
  2205.  number of simultaneous connections by one user.  I have not heard of this 
  2206.  happening, but who knows! 
  2207.  
  2208.  
  2209. ΓòÉΓòÉΓòÉ 12.12. I am getting mails, which actually seems to be news articles!? ΓòÉΓòÉΓòÉ
  2210.  
  2211.  I am getting mails, which actually seems to be news articles!? 
  2212.  
  2213.  You are using OwnSoup somewhere.  If you are using YarnIo for you I/O 
  2214.  operations, check in YARNIO.SET the preImportProg line, which should either be 
  2215.  empty ('') or should contain arguments to match your needs (not mine as the 
  2216.  settings reflect in the sample YARNIO.SET in the archive). 
  2217.  
  2218.  
  2219. ΓòÉΓòÉΓòÉ 12.13. How can I setup more than one filter with OwnSoup? ΓòÉΓòÉΓòÉ
  2220.  
  2221.  I am using YARNIO.SET.  How can I setup more than one filter with OwnSoup? 
  2222.  
  2223.  You have to use the command concatenator in the preImportProg line of 
  2224.  YARNIO.SET, e.g. 
  2225.  
  2226.   preImportProg = 'ownsoup -q rgriech stuff4me OwnTemp'
  2227.   preImportProg = preImportProg '&& ownsoup -bq vsoup vsoupstuff VsTemp'
  2228.  
  2229.  This example will search for "rgriech" in header and body and additionally for 
  2230.  "vsoup" in the body section of the news articles. 
  2231.  
  2232.  In a second step you have to setup the corresponding mail filter with the Yarn 
  2233.  filter program. 
  2234.  
  2235.  
  2236. ΓòÉΓòÉΓòÉ 12.14. How to move the VSoup status mails into a pseudo newsgroup? ΓòÉΓòÉΓòÉ
  2237.  
  2238.  How to move the VSoup status mails into a pseudo newsgroup? 
  2239.  
  2240.      create a newsgroup with the Yarn utility newgroup, e.g. 
  2241.  
  2242.                newgroup VSoupStatus 3
  2243.  
  2244.       This will create the group VSoupStatus with three days expiration time. 
  2245.  
  2246.      Setup a filter with the Yarn filter.  The filter parameters are as 
  2247.       follows: 
  2248.  
  2249.             Γöî Mail Rule ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  2250.             Γöé                                                                          Γöé
  2251.             Γöé  Rule name: VSoup Status                                                 Γöé
  2252.             Γöé                                                                          Γöé
  2253.             Γöé  Search in: ( ) From                                                     Γöé
  2254.             Γöé             (*) To                                                       Γöé
  2255.             Γöé             ( ) Subject                                                  Γöé
  2256.             Γöé             ( ) Header                                                   Γöé
  2257.             Γöé             ( ) Body                                                     Γöé
  2258.             Γöé             ( ) Header and body                                          Γöé
  2259.             Γöé                                                                          Γöé
  2260.             Γöé Search for: vsoupuser                                                    Γöé
  2261.             Γöé Match case: No                                                           Γöé
  2262.             Γöé                                                                          Γöé
  2263.             Γöé     Action: (*) Move to folder/newsgroup: VSoupStatus                    Γöé
  2264.             Γöé             ( ) Delete                                                   Γöé
  2265.             Γöé                                                                          Γöé
  2266.             ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  2267.  
  2268.  From now on the VSoup status mails are put into the newsgroup VSoupStatus. 
  2269.  Because the Subject: header also contains the server names, Yarn will 
  2270.  automatically sort the status mail/news by action. 
  2271.  
  2272.  
  2273. ΓòÉΓòÉΓòÉ 12.15. How do I get a listing of all available newsgroups? ΓòÉΓòÉΓòÉ
  2274.  
  2275.  How do I get a listing of all available newsgroups? 
  2276.  
  2277.  Delete the file NEWSTIME in the directory of your NEWSRC file and call VSoup 
  2278.  with the -a option the next time.  After that you will get a status mail and 
  2279.  the available groups are appended to your NEWSRC file.  Note that groups 
  2280.  already contained in NEWSRC will not appear in the status mail. 
  2281.  
  2282.  
  2283. ΓòÉΓòÉΓòÉ 12.16. How to clean up the NEWSRC file? ΓòÉΓòÉΓòÉ
  2284.  
  2285.  How to clean up the NEWSRC file? 
  2286.  
  2287.  After a while the NEWSRC will contain many unsubscribed groups if VSoup will 
  2288.  be called with the -a option.  You can get rid off those unsubscribed groups 
  2289.  with the following commands: 
  2290.  
  2291.      cd 'directory of newsrc'
  2292.      find ":" < newsrc > newsrc.tmp
  2293.      copy newsrc.tmp newsrc
  2294.      del newsrc.tmp
  2295.  
  2296.  
  2297. ΓòÉΓòÉΓòÉ 12.17. How to subscribe to a newsgroup? ΓòÉΓòÉΓòÉ
  2298.  
  2299.  How to subscribe to a newsgroup? 
  2300.  
  2301.      Open the NEWSRC file of the NNTP server you like to add an subscription, 
  2302.  
  2303.      add the line GroupYouLikeToSubscribe: to the file. 
  2304.  
  2305.  On the next import to Yarn, import will add the new group to the %YARN\ACTIVE 
  2306.  file automatically with defaults specified in the %HOME%\YARN\CONFIG file 
  2307.  (keep and max-keep entries).  It is not required to invoke the Yarn newgroup 
  2308.  command.  The new group will also appear in the newsgroup selection level of 
  2309.  Yarn. 
  2310.  
  2311.  Keep in mind that there are several NEWSRC files!  Some of them are used by 
  2312.  VSoup (especially if you access multiples NNTP servers), others are used by 
  2313.  Yarn (i.e. %HOME%\YARN\NEWSRC). 
  2314.  
  2315.  
  2316. ΓòÉΓòÉΓòÉ 12.18. How to unsubscribe and delete a newsgroup? ΓòÉΓòÉΓòÉ
  2317.  
  2318.  How to unsubscribe and delete a newsgroup? 
  2319.  
  2320.      Delete the newsgroup from the corresponding NEWSRC file, 
  2321.  
  2322.      if you have one single NEWSRC file or multiple NEWSRC files and none of 
  2323.       them contains any longer the respective group you could delete the 
  2324.       newsgroup from the %YARN%\NEWS.DAT database with the Yarn rmgroup 
  2325.       command. 
  2326.  
  2327.  
  2328. ΓòÉΓòÉΓòÉ 12.19. Can I abort VSoup operation safely? ΓòÉΓòÉΓòÉ
  2329.  
  2330.  Can I abort VSoup operation safely? 
  2331.  
  2332.  Yes, it is safe to abort VSoup by ^C or ^BREAK.  The following takes place: 
  2333.  
  2334.  News reception: VSoup will save the current NEWSRC contents and the articles 
  2335.          are stored after the reception of each single article into the 
  2336.          corresponding .\00*.MSG file.  The .\AREAS file will be left in a 
  2337.          proper state for import. 
  2338.  
  2339.  EMail reception: The QUIT command will not be sent to the POP3 server, which 
  2340.          means that the mailbox will not be emptied which again means that when 
  2341.          you next call you will get the already received EMails of the aborted 
  2342.          VSoup session again. 
  2343.  
  2344.  News transmission: Double sent articles are detected by the news server and 
  2345.          will be rejected by it.  This special type of rejection (435 & 437 
  2346.          error number in NNTP reply) will be considered by VSoup as a non-error 
  2347.          condition, thus the articles are handled as having been successfully 
  2348.          delivered (which in fact they are). 
  2349.  
  2350.  EMail transmission: If the VSoup session has been aborted during EMail 
  2351.          transmission, the whole EMail batch will be resent. 
  2352.  
  2353.  
  2354. ΓòÉΓòÉΓòÉ 12.20. Can you show me the 'diff' between your sendmail.cf and... ΓòÉΓòÉΓòÉ
  2355.  
  2356.  Can you show me the 'diff' between your sendmail.cf and the original 
  2357.  sendmail.uml? 
  2358.  
  2359.  Of course, but you should be capable of reading 'diffs'.  Also be aware, that 
  2360.  sendmail requires tabs as delimiter between the ruleset fields. 
  2361.  
  2362.   *** sendmail.uml        Tue Oct  3 23:09:04 1995
  2363.   --- d:sendmail.cf       Sat Nov  9 19:20:30 1996
  2364.   ***************
  2365.   *** 1,3 ****
  2366.   --- 1,7 ----
  2367.   + Cwswol.de
  2368.   + Dwswol.de
  2369.     #########################################################################
  2370.     #                                                                       #
  2371.     #  Sendmail                                                             #
  2372.   ***************
  2373.   *** 102,108 ****
  2374.     #
  2375.     # If macro R is undefined, then mail for internal destinations will be
  2376.     # delivered directly
  2377.   ! DDYour.Domain
  2378.  
  2379.     # Internal, directly connected domains
  2380.     #
  2381.   --- 106,112 ----
  2382.     #
  2383.     # If macro R is undefined, then mail for internal destinations will be
  2384.     # delivered directly
  2385.   ! DD
  2386.  
  2387.     # Internal, directly connected domains
  2388.     #
  2389.   ***************
  2390.   *** 154,160 ****
  2391.     # SMTP read timeout
  2392.     Or15m
  2393.     # Queue directory - this must be changed if TCP/IP is moved!
  2394.   ! OQC:\MPTN\ETC\mqueue
  2395.     # Always queue for safety
  2396.     Os
  2397.     # Time to live in the queue
  2398.   --- 158,164 ----
  2399.     # SMTP read timeout
  2400.     Or15m
  2401.     # Queue directory - this must be changed if TCP/IP is moved!
  2402.   ! OQd:\ETC\MQUEUE
  2403.     # Always queue for safety
  2404.     Os
  2405.     # Time to live in the queue
  2406.   ***************
  2407.   *** 173,179 ****
  2408.     #
  2409.     HReceived: $?sfrom $s $.by $j ($v/$Z) id $i; $b
  2410.     H?D?Date: $a
  2411.   ! H?F?From: $q
  2412.     H?M?Message-Id: <$t.$i@$j>
  2413.     H?D?Resent-Date: $a
  2414.     H?F?Resent-From: $q
  2415.   --- 177,183 ----
  2416.     #
  2417.     HReceived: $?sfrom $s $.by $j ($v/$Z) id $i; $b
  2418.     H?D?Date: $a
  2419.   ! H?F?From: Hardy Griech <rgriech@swol.de>
  2420.     H?M?Message-Id: <$t.$i@$j>
  2421.     H?D?Resent-Date: $a
  2422.     H?F?Resent-From: $q
  2423.   ***************
  2424.   *** 297,302 ****
  2425.   --- 301,307 ----
  2426.     R$* : $* ;              $#error $@ USAGE $: "list:; syntax illegal for...
  2427.     R<@ $+>                 $#error $@ USAGE $: "user address required"
  2428.     R<$* : $* >             $#error $@ USAGE $: "colon illegal in host name part"
  2429.   + R$+<@$+>                $#local $:$1
  2430.  
  2431.     # handle numeric address spec
  2432.     R$* < @ [ $+ ] > $*     $#smtp $@ [$2] $: $1 < @ [$2] > $3      numeric...
  2433.   ***************
  2434.   *** 387,393 ****
  2435.     #
  2436.  
  2437.     Msmtp,  P=[IPC], F=mDFMuX, S=10, R=0, A=IPC $h
  2438.   ! Mlocal, P=C:\TCPIP\UMAIL\UMAILER.EXE , F=lsm, S=10, R=0, A=-dest C:\TCP...
  2439.     Mprog,  P=xxx, A=Required by sendmail but unused
  2440.  
  2441.  
  2442.   --- 392,398 ----
  2443.     #
  2444.  
  2445.     Msmtp,  P=[IPC], F=mDFMuX, S=10, R=0, A=IPC $h
  2446.   ! Mlocal, P=d:\b\32\qsoup.exe , F=lmnDFM, S=10, R=0, A=-m -i $u
  2447.     Mprog,  P=xxx, A=Required by sendmail but unused
  2448.  
  2449.  
  2450. ΓòÉΓòÉΓòÉ 12.21. Can I use VSoup together with Changi? ΓòÉΓòÉΓòÉ
  2451.  
  2452.  Can I use VSoup together with Changi? 
  2453.  
  2454.  Yes, you can use VSoup as the news feeder for Changi.  For reply transmission 
  2455.  Chanx must still be used.  The following setup should work: 
  2456.  
  2457.      setup VSoup for news reception as described in the installation section, 
  2458.  
  2459.      after VSoup operation ConvSoup must be called, which converts the 
  2460.       .\00*.MSG from binary format to the USENET batch format, 
  2461.  
  2462.      then do a copy 00*.msg all_in_one, 
  2463.  
  2464.      then call the Changi RNews with all_in_one as input file. 
  2465.  
  2466.  The above is not tested!  If anybody likes to confirm the procedure, please 
  2467.  send me an EMail.  Anyway the .\STSMAIL.MSG is not handled by the above 
  2468.  procedure. 
  2469.  
  2470.  Remark: The question 'why should I use VSoup together with Changi?' is 
  2471.          triggered by the fact that several news servers do not allow the 
  2472.          NEWNEWS command, which is used by Chanx for multithreaded news 
  2473.          reception. 
  2474.  
  2475.  
  2476. ΓòÉΓòÉΓòÉ 12.22. Can I use VSoup together with another offline newsreader... ΓòÉΓòÉΓòÉ
  2477.  
  2478.  Can I use VSoup together with another offline newsreader than Yarn/Changi? 
  2479.  
  2480.  VSoup can be used as news/mail client for all offline newsreaders which expect 
  2481.  SOUP format as input and generate articles in SOUP format on the output side. 
  2482.  Perhaps ConvSoup has to be used to convert the received messages into the 
  2483.  correct data format known by your newsreader. 
  2484.  
  2485.  For squish based newsreader there exists a free converter which makes VSoup 
  2486.  usable also for people prefering such readers. 
  2487.  
  2488.  Reports of successfully combining VSoup with other newsreaders than Yarn and 
  2489.  the corresponding recipes are highly welcome and (c|sh)ould be submitted to 
  2490.  rgriech@swol.de. 
  2491.  
  2492.  
  2493. ΓòÉΓòÉΓòÉ 12.23. Where to obtain more information about SOUP? ΓòÉΓòÉΓòÉ
  2494.  
  2495.  Where to obtain more information about SOUP? 
  2496.  
  2497.  For more information about SOUP refer to Soup12.Html which can be found on the 
  2498.  net, e.g. at http://www.eden.com/~combee/soup12.html. 
  2499.  
  2500.  
  2501. ΓòÉΓòÉΓòÉ 12.24. Where are the internet standards described? ΓòÉΓòÉΓòÉ
  2502.  
  2503.  Where are the internet standards described? 
  2504.  
  2505.  The internet standards are described in Request For Comment documents (RFC). 
  2506.  VSoup uses the NNTP, POP3 and SMTP standards.  A good starting point for RFC 
  2507.  reading is e.g. http://ds2.internic.net/ds/rfc-index.html. 
  2508.  
  2509.  RFCs of interest are: 
  2510.  
  2511.  RFC821  Simple Mail Transfer Protocol, 
  2512.  
  2513.  RFC822  Standard for the format of ARPA Internet text messages, 
  2514.  
  2515.  RFC977  Network News Transfer Protocol, 
  2516.  
  2517.  RFC1036 Standard for interchange of USENET messages, 
  2518.  
  2519.  RFC1460 Post Office Protocol - Version 3. 
  2520.  
  2521.  
  2522. ΓòÉΓòÉΓòÉ 12.25. Where can I obtain the latest version of VSoup? ΓòÉΓòÉΓòÉ
  2523.  
  2524.  Where to obtain the latest version of VSoup? 
  2525.  
  2526.  I will upload public releases of VSoup to ftp.cdrom.com, ftp.leo.org and 
  2527.  ftp-os2.nmsu.edu (Hobbes).  The corresponding URLs are: 
  2528.  
  2529.      ftp://ftp.leo.org/pub/comp/os/os2/leo/tcpip/news/vsoup*.zip 
  2530.  
  2531.      ftp://ftp.cdrom.com/pub/os2/new/vsoup*.zip, later on it can be found at 
  2532.       ftp://ftp.cdrom.com/pub/os2/internet/vsoup*.zip. 
  2533.  
  2534.      ftp://ftp-os2.nmsu.edu/new/vsoup*.zip, later on it can be found at 
  2535.       ftp://ftp-os2.nmsu.edu/os2/internet/vsoup*.zip. 
  2536.  
  2537.  Version notification will take place in the Yarn mailing list. 
  2538.  
  2539.  The current update frequency is at about one release per month.  But this will 
  2540.  stabilize in the very near future (09-Nov-1996). 
  2541.  
  2542.  Experimental versions can be downloaded from 
  2543.  http://privat.swol.de/ReinhardGriech/vsoup.zip.  Very experimental - one could 
  2544.  say: alphas - can be obtained from 
  2545.  http://privat.swol.de/ReinhardGriech/vsoupbeta.zip.  Content of both archives 
  2546.  is only an executable of VSoup.  The alpha version could contain perhaps some 
  2547.  debugging output.  Neither there is a guarantee that versions downloaded from 
  2548.  this site will work, nor will they be supported in any way from my side (if 
  2549.  anybody likes to call that support...). 
  2550.  
  2551.  
  2552. ΓòÉΓòÉΓòÉ 12.26. Where to obtain the latest version of Yarn? ΓòÉΓòÉΓòÉ
  2553.  
  2554.  Where to obtain the latest version of Yarn? 
  2555.  
  2556.  Best place to check is http://www.vex.net/yarn/.  For notification about new 
  2557.  versions check the Yarn mailing list. 
  2558.  
  2559.  
  2560. ΓòÉΓòÉΓòÉ 12.27. How to subscribe to the Yarn mailing list? ΓòÉΓòÉΓòÉ
  2561.  
  2562.  How to subscribe to the Yarn mailing list? 
  2563.  
  2564.  To subscribe to the mailing list, mail a message to 
  2565.  listproc@lists.colorado.edu.  The body of the message should be the line 
  2566.  subscribe yarn-list Your Full Name, assuming Your Full Name is your full name. 
  2567.  If it isn't, substitute your own