Eznews 2.000

Selective news download agent
(for MS Windows 95/98/NT)

(c) 1999-2000, Mikhail V. Ivanov
eznews@pair.com


Contents:



1. General info

Eznews is an NNTP client with search capabilities and GUI. The program selectively downloads news articles from news server for offline reading. Given a search criteria, Eznews scans headers of all articles in the newsgroup and requests only those matching the criteria. The program receives found articles from server and displays the search results for offline browsing. The results then can be saved in file to be loaded later. This version of Eznews is a 32-bit executable for MS Windows 95/98/NT.

Eznews' basic features include:

Eznews is written in C/C++. wxWindows class library has been used for programming the user interface.

2. Installation

To install Eznews, choose a directory for the program (or create a new one). Then unpack the archive with a command like:

pkunzip eznews.zip

The files in the package are:

That's it, the installation is completed. (You can as well put eznews.ini file and help file into Windows directory, if you like.)

3. Using Eznews

3.1 How to search

With Eznews running, choosing File->Search, then entering search parameters in the dialog box, and pressing OK button starts search (TCP/IP connection must be up). During search, Eznews supplies progress information in the status line at the bottom of the main Eznews window. In case of error, the program displays an error message (See 5. Program messages section later in this file). On success, the message:

SUCCESS: <nn> articles received

appears in the status line. Information about viewing search results can be found in the Section 3.2 Viewing, saving and loading results later in this file. But, before the search starts, search parameters must be entered in the Search parameters dialog box. This dialog contains the following items:

Search For text field/menu

This field is where search keywords are entered. It can contain up to 10 search keywords or "keyword phrases", or one long search phrase. Keywords are delimited by spaces or tabs, and can be maximum 24 characters long. Longer keywords are truncated. (Distinguishing keywords by the first 24 charaters should be sufficient in most cases.) Note: Eznews does not use wildcards, because it does not use the "whole word" option; for example, searching for room will find not only room, but also broom, groom, mashroom, and roommate, unless these words are explicitely excluded: -broom, -mashroom, etc. (Information about excluding certain keywords can be found later in this section). A "key phrase" is any sequence of characters (except for the double quote character), enclosed in double quotes. "Key phrases" can be used along with sepatare keywords inside the same search pattern, for example: room "green apple" wall.

Search phrase is any sequence of characters (including double quote characters), maximum 255 characters long. Phrase search is indicated by the Phrase setting of Match radio button. Depending on the setting of the Match radio button (All words or Any word), logical AND or logical OR operations will be applied to keywords/"key phrases"

If a keyword/"key phrase" is preceded by a hyphen, for example, -word1, then Eznews excludes such keyword from search by looking only for articles with headers NOT containing this keyword/"key phrase". To search for a keyword/"key phrase" starting with a hyphen (e.g, -word2), the leading hyphen must be doubled: --word2 will search for the keyword -word2. Note: Any word setting is never applied to NOTted keywords/"key phrases"; logical AND is always applied to such keywords, for example: word1 -word2 word3 -word4 (ANY WORD) will find articles with word1 or word3 in the header, but articles with either word2 or word4 will be dropped.

Entering an empty search pattern (containing only blanks) results in requesting all articles in the newsgroup, limited only by the Limit # of articles to find setting. Search can be case-sensitive or case-insensitive, depending on the setting of Case radio button (Match case or Don't match, respectively). Search pattern may contain words in any language; however, only case-sensitive search is guaranteed to work for non-English keywords.

Frequently used search patterns can be conveniently picked up from the Search For menu (on the right of the text field) which displays the contents of the [Patterns] section of eznews.dat file.

Match radio button

There are three setting for this radio button: All words means that article header must contain all indicated keywords to fit the search criteria (logical AND), Any word represents logical OR (article header must contain at least one of the keywords), and Phrase means that the program will look for one exact phrase. Default setting is defined by the value of MATCH_WORD keyword in eznews.dat file.

Examples of search patterns/Match settings:

Alice Hare Hatter Dormouse (All words):

Alice AND Hare AND Hatter AND Dormouse

Alice -Hare Hatter -Dormouse (All words):

Alice AND Hatter AND NOT Hare AND NOT Dormouse i.e., Alice AND Hatter AND NOT (Hare OR Dormouse)

Alice Hare Hatter Dormouse (Any word):

Alice OR Hare OR Hatter OR Dormouse

Alice -Hare Hatter -Dormouse (Any word):

Alice OR Hatter _AND_ NOT Hare _AND_ NOT Dormouse
(Note that Any word setting has no effect on reversed keywords)

Have some wine (Phrase):

Have some wine, the exact phrase

Alice "March Hare" "Mad Hatter" Dormouse (All words):

Alice AND "March Hare" AND "Mad Hatter" AND Dormouse

Alice -"March Hare" "Mad Hatter" -Dormouse (All words):

Alice AND NOT "March Hare" AND "Mad Hatter" AND NOT Dormouse

Case radio button

There are two options: Match case and Don't match. Default setting is defined by the value of MATCH_CASE keyword in eznews.dat file.

News Server text field/menu

News server name. Must be a fully-qualified domain name or a dotted IP-address. May be entered into text field or picked up from the menu of news servers (frequently used news servers can be listed in [Servers] section in eznews.dat file; they are displayed in the menu on the right of the text field). Eznews always uses port 119 of the news server.

Newsgroup text field/menu

Newsgroup name, may be entered into text field or picked up from the menu. Frequently used newsgroups can be listed in [Newsgroups] section in eznews.dat file; they are displayed in the menu on the right of the text field.

Limit # of articles to find checkbox/slider

Restricts the number of matching articles which will be requested from the server. Checking the box enables the slider, unchecking the box disables it. The limit is set with the slider, and must be between 10 and 1,000 articles. The default setting for the slider is defined by the MAX_ARTICLES keyword in eznews.dat file.

Limit # of articles to scan checkbox/slider

Restricts the number of article headers which will be scanned. (May be useful with servers containing thousands of articles in one group). Checking the box enables the slider, unchecking the box disables it. The limit is set with the slider, and must be between 100 and 30,000 headers. The default setting for the slider is defined by the MAX_HEADERS keyword in eznews.dat file.

Search in menu

Defines which NNTP header will be scanned. Possible choices are: Subject, Keywords, Summary, Date, From, Reply-To, Message-ID, and Organization. The default setting is defined by the value of SEARCH_IN keyword in eznews.dat file.

3.2 Viewing, saving and loading results

Viewing search results

After successful search completion, File->Display results shows search results on screen. Main Eznews window displays a listbox with Subject lines of received news articles. The search pattern is displayed in the title bar of the main window which is resized in accordance with the size and dimensions values taken from the program's ini-file. Received articles are sorted by subject, so that articles with the same Subject line are displayed adjacent to each other. The most recent articles are shown first ('recent' refers to the order in which the articles are stored on server, not their posting times).

The article which has its Subject line selected in listbox is the 'current' article. A text window with the current article is displayed on screen, with the article subject in the title bar. Different articles can be browsed by clicking on the Subject lines in listbox; corresponding articles appear in the 'active' article window. Active article window is the one which was opened last; it changes its contents as the user clicks on Subject lines in listbox. Clicking on any of article windows makes that window active. New article windows can be opened (a maximum of 10 windows).

Search results can be saved and closed. Individual articles can be saved in text files and deleted from search results.

Viewing search info

File->Show search info opens a window with the information about current search: search pattern, server name, newsgroup name, time stamp, total number of articles in group, number of matching articles, filename (in the search was loaded from file). If there is no open search, the latest status message is displayed.

Other operations

File->Save results in file saves search results in a file. Standard Save file dialog box is used; the program creates a file in special .ezn format for storing search results. Do not edit .ezn files with text editors because this will make the files unreadable by Eznews.

File->Close current search closes current search results. If the results have not been saved, the program will display a corresponding reminder. After closing search, the program saves current sizes and dimensions of main window and active article window in eznews.ini file.

File->Load results from file loads search results from an .ezn file for offline reading. TCP/IP connection is not required to read downloaded articles.

File->Quit quits Eznews. If there are unsaved search results on screen, the program will display a corresponding reminder before exiting. If there is an open search on screen, the program will close it, saving current sizes and dimensions of main window and active article window in eznews.ini file.

Edit->Copy copies the selected text from the active article window to clipboard.

3.3 Article menu

Article menu is enabled only when search results are loaded and displayed on screen. There are the following choices in the Article menu:

Article->Save current article saves the article which is displayed in the active article window. Article is saved in a text file; standard Save file dialog box is used.

Article->Delete current article deletes the article which is displayed in the active article window. The article is deleted from the search results set, and the previous article is displayed in the active article window. However, if after deleting an article there are more article windows on screen than there are articles in the current search, the active article window is closed, and the previous active article window becomes active again.

Article->Close article window closes active article window. The previous active article window becomes active again. After closing the last article window, no article windows are displayed, and clicking on Subject line in Search Results window opens new article window automatically.

Article->New article window opens one more article window; this new window becomes active article window and displays current article. No more than 10 article windows can be open at the same time.

Article->Save all articles Saves all articles in one text file; standard Save file dialog box is used. All articles are written to one text file, preceded by search information (search string, server name, newsgroup name, time stamp, and number of articles).

Article->Create reply list creates the list of email addresses of posters. Eznews writes the list of addresses to a text file, one address on a line. Reply addresses are taken from Reply-To header; if article has no Reply-To header, then From header is taken. Duplicate addresses are skipped (that is, only one copy is written).

3.4 Help menu

Help->Help displays a text window with help text.

Help->Close help window closes window with help text. Has no effect if help window is not displayed.

Help->About Eznews displays information about the program version and user registration information.

4. Preferences (eznews.dat file)

Eznews user preferences are stored in eznews.dat file in program directory. (This file can also be placed in Windows directory.) The file is divided onto 4 sections: [Settings], [Servers], [Newsgroups], and [Patterns]. Defaults for news server names, newsgroup names, search patterns can be set in this file; also default settings for Match and Case radio buttons, Limit # of articles to find and Limit # of articles to scan checkboxes/sliders, and Search in menu can be set. Also, eznews.dat file is the only place where time limit for search and socket timeout values for the program can be set.

4.1 [Settings]

This section contains 6 keyword/value pairs defining initial settings for various search parameters. The format is: KEYWORD=value, without spaces. There may be comments on the same line after keyword/value pair; comments start with the # sign. Allowed keyword/value pairs are:

MATCH_WORD=value -- possible values are all or any. The corresponding value (match All words or Any word) is automatically selected for the Match radio button in Search parameters dialog.

MATCH_CASE=value -- possible values are match or dont. The corresponding value (Match case or Don't match) is automatically selected for the Case radio button in Search parameters dialog.

MAX_ARTICLES=value -- value is a number between 10 and 1,000 or the word all. This sets the default for the Limit # of articles to find checkbox/slider in Search parameters dialog. If all is chosen, then initially the checkbox will be unchecked, and the slider will be disabled.

MAX_HEADERS=value -- value is a number between 100 and 30,000 or the word all. This sets the default for the Limit # of articles to scan checkbox/slider in Search parameters dialog. If all is chosen, then initially the checkbox will be unchecked, and the slider will be disabled.

SEARCH_IN=value -- default setting for the Search in menu. Possible choices are subj for Subject, keyw for Keywords, summ for Summary, from for From, and date for Date header.

TIME_LIMIT=value -- time limit for search (in minutes), or the word any (no time limit). If the search is not completed after search time has expired, the search will be stopped; any matching articles already received from server will be displayed, as if the search was completed.

TIMEOUTS=value -- socket timeout (in seconds). Sets the amount of time for which the program will wait for a response from server before returning timeout error.

4.2 [Servers]

This section can contain up to 24 names of NNTP servers. They are displayed in news server menu in Search parameters dialog.

4.3 [Newsgroups]

This section can contain up to 24 newsgroup names. They are displayed in newsgroups menu in Search parameters dialog.

4.4 [Patterns]

This section can contain up to 24 predefined search patterns. They are displayed in search patterns menu in Search parameters dialog.

4.5 Sample eznews.dat file

########################
# Sample eznews.dat file
########################

[Settings]
MATCH_WORD=all		# The options are: "all", "any", or "phrase"
MATCH_CASE=dont		# The options are: "match" or "dont"
MAX_ARTICLES=all	# A number between 10-1000 (e.g. 10, 20, 99), or the word "all"
MAX_HEADERS=5000    	# A number between 100-30000 (e.g. 1500, 2000), or the word "all"
SEARCH_IN=subj		# "subj", "keyw", "summ", "from", or "date"

TIME_LIMIT=any		# Time in minutes (e.g. 1, 7, 500), or the word "any"
TIMEOUTS=60		# Socket timeouts (in seconds)
[/Settings]

[Servers]
news.your-isp.com	# a comment
----------------	# separator
news.another-isp.com	
[/Servers]

[Newsgroups]
your.favourite.newsgroup	# a comment
your.favourite.newsgroup2
[/Newsgroups]

[Patterns]
sample search pattern
sample search pattern #2
word1 -word2 word3
"word1 word2" word3
[/Patterns]

########################
# End of eznews.dat file
########################

5. Program messages

Eznews supplies status/progress information in a form of message boxes or as status line information (status line is permanently present at the bottom of the main window). Listed below are all error messages with explanations of their probable reasons. Other program messages are self-explanatory.

"ERROR: Unable to initialize Winsock."

There is a problem with the TCP/IP stack.

"ERROR: Host not found."

Non-existant news server name or IP address was entered, or there is a problem with DNS server, or the system is not connected to the Internet.

"ERROR: Can't connect to server."

The server is down, or connection is broken.

"ERROR: Socket read failure."

Internet connection is broken.

"ERROR: Timeout expired, no response from server."

NNTP server is down or busy, or connection is very slow (try increasing socket timeout).

"ERROR: NNTP-server is not responding."

NNTP server is down or busy, or connection is very slow (try increasing socket timeout).

"ERROR: Not permitted to talk to this server."

You are not authorized to communicate with this news server.

"ERROR: No such group on server."

The indicated newsgroup does not exist on this server.

"ERROR: GROUP command error."

Unknown error.

"ERROR: Low memory."

Not enough memory in the system.

"ERROR requesting article headers."

Internet connetcion might have been lost while the program was receiving article headers.

"ERROR connection failure; <nn> complete articles received."

Internet connetcion might have been lost while the program was receiving articles.

"SEARCH: No articles in this group on server."

Newsgroup does not contain any articles.

"Help file not found."

Help file could not be found in program directory or Windows directory.

6. Limitations

The maximum article size which Eznews can handle is 32,000 bytes. Longer articles are truncated, the message:

"***** Warning: Long article, truncated! *****"

is displayed at the end of article text. Attachments are not supported, they are shown as part of article text.

The program will scan a maximum of 30,000 article headers. It will find and display a maximum of 1,024 articles.

The maximum length of any separate search keyword/"key phrase" is 24 characters, the maximum number of keywords/"key phrases" is 10, the maximum length of search phrase is 255 characters.

No more than 10 article windows can be open simultaneously.

Eznews will connect only to port 119 of NNTP-server. If a news server is using a different port, the program will not be able to communicate with it.

7. Registering the program

Eznews 2.000 for Windows 95/98/NT is shareware. Unregistered version of the program is restricted -- it allows to download only the first 10 of all news articles matching the search criteria. You can use this unregistered version for 30 days. If you wish to continue to use the program after that period, please register. By registering Eznews, you will eliminate the restriction of 'no more than 10 articles'. You will also support shareware. To register, please go to the Secure Order Form for Eznews:

http://www.regsoft.net/purchase.php3?productid=33219

or, for non-secure transactions,

http://www.regsoft.net/purchase_nonsecure.php3?productid=33219

The registration fee for Eznews is $20. After registering, you will receive your personal registration key from RegSoft. With Eznews running, choose Help->I Paid menu item, and enter your registration key and your name. Then quit and restart the program, and you're done.

8. Disclaimer

EZNEWS COMES "AS IS", IN A HOPE THAT IT WILL BE USEFUL, BUT WITH ABSOLUTELY NO WARRANTY OF ANY KIND. IN NO EVENT THE AUTHOR OF THE PROGRAM SHALL BE FOUND LIABLE FOR ANY DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM. YOU ARE USING THE PROGRAM AT YOUR OWN RISK.

COPYRIGHT 1999-2000, MIKHAIL V. IVANOV



Last modified: July 24, 2000
Mikhail V. Ivanov