ftp.wwiv.com/ftp.wwiv.com.zip/ftp.wwiv.com/pub/OFFLINE/VALEN130.ZIP/QWKNET.DOC

Text File | 1993-08-17 | 12KB | 242 lines

                                  Valence
                          QWK Networking Functions

                             by William McBrine
                   Copyright (c) 1993 Iconoclast Software


:::: INTRODUCTION ::::

Beginning with version 1.3, Valence offers node-level QWK networking
functions. You can import net-status .QWK packets and export .REPs to upload
to your hub. These functions are built-in to VALENCE.EXE, and add little
overhead.

This file is a bit sketchy, as I'm in a rush. I'll write more for the next
version. In the meantime, I hope your hub sysop can answer most of your QWK
networking questions and help you with your setup.

Please read the file QWKNET.CFG for more setup details.


:::: QWK VERSUS FIDO ::::

Perhaps the two most popular BBS networking systems today are QWK and Fido.
Many of you are familiar with Fidonet or Fidonet-technology systems. QWK
nets are less widespread, but are growing rapidly, as more and more systems
gain QWK-net support. Each system has its advantages and disadvantages.

QWK nets are generally considered far easier to set up than Fido-type nets.
Not that it would take much. :-) QWK nets import and export directly from
the message base; .PKT files, .MSG files, extra directories, mailers,
nodelists and so on don't clutter up your hard disk. The simple topology of
a QWK network reduces dupes.

On the other hand, QWK networks force you to wait online while your hub
packs your mail, which can increase your LD phone costs. (Some QWK doors do
offer prepacking, however.) The absence of a mailer program is a mixed
blessing, because QWK nets allow no file requests. Access in QWK nets is
somewhat restricted; you can only connect through your hub. Private mail may
be more difficult to use than Fido netmail - in the case of Valence, private
mail cannot be sent at all (yet). And setting up a script for a terminal
program to call your hub can be a pain, although there are a few dedicated
programs to automate it.

I'd like to tell you that QWK-net importing and exporting with Valence is
faster than Fido importing and exporting with SLMAIL, but that hasn't
materialized. In my benchmarks, I've found the performance to be nearly
identical. However, with QWK nets you won't need the several intermediate
steps used for Fido, so your overall performance may be better. The required
disk space for QWK nets is dramatically less.


:::: INSTALLATION, SETUP AND OPERATION ::::

First, if you're not already in a QWK net, find a hub and get the sysop to
give you a "net-status" or "net-sysop" account. Your hub sysop can help
explain this to you. Then, you may want to download your first net-status
packet before proceeding. You log in like a regular user, but using your
net-sysop account, and download a packet from the mail door, just as you
would a regular QWK packet. (Later, you'll upload a .REP the same way.)

If you're already using Valence as a QWK door on your system, all you need
to do is upgrade to version 1.3 by copying the files over in the usual way,
then add one small config file. If you're not already using Valence, I
recommend you just run INSTALL, then edit your network configuration
file(s). However, you can use Valence to import and export with QWK nets
without installing it as a QWK door on your board; just edit the .CFG file
manually, and please read all the documentation before you use it.

QWKNET.CFG is an example config file. When you join a QWK net, your hub
sysop might give you an example config file for Tomcat, Trinet, or some
other QWK-net program; you must adapt this to the format shown in
QWKNET.CFG. Usually it's pretty straightforward. You can also read the
CONTROL.DAT file from your net-status packet to see which numbers correspond
to which areas.

You must manually create the subboards you name in your network .CFG file,
if they don't exist already. Be sure to set the option "Auto Purge Old
Messages" to "Yes". You might also want to adjust the maximum number of
messages. Other than that, the defaults are fine. Do NOT fill in the
echomail fields, and do NOT mix QWK and Fido messages on the same subboard.

Now, import your first .QWK packet. To do this, run either from the home
(CONFIG.SL2) directory of a node with no one logged in, or with the SLBBS
environment variable pointing to such a node. Use the "I" parameter for
Import (you can also spell out "Import" if you like), followed by the BBSID
of your hub. E.G.:

 cd\sl
 valence\valence i hubsys

Watch and enjoy. :-) Depending on your system, it may take a while. (If you
can, use a disk cache, and enable both read and write caching, at least for
the duration of the import. It makes a dramatic difference.) The imported
.QWK packet will be deleted if successfully imported.

*** Normal operation ***

After your first import, you'll want to automate things. Always EXPORT
FIRST. The exporting process is identical to importing, but uses "E" (or
"Export") instead of "I".

You'll probably want to create a batch file which runs as an event,
something like this:

 cd\sl
 valence\valence e hubsys
 {launch terminal program with script to call hub,}
 {upload .REP and download .QWK}
 valence\valence i hubsys

That's really all there is to the setup. However, that middle part can be
tricky. I can't lay out the setup for you, but your hub sysop should be able
to help. Most QWK network hubs will have scripts for the more popular
terminal programs, plus dedicated QWK-network term programs like Robocomm
(? I think). Some people never do automate their sessions, and call manually
for their network transfers. I can't recommend that, but it does work.

*** Errorlevels ***

Import and Export functions return an errorlevel of 0 if everything went
normally; other errorlevels are as follows:

 81: COMPRESS.CFG not found
 82: Unable to open BBS system files
 83: CONFIG.SL2 not found
 85: Error from DOS operation
 86: Error changing directories
 87: .EXE or .COM not found
 88: Error in .REP packet
 92: Error in archiving
 94: SUBBOARD.SL2 not found
 97: Unable to open VALENCE.USR
 98: VALENCE.USR: wrong version
 99: No room for packet in directory
100: No new messages
101: Disk I/O error
104: Network .CFG file not found
105: QWK packet not found
106: Error in unarcing
107: Not a net-status packet!

You might check some of these in your import/export batch file(s). Notice
that error 100 is not really an error condition; unless your users do a lot
of posting, you can expect to get this one frequently when exporting. Error
107 is what you get if you try to import a regular .QWK packet. If you get
this error, and you KNOW you have a net-status packet, let me know (and send
me the packet).


:::: WHERE TO CONNECT ::::

The first board ever to be in QWK networks was PCBoard. Qmail, the original
QWK door, also became the original QWK networker. It was followed by Tomcat
for Wildcat BBSes. QWK networking has since spread to other types of boards,
but it's still most widespread among Wildcat and PCBoard systems - in fact,
my experience suggests QWK nets are more common than Fido nets on these two
boards. You may have noticed that many of them don't run front-end mailers,
but still carry networked conferences.

If you're interested in QWK networking, but don't know already know where
you can find a hub, try large local PCBoard and Wildcat systems first. Even
if they're not in a QWK net, almost all of them have the necessary software
already in place. You might prompt them to join. :-)


:::: SOME INNER DETAILS ::::

Most QWK-net import/export programs are separate from the QWK doors; I'm not
sure why. I found I could add import and export functions to Valence with a
minimum of new code, using much of the existing .QWK code to create network
.REPs, and the .REP code to read network .QWKs. But of course, the
differences are considerable, and I had a hell of a time finding out the
picky little details I needed to implement this thing. For some reason, the
QWK networking specs aren't nearly as well-publicized as the general QWK
specs.

When imported, messages are marked with an [I] flag. Network taglines are
added to those that don't have them. The high-message pointers are updated,
as after a download or export. (This is why it is critical that you export
FIRST.) And instead of a message-by-message display, there's a subboard-by-
subboard display very similar to the one you see when downloading. Other
than that, importing works the same as uploading a .REP. High-bit filtering
and threading are always off.

When exported, messages are marked with an [E] flag, if they don't already
have an [I] or [E] on them. Messages without an [I] have the network tagline
added. (Normally, the only messages in a QWK-net sub that will have [I]'s on
them are the ones downloaded from the hub, which will never be exported; but
when hubbing capability is added, messages uploaded from nodes will also be
marked with [I]'s. This is how Valence knows if the message already has a
network tagline or not.) The high-message pointers are updated immediately,
rather than after a successful download. Color codes are always stripped,
metacharacters are untranslated, and no "extra" header information is
included in a message. Otherwise, exporting is much like downloading.

The status line is not displayed in either network mode, the protocols are
ignored, and no user's record is read. Member records are created in all
network subboards with the hub's BBSID as the name.


:::: FOR THE FUTURE ::::

In the next release of Valence, I intend to offer hubbing ability. Before I
can do this, I'll have to resolve some problems with echoed private
messages. I also hope to increase the speed of importing.

*** Known flaws in the present version ***

* Importing is too slow. To improve it, I will have to write my own routines
  to replace the SLTPU's message post. Any tips on this - how to calculate a
  UID, how the compression scheme works, etc. - would be appreciated.

* Private echoed messages are merely posted to MAIL if they're to an
  existing user and discarded otherwise. It's impossible to send a private
  message through the network.

* Any existing network .REP file is killed on export. There should at least
  be the option to append newly exported messages to an existing .REP. This
  is the default behavior on the other QWK-net programs I've looked at. I
  coded this, but could not get it to work due to bizarre memory allocation
  problems. I hope to fix it for the next version, but for now I haven't the
  patience to keep beating my head against the wall.

* There should probably be an option not to kill the .QWK packet after
  import, too. And a few other options I can think of as well. <sigh>

* Overall number of messages imported and exported can be logged, but not
  area-by-area.


:::: ACKNOWLEDGMENTS ::::

Thanks to Jessica Mack aka Razor Girl for providing me with a net-sysop
account. This allowed me, finally, to figure out and implement the
mysterious QWK network system. Thanks also to all those who operate free and
open boards.

Unthanks to the many I asked for help on this who didn't give it. Also,
special unthanks to all the bums who sent me netmail and echomail saying
"Hey, I'm gonna send ya a donation check on Friday!" and never did so.