Power Programming/powerprogramming1994.iso/progtool/bss/pup.arc/PUP.DOC

Text File | 1987-12-11 | 20KB | 533 lines

T. Jennings
Fido Software
164 Shipley
San Francisco CA 94107

document updated: 10 Dec 87


            Puppy

Pup is a very modest project: it is a very small scaleì
bulletin board, targeted mainly for the current low-end typeì
machines; Z80, 64K, maybe 500K disk storage, primitive DOS.ì
It of course works fine on MSDOS; there is a pclone versionì
available. (Ask)

By Jan/Feb of 88, Pup will have a full featured FidoNetì
compatible network interface. The design is complete, andì
some code is done.


While the pclone version is where new things get tested, itì
is NOT the point of Pup. There are already more than enoughì
pclone BBSs to choose from; Pup however would fit veryì
comfortably into the smallest possible pclone these days.

BBSs have escalated in complexity way out of proportion toì
their usefulness; most BBSs are used by highly skilledì
people with lots of resource$ to talk to people likeì
themselves. This is fine, but most of the world isn't in theì
position to sit $1,000 (or more!) in a corner of the roomì
for one special purpose only.

Also, the trend is towards larger, more complex systems,ì
wide area networking, extremely high throughput dataì
transfers and other things that just push the likes of Fido,ì
Opus, TBBS an order of magnitude or two out of the range ofì
many (if not most) people who might benefit from them.

Seems we've forgotten that the original intent of BBSs wasì
to communicate with other people. It is not obvious to meì
that talking to more people is better. The best BBSs I'veì
ever used, of any type, were all very small systems; RCP/Ms,ì
Apple][/GBBS, etc. Most used awful software, but were stillì
the best (meaning most useful or most amusing) systems I'veì
run across. There's a hint there, I think.


I would love to see Pup ported to CP/M (especially: thatì
awful Heath/Zenith H-89) and Apple ][ PRODOS or something.
.pa
.he Copyrights, trademarks, money, that sort of thing.

        S H A R E W A R E

Puppy is shareware; if you like it or find it or parts of itì
useful, then mail me what you think it's worth. $40 isì
suggested. Less will not be considered an insult. In return,ì
I will mail you a diskette with the latest & greatest on it.


-*-*- -*-*- -*-*- -*-*- -*-*- -*-*- -*-*- -*-*- -*-*-

PUPPY PRE-RELEASE NOTE: The message base design reallyì
annoys some people. Instead of the usual linear numberedì
messages, I opted for a stack-like design (see the next pageì
or so for details.)

I may do another message base that is in the more usualì
linear fashion; it will be fully compatible with the messageì
base data files that this Pup generates; only the programì
will change. It's not all that big code-wise, but the Pileì
really bugs some people. I do eventually take hints, so ...

-*-*- -*-*- -*-*- -*-*- -*-*- -*-*- -*-*- -*-*- -*-*-

Check out the pclone version, show it to people, see whatì
your reaction is. It should be portable as-is to smallì
machines.

OK, down to brass tacks. (What on earth does that mean?) I,ì
Tom Jennings, do business as Fido Software, at the addressì
below. My commercial products are copyrighted works, and myì
sole source of income. Copyrighted works produced by me willì
be marked as such:

        Copyright Tom Jennings 1987, etc

This is very straightforward. These are commercial products;ì
you want, you pay. Or the guy in the big car over there willì
make you pay double later, OK?


Now for years I have been writing programs and distributingì
them, in binary and some in source form, but I've never madeì
it very clear what their status was. Partly this is becauseì
the previous environment (less cutthroat) was more friendlyì
and less demanding, and partly because I just wasn't thatì
organized. This is to change starting now. (now?)


The following notice will be firmly affixed to all programsì
produced by me that are not commercial copyrighted works.ì
Please don't utter the phrase "public domain" because thatì
means something awful:

        (k) All Rights Reversed

(all hail Eris) This means: what you do with it is up toì
you. I ask though, that if you distribute it, you provideì
sources as part of the package, at no extra cost or penaltyì
or obligation to the person receiving it; and that you alsoì
do not remove the (k) All Rights Reversed notice. I also askì
that you don't change the version number, if there is one;ì
you will only needlessly confuse people when I come out withì
a new version. Hint: Add your own IDs after it, like "1-AB"ì
where "AB" is your version number.


"Fido" is a trademark of Tom Jennings. It you utter it sendì
me a dollar. "FidoNet" is a also registered trademark of Tomì
Jennings. If you even think it send me two dollars. If youì
use both, send me ten dollars and your first born child. Allì
rights reserved, and all wrongs righted. So there.



    Fido Software
    164 Shipley
    San Francisco CA 94107
    (415)-764-1629, FidoSW, using Fido v12 1:125/111
    (415)-882-9835, ch@os, using Puppy v1
      soon will be known as 1:125/164

If you have anything to contribute, please do.
.pa
Historical Curiosities: An Editorial

A little history is in order here. I, like hundreds ofì
others, have been hanging out on BBSs and writing freeì
programs since Ward & Randy's CBBS. Nothing new or unique orì
interesting here.

Fido, started in 1984, is by far the most popular and wellì
known program I have ever produced. To say it exceededì
anything I ever planned for it is an understatement.ì
Requests for diskettes got so heavy that I started chargingì
for diskettes; as demand for functions and reliabilityì
increased, by many hundreds of people, it slowly turned intoì
a part-time business.

Now it eventually became obvious that this wasn't a typicalì
free BBS program, and that others wanted to write FidoNet¡
compatible programs; Thom Henderson had sucessfully gottenì
SeaDog running. An effort went into documenting the protocolì
(Randy Bush did a wonderful job with the FSC001 doc a yearì
later) and making structures public, etc. Interfaceì
information was released with each version, and work wasì
started towards the real technical specification,ì
culminating in FSC001.

Eventually, Fido/FidoNet became a full time job. I nowì
derive all of my income from it. (I license Fido/FidoNet toì
mostly small to medium companies and non-militaryì
governmental agencies.) Because of this, Fido is no longerì
free, starting with version 12. (You can now use previousì
versions for free; v11 manuals once again available for $35)

My roots and heart is still in the hobbiest end of things,ì
and Fido Software is hardly a traditional software company.ì
I am working on new software for hobbiests, both "free" andì
"shareware". I now fund this development from licensingì
Fido, and hopefully other sources in the future. I'm hardlyì
getting rich from this, and that's not the point.

My goal today is somewhat subversive I suppose; I want toì
see more non-technical people use computers forì
communicating in ways not traditionally though of, and onì
small cheap machines; not by throwing money at high-endì
Pclones or traditional services. (You're supposed to doì
wierd things with computers, that's what they're for!)

Traditional media in the U. S. is getting more and moreì
restricted to lowest-common-denominator, safe, bland,ì
*profitable* mindless pap. (Did you know: only 26ì
corporations own 1/2 or more of all media in the US:ì
magazines, books, TV, radio, newspapers, etc? Source:ì
"Fairness & Accuracy in Reporting", June 87) Individuals andì
small groups running BBSs and writing zines is one way toì
promote free (as in open) communications.

Some have asserted that I'm a greedy programmer trying toì
milk money from peoples hobby with Fido (how dare I chargeì
money) and that I don't care about much else.

I will merely say: I've been writing free software sinceì
1979, and have had phenomenal, unexpected success withì
Fido/FidoNet, which I have basically given to the world,ì
gratis. My attitudes haven't changed much, except to get aì
bit more radical. Time will tell, as it always does.

OK, I'll shut up now.
.pa
Pup's FidoNet interface

Suffice to say at this point, it will be both highì
performance, and will fit very nicely on a 64K Z80 with aì
couple of decent sized floppies.

Keep in mind it's not meant to act as a gateway to all ofì
Western Europe. You would probably have a hard time evenì
making it a Net Host.

What it will do though is run up to 16 echo conferences at aì
higher software-performance level available on any machineì
today, period. No space- and time-consuming packeting andì
unpacketing, no external conferencing packages.

Use of the nodelist will be optional; for echo conferences,ì
only the system information for the next-in-line systemì
(Pup, Fido, Opus, etc) is needed.


The method is: on-the-fly packeting and unpacketing. The Pupì
FidoNet code uses XMODEM to send the packet, as per FSC001ì
specifications. However, instead of generating a packet fileì
ahead of time, then XMODEMing it out, when XMODEM goes toì
"read" a block from the packet file, it uses a state machineì
to generate the data as it goes. Because the message base isì
one contiguous file, with a memory resident index,ì
performance is not a problem. This part is already coded.

The receiver does a similar thing. As XMODEM receivesì
blocks, it would normally write them to a packet file forì
later unpacking into messages. In Pup, the blocks are notì
written to a file, but decomposed byte by byte into theì
message base directly. Again, because of the message baseì
design performance isn't an issue.

.pa
Pup the Bulletin Board

Pup has all the usual amenities, but it doesn't appear thatì
way when you first look at it. There's only ten commands orì
so total.

The message base consists of two files, one that containsì
the message body text, and the other is an index with theì
usual TO:, FROM:, etc information, as well as the TOPICì
information. (More on Topics later.)

Pup's message base is created once when SET-PUP is run, andì
never changes in size. (You can set the size of each messageì
and the number of messages.) (And later there will be a wayì
to change the size, but not right away.) The advantages: itì
never grows to fill your disk; performance is extremely goodì
(if you format the disk first, you will be guarenteed thatì
all sectors in the file are contiguous); there is no needì
for message base maintenance.

(NOTE: See the PRE-RELEASE NOTE mentioned earlier aboutì
message base paradigm.)

Messages are arranged to match my desk: a Pile. I work byì
writing things on these tiny 3 x 5 pads of paper; one note,ì
phone number, bug, etc per sheet. I stack 'em up, move themì
around, etc. The one on the top is the newest.

Pups messages are in a Pile. When you enter a message, itì
goes on the Top; ones entered before are still there, underì
the top. Eventually, they reach the bottom, then they fallì
off. If you set Pup to have 100 messages, then when youì
enter the 101st message, the first one ever entered fallsì
off the bottom.

Yeah, its a ring buffer.

When you read messages you start, by default, at the Top ofì
the Pile. From there you can read messages, one afterì
another, until you hit the Bottom. You can of course hopì
around as you wish.

Now a huge monolithic messag base isn't much fun to pokeì
around in. This is where Topics come in.

Pup can have up to 16 topics; you must have at least one.ì
Topics are the usual grouping, areas, subjects, that sort ofì
thing. In Pup though, instead of rigid barricades thatì
messages must be forced within, in Pup you can hop Topics atì
will.

When reading messages, you can choose which which topics youì
wish to see, including "all". If you choose one topic, thenì
those are the only messages you will see. If you chooseì
"all", then you see all messages in all topics; this is niceì
for browsing a board for the first time or two. If you'reì
only interested in two or three topics, you can select onlyì
those and you will see no others.

When entering messages, you choose which topic the messageì
resides in; one message can also reside in any number ofì
topics. Obviously to be use with caution, but great forì
notices and such.


One of the reasons I chose this was because of a commonì
problem when using Fido-type message areas; neophyte usersì
tend to not change areas, and never become aware of theì
different catagories that may exist. Even sophisticatedì
users say "A 5" and therefore won't see if the list ofì
message areas has changed.

By default, in Pup you see all messages in all topics,ì
starting at the newest. If this annoys you, you can useì
choose which topics to see and not see, including "ALL".ì
This is the exact opposite of the Fido (and RBBS, Opus, etc)ì
philosophy.
.pa
Puppy and human callers

One of the first things to go in the trash when designingì
Pup was anything relating to "callers". As I see it, callerì
records have the following main purposes:

    terminal settings (lines, columns, etc)
    where they left off last time
    access controls
    let users see their name in lights

I consider all the other junk like help levels, last¡
accessed message area or file areas and times called to beì
design deficiencies (help levels?) or froo-froo (lastì
message area).

If you need access controls you don't want Puppy. Accessì
controls always escalate into huge monstrosities. Theì
purpose of Pup is so that people can communicate, in an easyì
to use and effecient manner. It's not an operating system,ì
like some BBS installations are approaching.

Its a little wierd at first ... but you get used to it. Oneì
objection that pops to mind is: how do I know that thatì
person is who he says he is? Well, you don't. Actually ...ì
if you are conversing with someone (not what you call whatì
happens when there are 500+ people using a system!) it'sì
pretty obvious. Also, it's not much of a challenge and notì
worth the bother of entering stupid messages. Remember also,ì
this isn't targeted at the mainstream BBS crowd.

How do you run a system then, with upwards of 500 differentì
people per month? Get a Fido or other large scale (largeì
resource) type program, which fits those sort ofì
installations perfectly.
.pa
OK, enough: what's on the disk

The end result of all the crap in the Pup package is twoì
programs and a few support files:

    PUP.EXE        the Pup program
    SET-PUP.EXE    the Pup installer
    PUP.SET        Pup configuration text file
    FIDO2PUP.EXE    Fido to Pup message converter

    WELCOME.PUP    the initial welcome message
    FILES.PUP    list of download files
    MAIN.HLP    various help files ...
    MESSAGE.HLP    ...
    EDIT.HLP    ...

    PUPPY.SYS    main system file
    MESSAGE.DAT    the message base itself
    MESSAGE.IDX    the message bsae index

SET-PUP reads the text file PUP.SET and compiles it into theì
PUPPY.SYS file that contains the installation type goodiesì
(modem type, node number, limits and controls) and createsì
an empty message base, if one doesn't already exist.

PUP is the BBS program, and reads all the other junk.

FIDO2PUP puts any Fido .MSG messages into the Pup messageì
base, and leaves the highest numbered one as the Topì
message. Gives you something to start with.

.pa
The complete list of files is:

Include files:
ASCII.H
PUPMEM.H
PUPPY.H
DRIVER.H
LATTICE.ASH

Various tools for compilation:
C.BAT
PUP        MAKE file
PUP.LNK        PLINK command file
IBM.LIB        pclone serial driver library
DRIVER.DOC    Pup/Fido driver specification

PUPMAIN.C    Pup main() and main loop
PUP.C        Pup commands
MSGBASE.C    the message base system
FILES.C        Pup file commands
QUOTE.C        signon quotations
SCHED.C        the scheduler
EDIT.C        message editor
XMODEM.C    XMODEM/TELINK protocol handler
MODEMIO.C    (not so) low level I/O
MDMFUNC.C    modem drivers
SUPPORT.C    misc. support routines
PRINTF.C    a real printf()
MS-C.C        DOS dependent C routines
MS-ASM.ASM    DOS dependent ASM routines
ABORT.ASM

FIDO2PUP.C    Fido msg converter
SET-PUP.C    config program

PUP.SET        sample config file
FILES.PUP    sample files list
WELCOME.PUP    sample welcome file
QUOTES.PUP    sample quotations
MAIN.HLP    sample help files
MESSAGE.HLP
EDIT.HLP
.pa
.he Implementation Notes

GENERAL

Data structures and other definitions of global importanceì
to Pup are in PUPPY.H, which is included by all .C files inì
Pup. When you change this file, recompile all modules; theì
make file provided will do this with RMAKE.EXE from Phoenixì
Software.

Global static data is defined in PUPMAIN.C, and referencesì
to it via #extern's are in PUPMEM.H. All sources exceptì
PUPMAIN.H include PUPMEM.H. It's the easiest way I've foundì
to manage external data; the one time it's a pain is if youì
add or delete a global variable (in PUPMAIN.C); you have toì
recompile everything. Oh well.


SERIAL INTERFACE

The serial I/O driver provided, IBM.LIB, is for pclonesì
only; you will need to write equivelant routines forì
whatever your machine is, even on CP/M. Most are prettyì
simple, and even polled is OK; Pup will even allow typeaheadì
on polled machines, due to the lookeahead done in MODEMIO.C.

Note that the drivers as defined in DRIVER.DOC are ratherì
complex; you don't need anything but the low level serialì
parts. (Poke through MODEMIO) Why not prune DRIVER.DOC andì
pass out a proper version?

Pup uses a three or four wire modem installation. It needs:

    Tx Data        obviously
    Rx Data        obviously
    Ground        obviously
    CD        Carrier Detect (pin 6 or 8)
    DTR        Data Terminal Ready (pin 20)

DTR is optional; see below.

Pup has a parameter "cd-bit" in PUP.SET; this is the bitì
mask pup uses to check for CD on the serial port. Pup ANDsì
the contents of the status register with the cd-bit, and ifì
the result is not zero, then the modem is assumed to beì
online.

CALLER INTERFACE I/O

Basically, the I/O system is the same as Fido and has all ofì
it's features: full typeahead, output pause (^S, ^Q),ì
background abort-detect (^C, ^K), typeahead flush (^F),ì
"command-ahead" (ie. "D N FILENAME.EXT X" executes a wholeì
download command skipping all the prompts), formatted I/O,ì
complete carrier loss detection with no programmaticì
overhead, dead-user timer, full time limit enforcement.

In theory, you should never have to mess with anything inì
MODEMIO. And be careful if you do, it's filled withì
recursive and effecient stuff, and I think it's pretty wellì
documented. It does a lot just as it stands; it is fourì
years accumulated work and experience.


MODEM SUPPORT

As implemented, Pup will support just about any Hayes typeì
modem. The modem must have a CD (Carrier Detect) line. DTRì
is reccomended, but not required.

The initialization specified in PUP.SET should set the modemì
to numeric result codes and autoanswer OFF. Pup answers theì
phone by waiting for a RING result code, then issuing an ATAì
command, and waiting for the CONNECT 1200 (or 2400, etc)ì
message, and then assumes it's online and connected. Noì
hocus pocus or complicated autobaud.


LITTLE ENDIAN vs. BIG ENDIAN

This is the endless "Intel" vs. "Motorola" argument. Iì
really don't care either way; neither does Pup. The onlyì
part that cares about byte order is the FidoNet interface,ì
and there you have no choice.

The only time this might matter is if you were to generate aì
message base on a Z80 and physically copy it to a 6502ì
machine; you'd have to convert byte order. For locally¡
generated data, it's not an issue.


FUNCTION PORTABILITY

I tried to keep things down to two kinds of portabilityì
problems: C language data typing and O/S functionality.

On C data types, most things don't care; general purposeì
counters etc are just "int"s, etc. For ones that matter,ì
almost all want to be either 8 or 16 bit data. For these, Iì
defined two types: BYTE and WORD. In the Lattice 2.12/MSDOSì
version, BYTE is defined as char, and WORD as int. Changeì
accordingly to fit your system. These are defined inì
PUPPY.H.