textfiles/apple/puppy

 This is the PUP.DOC file from T. Jennings' *new* PUPPY program;
 it has to be compiled with a C compiler; thought I'd let you all
 know about it in case anyone wants to investigate the Fidonetwork's
 new PUPPY!
 
 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.
 
 
 Any/all of you can reach Tom Jennings by dialing his
 BBS number:  415-764-1629
 
 Please *do not* send email to me; I haven't compiled the program
 and don't yet know how it works.