home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / bnews96.zip / bnews.doc next >
Text File  |  1997-03-09  |  18KB  |  490 lines
  1.  
  2.                     B I N A R Y   N E W S   G A T H E R E R
  3.                     =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  4.                     Copyright 1996, 1997 by Crown Software
  5.                                    Phil Crown
  6.                                pcrown@airmail.net
  7.                         http://web2.airmail.net/pcrown/
  8.  
  9.  
  10. THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  11. INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  12. FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  13. REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  14. SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  15. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  16. OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  17. WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  18. OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  19. ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  20.  
  21.  
  22. Contents
  23. =-=-=-=-
  24.  
  25.  1.  Overview
  26.  2   System Requirements
  27.  3.  Quick Start
  28.  4.  Configuration File
  29.  5.  Command Line Options
  30.  6.  Tips - Examples
  31.  7.  File Naming Mechanism
  32.  8.  Problems
  33.  9.  Future versions
  34. 10.  Registration - FREEWARE!
  35. 11.  History
  36.  
  37.  
  38. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  39. 1.  Overview
  40.  
  41. Binary News Gatherer is an OS/2 text mode application for downloading an
  42. overview and selected articles from binary news groups via NNTP.
  43.  
  44. See "History" at the end of this document for recent changes.
  45.  
  46.  
  47. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  48. 2.  System Requirements
  49.  
  50. OS/2 Warp v3 or higher.
  51.  
  52. This program uses longfilenames, therefore requires HPFS.
  53.  
  54. OS/2 Warp IAK (so32dll.dll and tcp32dll.dll, and setloc1.dll).
  55.  
  56.  
  57. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  58. 3.  Quick Start
  59.  
  60. Typical usage consists of following steps:
  61.  
  62.   1.  Edit bnews.ini (first time usage only) for your system.
  63.       See bnews.ini.
  64.  
  65.   2.  Download an overview of a group:  bnews /Covernew /G<group> /H<host>
  66.       Overview is saved as <group>.over.txt.
  67.  
  68.   3.  Create a list of articles that you want to retrieve.  You must do
  69.       this with your favorite text editor.  Load the <group>.over.txt
  70.       file in your editor, and cut and paste the articles that you
  71.       want to get, save as <group>.get.txt
  72.  
  73.   4.  Download the articles:  bnews /Cart /G<group> /H<host>
  74.       Articles are saved in <group>.uue.
  75.  
  76.  
  77. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  78. 4.  Configuration File
  79.  
  80. Bnews.ini is the configuration file.  This file is not required, but it
  81. will save some typing at the command line.
  82.  
  83. The default configuration file is bnews.ini, in the same directory as
  84. bnews.exe.  To specify a different configuration file, use the /Imy.ini
  85. switch.
  86.  
  87. The configuration file can contain any valid Command Line Options,
  88. except; /I<my.ini>
  89.  
  90. See:  bnews.ini
  91.  
  92. Parameters on the command line that appear after /imy.ini override
  93. settings in the configuration file.
  94.  
  95.  
  96. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  97. 5.  Command Line Options
  98.  
  99. /A[U|P]       AUTHINFO
  100.  
  101.               /au<username> /ap<password>
  102.  
  103.               Environment variables are searched for in the following
  104.               order (command line overrides environment):
  105.  
  106.                 USER
  107.                 USERID
  108.  
  109.                 PASSWORD
  110.                 PASS
  111.                 PASSIP
  112.  
  113.               These options can also be placed in bnews.ini
  114.               
  115.  
  116. /C<command>   ART, OVERALL, OVERNEW, NEW, NEXT, LIST, HELP
  117.  
  118.     /CART     ARTICLE - Download articles listed in <group>.get.txt.
  119.  
  120.     /COVERALL Download an overview of the entire group.
  121.  
  122.     /COVERNEW Download new overview of the group.
  123.               (new overview only, not the entire article).
  124.  
  125.               bnews.newsrc (in the same directory as bnews.exe)
  126.               contains the high water marks for each group.
  127.  
  128.               The format of bnews.newsrc is:
  129.  
  130.               group: highwater, highwater
  131.  
  132.               highwater = highest article since last overnew command.
  133.               highwater = highest article since last next command.
  134.  
  135.     /CNEW     NEWNEWS - Downloads only new articles since the
  136.               last /cnew session was run.  The file
  137.               bnews.newstime (in the same directory as
  138.               bnews.exe) contains the last access time for
  139.               each group.
  140.  
  141.               The format of bnews.newstime is
  142.  
  143.               group=yymmdd hhmmss
  144.  
  145.               yymmdd hhmms = yearmonthday<space>hourminutesecond
  146.               that the group was last accessed.
  147.  
  148.               Note:  NEWNEWS downloads *all* new articles, not
  149.               just and overview.
  150.  
  151.               NEWNEWS can take quite a long time if the last access
  152.               time is very old.  Try using a later access time.
  153.  
  154.               Some servers have disabled the NEWNEWS command.
  155.  
  156.     /CNEXT    Downloads articles starting with the last highest
  157.               read article number.  This command downloads all
  158.               new articles, not just an overview.
  159.               bnews.newsrc (in the same directory as bnews.exe)
  160.               contains the high water marks for each group.
  161.  
  162.               The format of bnews.newsrc is:
  163.  
  164.               group: highwater, highwater
  165.  
  166.               highwater = highest article since last overnew command.
  167.               highwater = highest article since last next command.
  168.  
  169.     /LIST     Get a list of all newgroups from the server.
  170.               Groups are saved in a file called <host>.list.txt.
  171.               This can take quite a while, some servers have
  172.               more than 20,000 news groups.
  173.  
  174.     /CHELP    Get list of commands from newsserver.
  175.               Saved as <host>.help.txt
  176.  
  177. /G<group>     The full name of the news group to retrieve articles or an
  178.               overview from.
  179.  
  180.               /Galt.binaries.pictures
  181.               /Gmy.favorite.binaries.group
  182.  
  183. /H<hostname>  Your NNTP news server.
  184.  
  185.               /Hnews.your.net
  186.               /Hnews
  187.  
  188. /I<my.ini>    Use my.ini as the configuration file.  Default is bnews.ini
  189.               in the same directory as bnews.exe.
  190.  
  191.               /Imy.ini
  192.               /Ix:\path\my.ini
  193.  
  194. /K<killfile>  Use killfile.  Default is bnews.kill in the same
  195.               directory as bnews.exe.
  196.  
  197.               The format of the killfile is
  198.  
  199.               all {
  200.                   From someone@something.com
  201.                   Subject \$\$\$
  202.                   Header sometrash
  203.               }
  204.               
  205.               group.name {
  206.                   From someoneelse@something.com
  207.                   Subject FREE
  208.                   Header sometrash
  209.               }
  210.  
  211.               Regular expressions can be used in the group name too.
  212.  
  213.               alt.binaries* {
  214.                   ...
  215.               }
  216.  
  217.               Regular expressions are supported.
  218.               All comparisons are case insensitive.
  219.  
  220. /L<logfile>   NOTE : logging is currently disabled, this switch has no
  221.                      effect.
  222.  
  223.               Create a log file for error messages.  Default is
  224.               bnews.log in the same path as bnews.exe.
  225.  
  226.               /L
  227.  
  228.               To specify the logfile name.
  229.  
  230.               /Lmylog.txt
  231.               /Lx:\path\mylog.txt
  232.  
  233. /M<maxpacket> Maximum kilobytes to download this session.  Default is 1024k.
  234.               If an article is incomplete bnews will finish downloading
  235.               the remaining article, then quit.
  236.               This switch only applies when /cNEXT is used.
  237.  
  238. /O            Read from stdin and write to stdout.
  239.  
  240. /P<port>      Port number.  Default is 119, this switch will probably
  241.               never need to be used.
  242.  
  243.               /P119
  244.  
  245. /S            Sort the overview of a group by Subject.  Default is not
  246.               to sort the group overview.  This switch only applies in
  247.               overview mode, /cOVERALL or /cOVERNEW
  248.  
  249. /V            Verify articles exist on server before downloading begins.
  250.               Useful when downloading multi-part messages.
  251.               This switch only applies in articles mode, /cART.
  252.  
  253. /D            Show debug information.
  254.  
  255.  
  256. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  257. 6.  Tips - Examples
  258.  
  259. Options are searched for in the following order:
  260.  
  261.     1.  Environment Variable(s) - NNTPSERVER=news.my.net
  262.     2.  Bnews.ini
  263.     3.  Commandline parameters
  264.  
  265.     Parameters on the command line that come before /I<my.ini> will be
  266.     overridden if they are also defined in <my.ini>
  267.  
  268. Redirect stderr to a file to save a copy of error messages.
  269.  
  270.     bnews <options> -d 2>errlog.txt
  271.     
  272. Examples:
  273.  
  274.   Download an overview of the entire group:
  275.  
  276.     bnews -coverall -galt.binaries.pictures -hnews.your.net
  277.  
  278.   Download only a new overview:
  279.  
  280.     bnews -covernew -galt.binaries.pictures -hnews.your.net
  281.  
  282.   Download 2 megs of new articles:
  283.  
  284.     bnews -cnext -galt.binaries.pictures -hnew.your.net -m2048
  285.  
  286.   Download articles listed in <group>.get.txt:
  287.  
  288.     bnews -cart -galt.binaries.pictures -hnew.your.net
  289.  
  290.   Download a list of all newsgroups:
  291.  
  292.     bnews -clist -hnews.your.net
  293.  
  294.   Get a list of commands the server recognizes:
  295.  
  296.     bnews -chelp -hnews.your.net
  297.  
  298.   Read from stdin and write to stdout
  299.  
  300.     bnews -covernew -o | bnewsfilter | bnews -cart -o > art.uue
  301.     bnews -covernew -o | bnewsfilter | bnews -cart -o | uudeview -io -
  302.  
  303.  
  304. The overview is saved to a text file named <group>.over.txt.  The text
  305. file is named by the group with ".over.txt" appended at the end of the
  306. group's name. See "File Naming Mechanism", below.
  307.  
  308. You must have the appropriate tools (uudecode, pmuue, mime, ...) to
  309. extract the encoded <group>.uue file.
  310.  
  311. When the /V command line option is used (only valid with /cART), bnews
  312. verifies that the all articles exist on the server before downloading
  313. begins.  There are rare occasions when an article(s) listed in the
  314. overview does not exist on the server, so it seems pointless to download
  315. 6/7 to find that 7/7 doesn't exist.  At least, all articles are known to
  316. exist when the download begins, its still possible that article(s) may
  317. be deleted on the server after the download begins, but this is even
  318. rarer in my experience.
  319.  
  320.  
  321. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  322. 7.  File Naming Mechanism
  323.  
  324. *NOTE*:  You must provide the group's FULL NAME on the command line or
  325.          in the configuration file.
  326.  
  327. <host>.list.txt   - List of all newsgroups created when /cLIST is used.
  328.                     Always overwritten, truncated.
  329.  
  330. <group>.over.txt  - Overview of articles, created by bnews.
  331.                     /coverall = Always overwritten, truncated.
  332.                     /covernew = Never overwritten, appended.
  333.                     
  334. <group>.get.txt   - List of articles to get, created by you.
  335.                     Only read.
  336.  
  337. <group>.uue       - Downloaded articles, created by bnews.
  338.                     Never overwritten, appended.
  339.  
  340. To keep filenames shorter, the following hierarchies are abbreviated:
  341.  
  342.           alt.bbs.doors.binaries.           = a.b.d.b.
  343.           alt.binaries.erotica.             = a.b.e.
  344.           alt.binaries.games.               = a.b.g.
  345.           alt.binaries.multimedia.          = a.b.m.
  346.           alt.binaries.nude.                = a.b.n.
  347.           alt.binaries.pictures.erotica.    = a.b.p.e.
  348.           alt.binaries.pictures.            = a.b.p.
  349.           alt.binaries.sounds.              = a.b.s.
  350.           alt.binaries.warez.               = a.b.w.
  351.           alt.binaries.                     = a.b.
  352.           alt.games.                        = a.g.
  353.           comp.binaries.                    = c.b.
  354.           de.alt.binaries.                  = d.a.b.
  355.           fj.binaries.                      = f.b.
  356.           relcom.comp.                      = r.c.
  357.  
  358.  
  359. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  360. 8.  Problems
  361.  
  362. When pasting to <group>.get.txt, care must be used to preserve the tab
  363. (0x09) characters, otherwise the byte count will not be accurate.  This
  364. does not affect the program's operation.  The byte count is only an
  365. estimate the total number of bytes expected, minus the headers.
  366. (Note: byte count is currently disabled).
  367.  
  368. The following only applies when /cART is used:
  369.  
  370.  If the download is interrupted, for any reason, the <group>.get.txt and
  371.  <group>.uue files must be reset to the last complete message manually by
  372.  you with your text editor.  Follow these two steps:
  373.  
  374.    1.  Load <group>.uue in your text editor, look at the end of the file
  375.        to see if the last message is complete or incomplete.  Most
  376.        complete uuencoded articles end with "end" as the last line.
  377.        Delete any incomplete message at the end of the <group>.uue file.
  378.  
  379.    2.  Reset the <group>.get.txt file by deleting the articles at the
  380.        beginning of the file which were completely downloaded, so that
  381.        when Bnews is run again it will begin downloading the article that
  382.        was incomplete.  You may have to look in <group>.uue to see which,
  383.        if any, article was incomplete.
  384.  
  385.                                  ***IMPORTANT***
  386.              If you don't follow these two steps, the encoded data in
  387.                       <group>.uue will not decode properly!
  388.  
  389.  
  390. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  391. 9.  Future versions
  392.  
  393. Fix the above problems.
  394.  
  395. Improve logging.
  396.  
  397. Suggestions welcome.
  398.  
  399.  
  400. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  401. 10.  Registration
  402.  
  403. This program is donated to the Public Domain and is free for
  404. anyone to use.  I would appreciate an email if you are using the program,
  405. just to know that someone is using it.
  406.  
  407. Email to: pcrown@airmail.net (Phil Crown)
  408.  
  409.  
  410. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  411. 11.  History
  412.  
  413. 0.90  Jul 31 96 - First release.
  414.  
  415. 0.91  Aug 17 96 - Touches <group>.get.txt, if it doesn't exist,
  416.                   when downloading an overview.  Helps with
  417.                   cutting/pasting with QEdit, maybe others.
  418.                   Fewer lines from the headers are saved.
  419.                   Shows cps.
  420.                   Shows elapsed runtime.
  421.                   Added cleanover.cmd - REXX script to discard trash
  422.                   from <group>.over.txt.
  423.                   Added /D /I /L /S and /V command line options.
  424.                   More options in .ini file.
  425.  
  426. 0.92  Aug 20 96 - Output to log file is flushed.
  427.                   File Naming Mechanism improved.
  428.                   Article number appended to "423 Bad Article" message.
  429.                   Fixed spelling of Article in Good Article.
  430.  
  431. 0.93  Oct 31 96 - /O switch added - read from stdin and write to stdout.
  432.                   /Cnew - newnews command added.
  433.                   fixed bug in /cnew command that corrupted the date/time
  434.                   in bnews.newstime.
  435.                   fixed bug in socket function when '.' is the first
  436.                   character of a line of an article.
  437.                   Compiled with IBM CSet++ v2.01
  438.                   c2151mt.dll no longer needed
  439.  
  440. 0.94a Jan 15 97 - REXX .cmd files now load the REXXUTIL functions.
  441.                   Bnews.exe is packed with repack.exe, which means it
  442.                   consumes less disk space, loads faster, and will run
  443.                   only under OS/2 Warp v3 or higher.
  444.                   Memory leaks plugged thanks to CSet++'s Debug Memory
  445.                   Management Features (no more memory leaks, which OS/2
  446.                   cleans up when the program terminates anyway).
  447.                   /cHelp HELP command documented.
  448.                   bnews.newstime format documented.
  449.                   Source for bnews cleaned up quite a bit, (almost a total
  450.                   rewrite).
  451.                   Checks for the environment variable NNTPSERVER
  452.                   NEXT command added to get articles by number.
  453.                   LIST command added to get a list of all newsgroups.
  454.                   OVERNEW and OVERALL commands replace OVER command.
  455.                   Kill file added (regular expressions).
  456.                   /M<maxpacket> switch added.
  457.                   oclii.dll no longer required (statically linked).
  458.                   changes to bnews.ini:
  459.                       dostdinstdout is now dostdio
  460.                       killfile added
  461.  
  462. 0.94b           - Fixed bug in the sorting routine (/cLIST and /cOVER*)
  463.                   Not publicly released.
  464.  
  465. 0.94c Jan 23 97 - Fixed SYS3171 when -clist or -chelp is used and no group
  466.                   is specified.
  467.                   Fixed rc = 3 error (Thanks Dave! :-)
  468.  
  469. 0.95  Jan 25 97 - AUTHINFO authentication support added:
  470.                     AUTHINFO USER AUTHINFO PASS
  471.                     AUTHINFO SIMPLE
  472.                   Changes to bnews.ini:
  473.                     added authuser
  474.                     added authpass
  475.                   Fixed /cnext to get first article when the highwater
  476.                   mark is 0 in bnewes.newsrc
  477.                   Made some changes to the killfile handling. There is
  478.                   now no limit on the number of groups or kill expressions.
  479.  
  480. 0.95a Jan 01 97 - Fixed bug in /coverall - would not get an overview if
  481.                   the highwatermark = highest article available on server.
  482.                   Fixed bug that caused /cover* to read the wrong highwater
  483.                   mark under certain conditions.
  484.  
  485. 0.96  Mar 09 97 - Errorlevel  1 returned if no connection is made.
  486.                   Errorlevel 99 returned if Ctrl+C/Break is pressed.
  487.                   Errorlevel  0 otherwise.
  488.                   Authinfo username/password is not converted to lower case.
  489.  
  490.