The Devil's Doorknob BBS Capture (1996-2003)/devilsdoorknobbbscapture1996-2003.iso/Dloads/OTHERUTI/WWIV412S.ZIP/WWIVSOUR.DOC

Text File | 1990-08-05 | 15KB | 371 lines

                    WWIV Source Documentation
                Copyright (c) 1988 by Wayne Bell



If you have this file, you should also have the source code for
WWIV.  This means you have sent in a donation.  The source code
is ONLY available to people who have sent in donations, NOT FOR
OTHER PEOPLE.  As can be seen in the notice at the beginning of
all the source files, DISTRIBUTION OF THE SOURCE BY ANYONE EXCEPT
ME IS PROHIBITED.  Even if your best friend mails me a check
right before your eyes, he must get the source from ME, you may
not give him a copy.

If you have somehow gotten ahold of this WITHOUT either
downloading it from my BBS, or having me send you a copy, then
you are hurting the cause of good software.  If it turns out that
it is not possible to control distribution of the source by
reasonable means, you will probably find that the source WILL NOT
BE AVAILABLE for future versions.

The source is being given out so that you may modify the BBS to
suit your own needs and desires, for your system only.  You may
not give out a copy of your modified program to anyone (either
the source or compiled).

This does not mean, however, that you can't distribute CHANGES.
You may not distribute a copy of WWIV that you have compiled,
ever, or any major portions of the source code.  You can,
however, distribute changes you made to the source, so that
other people with the source may make the same changes.

For example, suppose you made a modification to function
sublist() in BBS.C, and wanted to allow other people to make the
same modification.  Now, since function sublist() is under 50
lines (rather short), you may just go ahead and distribute the
entire procedure, telling people they need to replace function
sublist() in BBS.C with your new one.

Suppose, on the other hand, that you have made modifications to
function scan() in MSGBASE.C.  Since function scan() is around
350 lines, it is unlikely you will have made modifications to the
entire thing.  Most likely, it will be just a block of code,
maybe 50-75 lines long, that contains the bulk of your changes.
Just pull out those blocks that you have made changes to, and
distribute those, along with a short note telling which lines to
delete, and where to insert your new ones.

Suppose, instead, that your modification required you to insert 3
new variables, and put in a few lines of code in 4 of the source
files.  DO NOT JUST DISTRIBUTE ALL THE FILES YOU CHANGED.
Instead, document where you made the changes, and list where to
insert (or delete) the few lines of code you did change.

If your modifications would require you to distribute over 100
lines of the initial BBS code, you should contact me before you
distribute it, sending me a copy, and asking if it's OK.  Most
likely it will be.

If you have any questions about this policy, or how it might
apply to you, feel free to contact me on my system at 213-208-
6689 300/1200/2400/24 hrs.

You may wonder why I have put such restrictions on distribution
of changes.  The main reason is the wreckless abandon some people
have exhibited in just doing whatever they damn well pleased with
earlier versions of WWIV.  I've heard of people making changes to
the code, inserting profanity in comments throughout the program,
and distributing that as if it were a perfectly normal copy of
WWIV.  This is what I want to prevent.

As long as your changes don't contain a significant portion of
the BBS source in them, I will probably have no problems about
your distributing them.  But, do check, BEFOREHAND.

Also, any changes that you do distribute, I'd appreciate it if
you'd upload a copy to my system, so that there can be a sort of
"central area" where people can find things.

About INIT.EXE.  As you can see, I'm not distributing the source
to the init program.  See the main docs as to the reason why.  If
you feel you really NEED the source to init, and have a good
reason why, contact me, and we'll try to work it out.


/****************************************************************************/


There.  Now that I'm through with that, I can get about describing the
source a bit.  First, how to set everything up so that it compiles.

WWIV will compile correctly under Turbo C v1.5, Turbo C v2.0, and Turbo
C++ v1.0.  It will not compile correctly under Turbo C v1.0, and it will
not compile correctly under Microsoft C, or any other C compiler.  Using
TC++, you get to use overlays, and a more powerful make utility, and
everything is really a lot nicer.  Therefore, I really would suggest
that people upgrade to TC++, even if you don't use any of the C++
extensions.

Needless to say, that creates quite a few different environments that
everything has to work under.  Therefore, I am NOT going to describe how
to get WWIV to compile under the Turbo C integrated environment.  There
are just too many things you have to do, and too many ways you can mess
up, especially if you are not very familiar with it.  So, if you want to
compile using the integrated environment, you're on your own.

My preferred method of compiling is therefore using the make utility.
Once you make a few simple modifications to the file 'makefile.mak',
everything will magically compile optimally under any version of Turbo
C, including using overlays if you are using TC++.  Note, however,
that if you upgrade from TC1.5/2.0 to TC++, you will have to remove all
your .obj files and re-compile all of them to allow the overlay system
to work correctly.

First, un-zip the WWIV source archive into a WWIV dir.  DO NOT put it in
your Turbo C directory.

If you boot up an editor and edit 'makefile.mak', you'll find that the
first section looks like:


#############################################################################
#
# Specify directories to use
#

!if $(__MAKE__) >= 0x0300
TC  = d:\tcpp
!else
TC  = c:\tc
!endif

OBJ = obj\\

EXE = exe\\

The first part up there attempts to determine if you are using TC1.5/2.0
or TC++.  You will need to edit the appropriate "TC = " line to point to
your Turbo C directory.  If you have Turbo C++ installed in c:\cpp, then
set the first TC line to be "TC = c:\cpp".  If you have Turbo C v2.0
installed in "d:\c", then set the second TC line to "TC = d:\c".

The next statement is "OBJ = obj\\", which points to the directory to
put the object files (.obj) in.  I prefer to put them off in a separate
directory, since you don't do anything with them directly.  To use this
setup, from your main WWIV directory, type "md obj" and all the .obj
files will go there.  If you want them to just stay in the same
directory as the source code, then change the line to "OBJ = .\\"

The final line you will have to worry about is "EXE = exe\\".  This
specifies where to put the executables (bbs.exe and return.exe).  You
will most likely want to leave those in the same directory as the source
files, so change it to "EXE = .\\"

Now, whenever you want to re-compile any changed files and re-link the
executables, go to the WWIV source directory and type "make".  If
everything is set up correctly, the source should compile without any
errors or warnings.  If you have any errors or warnings, you have done
something wrong.  Go back and check to ensure that you have the
directory variables set up correctly.


Under TC++, I have an extra option in the makefile - it creates the
fcns.h file based upon your source files.  To re-create the fcns.h file
just type "make fcns".  This is what I have used to create it in the
first place, so if you run it on an unmodified copy of the source, it
should end up being the same.  Additionally, if you add additional
source files, this will include the prototypes from those files also
(assuming, of course, that you use the same function declaration style
that I do - the technique is pretty dumb, but it works).



/****************************************************************************/


The rest of this document is to describe some general things about the
source, and is not meant to describe how to use Turbo C.  If you need
help with the TC integrated environment, look through the manual, and
play around with it a bit.  Unfortunately, I haven't updated this
section in a long time, and so most of the .c file descriptions are out
of date.  The function and global variable declarations should still be
fairly close, though.  If you have problems, try contacting a WWIV
support system.


Header files:

VARDEC.H - holds the type declarations and #define's for the BBS.

FCNS.H - holds most of the main function declarations (but not
all).

VARS.H - Holds declarations for all global variables.

NET.H - holds declarations for WWIVnet.


Main source files:

BBS.C - Main BBS files - main menu, main DL menu, and procedures
to log on a caller.  If you add new functions to the main menu,
you'll need to modify some procedure in BBS.C to have a call to
execute it.

COM.C - Contains all the modem routines - input/output to the com
port.  This also has all the combined com/screen routines - like,
to output to both the screen and com port, the routine is in
here.  ANSI interpretation is also in here, along with standard
"input a line" functions.

CONIO.C - Contains console I/O routines, to output a character to
the screen, and get a character from the keyboard.  You'll notice
I do a lot of _AH=; geninterrupt(), instead of using the console
I/O functions in TC 1.5.  This is because most of those functions
weren't in 1.0, and I wrote these routines under TC 1.0.  Also,
the code for top of screen data, and chat, and validating a user
are in here, along with sysop key interpretation (f-keys).

NEWUSER.C - Obviously, contains info for logging on new users
(and nothing else).

XFER.C - Contains most of the DL functions, anything from the
transfer menu will be in here (but the actual transfer main menu
is in BBS.C).

SR.C - Send/Receive files.  Internal and external protocols are
implemented in here.

UTILITY.C - Utility functions, not expressly relating to the BBS.
Such as free disk space, time & date, initialization, reading &
writing to the user list.

SYSOPF.C - Most of the sysop functions.  uedit, boardedit,
diredit, chainedit, system status, validating a user, voting
initialization.

SYSOPF1.C - More sysop functions.  Internal sysop editor,
gfileedit (overflow from sysopf.c).

EXTRN.C - external program interface.  Runs external programs,
but re-directs all I/O (through dos calls) to go to BBS routines
instead of just to the console.

MSGBASE.C - Message base, e-mail.  Entering message, scan prompt,
sending e-mail, posting, reading e-mail, multi-mail.

BBSUTL.C - Other BBS functions not relating to file transfer or
mail/messages.  Gfiles, main menu get key function, inputting a
line (for a message), logon, logoff, yourinfo, request chat,
selecting colors.

BBSUTL1.C - overflow from bbsutl.c, mostly.  Rest of default
section, sysop log, auto-message, bbslist, kill old e-mail, user
list, voting, zlog, external programs.

If you don't see anything listed here, find whatever seems to be
closest, and search that file.

Common functions:

char getkey() - waits for, and returns one character of input

void input(char *s, int len) - inputs len characters (uppercase
only) to string s.

void inputl(char *s, int len) - same as input, but allows
lowercase.

int yn() - returns 1 for yes, 0 for no.  C/R=no

int ny() - same as yn(), but C/R=yes

void ansic(int n) - selects a color (if user supports ANSI).  n
is 0 to 7.

char onek(char *s) - pass it a string, and it allows the user to
hit one key in the string, which it returns.  ie, you want
Delete, Ignore, Retry, so you do onek("DIR"), and it will return
D, I, or R.  If the user hangs up, it returns the first
character, so if one option is Quit, have the Q first.

void prt(int i, char *s) - selects color i, prints string s,
returns to color 0.

void nl() - does a carriage return/line feed - go to new line.

void print(char *s, ...) - pass one or more strings, they are
printed.  Terminate list with null string, ie, print("You are
","here and"," now","") - DON'T terminate with NULL.

void prompt(char *s, ...) - same as print, but no cr/lf on end.

void pl(char *s) - prints string s, with a cr/lf on end

void outstr(char *s) - prints s, no cr/lf on end

void pla(char *s, int *abort) - prints s, allowing abort.  Pass
pointer to an integer, if user aborts, *abort will be 1, and
output is terminated.  You MUST initialize *abort to zero.

void outs(char *s) - outputs a string, to the screen only (not to
remote user).

void tleft(int x) - updates time left display at top of screen.
if x is non-zero, the user will be hung up on if his time is
expired.  If x is zero, time display will be updated, but user
won't be hung up on.

void topscreen() - updates top of screen info.

char *mmkey(int n) - inputs data for the main menu.  see odc
below.



global variables:

int using_modem - is non-zero if there is a remote user

int hangup - is non-zero if the user has hung up.  MUST BE AN
EXIT CONDITION FOR ALL LOOPS THAT DO I/O.

userrec thisuser - holds information about the current user

int usernum - holds user number of current user

configrec syscfg - holds system configuration.  SHOULD NOT BE
MODIFIED IN PROGRAM.  The data in here should be changed ONLY in
init, the main BBS should use this as READ-ONLY.

statusrec status - holds current stats information.

char odc[81] - If you want to have an input like the main menu
(ie, certain characters mean get a second character, ie, you hit
O at main menu, it goes right to that function, hitting / will
get another character), set odc to a string containing the
characters you wish a second character for, then call mmkey(2) -
will return a pointer to a string for the data entered.

ie, if you want to enter a number 1-19, you have to get a second
character if the user hits one, so you'd say:

char *ss;

strcpy(odc,"1");
ss=mmkey(2);

Then ss can point to a string "1", "5","15","1X", "G","19", etc.


char curspeed[80] - string holding current baud rate in use, can
be "KB","300","1200","2400","9600", or "19200".

char crttype - screen mode currently active (7 means monochrome
dispaly).



OK, that's all I can think of for now.  Any questions/comments,
please f-back me on my system, 213-208-6689 300/1200/2400/24 hrs.
Anything you think I left out or could expand upon more, tell me,
and I'll have that in the next version of the source docs.


Wayne Bell
Box 636
904 Silver Spur Road
Rolling Hills Estates, CA  90274
213-208-6689 300/1200/2400/24 hrs.