                         nGate 0.3

               Copyright (c) Dave Hamilton 1995, 1997




                        WARNING

	This is freeware. It is not guaranteed to do anything, or
	to not do anything. Use it at your own risk.

	Future versions, as features are added, may become shareware.
	It is my hope that I can maintain a pre 1.0 version as freeware
	always, and add a post 1.0 version as shareware that will simply
	be more functional. I intend to have two versions. Have fun with
	this one.

	This release is, I hope, the last beta before 1.0.


Acknowledgements

	OS/2, Warp, and IBM's version of SENDMAIL are copyright (c) IBM Corp.
	Msgapi32.dll and Squish are copyright (c) SCI Communications, and are
	trademarks of Lanius Corporation.
	FleetStreet is copyright (c) by Michael Hohner and Harry Herrmannsdorfer.
	MailGate is copyright (c) by Dave Hamilton.

	Special thanks to Fabian Beutin for very heavy beta testing.

1.0 Changes

	0.34 Adds switch (-s) to use the short date posting
	     format for those servers that choke on a GMT date.
		 The default is the GMT date as specified in RFC977.

		 Adds switch (-v) to supply verbose screen output
		 during processing. The more v's you add, the more
		 verbose the output, up to a level of 5. At Level
		 3, you can watch the article text and headers
		 come in.

		 Adds switch (-a) to download a list of all newsgroups
		 from your server. Warning! This could take a very long
		 time. The results are stored in newsrc.all. You can
		 cut and paste from there to your newsrc file to add
		 new groups.

	0.33 We discover that some servers support both of the 
	     date formats we offer, but most will accept one
		 and choke on the other.

		 Added larger input buffers  which should increase
		 download speed at higher connection rates.


	0.32 Fixes date bug that was reintroduced in 0.30

		 Increased logging debugging degree. By increasing the
		 number of 'l's you increase the verbosity of the log.
		 The highest supported now is -lllll (5 l's) which will
		 log the incoming lines of an article. Some users are
		 reporting failure during the processing of articles.

	0.30 Increased line buffer size. It was crashing on headers with
		 very long newsgroups: entries.

		 Made date routine yet smarter.

	0.20 Made config file reader a little more intelligent, was crashing
	     and in some cases linking the wrong area with newsgroup

		 Changed Date on posted articles to conform with more news
		 servers.

		 Increased logging information

	     Now rewrites newsrc file after each group is received instead
		 of after entire retrieval

		 Fixed buffer overrun when very long list of Newsgroups: was
		 read, causing trap 05 crash

	0.10 First Beta Release


1.1	What is nGate?

	nGate (NewsGate) is a simple program that acts as an interface between
	an nntp news server and your Squish message base. It was designed as
	a companion program for MailGate, but kept apart from it so that

		1) a simple version could be distributed as freeware
		2) both MailGate and nGate could remain simple

	nGate retrieves unread news articles from an nntp server that you
	are connected to and tosses them into your Squish message base.
	nGate also scans messages from your Squish message base and
	posts them to an nntp news server.

	Once messages are in your message base, they may be read by
	you or your users. Depending upon how you have your BBS configured,
	your users may post responses or new messages in those areas.

	See section 4.0 for some history of how nGate evovled and how
	the author has it configured on a busy system.

1.2 Requirements

	You must be running OS/2 version 3.0 (Warp) or above.

	At the time  you run nGate, you must be connected to an internet
	provider service (ISP) and have access to a news server that uses the
	NNTP protocol. Finally, you must have a message base that is
	either Squish or *.MSG (Star-dot-Message).

	nGate does not create any temporary files when working; it relies
	on OS/2's virtual memory and handles one news article at a time.
	The more memory your machine has, the better for every program
	you run, but nGate will run safely in any amount of memory that
	OS/2 can run in.

1.3 Files and Directories

	nGate requires two files to run:

		newsrc
		ngate.cfg

	The newsrc file is a list of newsgroups that you are interested
	in or "subscribed to".

	The ngate.cfg file is nGate's configuration file (big surprise)
	containing basic configuration information and a list of
	newsgroups along with the message bases that are associated
	with them.

	To locate these files, nGate searches in the following order:

		1) the environment variable MAILGATE
		2) the current directory

	Please note the order. If you have a line in your config.sys
	such as:

		SET MAILGATE=C:\MG

	nGate will look in c:\mg for its files before it looks in the
	directory you are in when it runs.

	nGate can create a log file that records its actions. If you
	run it with the logging option on, it creates the log file
	called ngate.log in the same directory as its two files.

1.3 Setting Up

	If you are already using MailGate, and have the MAILGATE environment
	variable set, it is suggested you copy nGate.exe to that directory
	and create your configuration files there. If not, create a
	directory (it doesn't have to be at the root of the drive) and
	create your configs in that directory. When you run nGate, change
	to that directory.

	If you don't already have MSGAPI32.DLL on your system, copy the
	one enclosed to somewhere in your LIB path. OS2\DLL is usually
	a good place to put it.

1.4 The newsrc File

	Using a text editor, create a file called "newsrc" (without the
	quotes, no file extension). Create one line for each newsgroup
	you want, ending with a colon. Example:

		comp.os.os2.advocacy:
		comp.os.os2.bugs:

	Each time nGate runs, it will read this file, and it will UPDATE
	this file with the low and high article number pointers from the
	server. After nGate has run, your newsrc file will look something
	like this:

			comp.os.os2.advocacy: 23413-25752
			comp.os.os2.bugs: 7361-7407

	You can add a new group any time you like. It is the colon that
	causes nGate to query the server for new articles, and the existing
	numbers that let nGate and the server to know which articles you
	haven't received yet.

	Note that nGate uses a conventional newsrc file common to many
	Unix and OS/2 applications. If you are installing nGate along with
	or in place of, another news reader, you may be able to use an
	existing file. Most newsreaders we've seen use this format.

2.1 ngate.cfg

	This file is also created with a text editor. The first few lines
	describe environment information. These are followed by one line
	for every news group you subscribe to.

	Here's an example file:

		from			1:229/622.0			; From node
		to				All					; To: field
		origin			"Serenity Base"		; for in and out msgs
		domain 			sbase.com			; for outbound
		newsserver		leebeach.sbase.com	; our news server's address
		
		alt.als  $L:\Max\News\7003
		alt.religion.scientology $L:\Max\News\1999
		comp.os.os2.comm   $L:\Max\News\5006 
		comp.os.os2.games   $L:\Max\News\5007 
		comp.os.os2.mail-news   $L:\Max\News\5008
		comp.os.os2.marketplace   $L:\Max\News\5009
		comp.os.os2.misc   $L:\Max\News\5010 
		comp.os.os2.multimedia   $L:\Max\News\5011
		comp.os.os2.networking   $L:\Max\News\5012
		comp.os.os2.networking.misc   $L:\Max\News\5013
		
	You can probably figure out most of the config file from the
	example above, but we'll go over each of the lines just in
	case.

	Blank lines are ignored.

	A semicolon and everything to the right of it is ignored. You can
	(and are encouraged to) use semicolons to comment the lines in
	your file, or to 'comment-out' lines you with to temporarily
	turn off.

2.2 From

	This is the fido or network address of your own system. It is
	used for incoming articles to fill in the 'from' address, because
	FIDO requires such address to be present. From a working perspective
	it doesn't do anything at all, but it must be entered.

2.3 To

	As above, this field must be filled in, or some message readers
	will lose their minds. 'All' is probably the best choice here,
	given the nature of usenet.

2.4 Origin

	This field serves two purposes. On inbound mail, it takes on a
	role similar to above, and just fills in a field in the message.

	For outbound articles, it is used for the 'Organization:' field
	in articles posted from your system to usenet.

	Unless you can think of anything better, this would normally be
	the name of your BBS.

2.5 Domain

	This is the domain name of your BBS. It is used by nGate to
	generate an email address for the person posting articles
	from your system to usenet. Some message editors such as
	FleetStreet let you use a complete email address in the
	From field. Others insist on first/last names, or aliases.

	When nGate is scanning outbound messages, it looks at the
	'from' field to see if it contains an atpersand (@). If it
	does, the field is used as-is. If not, the contents of the
	field are trimmed of leading and trailing spaces, internal
	spaces are converted to dots, and it is converted to lower
	case. Then, the atpersand is appended, followed by this
	Domain name.

	For example, assume you have this configured:

		domain my-bbs.com

	Here's what nGate will do with the names of these posters:

		Finds					Changes to
		-----					----------
		alvin@my-bbs.com		alvin@my-bbs.com
		Squeaky					squeaky@my-bbs.com
		Harry Armes				harry.armes@my-bbs.com

2.6 newsserver

	This is the tcp/ip address of the news server you will connect
	to. Example:

		rosie.sbase.com

	Note that ISP's can configure their servers so that you can have
	read-only access, read-and-post access, or no access.

	When nGate first connects with the server it will determine access
	from the server. If you don't have posting permission and you
	attempt to post articles to the server, nGate will tell you so.
	If you operate within the access you have, nGate will not report
	anything. If nGate is silent, everything's working.

2.7 newsgroup <-> message base lines

	These lines consist of a newsgroup name, one or more spaces,
	and the path to the message base associated with the newsgroup.

	If the message base is Squish, the path will begin with a
	dollar sign ($).

	If the message base is *.MSG, just provide the path.

	Example:

		comp.os.os2.comm   $L:\Max\News\5006 

3.1 Running nGate

	Ok, let's assume you have your config files set up. Change to
	the directory where nGate and its config files live.

	To IMPORT articles, type:

		ngate -i

	nGate will connect to the server and process all lines you
	have entered in your newsrc file. For each line, it will locate
	your Squish or *.MSG message base, and query the server for any
	new articles. As it runs, it will display the newsgroup it is
	currently working on, the number of new articles to be downloaded,
	and its progress as it downloads them and tosses them into your
	message base. When it has downloaded all the articles, it will
	return to the OS/2 command prompt.

	To send OUTBOUND articles, type:

		ngate -o

	nGate will connect to the server and determine that you do have
	posting access. Next it will process each message base you have
	configured, scanning for newly entered messages. As it finds
	them, it will post them to the newsserver and mark them as
	SENT in your message base. nGate will display a line for each
	newsgroup it is processing, and if there are any articles to post,
	will display a count of posted articles. Depending upon your
	hardware and memory, it may take several seconds or longer to
	scan each message area.

	If you want to process INBOUND and OUTBOUND articles on the
	same pass, type:

		ngate -i -o

	nGate will process INBOUND first, then OUTBOUND.

3.2 Logging

	To turn on logging (recommended), add the -l switch to your
	command. For example, to import articles with logging, type:

		ngate -i -l

	As newer versions of nGate are released, more detail will be
	available to your logs by appending more l's, as in:

		ngate -i -lll

	which would set a logging level of 3. Ngate 0.20 has only one
	logging level, but more detail is planned for subsequent releases.

4.0 The History of nGate

	I read a lot of electronic mail. I get FIDO netmail, FIDO echomail,
	internet email, and usenet.

	No one reader is suited to dealing with all these kinds of messages.
	I have used many of the BBS readers, email mailers, and newsreaders
	available under DOS, Windows, OS/2, and Unix. Although I have my
	favourites, I have found it a real pain to get 10 minutes in a day
	when I can look at mail and then have to load up several different
	packages. Also, these specialized readers are very good at the
	handling of mail and news data, but some have user interfaces that
	are far and away ahead of the rest. I have yet to see a newsreader
	that is as easy to use on a notebook as most of the FIDO message
	readers are.

	My personal favourite OS/2 editor is FleetStreet, though a lot of
	people prefer GoldEd, TimeEd, or the integrated editors within
	BBS packages.

	In early 1995 I wrote MailGate to connect smtp email with Squish
	and *.MSG message bases. The goal with it was to connect BBS's with
	internet email, allowing BBS sysops to easily provide their users
	with internet mail. OS/2's implementation of the unix program
	SENDMAIL is short of some of the extended features available in
	Unix versions, but it works extremely well and is quite reliable.
	So, MailGate was born as a low-cost shareware program to accomplish
	this task, and is now in use on many BBS's around the world.

	A plug: MailGate is available by anonymous ftp via:

		hobbes.nmsu.edu/incoming/mg111d.zip

	or by FREQ to fido:

		1:229/622, magic name MAILGATE

	Usenet was available through fidonet, but in my area it was slow
	and sporadic. I had it available from my nntp server, but it was
	difficult to locate software that would import it into a Squish
	message base. The closest I was able to get was cthuang's excellent
	SOUPER, which uploads and downloads SOUP packets from a news
	server. Early parts of nGate were derived from his work - the
	pre-release version used SOUP as an intermediary step.

	I was able to find a utility to import nntp messages to a squish
	base, but not export them. I found some products that claimed
	to be able to handle news import/export that crashed, messed up
	the message bases, and were otherwise ill-behaved.

	Finally I decided to extend MailGate to include News, but on each
	pass with the design, MailGate would lose its simplicity - one of
	its most endearing features. So I created nGate as a separate
	small program to do the job and to share conventions with Unix
	news utilities. I have decided to start this off as a functioning
	freeware utility to help other sysops avoid the frustration I
	encountered, and to help mesh BBS's with the internet.

	On our system, we are lucky enough to have a full-time internet
	connect, but our setup will work with a part time connect.

	We run Harald Kipp's excellent Changi news server on OS/2. It
	connects to our internet connection's nntp server once an hour
	and exchanges usenet articles. This setup allows us to connect
	newsreaders, including nGate, to our own newsserver and read
	or exchange news much more quickly than we could online.

	We run nGate -i once an hour, and a half hour later, we run
	nGate -o. This keeps our usenet message bases right up to date
	without clogging up our local FIDO net.

	We offer email and usenet to our BBS users for free as a community
	service. 

	I have no idea what the future of BBS's is as more and more
	people are web browsing, but I know it would be a worldwide
	loss if BBS's were to disappear, along with the community
	created and shared by sysops.

	So give nGate a whirl and let me know what you think. I'm at:

		1:229/622
		daveh@sbase.com

	Have fun,

		Dave Hamilton
