home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ftp.wwiv.com
/
ftp.wwiv.com.zip
/
ftp.wwiv.com
/
pub
/
OFFLINE
/
ZNEWS97D.ZIP
/
ZIPNEWS.DOC
< prev
next >
Wrap
Text File
|
1994-01-09
|
32KB
|
623 lines
ZipNews v0.97d (1/09/94)
(c) Copyright 1993-94 by J.C. Kilday Associates
Developed at the Northern Lights BBS
207-761-4782 v.32bis/VHST
Table of Contents
-----------------
Introduction ..................... 1
Description ...................... 2
Installation Overview ............ 3
Installation Details ............. 4
Operating/Using ZipNews .......... 9
Distribution and Restrictions .... 9
After You Register ZipNews ...... 10
Support ......................... 10
ZipNews v0.97d Page 1
Introduction
------------
ZipNews is a door for use on PCBoard, Wildcat!, Waffle, Spitfire or
BBSs using the DOOR.SYS drop file format. When operating on a Waffle
system it is run as Waffle "external command". It's purpose is fast
delivery of Usenet news articles for offline reading. It greatly
simplifies the process of reading Usenet news by allowing the caller
to download new postings in compressed form for reading offline.
Callers may download their news in plain ASCII format, compressed
using an archiver of their choice. But the primary function of this
door is to provide news "packets" for offline reading through use of
the ZipNews Reader. The ZipNews Reader is a companion program to the
door and usually may be obtained from the same source as this door.
The ZipNews door allows a broad selection of DOS-based archiving
utilities for compressing the news packet and it supports a variety of
file transfer protocols (use of Forsberg's DSZ file transfer protocol
module is recommended). The selection of archiving utilities and
protocols is determined by the system operator. The individual
command line specifications are also established by the system
operator using a configuration text file. A sample configuration file
is included in this package.
First-time users entering the ZipNews Door are prompted to establish
their personal choices of archive utility and file transfer protocol.
User choices are maintained by the system and may be changed by the
user during subsequent calls. First-time users of the door on PCBoard
and other-than-Waffle systems are prompted to choose an Internet ID of
up to 8-characters in length. The door does not allow a caller to
choose an Internet ID that is already in use by another caller to the
same system. On Waffle-only systems, users are registered per the
normal Waffle conventions.
During their first use of the ZipNews door on PCBoard, Wildcat! and
DOOR.SYSsystems, users are prompted to download a list of newsgroups
within their first packet. If the caller is using the DOS-based
ZipNews Reader, newsgroup selections and settings of last article read
pointers are established offline, and the results are uploaded back to
the door. Callers to Waffle-only systems may also use this procedure
(first-time callers are not automatically prompted to do this,
however).
If the caller is NOT using the ZipNews Reader, when accessing the door
on other-than-Waffle systems (such as PCBoard or Wildcat! systems),
there is presently no provision for selecting newsgroups. Perhaps a
friendly sysop could help such callers by modifying their JOIN files
via a standard text editor. The reader is required, when accessing
such systems, for selecting newsgroups (unless the sysop is willing to
lend a hand). On Waffle BBS systems or on systems where Waffle runs
as a door, however, callers without ZipNews readers, may use the
normal Waffle commands to join the desired groups.
ZipNews v0.97d Page 2
When download of a news packet is requested, the user is presented an
active display indicating the newsgroups being scanned, the number of
articles being extracted, and other progress information. At the
conclusion of the scan, the user has the option of NOT accepting the
packet and returning to the Waffle system to alter groups JOINed, etc.
Once the user affirms that an assembled packet should be sent, the
packet is compressed and the transfer of the resulting file is
initiated. If the normal process is interrupted before a successful
conclusion, the "last article read" pointers in the user's JOIN file
are restored to their previous settings. Otherwise, upon a successful
download, these pointers are appropriately updated. (Note: this
operation is dependent upon the archiver and protocol modules
returning appropriate "success/fail" DOS ERRORLEVELs. Utilities such
as PKZIP and DSZ are known to work correctly in this regard.)
ZipNews is SHARE-compatible and can support multi-node operations from
a single configuration file (ZN.CFG). It can handle non-standard comm
port specifications and speeds to 57,600 bps. FOSSIL communications
are not used. ZipNews disables FOSSIL supported comm when run. On
Waffle systems, FOSSIL support is "reset" per the normal way when
returning to Waffle. On other systems, ZipNews leaves the
communications set up such that the FOSSIL can resume upon when the
door exits back to the main board.
ZipNews is being distributed as a fully functional news delivery door.
In its unregistered form, ZipNews displays on-screen, and in the files
produced, notices informing system operators and users that it is an
unregistered, evaluation copy. The executable is self-registering in
that when a valid registration number is input these notices are
removed and, thereafter, the registrant's name is displayed. The
registered version of ZipNews also extracts/delivers the caller's
private e-mail if the caller chooses.
The complete ZipNews v0.97d package includes the following files:
ZIPNEWS.DOC - this file
ZN.EXE - executable module
ZN.CFG - sample ZipNews configuration file
ZIPNEWS - the Waffle external command file for ZipNews
ZNORDER.FRM - order form for registering ZipNews
READ.ME - quick review and features summary
WHATS.NEW - major enhancements and bug fixes in this
release.
ZIPNEWS.PCB - sample ZipNews door batch file for use on
PCBoard (and other) BBS systems
NLBBS.GPS - Sample newsgroups file
Description
-----------
ZipNews is designed for operation on MS-DOS 3.O and later systems.
Operation with earlier DOS versions is not supported.
ZipNews is being released for widespread use while in its final BETA
test stages. Operation of the door is very sound, but there are some
original requirements of the package that are not yet implemented.
Until such requirements have been completed, it is planned that the
ZipNews door will remain a product in BETA testing.
Zipnews has been tested primarily in a DOS 5.0/DESQview environment,
on a system running 4 nodes (PCBoard as the primary BBS and Waffle
1.65 as a Door). It has not been tested with other versions of
Waffle.
ZipNews v0.97d Page 3
Installation Overview
---------------------
This section attempts to suumarize the major steps in setting up. The
next section covers installation in greater detail.
ZipNews requires the installation of at least portions of the Waffle
BBS package if you are not running the full Waffle BBS. The required
parts of Waffle are basically the files necessary to implement the
uucp transport mechanism and to establish the structure and control of
newsgroups and mailboxes. This document is not intended to serve as a
substitute for Waffle documentation or as a guide in its installation.
Suffice it to say, that the Waffle docs and configuration files
pertaining to the following executables are needed for the basic
(non-Waffle BBS) setup:
UUCICO.EXE
COMPRESS.EXE
UUX.EXE
UUXQT.EXE
BATCH.EXE
RMAIL.EXE
RNEWS.EXE
The first two files listed above are actually public domain programs,
but the remainder and the needed docs are copyrighted by Darkside
International, and require a registration fee of $30 payable to Thomas
E. Dell. The complete Waffle package can be obtained at most large
BBSs or via anonymous FTP from major Internet archive sites under the
name WAF165.ZIP (the name as of this writing).
Once Waffle (or Waffle uucp operation) is installed:
1. Place ZN.EXE and the sample ZN.CFG into a directory in your PATH
(\waffle\bin will do quite nicely).
2. Customize ZN.CFG as needed using an ASCII text editor. This also
involves naming and specifying command lines for archive utilities
and file tranfer protocols you wish to make available to callers.
3. a. For ZipNews as a Waffle external command:
Make (or modify) the ZIPNEWS external command file and place
it in your \waffle\external directory. See the sample external
command file included in this package -- filename is ZIPNEWS.
b. For ZipNews as a door under PCBoard, Wildcat! or other BBSs:
Using the file ZIPNEWS.PCB as a guide, set up the necessary
door batch file for your system (possibly multiple files if
running multi-node).
4. Provide for setting the required DOS ENVIRONMENT variables. A very
important one is the DSZPORT variable.
5. If running a multi-node system, provide for uniquely named work
directories (one for each node) for temporary file storage. This
will require an environment variable also.
ZipNews v0.97d Page 4
6. If running a multi-node system, set the read-only (write protect)
file attribute bit on ZN.EXE (avoids SHARE violations while
program loading during normal multi-node operations).
Installation Details
--------------------
ZipNews (ZN.EXE) should be placed in a directory contained in your DOS
PATH (e.g., \waffle\bin). Your ZipNews configuration file (ZN.CFG)
should be placed in the same directory. WARNING: ZN.EXE locates the
directory in which it resides, no matter how started, and you MUST(!)
have ZN.CFG located in that same directory for proper operation.
If you are running ZipNews as a Waffle external command, the external
command file should be quite similar to that provided as part of this
package. It should be placed in your \waffle\external directory (on
Waffle v1.65 systems). An example of this one-line file appears
below:
zipnews /local /reset /command="d:\waffle\bin\zn %A"
Note that the only command line parm required on startup is the Waffle
account (caller's ID).
If you are running ZipNews as a door under PCBoard or Wildcat!: the
sample door batch file contained in ZIPNEWS.PCB should be used as a
guide in setting up the necessary door batch file(s) on your system.
The sample file shows how a multi-node system might be set up using a
single door batch file (through use of PCBoard's door environment
variables).
Also it should be noted that two methods of providing user access to
ZipNews on PCBoard systems are documented in ZIPNEWS.PCB. The first
is now the preferred method and the one that MUST be employed if
setting up for use with Wildcat! systems. We'll get into the details
of the two methods shortly.
Here's the syntax for invoking the ZipNews door:
zn @UserListName | Username [local] [pcb|wc|sf|ds]
Where:
zn is the executable name
@UserListName indicates a list is specified, and UserListName
is the full pathname to the list of ZipNews door users (created
and maintained by the door). This option, rather than the
alternative specification of UserName is the recommended method
for invoking the door from PCBoard or Wildcat!.
UserName is the Internet ID, or the Waffle "username" of the
caller (for whom a directory of that name is maintained on the
system containing personal configuration data). This option is
the required method for invoking from Waffle as an external
command.
(You must specify either the user list path prefixed by the @
symbol OR the username when invoking the door.)
ZipNews v0.97d Page 5
"local" may be specifed for sysop testing of the setup without
having to go online to test. (Note: new user registration
processes are not functioning well in local mode in v0.97d BETA;
but all other online door operations are pretty well emulated in
the local mode.)
If the door is NOT being run as an external command under
Waffle, "pcb", "wc", "sf", or "ds" must be specified as the 2nd
or 3rd parm (depending on whether the "local" parm was given).
Use pcb for PCBoard; wc for Wildcat!; sf for Spitfire; ds for BBSs
that are DOOR.SYS-compatible.
Examples:
zn @c:\user\zn_users.lst local pcb
Above, the system operator invokes the door locally to simulate
operation as a PCBoard door, and points it to the list of valid
users of the door located in c:\user . (By the way, that list
of users will be searched for a match against the caller name
extracted from PCBoard's drop file, PCBOARD.SYS. If a match is
found, the caller's Internet-style login ID is extracted from the
file. If a match is not found, the caller will be handled as a
first-time ZipNews user.)
zn @c:\user\zn_users.lst wc
Similar to the first example, but here the door is invoked in
online mode (comes up as a communications application) and
looks for the Wildcat! door drop file, USERINFO.DAT. It will
extract the caller name from line 1 of this file.
zn johndoe pcb
This is an older form of invoking the door that was the only one
available for operations with PCBoard before v0.97c BETA. It is
still available for any PCBoard operators that might prefer it,
OR be unwilling to change their current setup. The method
requires the caller to invoke the door by following the PCBoard
door command with his/her Internet-style login ID, thusly:
zipnews johndoe OR door 1 johndoe
More will be said about this method next, but it is no longer the
recommended method for invoking ZipNews.
With basic understanding of the door's command syntax out of the way
let's return to the door batch file (the sample being ZIPNEWS.PCB) and
discuss how the door is accessed. The line invoking the door uses the
preferred method of accessing the door from PCBoard (and the only
method for Wildcat!) in that the first parm points a file that is a
list of users. This file in d:\users\zn_users.lst per the example is
completely maintained by the door. If no such list exists when the
door is first installed, it is created when the door handles its first
caller. When a caller uses the ZipNews door for the first time, the
door adds the caller's BBS name and requested Internet-style login ID
to the list.
ZipNews v0.97d Page 6
The ZipNews users list is in standard ASCII text format. A few lines
of the list list might look like this:
JOHN DOE jdoe
MARY DOE maryd
SYSOP jkilday
The words in all caps on each line are the full caller name extracted
from the door drop file (PCBOARD.SYS, USERINFO.DAT, etc.). Separated
by a space from the full caller name, and in all lower case, is the
Internet-style ID which the caller chose during his/her first session
with the door.
IMPORTANT NOTE:
If you are upgrading from a prior release of the ZipNews door
used as a door under PCBoard, OR if you are adding ZipNews as
a door in a system that also has been running Waffle as a
door, there is an important task you must perform in order to
allow former users of the door (or users of the Waffle
system) access to this version of the ZipNews door. You must
add your current Waffle door users to the ZipNews users list
manually with a text editor!
Reason: Beneath the "user" directory specified in your
ZN.CFG file (and the same directory used by the Waffle BBS,
if used on your system) individual callers' directories are
created to contain personal setup and status information.
When ZipNews identifies a new, first-time user of the door
(caller name not on the ZipNews users list), the door asks
the "new user" to specify their desired login ID. THE CALLER
IS NOT PERMITTED TO USE ANY ID THAT CORRESPONDS TO A USER
DIRECTORY ALREADY IN EXISTENCE.
Therefore, any users of a Waffle system already installed on
your system (or of a ZipNews door earlier than v0.97c and
formerly used under PCBoard) must be added manually to the
new ZipNews users list. Otherwise, they will NOT be granted
access to this implementation of the door with their current
or former ID.
If you are operating ZipNews as a door under PCBoard, you may choose
to set up access by your callers in a different way. This method is
ONLY available for PCBoard systems, and was used in earlier releases
of ZipNews. If you examine the ZIPNEWS.PCB file (sample door batch
file provided with this package, you will see a door invocation line
that has been commented out. It makes use of the PCBoard environment
variable named PCBDOOR (and whose value is denoted in the batch file
by %pcbdoor%). This method requires your caller to invoke the door by
following the door command with his/her login ID, thusly: zipnews
johndoe ; OR door 1 johnndoe ; OR open 1 johndoe
This form of access is similar to that used for invoking from Waffle.
But, if used for PCBoard (with the "pcb" parm on the command line) the
door does not unconditionally allow access even if it finds a user
directory corresponding to the login ID. It must also find a file in
that directory named PCB.ID and that file must contain the caller name
as contained in the PCBoard door drop file, PCBOARD.SYS. So, if
johndoe logs in under this access method, ZipNews would verify that
ZipNews v0.97d Page 7
the PCB.ID file in the johndoe user directory contains the single
line containing "JOHN DOE" (assuming this caller name was in
PCBOARD.SYS). This form of addressing scheme works well, and handles
first-time user logins just as effectively as does the ZipNews user
list method (using the @users.lst approach), but it does force your
callers to always enter their ID following the door command. Not as
"seamless" perhaps as the newer method, but just as effective. This
method remains available in ZipNews to accommodate those who might
have set it up using earlier releases on their PCBoard systems.
To configure ZipNews to your system, use a standard ASCII text editor
to modify the ZN.CFG provided. The basic ZN.CFG format rules are:
1) Lines beginning with a space or a # symbol are ignored.
2) The 12 configuration subject titles listed below MUST be
present in the finished .CFG file and each must be followed
by a colon (:). There MAY be intervening whitespace.
newsgroups
user
temporary
bbs
abbrev
maximum
archivers
protocols
formats
organization
hostname
list
3) The lines may be in any order, but the sub-lines for archivers
and protocols must be grouped within their respective sections,
and with the "prompt" lines immediately preceding the
corresponding command line specifications.
4) The command lines for the protocols contain one character in
the first position which is not a part of the command line.
This is the "selection character", that by which a caller may
express his/her protocol choice.
Additional conventions used in the ZN.CFG file follow.
If you need to specify more than one top level news directory on your
system, indicate the full pathname to each (without a trailing "\")
and with a space separating each pathname.
If you have sufficient RAM available for use of a RAMDISK, such is
heartily recommended -- not only for speed gains, but for preventing
wear and tear on your hard drive. However, you may name a hard disk
and directory in the "temporary" parameter as your work directory.
This is the directory in which the extracted news articles are placed
and compressed for download. If you are running a multi-node system,
you will need to specify multiple temporary work directories (one for
each node) using this parameter . Here's how to do it:
ZipNews v0.97d Page 8
1) Set an ENVIRONMENT variable for each node. In each node's
ENVIRONMENT a new variable should be defined, NODE, for example.
Assign the number of the node to each one as required. Thus
in the ENVIRONMENT controlling node 1, you would set NODE=1,
for node 2, NODE=2 , etc.
(On PCBoard systems you could use the standard PCBNODE variable,
and on Wildcat!, WCNODEID, etc.)
2) Specify your "temporary" parameter such that it contains
the variable name with a % before and after it (just as in
DOS batch files). So you might specify in your ZN.CFG line:
temporary : g:\work%node%
This would be interpreted by ZipNews running on node 1 as
g:\work1, on node 2 as g:\work2, etc.
This method will allow you to run any number of BBS nodes from a
single copy of ZN.COM and ZN.CFG.
It is recommended that Forsberg's ubiquitous DSZ protocol module be
used to support file transfers. In fact, ZipNews has not been tested
with any other. Normally protocol modules must have the comm port and
speed communicated to them when invoked. DSZ automatically determines
the speed, so this spec is not necessary. To specify the comm port
number, or to specify a non-standard comm port, you set the DSZPORT
environment variable. (Set DSZPORT=1, for COM1:, for example. Or for
a non-standard port at hex address 3e8 and using IRQ 5, it would be
necessary to specify DSZPORT=3e8,5. See DSZ docs for further info as
necessary.)
WARNING: If you do not SET DSZPORT=SomeCommPort, ZipNews will exit
with an error message. The DSZPORT setting is required even if you
opt to use a different protocol module.
(A future release of ZipNews may allow specification of port and speed
via substitutable parameters, such as %1, %2, etc. If DSZ is used
with this release, however, capability for handling substitutable
parameters is not necessary.)
Another required environment variable for the running of ZipNews is
the WAFFLE variable. But you're all using that already, right? :)
ZipNews requires that the WAFFLE variable be present, but the present
release does not actually access your STATIC file.
If you're running a multi-node system, there's one last step necessary
for reliable operations. Switch to the directory in which you placed
ZN.EXE and, using the DOS ATTRIB command or other file attribute
setting/resetting utility, set the READ ONLY attribute bit ON (write
protect). This will prevent SHARE violations during program loading
under normal multi-node operations.
This completes the installation process.
ZipNews v0.97d Page 9
Operating/Using ZipNews
-----------------------
There is not much more to say re: operations; ... the first time you
fire up ZipNews, it will be pretty obvious how it is used. You should
be reminded of the local mode of operation. You might start it up on
a Wildcat! system like this:
zn @d:\waffle\user\zn_user.lst local wc
The above assumes you are PATHed to the directory in which you loaded
ZN.EXE and that there is a USERINFO.DAT (Wilcat! door drop file) in
the current directory.
In local mode you may operate the door pretty much as you would if it
were online. There currently are two areas of exeception. If you
request a download, a ZipNews packet (not compressed) may be created
and left in the work directory (specified by "temporary" in the ZN.CFG
file). This should prove helpful in testing parts of your setup. The
second area is the new user login process, the prompting for new user
ID, etc. This functional area of the code not been finished to
operate well in local mode in this release.
Re: advising your users in use of the ZipNews door and its output --
ZipNews' ASCII text format can be viewed quite conveniently using a
text viewer such as Vern Buerg's LIST utility. If, for example, you'd
like to quickly move from one message to another, set LIST to search
for "Subject:". LIST nicely highlights the found line. To search for
the next occurrence with LIST, hit the "A" key. To quickly scan to
reach the next newsgroup, use "* * <" as the search argument, etc.
Some of your callers might be confused as to what first to do with the
news packet received. The source of confusion stems from the use of a
characteristic file extension of "ZNS" for the compressed news packet,
rather than ZIP or ARC, etc. Most unarchiving utilities will work on
a valid archive when supplied the full filename and extension. If a
caller has a ZipNews packet created with PKZIP, for example, the
unarchiving command would be:
PKUNZIP yourbbs.zns (where "yourbbs" represents the name you have
selected for the "abbrev" parm in ZN.CFG)
Distribution and Restrictions
-------------------------------
ZipNews is made available to you as a fully functional news delivery
package. It is distributed as SHAREWARE. Should you decide to use
ZipNews on your system you are obliged to register the product for a
fee of $19.95. Use the form ZNORDER.FRM for registering your copy.
You are welcome to distribute this package to others so long as it is
unmodified and distributed in its entirety, and it is not included or
bundled with other goods or services for which a fee is charged.
Exceptions are that ZipNews may be distributed by bulletin boards,
Internet archive sites, or other information services even though they
receive fees to access their downloadable files, or by library
services so long as the fee for the diskette on which this package is
contained is not more than $6.50.
ZipNews v0.97d Page 10
Use of ZipNews beyond a brief evaluation period by individuals,
business entities, corporations, and government agencies is prohibited
without payment of a registration fee of $19.95 per copy.
After You Register ZipNews
--------------------------
Once your registration and check have been received, you will be sent
a registration number (via U.S. mail OR Internet e-mail, at your
option). You may use this number to convert to a registered copy of
ZipNews which will eliminate displays of "unregistered", "evaluation
copy", etc., and it will insert your name in displays and text files
as having duly registered the product.
To make a registered copy, invoke ZipNews with the command line
parameter of --REGISTER, thusly:
zn --register
You are prompted to enter your name and your registration number.
That's all there is to it.
(IMPORTANT NOTE: If you are running a multi-node system and have
followed the suggestion of setting the file attribute of ZN.EXE to
READ ONLY, you will have to set it back to normal before invoking
ZN.EXE in registration mode. Once you have completed the registration
procedure, you should set ZN.EXE back to READ ONLY mode.)
Support
-------
Support is available to registered users of ZipNews primarily through
the main message base of the Northern Lights BBS which can be reached
at the number given below.
Registration fees may be made payable to:
J.C. Kilday Associates
P.O. Box 1961
Portland, ME 04104
The author may be contacted at the above address, or via Internet
e-mail (jkilday@nlbbs.com), or at the Northern Lights BBS (address
messages to "Sysop") at 207-761-4782. The BBS operates 24 hours, 7
days. Calls accepted at 14400 (v.32bis or VHST) or below.
