home *** CD-ROM | disk | FTP | other *** search
Wrap
Text File | 1997-02-12 | 99.5 KB | 3,406 lines
■if false $Id: vsoup.src 1.13 1997/02/12 10:05:41 hardy Exp $ ■endif ■language english ■replace VS VSoup1.2.7 ■replace VSZip ■bf{VSOUP127.ZIP} ■format bold VSoup1.2.7 VSoup1.2.5 VSoup1.2 VSoup ■replace LOGINISP ■hpt{LOGINISP.CMD} ■replace LOGOUTISP ■hpt{LOGOUTISP.CMD} ■replace YARNIOSET ■hpt{YARNIO.SET} ■replace YIO ■hpt{YarnIo} ■replace ConvS ■hpt{ConvSoup} ■replace CONVSOUPEXE ■hpt{CONVSOUP.EXE} ■replace OwnS ■hpt{OwnSoup} ■replace OWNSOUPEXE ■hpt{OWNSOUP.EXE} ■replace QS ■hpt{QSoup} ■replace QSOUPEXE ■hpt{QSOUP.EXE} ■replace ImportProg ■bf{import} ■replace FilterProg ■bf{filter} ■format bold Yarn emxrev emxdoc REXXTRY ■format bold YARNIO VSOUP.EXE YARNIO.CMD MODIFYEMXH.CMD RMHIGH.CMD FILTER.EXE ■format bold VSOUP.INF VSOUP.TXT ■format bold emx emx09a emx09b emx09c SOUP Souper Souper16 USENET UNIX Changi Chanx RNews sendmail inews GNU ■format abbrev e.g. i.e. etc. Str. D. ■format tty ETC EMXOPT HOME MAILER NNTPSERVER PATH POSTER TMP TZ ■format tty NNTP POP3 SMTP ■format tty nntp:// pop3:// smtp:// ■format tty %HOME% %HOME%\NEWSRC %HOME%\NEWSTIME %HOME%\NEWSAUTH %HOME%\KILL NEWSRC NEWSTIME KILL ■format tty %HOME%\YARN\CONFIG %HOME%\YARN\IN\NEWS2 ■format tty NEWSRC NEWSTIME ■format tty %TMP% ■format tty %ETC%\SERVICES %ETC%\TCPOS2.INI ■format tty .\COMMANDS ■format tty .\STSMAIL.MSG .\NEWS.MSG .\MAIL.MSG .\REPLIES .\AREAS CONFIG.SYS ■format tty .\*.MSG .\00*.MSG .\00*.IDX ■format tty RCVNEWS RCVNEWS2 RCVMAIL SEND ■format tty reply-packet sendmail.uml sendmail.cf ■replace ReplyPacket ■sl{reply packet} ■replace VSoupSend ■sy{"VSoup -s"} ■replace LESS ■bf{Less} ■replace GNU ■bf{GNU} ■replace GNUs ■bf{GNU}s ■format syntax -i -h40 -M -h<dir> -m -n -r -s -T<n> -K -N -h -l -c -T-1 -t8 -D ■format syntax -a -c[n] -k<n> -K<file> -l<n> -L<n> -N<file> -S<n> -t<n> -u -x -S0 -S1 -S2 ■format bold Q- A- Q1- Q2- A1- A2- ■if text ■replace LINEBREAK ■break ---------------------- ■break ■endif ■if ipf ■replace LINEBREAK ■break ■endif ■if html ■replace LINEBREAK ■em{} ■endif ■text =============================================================================== VSoup1.2.7 NNTP/POP3/SMTP client 12-Feb-1997 =============================================================================== Copyright (c) 1996-1997 by Hardy Griech ■endtext ■html <hr size=4><center> <h1>VSoup1.2.7 12-Feb-1997</h1><p> <h2>The multithreaded Souper for OS/2</h2><p> <i>Copyright (c) 1996-1997 by Hardy Griech</i><p> </center><hr size=4> ■endhtml ■title VSoup1.2.7 - the multithreaded Souper for OS/2 ■if text ■h= Table of Contents ■toc ■endif ■if html ■html <h1>Table of Contents</h1> ■endhtml ■toc ■endif ■h1 Introduction to VSoup ■ipf :font facename=Helv size=24x14. :hp2. .ce VSoup1.2.7 12-Feb-1997 :p. .ce The multithreaded Souper for OS/2 :ehp2. :p. :font facename=Helv size=16x10. .ce Copyright (c) 1996-1997 by Hardy Griech :font facename=default size=0x0. :p. :p. ■endipf VS is a multithreaded network mail and news client program for OS/2 Warp with TCP/IP (or the Internet Access Kit) installed. It transfers mail and news fetched from a POP3 server and NNTP server respectively to packets in SOUP format. It can also send messages in SOUP reply packets to NNTP / SMTP servers. VS is especially designed to work with Yarn, but it is probable that VS will work with most offline newsreaders which expect SOUP as their input and output. The program requires the emx run-time DLLs. You can get these from e.g. ■typewriter ■url{ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/emxrt.zip} ■endtypewriter The emx09c run-times or newer are required. emxrev should show at least revision 50 for the DLLs. VS may work with an earlier version such as emx09b, but keep in mind that there were many changes in the DLLs concerning multithreading / sockets since emx09a. ■break ■text ------------------------------------------------------------------------------- !!!!! MAKE SURE THAT YOU ARE USING THE CORRECT EMX DLL-VERSIONS !!!!! ------------------------------------------------------------------------------- ■endtext ■ipf :hp2. .ce !!!!! MAKE SURE THAT YOU ARE USING THE CORRECT EMX DLL-VERSIONS !!!!! :ehp2. ■endipf ■html <p><center> <hr size=2,width=20%> <tt><b>MAKE SURE THAT YOU ARE USING THE CORRECT EMX DLL-VERSIONS</tt></b> <hr size=2,width=20%> </center><p> ■endhtml ■h1 Legal Issues This program is heavily based on ideas and modules from Chin Huangs (cthuang@io.org) Souper15. Thanks to him for both Souper and Yarn. ■em{Please note that bug reports and everything else concerning VSoup} ■em{should be directed to Hardy Griech (rgriech@swol.de), not to Chin} ■em{Huang!} ■h- Standard Disclaimer VS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (GPL) as published by the Free Software Foundation; either version 2, or (at your option) any later version. For more details about the GPL see the file ■bf{COPYING} contained in this archive. VS is distributed in the hope that it will be useful, but ■em{without any warranty}; without even the implied warranty of ■em{merchantability} or ■em{fitness for a particular purpose}. See the GNU General Public License for more details. ■h- Warning Some news sites might see VSoup as a news sucking utility and might feel offended by its use. The intention is that VSoup is to be used to receive news for your personal use from a reasonable number of newsgroups. Misuse of this program could conceivably result in a general ban on the use of this or similar programs to the detriment of responsible VSoup users who certainly don't want a general ban of VSoup. ■h1 Features ■index Features of VSoup ■itemize ■item Multithreaded news receiving is supported, anything between 1 and 10 threads can be started (default 4), and in addition there are several possible strategies for fine tuning. Multithreading gives a speed gain of 200%-500% depending on the overall speed of the connection and the number of threads; on the other hand multiple connections have a communication overhead (i.e. the connections must be established, the groups selected). Estimated loss is around 5%... ■item all the packets are exchanged in SOUP format files, i.e. offline readers expecting as input format either SOUP or USENET batch format can be used together with VSoup. ■item VS generates a status message as incoming mail. (this is not in the SOUP standard, but is recognized by Yarn). Normally this message is only generated in case of failure (eg., cannot select newsgroup) or when special events occur (eg., when new newsgroups are added), but the generation can be forced to always occur by means of a command line option. ■item VS will show some statistic information about data transfer. ■item Specification of the required servers is easy by using ■hpt{URL}s on the command line. ■item It is possible to filter articles by header lines before retrieving the body text, see ■hpt{kill file} handling. ■item VS detects too low throughput or stuck connections. ■item VS knows about NNTP authentication. ■item YIO, a script to do VS operation safely (without risk of message loss etc.) is included in the archive. YIO is capable of simultaneously receiving news from up to nine separate NNTP news servers, posting news to NNTP, receiving mail from up to nine POP3 servers and sending mail to SMTP. ■item Other utilities included are ■description ■item OwnS This, with the help of the Yarn ImportProg program, redirects news articles matching a specific pattern into a separate mail folder which will show up when you read your mail with Yarn. For example you can search newsgroups for any mention of your name or any mention of a program you are interested in. ■item QS This appends mail and news messages to the Yarn ReplyPacket file for transmission by VSoup. ■item ConvS This transforms all articles from binary SOUP format to mailbox/USENET format. ■enddescription ■item ■hpt{FAQ} included. ■item source code included. ■item freeware according to GPL (without any warranty for correct function etc.). ■enditemize ■h1 Installation ■label Installation ■label installation ■index Installation This section describes the installation of VS on a step by step basis. Steps (1)-(4) are for preparation to ensure that you have a system configuration which can run VS. The installation instructions assume that you intend to run VS with the help of YIO. If you wish to use VS on its own for example to benefit from multithreaded news reception, but do not need YIO, simply skip the steps (7)-(11) and parts of (6). Anyway you can use YARNIO.CMD as an example. If you experience any problems take a look at the ■hpt{troubleshooting} section. If you are upgrading an older VSoup version, you should have a look at the ■hpt{history} section for hints on important changes. ■break ■enumerate ■item your system must be one of the following: ■itemize ■item OS/2 2.x with TCP/IP (not tested but should work) ■item OS/2 3.0 (Warp) with the 'Internet Access Kit' installed ■item OS/2 3.0 (Warp Connect) with TCP/IP installed ■item anything above ■enditemize ■item get the latest version of the emx runtime library and install it or check your current installation with emxrev. This should show a revision level higher than or equal to '50'. If you are not intending to use YIO, then add an environment setting of ■tt{SET EMXOPT=-h40} to your CONFIG.SYS as noted in the ■hpt{environment settings} section below. ■item check your environment variables according to the ■hpt{environment settings} section below. ■item check your %ETC%\SERVICES file to ensure that it contains the following lines: ■verbatim smtp 25/tcp mail #Simple Mail Transfer smtp 25/udp mail #Simple Mail Transfer pop3 110/tcp #Post Office Protocol - Version 3 pop3 110/udp #Post Office Protocol - Version 3 nntp 119/tcp readnews untp #Network News Transfer Protocol nntp 119/udp readnews untp #Network News Transfer Protocol ■endverbatim Most probably the %ETC%\SERVICES file is located either in ■tt{x:\TCPIP\ETC} or ■tt{x:\MPTN\ETC}. If you need to specify non-standard port numbers, you should do that in the command line. Check the ■hpt{URL} specification. ■item unzip the VSZip archive in a temporary file directory (%TMP% is a good place). ■item copy the following files into a subdirectory of your choice (using a subdirectory contained in the PATH statement is always a good choice): ■itemize ■item VSOUP.EXE, the VS executable ■item YARNIO.CMD, the YIO script ■item YARNIOSET, the YIO configuration file ■description ■item Note: YARNIO.CMD & YARNIOSET must reside in the same subdirectory and must have the same filename, except the extension... ■enddescription ■item If you want YIO dial automatically, then you should also copy LOGINISP and LOGOUTISP as templates for your own connect/disconnect scripts. ■item OWNSOUPEXE and/or QSOUPEXE and/or CONVSOUPEXE should be copied if required. ■item If you want to have help available, then copy also the documentation: either VSOUP.INF or VSOUP.TXT (both have the same content but different format). ■item If you are interested in the source code, move it also to a specific subdirectory. ■enditemize ■item review the ■hpt{Command Line Options} section below and edit the YARNIOSET configuration file according to your specific needs. Also read the comments in YARNIOSET. ■description ■item Note: the setup of YARNIOSET is required only once. In future, updates will be made by amending YARNIO.CMD. ■enddescription ■item If you wish YARNIO.CMD to dial for you, you must also setup the scripts LOGINISP and LOGOUTISP to reflect your needs. Another option is to use your dialer to call your ISP (provider) and start YIO after the connection has been established. The disadvantage of doing it this way is that after completion of YIO the dialer will not hang up immediately. ■description ■item Note: If you have only FAT drives you have to rename LOGOUTISP to something else. Therefor you have to change the ■tt{hangupISP} setting in YARNIOSET too. ■enddescription ■item setup the directory structure for YIO: ■verbatim %HOME%── yarn - subdirectory containing Yarn config file : ├── in - root of YarnIo input subdirectories │ ├── mail - primary subdir for EMail reception │ ├── mail2 - optional #2 subdir for EMail reception │ ├── : : │ ├── mail9 - optional #9 subdir for EMail reception │ │ │ ├── news - primary subdir for news reception │ ├── news2 - optional #2 subdir for news reception │ ├── : : │ └── news9 - optional #9 subdir for news reception ├── out - subdirectory for EMail&news transmission : ■endverbatim In each of the ■tt{NEWS} subdirectories you will need to create an appropriate NEWSRC file as detailed in the ■hpt{Newsrc File} section. The ■tt{..MAIL}, ■tt{..MAIL2} until ■tt{..MAIL9} subdirectories have to be created only. They should be left empty. The number of subdirectories depend on the number of servers you wish to poll. ■item change the following line in the Yarn-config file (%HOME%\YARN\CONFIG): ■verbatim reply-packet=%HOME%\yarn\out\reply.zip ■endverbatim If this is omitted or is incorrect then transmission of replies will not be possible, because Yarn will move its output to a place where VS does not expect it! Of course %HOME% should be replaced by the actual value of HOME. ■item if you have setup LOGINISP and LOGOUTISP, start YIO directly. Otherwise first dial-in to your ISP and then start YIO. ■endenumerate When you first start using VS I recommend that you add the -M option to each call of VS (e.g. in YARNIOSET) to force generation of the status mail. This can be a good debugging aid... ■h2 Environment Settings ■label environment settings ■label environment ■i1 Environment Settings Environment variables are set in your CONFIG.SYS by lines such as: ■verbatim SET ETC=D:\TCPIP\ETC ■endverbatim Also they can be set in a dedicated script, which calls VS. ■description ■item EMXOPT ■i2 EMXOPT This are the settings for the emx runtime DLLs. Recommended setting of this variable should contain -h40 to allow 40 file handles (not required, if you are calling VS through YIO). ■item ETC ■i2 ETC This is needed for accessing the TCP/IP configuration contained in the file %ETC%\TCPOS2.INI. If -i is specified in the command line, ETC is not required. ■item HOME ■i2 HOME your home directory (can also be specified on the command line). If HOME is not defined, it defaults to the current directory. ■item MAILER ■i2 MAILER command for transmitting EMails (the EMail is piped into the stdin of MAILER). If VS should do the job, MAILER must be undefined. ■item NNTPSERVER ■i2 NNTPSERVER hostname of the nntp server (can also be specified in the command line). This variable is, in my opinion, obsolete and remains only to avoid compatibility problems. ■item POSTER ■i2 POSTER command for transmitting news (the article is piped into the stdin of POSTER). If VS should do the job, POSTER must be undefined. ■item TMP ■i2 TMP points to the subdirectory which holds temporary files (VS generates ■sy{soup<xxxx>.tmp} as temporaries, with ■sy{<xxxx>} being a number between 0000 and 9999). If TMP does not exist, the temporaries will be generated in the current subdirectory. ■item TZ ■i2 TZ setting of your time zone (e.g. mine is ■tt{MET-1MES}). Due to a bug in the emx runtime, the setting of this variable is critical for correct functioning of the emx C library revision 50. Check the emx runtime documentation for the syntax of the TZ settings. An incorrect setting of TZ can also cause errors if you appear to be getting mail before it was sent. ■enddescription ■h2 VSoup And YarnIo Troubleshooting ■label troubleshooting some simple checks can be carried out: ■itemize ■item read the ■hpt{FAQ} section. ■item if VS does not run at all, initiate VS with ■tt{VSOUP -?}. This should output the usage information to the screen. If it does not, you have to check your system configuration. Otherwise you should try to call VS in its different modes directly from the command line to check all your command line options. ■item generate the VS status mail with -M and check if it tells you the expected file locations and server names. ■item is the configuration file YARNIOSET correct and in the same directory as YARNIO.CMD? ■item is the subdirectory setup correct for YIO? ■item does the ■tt{pingHost} command work as expected? Issue the program via REXXTRY to check the return values in connected/disconnected case. ■item if you have a setup including LOGINISP and LOGOUTISP you can also check if they work. Run LOGINISP from a command line - login should be performed. Then run LOGOUTISP - logout should be performed. Now also the YIO auto-dial/hangup should work... ■item connect to your ISP and try ■tt{YARNIO -RCVMAIL -SEND -RCVNEWS2}. This will start only the ■tt{YarnIo RCVNEWS} window (hit ctrl-ESC and open it). News reception should be performed as expected, at the end ImportProg to yarn will be initiated (after that 30s pause). You can check all single YIO modes this way. ■item is VS called in each window started by YIO? ■enditemize ■h1 Command Line Options ■label Command Line Options ■label command line option ■i1 Command Line Options This section describes the VS command line options in detail. An example is presented first. ■h- Example ■verbatim VSoup -m -h d:\yourHomedir nntp://your.news.server ■endverbatim This would start VS telling it not to fetch mail (i.e. to collect news only) using a home directory called ■tt{d:\yourHomedir} from a news server named ■tt{your.news.server}. The ■sy{loginid} and ■sy{password} would by default be taken from your TCP/IP configuration. ■ipfminitoc ■h2 Global Options ■label global options ■description ■item -h<dir> ■i2 -h<dir>, set home directory sets the home directory for the VS operation. You can also specify your home directory through the ■hpt{environment} variable HOME. ■item -i ■i2 -i, ignore TCP/IP configuration ignore the settings of the TCP/IP configuration. ■item -m ■i2 -m, do not fetch mail do not fetch mail. ■item -M ■i2 -M, generate status mail generate the VS status mail .\STSMAIL.MSG in any case. Default is to generate the message in case of error only. ■item -n ■i2 -n, do not fetch news do not fetch news. ■item -r ■i2 -r, read only mode read only mode. Only the .\AREAS, .\00*.MSG, .\00*.IDX files are written (e.g. %HOME%\NEWSTIME, %HOME%\NEWSRC are not written). Also the EMails are not deleted from the POP3 server. Main purpose for this option is debugging. ■item -s ■i2 -s, send replies send replies. Do not use this option in combination with -m or -n, if you do it will be ignored. ■item -T<n> ■i2 -T<n>, set throughput limit throughput must be higher than ■sy{<n>}, otherwise transfer will be aborted. Throughput is checked against the limit ■sy{<n>} every 10s after data transfer has begun. If 6 samples show not enough throughput, VS will be aborted. Default is '0 bytes/s', i.e. it will be checked for a stuck connection. Use ■sy{-T-<n>} to check your throughput conditions. Special case is -T-1, which disables throughput check. ■enddescription ■h2 News Receiving Options ■label news receiving options ■description ■item -a ■i2 -a, add new newsgroups add new newsgroups to the ■hpt{%HOME%\NEWSRC} file. If there are any new groups on the server, the generation of the status message will be forced. The new newsgroups will be added in the unsubscribed state. ■item -c[n] ■i2 -c[n], catchup catchup: mark every article as read except for the last ■sy{n} (default is 10). ■item -k<n> ■i2 -k<n>, set maximum packet size set maximum news packet size to n KBytes (default is no limit). ■sy{<n>} indicates the total amount of received messages, not the size of a single message (see -l). ■item -K<file> ■i2 -K<file>, set kill file set the name of the ■hpt{kill file} (see note below regarding ■hpt{-K/-N options}). ■item -l<n> ■i2 -l<n>, set maximum article length limit Do not fetch articles that contain more than ■sy{<n>} lines in the body of the message. This is intended for omitting binaries in text groups. ■item -L<n> ■i2 -L<n>, set minimum article length limit Do not fetch articles that contain less than ■sy{<n>} lines in the body of the message. This is intended for omitting texts in binary groups. ■item -N<file> ■i2 -N<file>, set newsrc file set the name of the ■hpt{NEWSRC} file (see note below regarding ■hpt{-K/-N options}). ■item -S<n> ■i2 -S<n>, set news receiving strategy receiving strategy (■sy{<n>}=0..2). Speed increases (at least it should) in the direction 0 to 2, danger of receiving crossposted articles increases also from 0 to 2. The default of 1 is ok for most cases, but this parameter is an issue of fine tuning! How the strategy parameter operates: ■description ■item -S0 groups are read sequentially, i.e. all threads are fetching articles from only one group. ■item -S1 if one thread goes into waiting state the next group will be accessed - only small modification of the above. ■item -S2 VS tries to keep all threads busy. I.e. each thread accesses one dedicated group, groups are read in parallel (if there are no more groups to access, the waiting threads are used for parallel reading from one group). ■enddescription Recommendation: ■itemize ■item If you have a lot of groups with small amount of articles per fetch and only a little bit cross-posting, -S2 will be the best option for you. If you allow reception of crossposted articles (see option -x), -S2 will be best for you in any case. ■item if you are accessing groups with large articles (i.e. cost of double reception of crossposted articles is high), -S0 will be the best for you. ■enditemize ■item -t<n> ■i2 -t<n>, set number of threads receive the news with ■sy{<n>} threads, i.e. connect to the NNTP server ■sy{<n>} times (limits are 1-10, default 4). ■item -u ■i2 -u, create news summary create news summary. Output can be found in the .\00*.IDX files. Be aware that the summarized articles are marked as read (one way to get out of this, is to call VS with -r). ■item -x ■i2 -x, do not process Xref headers do not process news Xref headers, i.e. allow reception of crossposted articles. ■enddescription ■h3 Note Regarding The -K And -N Options ■label -K/-N options If you are using the -h option then use of either of the options -K or -N is not recommended, because behavior is not very transparent. If the -h option is placed behind the -K / -N options the result will not be as expected - VS (and Souper) will revert to ■tt{KILL} and NEWSRC in the new specified home directory. If -K / -N options are placed behind the -h option and do not contain absolute paths, they will not be located in the home directory specified by -h. This is confusing and will be fixed in a future release. ■em{It is better and cleaner to use -h and setup the special} ■em{KILL/NEWSRC files in that subdirectory!} ■h2 Mail Receiving Option(s) ■label mail receiving options ■description ■item -D ■i2 -D, force delete of mail If specified, VSoup will logout and login after reception of each EMail, thus effectively forcing deletion of the letter on the POP3 server. This is useful, if your connection to the POP3 server is aborted often and your mailbox is full. Normal behaviour is to retrieve EMail without disconnecting/connecting. ■enddescription ■h2 URLs ■label URL ■i1 URLs The addresses of the hosts are given in ■bf{U}nified ■bf{R}esource ■bf{L}ocator (URL) form. These do not fully conform to the standard, so a short explanation follows: ■itemize ■item ■i2 nntp:// ■sy{nntp://[UserId[:Password]@]nntp-host[:port]} defines the address of your NNTP server (i.e. news server). ■sy{UserId} and ■sy{Password} can be given if required for AUTHINFO. ■item ■i2 pop3:// ■sy{pop3://[UserId[:Password]@]pop3-host[:port]} defines the address of your POP3 server. ■sy{UserId} and ■sy{Password} are usually required. ■item ■i2 smtp:// ■sy{smtp://[UserId[:password]@]smtp-gateway[:port]} defines your SMTP gateway. ■sy{UserId} and ■sy{Password} are not required, in fact they are ignored by VS! ■enditemize The URL-feature makes VSoup different to Souper16, which wants to see a %HOME%\NEWSAUTH file for NNTP authorization. Notes: ■enumerate ■item It is not intended to implement other protocols like ■tt{http} or so. ■item If ■sy{port} is not specified, the actual port number is taken from the %ETC%\SERVICES file. This is the recommended way of port number handling. ■endenumerate ■h3 Brief Description Of NNTP/POP3/SMTP Mail can be compared to the postal service, just like a letter. EMail-reception is handled through POP3 server (pop3:// prefix), transmission through SMTP gateways (smtp:// prefix). News messages are more like broadcasting, everybody will 'hear' your message. News messages are transmitted and received via NNTP servers (nntp:// prefix). Perhaps it is a little bit confusing, that you can also deliver news via EMail service (just like the Yarn list). The other way around is not possible... Anyway, please don't mix up news and EMail (your EMail might be news, but in these terms they remain EMails). ■h3 Evaluation Order Of URLs VSoup evaluates URLs in the following order: ■enumerate ■item take all information from the 'Internet Connection for OS/2' notebook settings ■item check the NNTPSERVER ■hpt{environment} settings ■description ■item Note1: NNTPSERVER is a URL without leading nntp:// ■item Note2: there are no environment variables for the SMTP / POP3 setup. ■enddescription ■item command line options ■endenumerate If you specify only e.g. ■sy{nntp://your.news.server} in the command line (without userid/password), the userid and password from the TCP/IP configuration are taken as a standard value. ■h2 News Reception ■label News Reception For news reception you have the following options (which cannot combined): ■itemize ■item either process .\COMMANDS (.\COMMANDS exists), ■item or catch-up the newsgroups (-c option), ■item or create newsgroups summary (-u option), ■item or receive the news in the standard way (no specific option). ■enditemize New newsgroups are added to the %HOME%\NEWSRC file, when news is received in the standard way and the command line option -a is given. ■h1 Diagnostics ■index Diagnostic Codes VS returns with an exit code of ■bf{1}, if any operation failed. Otherwise return code will be ■bf{0}. Failing operations are: ■itemize ■item bad command line options, ■item bad setup (e.g. no ETC set, but 'Internet Connection' settings requested), ■item bad OS (e.g. D*°@!S), ■item user hit ^C or ^BREAK, ■item throughput check failed (e.g. connection broken), ■item could not setup connection (e.g. server not defined, server does not exist, server is down, etc.), ■item there was no .\REPLIES file and you have requested -s, ■item .\REPLIES contains an illegal entry, ■item .\MAIL.MSG or .\NEWS.MSG is malformed, ■item could not deliver news article, e.g. NNTP server did not allow it, ■item could not deliver mail, e.g. POP3 authentication failed, ■item MAILER / POSTER contains illegal value, ■item there is no NEWSRC file, ■enditemize ■h- .\STSMAIL.MSG In case of an error condition the status message .\STSMAIL.MSG will be generated. Under the following additional cases .\STSMAIL.MSG will be generated too: ■itemize ■item VS was called with the -M option (force .\STSMAIL.MSG generation), ■item VS was called with -a and there were new newsgroups on your NNTP server, ■item VS could not select a newsgroup specified in NEWSRC, ■item VS could not select a newsgroup specified in .\COMMANDS, ■item a newsgroup specified in .\COMMANDS was not contained in NEWSRC, ■item there was another command than ■tt{sendme} contained in .\COMMANDS, ■item a specified (■sy{-K<file>}) kill file does not exist. ■item .\REPLIES contained an illegal (i.e. not understood by VS) reply type. Legal reply types are 'b' and 'B', ■item .\REPLIES contained an illegal (i.e. not understood by VS) reply kind. Legal reply kinds are ■sy{"mail"} and ■sy{"news"}. ■enditemize ■h- Future extensions The following failing operations are NOT yet implemented fully: ■itemize ■item there was no EMail in your POP3 mailbox, ■item there were no new news, ■item you have requested -s, but a message file is missing (VS deletes message files immediately after successful delivery. Note that if you need two runs to deliver all your messages e.g. one file will be missing on the second attempt. This is considered ok). ■enditemize It is possible, that diagnostics code will change in the future. Return codes with a cleared bit 0 (like 0,2,4,...) will indicate a non-fatal condition, return codes with a set bit 0 will indicate fatal conditions. ■h1 Utilities ■i1 Utilities This section describes the several utilities contained in VSZip archive in more detail. For most users only the YIO files will be of interest. ■ipfminitoc ■h2 YarnIo ■label YarnIo ■index YarnIo ■i2 YarnIo As stated before YIO - actually consisting of YARNIO.CMD, YARNIOSET and optionally of LOGINISP and LOGOUTISP - is responsible for safe VS I/O operations. The script(s) handle(s) the complete I/O between Yarn and the internet world. Newsgroups are read from up to nine NNTP servers, mail/news packets are transmitted and mail is received again from up to nine POP3 servers - all simultaneously. Actions can be disabled individually (type ■sy{YARNIO ?} for more information). The script should be started directly after the connection has been established. It is also possible to let YIO dial out to establish the connection. To do this you must provide the two scripts LOGINISP and LOGOUTISP (see the ■hpt{installation} section). Most items of the user configuration are in a file called YARNIOSET. It contains the settings for the initialization of the external programs including VSoup, ImportProg ... calls. ■indent ■bf{You WILL need to amend the details in the YARNIO.SET file.} ■endindent Sorry, but the directory structure must be set up manually! You should follow the structure given above in the ■hpt{installation} section. ■h3 YarnIo.Set ■label YARNIO.SET For configuration of YIO, YARNIOSET is required. YARNIOSET must reside in the same directory as YARNIO.CMD and must have the same filename prefix (i.e. YARNIO). YARNIOSET contains the statements which determine how YARNIO.CMD is to call the several commands. To give you an idea what must be configured in YARNIOSET, an example follows. There is a YARNIOSET contained in the archive, which includes more comments. ■verbatim : '@SET NNTPSERVER=' preImportProg = 'ownsoup -q rgriech stuff4me OwnTemp' importProg = 'import.exe -u' soupProg = 'vsoup.exe' soupSend = soupProg '-s nntp://xmt.nntp.server' soupRcvNews = soupProg '-mai' '-h' rcvNewsDir 'nntp://1st.nntp.server' soupRcvNews2 = soupProg '-mai' '-h' rcvNews2Dir 'nntp://2nd.nntp.server' soupRcvMail = soupProg '-n' pingHost = 'slipwait 2 2>&1 > nul' connectISP = 'cmd /c loginisp.cmd NOWAIT' hangupISP = 'cmd /c logoutisp.cmd' unzipProg = 'unzip.exe -oq' zipProg = 'zip -0mq' : ■endverbatim ■h- Remarks ■itemize ■item Instead of ■tt{slipwait} you could also use the command ■tt{'ping x.y.z 1 2>&1 > nul'}. The host ■tt{x.y.z} in ■tt{pingHost} must ■em{not} be contained in the ■tt{%ETC%\HOSTS}, because otherwise ■tt{pingHost} will return unexpected results. ■item Do not remove the option ■tt{'-h' rcvNewsDir} from the ■tt{soupRcvNews} line or the option ■tt{'-h' rcvNews2Dir} from the ■tt{soupRcvNews2} line. ■item If you are not interested in a service (e.g. ■tt{soupRcvNews2}), set the corresponding variable to '' (empty string). ■item If required, you can change the environment settings in YARNIOSET, e.g. the above ■tt{'@SET NNTPSERVER='} clears an existing ■tt{NNTPSERVER} environment variable. ■item To enable news server #3..#9, you have to add ■tt{soupRcvNews3}..■tt{soupRcvNews9} lines into YARNIOSET. Use ■tt{soupRcvNews2} as a template. Of course you have to set up the corresponding ■hpt{Newsrc File}s in the respective subdirectories. For POP3 server #2..#9 you have to set up ■tt{soupRcvMail2}..■tt{soupRcvMail9}. You have to create the corresponding subdirectories manually. For setting up the correct subdirectory structure see also the ■hpt[Installation] section. ■enditemize ■h3 LoginIsp ■label LOGINISP.CMD ■i2 LOGINISP.CMD LOGINISP is an optional script, which allows YIO to dial in to your ISP. The following example script will connect using the internet dialer. If you are a customer of Advantis the script will work for you without any changes - of course you have to insert the correct ■tt{account user passwd} information. ■verbatim /* LoginIsp - rg211096 Login to your ISP. If Option NOWAIT is given, the command will not wait until connection has been established. You have to do the following configuration: - the line '...logoutisp...' must show the effective logoff script - the line '...start...' must show the effective call of the dialer - the line '...ping...' must show a pinger to check connection */ call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs' call SysLoadFuncs TRACE('') option = ARG(1) DO FOREVER '@cmd /c logoutisp.cmd' '@start dialer.exe account user passwd '-m' IF option = 'NOWAIT' THEN LEAVE DO j = 1 TO 20 rc = SysSleep(3) '@ping www.ibm.net 2>&1 > nul' IF rc = 0 THEN EXIT END j END EXIT ■endverbatim ■description ■item Note1: You will find an almost identical LOGINISP in the VSZip archive. ■item Note2: This LOGINISP requires a working LOGOUTISP. ■enddescription ■h3 LogoutIsp ■label LOGOUTISP.CMD ■i2 LOGOUTISP.CMD LOGOUTISP is an optional script, which allows YIO to disconnect from your ISP. The following example script will disconnect using the internet dialer. If you are a customer of Advantis the script will work for you without any changes - other than maybe changing ■tt{dialer} and ■tt{comPort}. This script is a little bit more complicated than LOGINISP, because it will ■enumerate ■item block itself to avoid multiple instances of itself ■item wait until the dialer has been closed ■item force a disconnect of the modem through switching DTR ■endenumerate An almost identical version of the script is contained in the VSZip archive. ■verbatim /* LogoutIsp - rg211096 Logoff from your ISP. The lines dialer/dialerClose,comPort must be configured */ call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs' call SysLoadFuncs dialer = 'c:\tcpip\bin\dialer.exe' dialerClose = dialer '-c' comPort = 'com3' TRACE('') parse source . . compCmdName cmdName = filespec('name',compCmdName) tmpDir = value('tmp',,'os2environment') lockFile = '' IF tmpDir = '' THEN SAY 'please define %TMP% for locking' CmdName ELSE DO lockFile = tmpDir || '\logout.sem' if stream( lockFile,'c','open write') \= 'READY:' then DO SAY CmdName 'already active...' EXIT END END if isActive(dialer) then do SAY 'logging off...' '@start /min' dialerClose rc = SysSleep( 2 ) DO FOREVER IF \isActive(dialer) THEN LEAVE call HangupNow rc = SysSleep( 2 ) END end call HangupNow IF lockFile \= '' THEN DO rc = stream( lockFile,'c','close' ) rc = SysFileDelete( lockFile ) END EXIT HangupNow: '@mode' comPort || ',dtr=on > nul' '@mode' comPort || ',dtr=off > nul' '@mode' comPort || ',dtr=on > nul' RETURN isActive: PROCEDURE prog = ARG(1) '@pstat /c | RXQUEUE' prog = TRANSLATE(prog) found = 0 DO ii = 1 TO queued() PULL line IF POS(prog,TRANSLATE(line)) \= 0 THEN do found = 1 LEAVE END END RETURN found ■endverbatim ■h2 OwnSoup ■label OwnSoup ■label OWNSOUP.EXE ■index OwnSoup ■i2 OwnSoup OwnS, with the help of the Yarn ImportProg program, redirects news articles matching a specific pattern into a mail folder. OwnS can be seen as a notification program to allow easy tracking of news threads you are involved in. ■h- Syntax ■sy{ownsoup [-h] [-b] [-q] <pattern> <groupname> <outputfile>} where ■description ■item ■sy{[-h]} search for ■sy{<pattern>} in header of article only, ■item ■sy{[-b]} search for ■sy{<pattern>} in body of article only. The subject line of the header is considered to be part of header and body. If ■sy{-h} or ■sy{-b} is not specified the default is to search the complete article, ■item ■sy{[-q]} be quiet. Only the number of matches found will be displayed, ■item ■sy{<pattern>} is your search pattern which should be defined according to the ■hpt{regular expression} syntax, ■item ■sy{<groupname>} is a dummy groupname to allow easy filtering. All the matching articles will contain the header line ■sy{X-ownsoup: <groupname>}, ■item ■sy{<outputfile>} is the name of the temporary outputfile (the ■tt{.MSG}-extension will be added by OwnS). ■enddescription The generated ■sy{<outputfile>} will be registered in the .\AREAS file, thus ImportProg will also find the ■sy{<outputfile>}. Note that the ■sy{<outputfile>} will be deleted after the ImportProg so that the actual name you choose is almost unimportant. ■break ■h- Example Setup of OwnSoup ■itemize ■item Assuming a script is used when importing news, directly before ImportProg is called, a line calling OwnS is placed in the script. This would be something like: ■verbatim ownsoup rgriech stuff4me OwnTemp ■endverbatim This example would search for ■sy{"rgriech"} in the header and body sections of each message, writing matching messages to an output file called OwnTemp after marking them with ■verbatim X-ownsoup: stuff4me ■endverbatim The Yarn ImportProg can now easily filter out any such news articles and put them in a mail folder which in this example we will call ■sy{"Personal"}. The search pattern here is ■sy{"rgriech"} but a more complex pattern could be used, for example I could search on a pattern of ■sy{"rgriech|hardy.griech"} which would find either my EMail name or my full name. The '.' wildcard is used in place of a space. The pattern must be in quotes because of the '|' character. Note that because no ■sy{-h} or ■sy{-b} parameter is set, OwnS will search both the header and the body of all messages. If you are using YIO, OwnS would be called by setting the ■sy{preImportProg} line in YARNIOSET. Our example would require the following: ■verbatim preImportProg = 'ownsoup rgriech stuff4me OwnTemp' ■endverbatim ■item To setup a Yarn filter which moves all the messages matching the pattern ■sy{"X-ownsoup: stuff4me"} into the mail folder ■sy{"Personal"} you would do the following: Set up a filter using the Yarn FILTER.EXE program. When run, this shows a box for details, which you would complete as follows: ■verbatim ┌ Mail Rule ───────────────────────────────────────────────────────────────┐ │ │ │ Rule name: MentionsMe │ │ │ │ Search in: ( ) From │ │ ( ) To │ │ ( ) Subject │ │ (*) Header │ │ ( ) Body │ │ ( ) Header and body │ │ │ │ Search for: X-ownsoup: stuff4me │ │ Match case: No │ │ │ │ Action: (*) Move to folder/newsgroup: Personal │ │ ( ) Delete │ │ │ └──────────────────────────────────────────────────────────────────────────┘ ■endverbatim In the ■sy{"Search for"} line above, ■sy{"X-ownsoup: stuff4me"} represents the string you wish to search for, i.e. the string that OwnS puts in when it finds a match on its own search and ■sy{"Personal"} represents the name you wish the new mail folder to have. Note that Yarn's filter now only needs to search the header as it is only looking for the ■sy{"X-ownsoup: stuff4me"} line. After this preparation all incoming news articles will be checked for ■sy{<pattern>} as set in OwnS (in this case ■sy{"rgriech"}), and matching articles will be moved into the ■sy{"Personal"} mail folder. ■item Of course, you can set up more than one filter and if you wish you could put the output in different mail folders. ■enditemize ■h- Restriction Do not set up ■sy{"Personal"} as a newsgroup, because Yarn would skip the filtered articles in this case due to the ■tt{Message-ID:}. ■h- Others ■itemize ■item Articles filtered to ■sy{"Personal"} can be ■bf{replied} and ■bf{followed up}. ■item OwnS scans all files contained in .\AREAS matching the SOUP formats ■sy{"b"} and ■sy{"u"}, i.e. files containing news articles. The generated file has the binary 8-bit clean mail SOUP format (■sy{"bn"}). ■enditemize ■h2 QSoup ■label QSoup ■label QSOUP.EXE ■index QSoup ■i2 QSoup QS (pronounce 'queue soup') appends mail and news messages to the Yarn ReplyPacket file for transmission by VSoup. The messages must contain all required header fields, i.e. QS does not manipulate the content of the message, except that it does '\r' stripping and interpretes ^Z as end of message. ■h- Syntax ■sy{qsoup [-m] [-v] [-i] [-h<dir>] [-l<file>] [<inputfile>]} where ■description ■item ■sy{[-m]} the message input to QS is a mail, default is news, ■item ■sy{[-v]} be verbose, ■item ■sy{[-i]} ignore all options coming behind the ■sy{<-i>}. This is useful, if the calling program appends command line arguments which are not known by QS, ■item ■sy{[-r<file>]} set the name of the ReplyPacket to ■sy{<file>}. Default is to read the name of the ReplyPacket from ■tt{%HOME%\YARN\CONFIG} in the line reply-packet, ■item ■sy{[-l<file>]} use ■sy{<file>} as the lock file for access control to the ReplyPacket. Default is to use ■tt{%YARN%\HISTORY.PAG}, ■item ■sy{[<inputfile>]} is the name of the message file. If omitted, the message will be read from stdin, thus allowing to connect the message provider and QS through a pipe. ■enddescription ■break ■h- Example Setup Of QSoup And Sendmail Using sendmail has several advantages. First, it is a standard tool which is used by many programs for mail delivery (e.g. ■bf{Lynx}). Second, it is very flexible and allows routing of messages depending on their recipients address. The second point is also the weakest point of sendmail: it is hard to configure. This example shows my setup of sendmail. But be warned: I am no sendmail expert and to get this configuration running was a lot of fiddling! ■break My changes to the standard configuration were as follows: ■itemize ■item take the original sendmail.uml from Warp Connect and copy it to ■tt{%ETC%\sendmail.cf}, ■item insert the following two lines in the very beginning of sendmail.cf: ■verbatim Cwworkstationname.domain Dwworkstationname.domain ■endverbatim ■item change the ■tt{OQ} setting so it reflects the subdirectory of your mail queue (which in fact should not be required, because the mails are received by QS immediately), ■item set the ■tt{H?F?From:} field to your EMail address. This will be the default address, if nothing else is specified in the ■tt{From:}-header of the message, ■item in the ■tt{Ruleset 0} at the end of the first section specify the rule ■verbatim R$+<@$+> $#local $:$1 ■endverbatim This will instruct sendmail to direct all mails to the local mailer program. Note that the blanks between the ■tt{>} and the ■tt{$} have to be tabs, ■item change the local mailer program, so that it shows the following: ■verbatim Mlocal, P=d:\b\32\qsoup.exe , F=lmnDFM, S=10, R=0, A=-m -i $u ■endverbatim You have to replace the ■tt{d:\b\32} with the actual QS path. If this path is not correct, sendmail will not deliver the mails! ■enditemize After you have done the setup, you should check it with a dummy mail. Type in the following: ■verbatim sendmail -t --->IBM OS/2 SENDMAIL VERSION 1.3.17 --->reading ...\sendmail.cf 10 to: dummy@x.y.z subject: sendmail/qsoup testing Hello ^Z (this is a ctrl-Z!) --->11/09/96 19:01:03 mail delivered from: YourName ■endverbatim Now you can check the successful delivery with the command ■tt{unzip -Cp -aa reply-packet mail.msg}. The output should be something like that: ■verbatim Received: by ibm.net (IBM OS/2 SENDMAIL VERSION 1.3.17/2.12um) id AA3986; ... Date: Sat, 09 Nov 96 18:59:40 +0100 From: YourName Message-Id: <9611091759.AA3986@ibm.net> To: dummy@x.y.z Subject: sendmail/qsoup testing Hello ■endverbatim Note, that sendmail inserted the missing ■tt{Date:}, ■tt{From:} and ■tt{Message-Id:} header lines (the redundant header ■tt{Received:} too). ■tt{YourName} should show the correct settings. After successful test you should delete the reply packet file. For the actual 'diff' of my sendmail.cf and sendmail.umf see also the ■hpt{FAQ}. ■break ■h- Miscellaneous ■itemize ■item If you are using QS as a sendmail mailer program you can not setup sendmail as the MAILER of VSoup (see ■hpt{environment settings}). First, this would result in a deadlock during transmit action of VSoup, because the invoked sendmail would invoke an instance of QS, which could not proceed, because the Yarn ReplyPacket would be held by the transmitting VSoup. Second, this would not be a meaningful configuration, because the mail would loop endlessly in your computer without being ever transmitted to the external world. If other programs require the MAILER environment variable pointing to sendmail and if sendmail is configured to deliver mails to QS, one should clear MAILER prior to the VSoupSend call. For YIO operation this could be done in YARNIOSET. ■item Because QS has to unzip/zip the ReplyPacket, do not expect fast operation. Anyway appending a message to the ReplyPacket will be much faster than the actual delivery to the network. ■item If QS is copied to an executable with the name sendmail (■tt{SENDMAIL.EXE}) and is invoked as sendmail, QS mode defaults to 'get a mail from stdin'. If QS is copied to an executable with the name inews (■tt{INEWS.EXE}) and is invoked as inews, QS mode defaults to 'get a news article from stdin'. All command line options will be ignored in either case. Keep in mind, that the messages must contain all required header fields. ■item The exact access criteria for ReplyPacket access are as follows: ■enumerate ■item Set ■tt{%YARN%\HISTORY.PAG} to writable without access sharing. This operation must be accomplished successfully. ■tt{%YARN%\REPLIES} is the default lock file which can be overridden by the ■sy{-l<file>} option. ■item The ■tt{REPLIES} file in the ReplyPacket subdirectory must not exist. ■endenumerate Criterion (1) blocks QS, if Yarn is active. Also this works like a semaphor and prevents multiple instances of QS to access the ReplyPacket. Criterion (2) prevents QS from accessing the ReplyPacket if it is unzipped, e.g. during VSoupSend. Don't forget that an open Yarn or an active VSoupSend blocks QS. This means, as long as another application accesses either the ■tt{lockfile} or the Yarn ReplyPacket, QS can not perform the requested operation. ■enditemize ■h2 ConvSoup ■label ConvSoup ■label CONVSOUP.EXE ■index ConvSoup ■i2 ConvSoup ConvS is a small program which converts the VS SOUP output files, which are in binary format (■sy{"bn"} & ■sy{"Bn"}) into UNIX mailbox format (■sy{"mn"}) and USENET batch format (■sy{"un"}) respectively. The output files are written with '\n' as line separator. ConvS must be started in the subdirectory that contains the .\AREAS and the .\*.MSG files. ConvS is useful for people who wants to use VS with offline newsreader which do not recognize VSoup's packet format directly. Although VSoup complies to SOUP, some readers only know about UNIX mailbox and USENET batch format. E.g. Changi's RNews expects USENET batch format on its input. ■h2 ModifyEmxH ■index ModifyEmxH ■i2 ModifyEmxH This script is of interest for people who wants to compile VS on their own. MODIFYEMXH.CMD is required for multiple inclusion of the ■tt{os2.h} and ■tt{os2emx.h} header files. MODIFYEMXH.CMD reads form stdin and copies to stdout. Keep in mind, that multiple inclusion of the above mentioned headers is not standard. It is just for my convenience. ■h2 RmHigh ■index RmHigh ■i2 RmHigh ■label RmHigh ■label RmHigh.Cmd RMHIGH.CMD removes the highlighting from VSOUP.TXT. This is useful for people who wants to read the documentation in text mode and have no pager or editor available which understands the poor (wo)mans highlighting used in VSOUP.TXT. GNUs LESS is an example of a pager that handles the distributed VSOUP.TXT correctly. ■h1 Files ■i1 Files This section describes all the input and output files used and generated by VS in detail. Under normal circumstances %HOME%\NEWSRC and %HOME%\KILL are the only files of interest. For description of YIO files, see the YIO section. ■ipfminitoc ■h2 The Newsrc File ■label Newsrc File ■label %HOME%\NEWSRC ■label NEWSRC ■i2 The Newsrc File %HOME%\NEWSRC contains the list of newsgroups. ■description ■item ':' behind the name indicates subscribed group, ■item '!' indicates an unsubscribed one. ■enddescription The list of newsgroups can be obtained from the news server by using the -a option of VSoup (see ■hpt{FAQ}) or can be prepared with a text editor as follows: List the newsgroups you want to receive, one per line, and end each line with a colon. For example: ■verbatim comp.answers: news.answers: rec.humor.funny: ■endverbatim VSoup will keep track of fetched articles by recording the article numbers in this file. ■break ■h- Syntax For anyone who really wants to know, the syntax of the file is as follows: ■sy{%HOME%\NEWSRC ::= <lines>} ■sy{<lines> ::= <line> <lines> | empty} ■sy{<line> ::= <groupname> <sep> <article-ranges> "\n"} ■sy{<sep> ::= "!" | ":"} ■sy{<article-ranges> ::= <article-ranges> "," <art-range> | <art-range> } ■sy{<art-range> ::= " " <art-num> | " " <art-num> "-" <art-num> } ■sy{<groupname>} is the name of a group, ■sy{<art-num>} is a long integer. ■sy{<article-ranges>} must be sorted in ascending order to be recognized correctly. Blanks are only allowed at the indicated positions. Under normal circumstances, only the ■sy{<sep>} is important to the user for subscribing and unsubscribing groups. ■h2 The Kill File ■label killfile explanation ■label kill file ■i2 The Kill File The kill file specifies criteria used to exclude articles from the VS packet. You can kill articles that have a specific subject, are from a specific poster, or contain a particular string anywhere in the header. %HOME%\KILL is the default kill file. The name and subdirectory of the kill file can be configured by specifying the ■sy{-K<killfile>} ■hpt{command line option}. This allows one single kill file for all news servers you wish to access. An entry in the kill file, also called ■sy{<kill-section>}, has the format: ■sy[<killgroup> "{"]■break ■sy[ <search> <pattern>]■break ■sy{ ...}■break ■sy["}"] ■break where: ■description ■item ■sy{<killgroup>} ■sy{<killgroup>} is a ■hpt{regular expression}. The following ■sy{<search>}/■sy{<pattern>} rules are applied to newsgroups which are matched by the ■sy{<killgroup>} regular expression completely. If ■sy{<killgroup>} is the string ■tt{"all"} the ■sy{<search>}/■sy{<pattern>} rules are applied to all newsgroups. ■item ■sy{<search>} specifies where to search in the header. ■sy{from} searches the ■tt{From:} line, ■sy{subject} searches the ■tt{Subject:} line and so on. The special ■sy{<search>}-pattern ■sy{header} searches all the lines in the header of the article. ■item ■sy{<pattern>} is the string in form of a ■hpt{regular expression} to search for. ■enddescription ■break ■h- Remarks ■itemize ■item News transmission speed decreases if a kill file is used, because an article is fetched then in two steps: ■tt{HEAD <num>}, then ■tt{BODY <num>}. Otherwise an article will be fetched in only one single step: ■tt{ARTICLE <num>}. Scoring from Yarn is also more flexible than this simple killing, and anyway, who knows in advance about the development of a news thread... ■item It is pretty legal to break the kill criteria of several ■sy{<killgroup>}s in several ■sy{<kill-section>}s. ■item If ■sy{<header-name>} is equal to ■tt{"header"}, an article is killed if it matches ■sy{<kill-exp>}. Otherwise an article is killed, if it matches ■sy{<header-name>":.*"<kill-exp>}. ■item The ■sy{<killgroup>} ■tt{"all"} is transformed to the regular expression ■tt{".*"}. ■item Although the ■tt{"."}s in newsgroup names are meta characters this should not do any harm to 'normal' group matching. E.g. the ■sy{<killgroup>} expression ■tt{"comp.os.os2.programmer.misc"} will match only one group. ■item Upper/lower case is ignored for all fields. ■item The kill file works on news only. ■item Check the ■hpt{FAQ} for example kill files. ■enditemize ■break ■h- Syntax The exact syntax of the kill file is as follows: ■sy{%HOME%\KILL ::= {<line> "\n"}*} ■sy{<line> ::= '#' <text> | <kill-section>} ■indent Lines beginning with a '#' indicates a comment, ■sy{<text>} indicates a literal string. ■endindent ■sy{<kill-section> ::= "all" "{" <kill-exps> "}"} ■break ■sy{ | <kill-group> "{" <kill-exps> "}"} ■indent ■sy{"all"} indicates, that the following ■sy{<kill-exps>} is valid for all newsgroups, The ■hpt{regular expression} ■sy{<kill-group>} limits the ■sy{<kill-exps>} to specific newsgroups. ■endindent ■sy[<kill-exps> ::= <header-name> <kill-exp> "\n" {<kill-exps>}] ■indent ■sy{<header-name>} is a literal string. If ■sy{<header-name>} is ■sy{"header"}, the ■sy{<kill-exp>} is valid for the complete header. ■sy{<kill-exp>} is a ■hpt{regular expression}. ■endindent ■break ■description ■item Note: ■sy{"\n"} is the newline character. It is mandatory! ■enddescription ■h3 Regular expression syntax ■label regular expression syntax ■label regular expression The following description has been taken from the ■tt{man regexp} pages (BSD experimental). A regular expression is zero or more branches, separated by ■sy{|}. It matches anything that matches one of the branches. A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc. A piece is an atom possibly followed by ■sy{*}, ■sy{+}, or ■sy{?}. An atom followed by ■sy{*} matches a sequence of 0 or more matches of the atom. An atom followed by ■sy{+} matches a sequence of 1 or more matches of the atom. An atom followed by ■sy{?} matches a match of the atom, or the null string. An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), ■sy{.} (matching any single character), ■sy{^} (matching the null string at the beginning of the input string), ■sy{$} (matching the null string at the end of the input string), a ■sy{\} followed by a single character (matching that character), or a single character with no other significance (matching that character). A range is a sequence of characters enclosed in ■sy{[]}. It normally matches any single character from the sequence. If the sequence begins with ■sy{^}, it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by ■sy{-}, this is shorthand for the full list of ASCII characters between them (e.g. ■sy{[0-9]} matches any decimal digit). To include a literal ■sy{]} in the sequence, make it the first character (following a possible ■sy{^}). To include a literal ■sy{-}, make it the first or last character. ■h2 Other Files ■h- .\COMMANDS ■i2 .\COMMANDS contains lines with the syntax: ■sy{'sendme' <groupname> <article-ranges>}. .\COMMANDS is executed instead of standard fetching of news (see also ■hpt{News Reception}). After successful .\COMMANDS processing, the file will be deleted. ■description ■item Note: articles which have already been read (marked in %HOME%\NEWSRC) will be skipped! ■enddescription ■h- %HOME%\NEWSTIME ■i2 %HOME%\NEWSTIME contains the time of the last NNTP connection. This is for fetching of new newsgroups. If %HOME%\NEWSTIME does not exist, ■bf{all} currently available newsgroups are fetched from the server when VS was called with the -a option. ■h- %TMP%\SOUP*.TMP ■i2 %TMP%\SOUP*.TMP temporary files for received articles. ■sy{*} will be replaced by a number in the range 0-9999. If %TMP% is not defined, %TMP% will be substituted by a '.' ■break ■h- .\00*.MSG ■i2 .\00*.MSG contain the received messages (news articles & EMail). The files are written in the following SOUP formats: ■itemize ■item Binary 8-bit clean news format (■sy{"Bn"}) for incoming news. Lines are delimited by a single '\n', ■item Binary 8-bit clean mail format (■sy{"bn"}) for incoming mails. Lines are delimited by a single '\n'. ■enditemize Note that the format of the message files can be changed to UNIX mailbox and USENET batch using ConvS. ■h- .\00*.IDX ■i2 .\00*.IDX contain the received newsgroup summaries (-u option). The files are written in the SOUP ■sy{"ic"} format. ■h- .\STSMAIL.MSG ■i2 .\STSMAIL.MSG contains the status message generated by VS. This file is written in the SOUP UNIX mailbox format (■sy{"mn"}). Lines are delimited by a single '\n'. ■h- .\AREAS ■i2 .\AREAS contains the table of contents of the received .\00*.MSG / .\00*.IDX files (+ .\STSMAIL.MSG). ■break ■h- .\NEWS.MSG ■i2 .\NEWS.MSG contains the news messages that should be sent to the NNTP server. The following SOUP formats are supported: ■description ■item ■sy{"B"} Binary 8-bit clean news format. The files are read in binary mode but transferred in text mode to the NNTP host, ■item ■sy{"u"} USENET batch format with the area name ■sy{"news"}. The files are read in binary mode, thus '\r\n' pairs are treated as two characters (this is not according to RFC1036 but according to Soup12.Html). ■enddescription ■h- .\MAIL.MSG ■i2 .\MAIL.MSG contains the mail messages that should be sent to the SMTP server. The following SOUP formats are supported: ■description ■item ■sy{"b"} Binary 8-bit clean mail format. The files are read in binary mode but transferred in text mode to the SMTP gateway, ■item ■sy{"u"} USENET batch format with the area name ■sy{"mail"}. The files are read in binary mode, thus '\r\n' pairs are treated as two characters (this is not according to RFC1036 but according to Soup12.Html). ■enddescription ■h- .\REPLIES ■i2 .\REPLIES contains the table of contents of the .\NEWS.MSG / .\MAIL.MSG files to be transmitted. Instead of the above file names other names could be used too. ■h1 Insufficiencies, Bugs & Plans ■h- Insufficiencies ■itemize ■item only very basic killfile handling ■item some cmd options, some files (including the score/kill file) are not compatible with Souper16 ■item space allocated from the heap is not freed (debugging...) ■item behaviour for news receiving/posting, mail receiving/posting is not symmetrical, i.e. there is no multithreading except for news receiving... This will be (perhaps) fixed in a future version ■item only one single version (for OS/2) ■item it is not clear, how to handle '\r\n' pairs in the SOUP format! Soup12.Html says '\r' should be treated as data, but '\r\n' must be avoided. In Soup12.Html '\r' are counted just like normal data bytes. ■enditemize ■h- Bugs ■itemize ■item version of the emx runtime is not checked! ■enditemize ■h- Plans ■itemize ■item remove bugs & insufficiencies ■item more situation dependent return codes ■item perhaps more status information on the screen ■item perhaps the servers IP address will be added to status messages ■enditemize ■h1 Author & Acknowledgements ■h- Author Hardy Griech■break Ernetstr. 10/1■break 77933 Lahr■break Germany EMail: ■url{mailto:rgriech@swol.de (VSoup bug)|rgriech@swol.de} ■break ■h- Acknowledgements ■itemize ■item FSF for GCC (2.7.2.1 used), EMACS (19.31.1 used), ■item Eberhard Mattes for the GCC & EMACS ports to OS/2 and the documentation utility emxdoc, which made the ■tt{.INF}-file possible, ■item Chin Huang for Yarn and Souper, ■item the gamma testers Jim Holcomb, Kay Pyrtek, Phil Crown and Ralph D. Bednarski, ■item Barrie Smith for rework on the documentation, for many suggestions about documentation and a lot of proof reading! ■item Timo Maier for his excessive help finding the Warp4 related bug which led to system crashes (see ■hpt{history}, VSoup1.2.7). ■enditemize ■h1 History ■label history ■h- Version 1.2.7 (120297) ■itemize ■item new features: ■itemize ■item Port specification in ■hpt{URL}s is now supported. ■item .\STSMAIL.MSG now contains a ■tt{Date:} header field. This allows import of the .\STSMAIL.MSG into a pseudo newsgroup, see also the Yarn FilterProg program. ■item The ■tt{Subject:} header line of .\STSMAIL.MSG now contains also the server names which are relevant for the requested operation. ■item The first 40K of temporary files are kept in memory to reduce HDD access (class ■tt{TFileTmp}). ■item National language support (■tt{_nls_tolower()}) introduced for kill expressions, OwnS and hashing. ■item newsgroup names in ■hpt{kill file}s are now regular expressions. ■item new Option ■sy{-L<n>} allows specification of minimum article length (see ■hpt{news receiving options}). ■item new Option ■sy{-D} forces deletion of mails on POP3 server after reception of each mail (see ■hpt{mail receiving options}). ■item ■hpt{RmHigh.Cmd} added, which removes the highlighting in VSOUP.TXT. ■enditemize ■item bug fixes: ■itemize ■item VSoup crashed some Warp4 systems (trap address 0140:7d4c or 0140:7e33). This was fixed through serializing some C library calls (■tt{remove()}, ■tt{rename()}, ■tt{open()}, ■tt{close()}, ■tt{read()}, ■tt{write()}, ■tt{lseek()} and ■tt{ftruncate()}). This problem is most likely device driver related, although nothing specific is known. Thanks to Timo, Stefan, Nate, Rodney, Soenke, Tero and Chua Teng for their help in finding the problem. ■item Bug in emxlibcm <= 52 (don't know, what will happen later on): _fd_init() is not threadsafe, i.e. all callers too (open(), socket(), etc). Perhaps This is the cause of the trap problem above (not verified, rg120297) ■item Incomplete packets are now removed from the SOUP output. Problems appeared with aborted EMail reception (which writes directly into the SOUP output and not to a temporary). ■item -T-1 no longer shows throughput info (see ■hpt{global options}). ■item Signals were not initialized for ■tt{mtGetGroup()} with option -S2. ■item In SOUP .\REPLIES the types ■sy{"bn"}/■sy{"Bn"} now override the message kind ■sy{"mail"}/■sy{"news"}, which is required for type ■sy{"u"}. ■item handling of ■sy{"m"} and ■sy{"u"} SOUP format in .\REPLIES corrected (file positioning was wrong). ■item "ok, we've read enough..." now displays correctly. ■item ■tt{%}-display with -S1 reading strategy now (more) correct. ■item handling of "\r\n" delimited reply files corrected. ■item files are now opened with SH_DENYWR. ■item missing NEWSRC is no longer fatal (useful for initial setup). ■enditemize ■item other internal changes: ■itemize ■item The threads are no longer killed through ■tt{DosKillThread()}. Instead, threads are killing themselves (when they are detecting an abort condition) through ■tt{SIGUSR1}. Sockets are being set to ■tt{O_NONBLOCK} to abort current requests. ■item ■tt{assert(_heapchk() == _HEAPOK)} inserted in some places. ■item ■tt{nhandles()} aborts after checking 150 handles. ■enditemize ■enditemize ■h- Version 1.2.5 (091196) ■itemize ■item Improved Documentation, thanks to Barrie Smith. Documentation now in TXT and INF format available, thanks to emxdoc. ■item SOUP format for ImportProg has been changed: ■itemize ■item .\STSMAIL.MSG has format ■sy{"mn"} (same as before) ■item from POP3 incoming Mails have format ■sy{"bn"}: binary 8-bit clean mail format. This allows from headers in the first column of the mail, i.e. mail handling is now transparent (old was ■sy{"mn"}). ■item news have format ■sy{"Bn"}: binary 8-bit clean news format (old was ■sy{"un"}) ■enditemize To allow the conversion to the old format ConvS has been added. ■item Added OwnS which filters news articles containing a specific pattern into a mail folder. ■item Added QS to allow injection of messages into the SOUP reply packet. ■item YIO changes: ■itemize ■item YIO now only zips the SEND packets (this is to allow re-edit of the replies). Received messages are imported via ■tt{import -u}. If you have an older version of YARNIOSET it must be updated. ■item YIO now supports OwnS. To allow operation of OwnS the entry ■tt{preImportProg} has been added to YARNIOSET. ■item YIO now supports up to nine NNTP servers for news reception and up to nine POP3 servers for EMail reception. ■enditemize ■item -T-1 disables throughput check completely. ■item the ■sy{<kill-section>} for one ■sy{<group>} can now be seperated, e.g. the kill file may now contain several ■sy{"all"} sections. ■item now article ranges are allowed in the ■tt{sendme} of .\COMMANDS. This is a non-standard SOUP extension. ■item bug fixes: ■itemize ■item hostname is now fetched through TCP/IP API, no longer from 'internet settings' ■item it was possible in -S2 that during final catchup of articles the connections were changing group assignment on each fetched article ■item catchup did not work as expected. It sets the %HOME%\NEWSRC, so that in any case 'n' articles were read afterwards. Display now shows groupLo & groupHi ■item ^Z was not recognized correctly for %HOME%\NEWSRC & %HOME%\KILL ■item Now again linked dynamically, ths ■bf{EMX.DLL} and ■bf{EMXLIBCM.DLL} are required ■item Lines containing a single '.' were aborting EMails, even if the '.' is actually doubled for transfer. Don't know if this is an SMTP bug. Appending a blank behind the '.' helped (i.e. ".. " is actually transferred to the SMTP server). For news articles it works without appending the blank. ■item sockets are now opened in text mode, because all the RFCs requires \r\n as a line delimiter. ■enditemize ■enditemize ■h- Version 1.2 (061096) ■itemize ■item first non-beta release ■item more detailed README ■item YIO enhanced (autodial, disabling specific actions, configuration file, ...) ■item some changes/enhancements/extensions in .\STSMAIL.MSG, e.g. command line parameters are contain, important server names too... (useful for debugging) ■item if supported by the NNTP server, the XHDRs are retrieved to determine holes in the article sequence ■item throughput check (-T option) now replaces the old timeout detection. It is now working for all operations. ■item news reading, strategy parameter: ■description ■item -S0 groups are read sequentially, i.e. all threads are fetching articles from only one group ■item -S1 the next group will be accessed, if one thread goes into waiting state - only small modification of the above ■item -S2 it is tried, to keep all threads busy. I.e. each thread accesses one dedicated group, groups are read parallel (if there are no more groups to access, the waiting threads are used for parallel reading from one group) ■enddescription ■item more robust (but slower) reading of %HOME%\KILL and %HOME%\NEWSRC. Because it is slower: clean-up your %HOME%\NEWSRC from time to time, if you are using the -a option ■item bug fixes: ■itemize ■item 'internet connection' settings were never ignored (-i did not work) ■item some very minor bug fixes for handling of broken connections ■item under some circumstances broken SMTP connection did not produce an error condition ■item bug in kill file handling fixed (trailing blanks in line were not accepted). Lines in the kill file can now be outcommented through a '#' as the first non-blank character ■item if getArticle() fails, the according connection will be marked as failed. This lets VSoup die gracefully, if single connections are cancelled (by whom?) ■item signal handling changed: VSoup tries (!) to kill the sub-threads ■item number of file handles provided by emx is now checked ■item now compiled with emx09c. During this 'port' it became obvious, that streams are not appropriate. Thus all file i/o is done directly via handles (class TFile in mts.cc) ■enditemize ■enditemize ■h- Version 1.1ß (010996) ■itemize ■item first public beta ■item if NNTP server knows nothing about DATE command, the internal clock will be taken as a reference (required for -a cmd option only) ■item 'AUTHINFO USER' / 'AUTHINFO PASS' for nntp server implemented (RFC977 extension). Call VSoup simply with the nntp-URL nntp://user:passwd@nntpserver ■item NNTP NEXT will only be done, if there is a bigger gap between the articles ■item bug in socket.cc ((char)0xff == (int)-1 !!!) ■enditemize ■h- Version 1.0ß (010896) ■itemize ■item Program is now named VSoup. I am sorry, but the program again requires the emx DLLs (to my opinion no disadvantage, because most of the people will have them anyway). Also there is no support for Win95 (this was not intended and I am not sorry, but I have no Win95 system - and I am happy about that ;-) ■item Program is now multithreaded for news reading. This gives a speed gain of 200%-500% depending on the overall speed of the connection and the number of threads; on the other hand multiple connections have a communication overhead (i.e. the connections must be established, the groups selected). Estimated loss is around 5%... ■item Return codes are now much more consistent: on failure an EXIT_FAILURE (1) is returned, on success EXIT_SUCCESS (0) ■item On failure a status mail is generated. Most of the console messages are redirected into this status mail. The generation of the mail can be forced thru cmd option -M ■item If file %HOME%\NEWSTIME does not exist, the complete newsgroup list is retrieved from the news server (NNTP LIST) ■item Kill files may have comments ('#' in the first position of a line). This is very beta... ■item Readonly mode is now much more consistent (%HOME%\NEWSTIME is not updated, also the sent articles are not deleted) ■item the default maximum packet size has been changed to unlimited ■item Small bug in %HOME%\NEWSRC handling found (firstUnread was wrong sometimes) ■item automatic timeout for NNTP reception ■enditemize ■h1 FAQ ■label FAQ ■index FAQ This sections contains several frequently questions and the corresponding answers. The questions are: ■ipfminitoc LINEBREAK ■if ipf | html ■h2u Why do I get something like '0000002.msg: Too many open files'? ■endif ■bf{Why do I get something like '0000002.msg: Too many open files'?} and the related question ■bf{I am getting the message '...number of threads cut...'. What does it mean?} VSoup needs a lot of open file handles. The YIO script provides these automatically, but if you are not using this script then it is recommended that you add the following line to your CONFIG.SYS: ■sy{SET EMXOPT=-h40 -c -n}. This allows 40 open file handles which should be enough. LINEBREAK ■if ipf | html ■h2u Why is my news reception getting stuck sometimes? ■endif ■bf{Why is my news reception getting stuck sometimes?} One common reason is that you are using the wrong (too old) version of the emx-runtime-DLLs. Check them with emxrev (should show revisions >= 50) and update them if required. Also you have to avoid a mixture of emx runtime DLLs. LINEBREAK ■if ipf | html ■h2u Are there any specific problems with the different versions of the emx runtimes? ■endif ■bf{Are there any specific problems with the} ■bf{different versions of the emx runtimes?} Unfortunately there are! The revision of the runtime DLLs can be obtained via the command emxrev. Only the revision numbers of ■bf{emx.dll} and ■bf{emxlibcm.dl}l are important for VSoup. ■description ■item revision < 40 No way, because nothing of the TCP/IP stuff is included in the C library. ■item revision < 50, >= 40 This is not recommended, although it should work because VSoup serializes most of the calls to the C library. Nevertheless you should use the newest available revision of the emx09b runtimes, because there were many changes/bugfixes in the TCP/IP part. ■item revision = 50 (also > 50) Check the setting of the environment variable TZ. It should/must contain a value which is acceptable for the emx C library. Otherwise you will get an SYS3175. Revisions > 50 will not crash due to incorrect setting of TZ, anyway they cannot interprete the variable correctly. ■enddescription LINEBREAK ■if ipf | html ■h2u I cannot receive EMail from my POP3 server? ■endif ■bf{I cannot receive EMail from my POP3 server?} ■itemize ■item Check, if your UserId/Password settings are ok ■item Check, that your %ETC%\SERVICES file contains the following lines (see also ■hpt{Installation}): ■verbatim pop3 110/tcp #Post Office Protocol - Version 3 pop3 110/udp #Post Office Protocol - Version 3 ■endverbatim ■item Alternatively you can insert the port number in the command line POP3 ■hpt{URL}. ■enditemize LINEBREAK ■if ipf | html ■h2u I have another EMail program. Therefor I'd like to disable... ■endif ■bf{I have another EMail program.} ■bf{Therefor I'd like to disable the RCVMAIL feature of YarnIO. How do I do this?} You simply have to set ■tt{soupRcvMail} in YARNIOSET to '' (the empty string). LINEBREAK ■if ipf | html ■h2u Give me sample scripts for simple VSoup IO operation. ■endif ■bf{Give me sample scripts for simple VSoup IO operation.} ■description ■item Simple Reception: Because this is a simple approach, NEWSRC & KILL resides in the %HOME% directory. ■itemize ■item change to a directory for IO operation, e.g. ■tt{c:\vsoup}. ■item call VSoup, e.g. ■verbatim vsoup -M nntp://your.news.server pop3://your.pop3.server ■endverbatim The output of the VSoup operation will be in the current directory, i.e. in ■tt{c:\vsoup} in this example. If your 'internet settings' are setup correctly by your dialer, you could omit the ■tt{nntp://} and ■tt{pop3://} specifications in the command line. ■item feed the received news/EMails and the by VSoup generated status mail into the database of your newsreader. For Yarn the ImportProg program will be used (e.g. ■tt{import -u}). ■enditemize If you are using different programs for handling news/EMails, you could do two sequential invocations of VSoup: ■verbatim vsoup -Mm nntp://your.news.server handle_news_import vsoup -Mn pop3://your.pop3.server handle_mail_import ■endverbatim Of course this VSoup instances could also be started parallel through e.g.: ■verbatim start do_news_reception start do_mail_reception ■endverbatim This approach requires a little bit more effort than the sequential one. Check YIO as an example. ■item Simple Transmission: ■itemize ■item change to the directory where your reply packets (e.g. ■tt{reply.zip}) reside. If they are zipped (or packed in another way), you have to unzip/unpack them before VSoup will be called (e.g. ■tt{unzip -oq reply.zip & del reply.zip}). ■item call VSoup, e.g. ■verbatim vsoup -Ms nntp://your.news.server smtp://your.mail.gateway ■endverbatim Failure of transmission should be handled in a proper way, e.g. if .\REPLIES still exists, you have to rezip the not transmitted news/mails (for Yarn IO you have to invoke ■tt{zip -0m reply.zip replies news.msg mail.msg}). If your 'internet settings' are setup correctly by your dialer, you could omit the ■tt{nntp://} and ■tt{smtp://} specifications in the command line. ■item handle the by VSoup generated status mail (e.g. ■tt{import -u} for Yarn IO). ■enditemize If you are using different programs for handling news/mail, you could do two sequential invocations of VSoup or you could start two VSoup parallel (see above). ■enddescription ■h- IO for Yarn with simple scripts We assume, that the IO subdirectory is at ■tt{c:\vsoup}, the news/EMail reader/writer is Yarn and the server URLs are taken from the 'internet settings', a status mail is generated by VSoup, the reply packet is stored by Yarn to ■tt{c:\vsoup\reply.zip}, the NEWSRC & KILL (if one exists) are located in %HOME%: ■description ■item Script for simple reception: ■verbatim c: cd \vsoup vsoup -M import -u ■endverbatim ■item Script for simple transmission: ■verbatim c: cd \vsoup unzip -oq reply del reply.zip vsoup -Ms import -u zip -0m reply replies news.msg mail.msg ■endverbatim ■enddescription LINEBREAK ■if ipf | html ■h2u VSOUP.TXT contains strange characters... ■endif ■bf{VSOUP.TXT contains strange characaters. What's wrong?} VSOUP.TXT uses some kind of poor (wo)mans highlighting. This is obtained through backspacing and overwriting in the ASCII file. Some Viewers or Editors are not capable of handling such files correctly (GNUs LESS can do it). Solution is to remove the highlighting with the small script ■hpt{RmHigh}. LINEBREAK ■if ipf | html ■h2u Give me an example killfile!? ■endif ■bf{Give me an example killfile!?} Here you are: ■verbatim # this is a killfile for VSoup # all { header microsoft from bill.*gates } all { subject make.*money subject \$\$\$ x-newsreader forte agent } comp.os.os2.mail-news { subject ultimail subject netscape subject help: } .*binaries.* { lines [ ][0-9]$ lines [ ][0-9][0-9]$ } comp\..* { lines [0-9][0-9][0-9] } ■endverbatim ■itemize ■item First group would kill messages in ■sy{all} newsgroups which have ■itemize ■item the word ■sy{microsoft} somewhere in the header, ■item or are ■sy{from} a guy with a ■sy{bill}-pattern followed somewhere by a ■sy{gates} pattern, ■enditemize ■item Second group would again kill messages in ■sy{all} newsgroups which have ■itemize ■item ■sy{make} followed by ■sy{money} in the ■sy{subject}, ■item or contain three consecutive ■sy{$$$} in the ■sy{subject}, ■item or contain ■sy{forte agent} in the ■sy{x-newsreader} header line. ■enditemize ■item Third group would kill messages in the ■sy{comp.os.os2.mail-news} group which have ■sy{subject} lines containing the words ■sy{ultimail}, ■sy{netscape} or ■sy{help:}. ■item Forth group would kill articles in newsgroups matching ■tt{.*binaries.*}, if they contain less than 100 lines. ■item Fifth group would kill articles in newsgroups matching ■tt{comp\..*}, if they contain more than 99 lines. Note, that the newsgroup ■tt{comp.os.os2.mail.news} will match both the third and the fifth group! ■enditemize Also check ■hpt{killfile explanation} and the ■hpt{regular expression syntax}. LINEBREAK ■if ipf | html ■h2u How to kill heavily crossposted articles... ■endif ■bf{How to kill heavily crossposted articles (and thus avoid spams very likely)?} Add the following to your kill file: ■verbatim # this kills articles posted to more then 4 groups # all { newsgroups ,.*,.*,.*, } ■endverbatim LINEBREAK ■if ipf | html ■h2u I have 8 connections requested for news receiving... ■endif ■bf{I have 8 connections requested for} ■bf{news receiving (with the -t8 option),} ■bf{but the status message says that} ■bf{only 3 threads were connected successfully.} ■bf{What's wrong?} Nothing! Sometimes it takes very long to establish a connection to the news server which means that VS has finished before all requested threads have been connected. It is also possible that a news server might restrict the number of simultaneous connections by one user. I have not heard of this happening, but who knows! LINEBREAK ■if ipf | html ■h2u I am getting mails, which actually seems to be news articles!? ■endif ■bf{I am getting mails, which actually seems to be news articles!?} You are using OwnS somewhere. If you are using YIO for you I/O operations, check in YARNIOSET the ■tt{preImportProg} line, which should either be empty ('') or should contain arguments to match your needs (not ■em{mine} as the settings reflect in the sample YARNIOSET in the archive). LINEBREAK ■if ipf | html ■h2u How can I setup more than one filter with OwnSoup? ■endif ■bf{I am using YARNIO.SET. How can I setup more than one filter with OwnSoup?} You have to use the command concatenator in the ■tt{preImportProg} line of YARNIOSET, e.g. ■verbatim preImportProg = 'ownsoup -q rgriech stuff4me OwnTemp' preImportProg = preImportProg '&& ownsoup -bq vsoup vsoupstuff VsTemp' ■endverbatim This example will search for ■sy{"rgriech"} in header and body and additionally for ■sy{"vsoup"} in the body section of the news articles. In a second step you have to setup the corresponding mail filter with the Yarn FilterProg program. LINEBREAK ■if ipf | html ■h2u How to move the VSoup status mails into a pseudo newsgroup? ■endif ■bf{How to move the VSoup status mails into a pseudo newsgroup?} ■itemize ■item create a newsgroup with the Yarn utility ■bf{newgroup}, e.g. ■verbatim newgroup VSoupStatus 3 ■endverbatim This will create the group ■bf{VSoupStatus} with three days expiration time. ■item Setup a filter with the Yarn FilterProg. The filter parameters are as follows: ■verbatim ┌ Mail Rule ───────────────────────────────────────────────────────────────┐ │ │ │ Rule name: VSoup Status │ │ │ │ Search in: ( ) From │ │ (*) To │ │ ( ) Subject │ │ ( ) Header │ │ ( ) Body │ │ ( ) Header and body │ │ │ │ Search for: vsoupuser │ │ Match case: No │ │ │ │ Action: (*) Move to folder/newsgroup: VSoupStatus │ │ ( ) Delete │ │ │ └──────────────────────────────────────────────────────────────────────────┘ ■endverbatim ■enditemize From now on the VSoup status mails are put into the newsgroup ■bf{VSoupStatus}. Because the ■tt{Subject:} header also contains the server names, Yarn will automatically sort the status mail/news by action. LINEBREAK ■if ipf | html ■h2u How do I get a listing of all available newsgroups? ■endif ■bf{How do I get a listing of all available newsgroups?} Delete the file NEWSTIME in the directory of your NEWSRC file and call VSoup with the -a option the next time. After that you will get a status mail and the available groups are appended to your NEWSRC file. Note that groups already contained in NEWSRC will not appear in the status mail. LINEBREAK ■if ipf | html ■h2u How to clean up the NEWSRC file? ■endif ■bf{How to clean up the NEWSRC file?} After a while the NEWSRC will contain many unsubscribed groups if VSoup will be called with the -a option. You can get rid off those unsubscribed groups with the following commands: ■verbatim cd 'directory of newsrc' find ":" < newsrc > newsrc.tmp copy newsrc.tmp newsrc del newsrc.tmp ■endverbatim LINEBREAK ■if ipf | html ■h2u How to subscribe to a newsgroup? ■endif ■bf{How to subscribe to a newsgroup?} ■itemize ■item Open the NEWSRC file of the NNTP server you like to add an subscription, ■item add the line ■tt{GroupYouLikeToSubscribe:} to the file. ■enditemize On the next import to Yarn, ImportProg will add the new group to the ■tt{%YARN\ACTIVE} file automatically with defaults specified in the ■tt{%HOME%\YARN\CONFIG} file (■tt{keep} and ■tt{max-keep} entries). It is not required to invoke the Yarn ■bf{newgroup} command. The new group will also appear in the ■tt{newsgroup selection level} of Yarn. Keep in mind that there are several NEWSRC files! Some of them are used by VSoup (especially if you access multiples NNTP servers), others are used by Yarn (i.e. ■tt{%HOME%\YARN\NEWSRC}). LINEBREAK ■if ipf | html ■h2u How to unsubscribe and delete a newsgroup? ■endif ■bf{How to unsubscribe and delete a newsgroup?} ■itemize ■item Delete the newsgroup from the corresponding NEWSRC file, ■item if you have one single NEWSRC file or multiple NEWSRC files and none of them contains any longer the respective group you could delete the newsgroup from the ■tt{%YARN%\NEWS.DAT} database with the Yarn ■bf{rmgroup} command. ■enditemize LINEBREAK ■if ipf | html ■h2u Can I abort VSoup operation safely? ■endif ■bf{Can I abort VSoup operation safely?} Yes, it is safe to abort VS by ^C or ^BREAK. The following takes place: ■description ■item News reception: VS will save the current NEWSRC contents and the articles are stored after the reception of each single article into the corresponding .\00*.MSG file. The .\AREAS file will be left in a proper state for import. ■item EMail reception: The QUIT command will not be sent to the POP3 server, which means that the mailbox will not be emptied which again means that when you next call you will get the already received EMails of the aborted VS session again. ■item News transmission: Double sent articles are detected by the news server and will be rejected by it. This special type of rejection (435 & 437 error number in NNTP reply) will be considered by VS as a non-error condition, thus the articles are handled as having been successfully delivered (which in fact they are). ■item EMail transmission: If the VS session has been aborted during EMail transmission, the whole EMail batch will be resent. ■enddescription LINEBREAK ■if ipf | html ■h2u Can you show me the 'diff' between your sendmail.cf and... ■endif ■bf{Can you show me the 'diff' between your sendmail.cf and the original sendmail.uml?} Of course, but you should be capable of reading 'diffs'. Also be aware, that sendmail requires tabs as delimiter between the ruleset fields. ■verbatim *** sendmail.uml Tue Oct 3 23:09:04 1995 --- d:sendmail.cf Sat Nov 9 19:20:30 1996 *************** *** 1,3 **** --- 1,7 ---- + Cwswol.de + Dwswol.de ######################################################################### # # # Sendmail # *************** *** 102,108 **** # # If macro R is undefined, then mail for internal destinations will be # delivered directly ! DDYour.Domain # Internal, directly connected domains # --- 106,112 ---- # # If macro R is undefined, then mail for internal destinations will be # delivered directly ! DD # Internal, directly connected domains # *************** *** 154,160 **** # SMTP read timeout Or15m # Queue directory - this must be changed if TCP/IP is moved! ! OQC:\MPTN\ETC\mqueue # Always queue for safety Os # Time to live in the queue --- 158,164 ---- # SMTP read timeout Or15m # Queue directory - this must be changed if TCP/IP is moved! ! OQd:\ETC\MQUEUE # Always queue for safety Os # Time to live in the queue *************** *** 173,179 **** # HReceived: $?sfrom $s $.by $j ($v/$Z) id $i; $b H?D?Date: $a ! H?F?From: $q H?M?Message-Id: <$t.$i@$j> H?D?Resent-Date: $a H?F?Resent-From: $q --- 177,183 ---- # HReceived: $?sfrom $s $.by $j ($v/$Z) id $i; $b H?D?Date: $a ! H?F?From: Hardy Griech <rgriech@swol.de> H?M?Message-Id: <$t.$i@$j> H?D?Resent-Date: $a H?F?Resent-From: $q *************** *** 297,302 **** --- 301,307 ---- R$* : $* ; $#error $@ USAGE $: "list:; syntax illegal for... R<@ $+> $#error $@ USAGE $: "user address required" R<$* : $* > $#error $@ USAGE $: "colon illegal in host name part" + R$+<@$+> $#local $:$1 # handle numeric address spec R$* < @ [ $+ ] > $* $#smtp $@ [$2] $: $1 < @ [$2] > $3 numeric... *************** *** 387,393 **** # Msmtp, P=[IPC], F=mDFMuX, S=10, R=0, A=IPC $h ! Mlocal, P=C:\TCPIP\UMAIL\UMAILER.EXE , F=lsm, S=10, R=0, A=-dest C:\TCP... Mprog, P=xxx, A=Required by sendmail but unused --- 392,398 ---- # Msmtp, P=[IPC], F=mDFMuX, S=10, R=0, A=IPC $h ! Mlocal, P=d:\b\32\qsoup.exe , F=lmnDFM, S=10, R=0, A=-m -i $u Mprog, P=xxx, A=Required by sendmail but unused ■endverbatim LINEBREAK ■if ipf | html ■h2u Can I use VSoup together with Changi? ■endif ■bf{Can I use VSoup together with Changi?} Yes, you can use VSoup as the news feeder for Changi. For reply transmission Chanx must still be used. The following setup should work: ■itemize ■item setup VSoup for news reception as described in the ■hpt{installation} section, ■item after VSoup operation ConvS must be called, which converts the .\00*.MSG from binary format to the USENET batch format, ■item then do a ■tt{copy 00*.msg all_in_one}, ■item then call the Changi RNews with ■tt{all_in_one} as input file. ■enditemize The above is not tested! If anybody likes to confirm the procedure, please send me an EMail. Anyway the .\STSMAIL.MSG is not handled by the above procedure. ■description ■item Remark: The question 'why should I use VSoup together with Changi?' is triggered by the fact that several news servers do not allow the NEWNEWS command, which is used by Chanx for multithreaded news reception. ■enddescription LINEBREAK ■if ipf | html ■h2u Can I use VSoup together with another offline newsreader... ■endif ■bf{Can I use VSoup together with another offline newsreader than Yarn/Changi?} VSoup can be used as news/mail client for all offline newsreaders which expect SOUP format as input and generate articles in SOUP format on the output side. Perhaps ConvS has to be used to convert the received messages into the correct data format known by your newsreader. For squish based newsreader there exists a free converter which makes VSoup usable also for people prefering such readers. Reports of successfully combining VSoup with other newsreaders than Yarn and the corresponding recipes are highly welcome and (c|sh)ould be submitted to ■url{mailto:rgriech@swol.de (VSoup Combination)|rgriech@swol.de}. LINEBREAK ■if ipf | html ■h2u Where to obtain more information about SOUP? ■endif ■bf{Where to obtain more information about SOUP?} For more information about SOUP refer to Soup12.Html which can be found on the net, e.g. at ■url{http://www.eden.com/~combee/soup12.html}. LINEBREAK ■if ipf | html ■h2u Where are the internet standards described? ■endif ■bf{Where are the internet standards described?} The internet standards are described in Request For Comment documents (RFC). VSoup uses the NNTP, POP3 and SMTP standards. A good starting point for RFC reading is e.g. ■url{http://ds2.internic.net/ds/rfc-index.html}. RFCs of interest are: ■description ■item ■url{http://ds2.internic.net/rfc/rfc821.txt|RFC821} Simple Mail Transfer Protocol, ■item ■url{http://ds2.internic.net/rfc/rfc822.txt|RFC822} Standard for the format of ARPA Internet text messages, ■item ■url{http://ds2.internic.net/rfc/rfc977.txt|RFC977} Network News Transfer Protocol, ■item ■url{http://ds2.internic.net/rfc/rfc1036.txt|RFC1036} Standard for interchange of USENET messages, ■item ■url{http://ds2.internic.net/rfc/rfc1460.txt|RFC1460} Post Office Protocol - Version 3. ■enddescription LINEBREAK ■if ipf | html ■h2u Where can I obtain the latest version of VSoup? ■endif ■bf{Where to obtain the latest version of VSoup?} I will upload public releases of VSoup to ■tt{ftp.cdrom.com} and ■tt{ftp.leo.org}. The corresponding URLs are: ■itemize ■item ■url{ftp://ftp.leo.org/pub/comp/os/os2/leo/tcpip/news/|ftp://ftp.leo.org/pub/comp/os/os2/leo/tcpip/news/vsoup*.zip} ■item ■url{ftp://ftp.cdrom.com/pub/os2/incoming/|ftp://ftp.cdrom.com/pub/os2/incoming/vsoup*.zip}, later on it can be found at ■url{ftp://ftp.cdrom.com/pub/os2/internet/|ftp://ftp.cdrom.com/pub/os2/internet/vsoup*.zip}. ■enditemize I will not upload to Hobbes (■url{ftp://ftp-os2.nmsu.edu/}), because it seems to be not very reliable. Version notification will take place in the Yarn mailing list. The current update frequency is at about one release per month. But this will stabilize in the very near future (09-Nov-1996). ■bf{Experimental} versions can be downloaded from ■url{http://privat.swol.de/ReinhardGriech/vsoup.zip}. Only the executable is contained in this archive, perhaps with some debugging output. LINEBREAK ■if ipf | html ■h2u Where to obtain the latest version of Yarn? ■endif ■bf{Where to obtain the latest version of Yarn?} Best place to check is ■url{http://www.vex.net/yarn/}. For notification about new versions check the Yarn mailing list. LINEBREAK ■if ipf | html ■h2u How to subscribe to the Yarn mailing list? ■endif ■bf{How to subscribe to the Yarn mailing list?} To subscribe to the mailing list, mail a message to ■url{mailto:listproc@lists.colorado.edu|listproc@lists.colorado.edu}. The body of the message should be the line ■tt{subscribe yarn-list Your Full Name}, assuming ■tt{Your Full Name} is your full name. If it isn't, substitute your own name.