💾 Archived View for spam.works › mirrors › textfiles › apple › DOCUMENTATION › wapabbs captured on 2023-06-16 at 21:27:32.
-=-=-=-=-=-=-
IV. WAPABBS PROGRAM NOTES
WAPABBS is, of necessity, a long and complex program. This discussion will attempt to trace the execution of the program from the start through the end of initialization. Following this is a discussion of the subroutines (lines 30-910), and a discussion of the workings of the main routines.
Line 10 sets up HIMEM and certain of the key variables. Change SL if your Micromodem is not in slot 3. Execution then jumps via line 100 to line 20000.
Lines 20000-20999 initialize the program. Lines 20000 and 20010 check to see if the two machine language routines, ABBS1.OBJ0 and ABBS3.OBJ0, are in place; they are BLOADed if necessary. The next lines turn off TRACE, initialize the Micromodem, and hang up the telephone.
Lines 20040-20050 and 20070-20080 set up the variables for some of the PEEKs and POKEs and initialize the bytes as required. Line 20060 references two subroutines, at 30 and 32, which are discussed below. The cumulative effect of these two routines is to set Applesoft's "&" vector, located at $3F5.
Line 20090 sets up DOS commands as strings in order to save space. Line 20100 sets up the two strings of allowable commands.
Line 20110 says how many messages are allowed in the system at any one time. Many arrays are dimensioned with MS as a subscript.
Line 20120 gives the SYSOP's userid and S1$ value. It also dimensions array variables. Line 20130 reads in the file names.
Lines 20140-20250 read in the Messages file off of the disk and store the messages summaries in memory beginning at $6B00. Message 1 is stored first, message 2 second, etc. Lines 20250-20490 sort the message array by date order and create a list in the DA array that lists the messages in date order. Line numbers in this routine were carefully chosen in an attempt to minimize execution time.
Line 20500 loads USERS.OBJ into memory. Lines 20510-20540 load STARTUP into memory. Line 20550 reads the number of days in each month (change this during leap years!) and line 20999 says "READY" and returns execution to line 110, which passes control on to line 1000.
SUBROUTINES
Line 30 sets the Apple to standard system I/O routines: the keyboard and the screen. CALL 1002 is used rather than the traditional PRINT D$;"PR#0" so that no spurious returns are created.
Line 32 turns the ABBS's I/O routines on and sets the Applesoft "&" vector.
Line 33 makes editing simpler. To list a line in a form that is easy to copy with the right-arrow key, do a GOSUB 33:LIST [line number] and the screen will be cleared, the margins will be set to eliminate the extra spaces, and the line will be listed.
Lines 50-55 update the date string, DA$. If you do not have a CPS Multifunction Card, DA$ will not be changed.
Lines 200-240 print the Message Header for a number of routines. On input, Z is the message number. On exit, B$ is the date the message was entered; L is also changed.
Lines 300-350 print most files. After drive 2 is selected (if necessary), the file is read a line at a time. Because MON I is in effect, there is no specific printout of the line. Every second carriage return is converted into a space if the 80-column mode is in effect. If the file is the Messages file, the first 4 records are skipped, since they contain the same information as the message header, which was printed by the routine at line 200. Upon exit, the file is closed. On entry, F is the number of the file; upon exit A$ and Z are changed.
Lines 400-490 ask the user how far back he wishes to search for messages. "A" will retrieve all messages or summaries; a Return retrieves only those since the user's last call. Entry of a number will retrieve all messages within that number of days, where "0" will retrieve only those messages entered today. "Days" are calendar days, thus to a caller at 12:05 a.m., a message entered 10 minutes before would be one day ago. If no messages are found that qualify (i.e., if K > MC), control goes to line 2000. Upon exit, J is set to the date you are searching for (YYMMDD.HHX), K is the relative message (in date order) that was the oldest message within the chosen number of days. A$, B$, J, and JJ are changed.
Line 500 sets up the ABBS to write to File F, Record R.
Lines 600-630 call a machine language routine that takes a userid such as WAP001 and converts it into the record number in the USERS file. On exit, J is the relative record number and A$ is the numeric portion of the userid.
Lines 700 and 701 open the Messages and Users files as Random-Access files.
Lines 800-810 set up file F for input. Set R to the desired record number before opening Messages or Users.
Lines 900-910 perform a J = VAL(A$) function that prevents errors that would be inevitable if a user entered "1E99" in response to a request for numeric input. Since WAPABBS does not use negative numbers, this routine returns only absolute values.
Line 1000 begins the "AWAITING CALL" routine. Garbage is collected (line 1000), and all variables are initialized: the cursor is set so that DOS will allow deferred-execution commands, CKMASK is set so that ctrl-C and ctrl-K cannot interrupt execution, SPEED is set to the maximum, the modem is turned on, all files are closed, delay after Returns is turned off, lowercase-to-uppercase translation is turned on, drive 1 is selected, the "Knowledgable User" flag is cleared, 80-column mode is cleared, and WAPABBS waits for a call. Once a call has been received, the CALL INLIN,248 statement has been satisfied and the ONERR vector is reset.
Given the Micromodem's phone answering routine, only a response from the keyboard could have input a non-null string in response to the input statement in line 1000. Line 1010 therefore allows you to do certain things while WAPABBS is operating. If you enter SYSOP, you can change the STARTUP file, look at the "TO SYSOP" file, and check on the number of callers. This routine, at 30000, will return you to the "COMMAND?" level.
To bypass the STARTUP questions, you may enter a ctrl-S, which will automatically log you onto the ABBS. Others cannot use the ABBS while you are using it. Be aware that while ctrl-S relieves you from having to enter your password, it does not check the date you last called in, and so the "Last Call" value will be whatever it was for the previous caller.
You may signal your willingness to chat with users by entering "IN" or unwillingness by entering "OUT". If you enter a ctrl-C, the ABBS will quietly turn off the modem and return to BASIC.
Line 1040 is the first thing that your users will see when they call up. Asking for a return is necessary so that people with acoustic couplers have some time to get set up, and so that people with parity or other problems will see that they need to change something. Experience has taught me not to delete this line. If the user enters a number here, it will become the delay after carriage return when linefeed insertion is selected. Users requiring linefeeds or a delay should enter here a ctrl-J (linefeed), followed by the amount of delay (if any), followed by a Return.
Change line 1050 when you want to let your users know important news about the system.
Users have three tries to enter their passwords. Help is offered after the second unsuccessful attempt. Three incorrect tries jumps control to a "Guest" routine at line 22000.
Line 1100 converts userid's in the form WP0xyz to WAPxyz because otherwise the ABBS would not know the two were the same individual. Line 1120 looks up the password, and line 1130 reads and updates the "Last Call" variable. Line 1140, which only the SYSOP sees, says how many users have logged on. Line 1150 locks out other callers from the ABBS if you are using it. Since the only way for ACTIVE to be 0 at this point is if you have accessed the ABBS from the keyboard, ACTIVE is set to 64 so that any calls while you are using the ABBS will ring unanswered.
Line 1160 is the entry point for the "P" command. Line 1170 offers the user an opportunity to read the Bulletin, which is printed out by line 1180. The user is next shown the message numbers of all messages for him. The numbers are presented in chronological order.
Line 2000 is the "COMMAND?" processor. Once a user has logged on, control will always pass through this line. The ctrl-C and ctrl-K commands always return control to this line after they clear the stack of incomplete GOSUB-RETURNs and FOR-NEXTs. These things must be done: Forbid ctrl-C and ctrl-K briefly so that WAPABBS will be able to do some work without interruption, set ALLOWLC so that all lowercase will be converted to uppercase, turn the modem on (in case something turned it off), turn off MON I, close all files, enable ctrl-C/ctrl-K, set the drive to 1, and request a "COMMAND?"
Line 2010 gets a three-character input line and checks to see if it is a number. If so, control passes to the routine at 5200 that will print out that message. If the line entered was not a number, its first character is treated as a command and looked up in AC$. If it was not a valid command, a brief summary of legal commands is displayed. Control then returns to the "COMMAND?" processor.
THE ROUTINES (in order of line number):
Note that, for the most part, commands begin on lines with even hundred line numbers. While there were no rigid definitions applied to the order of the commands, you may notice that, generally, commands with line numbers in the 3000's access informational files, commands with line numbers in the 4000's set or clear flags, and commands with line numbers in the 5000-6000's process the Messages file. Upload is the 10000's and Download is the 11000's.
The first routine is the "Help" routine at line 2030 ("H"), which is essentially a one-line description of each available command.
The Bulletin, Meetings, and Instructions files are handled by lines 3000-3200 ("B", "M", and "I"). Lines 3300-3430 ("W") are the "Who" routine, which connects userid's with names. The name-to-number routine asks for the first two letters of the name and searches every user record for a match. The number-to-name routine, at line 3400, treats the USERS file as a Random-Access file and looks up only that particular password generally name.
Line 3500 ("$") lists the Club Store file.
Lines 3600-3690 ("Y") allow you and one other user, whose userid is stored in T2$, to look at one or all records in the USERS file. This will also print out passwords, except that the SYSOP's password cannot be printed. The SYSOP's password can only be inspected by a text editor from the keyboard of the ABBS.
Lines 3700-3750 ("O") control the public opinion poll. If you are the user, WAPABBS asks you if you wish to examine the file. Note that WAPABBS's error handling routines will cause program execution to return to the "COMMAND?" processor at the end of the Opinion file listing. If you do not ask to see the listing, and in any event for all other users, the question is posed and the user is asked if he or she wishes to respond. (You may wish to insert a routine that checks to see if the user has answered the question before.) If the user wishes to enter a response, up to 65 characters are allowed. Note that if this file fills up disk 2, your users may be thrown off of the system by a disk full error. Monitor the size of this file carefully.
Line 4000 ("K") toggles the "Knowledgable User" flag. If equal to one, many prompts are shortened; thus "COMMAND?" becomes "?".
Lines 4100-4180 ("N") allow the user to select linefeeds after carriage returns, delays after carriage returns, or overall speed delays. Read your Micromodem manual for a detailed description of how linefeed insertion and delay after carriage returns work.
Lines 4200-4230 ("C") allow the user to request a chat with the SYSOP. If the SYSOP comes to the ABBS keyboard and enters ctrl-A ctrl-B, line 4300 will print a greeting and enter Chat mode. Note that while in Chat mode, both you and the user must insert Returns at least every 248 characters. You will notice when chatting that WAPABBS will not allow you to enter more than 248 characters per line, but your user will hear beeps for every extra keystroke either you or he makes! Chat mode can ONLY be exited by ctrl-C or ctrl-K, which either you or the user can enter.
Lines 4400-4430 ("T") allow the SYSOP and the users designated T1$ and T2$ to change the date. This is unnecessary if you have a CPS Multifunction card. The date must be entered in the form YYMMDD.HHMMSS, where YY=year, MM=month, DD=date, HH=hours, MM=minutes, and SS=seconds.
Lines 4500-4530 ("?") simply prints out the letters of allowable commands. You, T1$, and T2$ are shown the special commands only you three may enter. Line 4600 ("+") toggles the 80-column mode. Only the subroutine beginning at line 300 recognizes 80-column mode, which merely converts every other Return into a space.
Lines 5000-5030 ("Q") give a quick summary of the messages for you, from you, and for all. Message numbers are listed in chronological order. Returns are inserted periodically so that message numbers are not split across text screen lines.
Lines 5100-5150 ("S") scan the message summaries. The user is first asked whether he wishes to flag messages for later reading in full; if he says yes, FG is set to 1 and the FG(MS) array is cleared. The user is then asked how far back he wishes to scan. See the description of the subroutine beginning at line 400. JJ is set to 0 so that, if no messages are selected for reading in full, execution will return immediately to line 2000. Then each message summary is listed, followed (if applicable) by a query as to whether the user wants the message flagged. Note that the SYSOP can read all message summaries, whereas others can read the summaries of messages to them, from them, or for all. Once a message is flagged, JJ is set to 1. At the conclusion of the summary of the most recent message, if the user has flagged any messages, KK is set to 0 and the user is sent to the "L" command at line 5810; otherwise, control returns to line 2000.
Lines 5200-5240 print particular message numbers. The SYSOP can read any message. If the message was to the user, he is asked whether he would like to delete it at once. If he does, control passes to the Delete subroutine at 5350; otherwise control returns to line 2000.
Lines 5300-5380 ("D") delete messages. Lines 5300-5310 merely let you select the message to delete. Only the sender of the message, the recipient and the SYSOP can delete a message. The actual deleting is done by a subroutine betinning at 5320. On entry to the subroutine, J is the message number to be deleted. The "From" portion of the message summary is made equal to "EMPTY ". Note that the message number is pulled out of the DA(MS) array and placed at the top of the inactive message portion of the array, i.e., at DA(MC+1). All other message numbers are moved up one in the array. On exit, K, L, Z, and B$ are changed; note that KK is reduced by one. KK is used by the Flush Messages ("F") routine.
Line 5400 ("E") calls the Enter Message subroutine at 5401-5680. This is one of the most important routines in WAPABBS, and you should consider studying it carefully.
After making sure that space is available for the message (line 5401), ctrl-C/ctrl-K recognition is disabled. J is set to the message number at the top of the available number stack. The user is asked to designate the recipient. Lines 5420-5460 handle the response. (Note that line 5440 handles the "C" response.)
Beginning with line 5470, the entry of the Message summary, lowercase is allowed. WAPABBS treats lowercase as lowercase only during entry of a message or its summary; at all other times, lowercase is converted by the ABBS into uppercase. Following the summary, the user enters the text of the message one line at a time. After he has entered a null line or the tenth line of text, ALLOWLC is turned off and the user is asked whether he wants to save the message. If he answers anything but "N", the messages is written to disk from the M$(13) array. After writing to disk is complete, the message summary is entered into memory using the "&" routine. Note that these two steps must be done after the user has approved the message, because if the user had begun to enter a message to ALL and had gotten cut off, a partially entered message would still have the text of someone else's old -- and perhaps confidential -- message, which would be retrievable by everyone. After the message is saved, FG(J) is set to 0 so that the message will not be retrieved by the flagging process, which may be underway if the Message Entry was entered from the "L" routine rather than directly with "E".
If the user elects not to save the message, he is presented with three options: edit the message, cancel it, or re-enter it from scratch. Cancelling the message concludes the Entry subroutine; "R" returns to the top of the Entry subroutine. Editing allows the sender (or the SYSOP) to change any part of the message except the date and the sender's userid. In many respects the Edit routine is merely a specialized Entry routine, allowing entry of particular lines instead of an entire message. By and large, the same variables are used in Edit as in Entry.
Lines 5800-5840 ("L") list out the full text of messages much in the same way as "S" lists out summaries. JJ is 0 to distinguish "L" from the flagged listing printed out by the "S" command, which enters at line 5810. KK is used as the index into the DA(MS) array, and Z is the actual number of the message being listed. Note again that the SYSOP sees all messages, whereas others can see messages for themselves, from themselves or for all. After listing the message in line 5830, the user is offered the option of deleting the message if it is to him.
The user is then asked if he would like to enter a message. If he responds Yes, the "Entry" subroutine at 5401 is called. In any event, WAPABBS goes back to line 5810 to list out the next message.
Lines 5900-5930 ("F") Flush old messages from the files. Only the SYSOP can flush messages. All messages older than message number KK are printed and you are given the opportunity of deleting them. At any given moment, KK is the relative number in the DA(MS) array of the message being listed, and JJ is the relative number in the DA(MS) array of the latest message that you will be offered the opportunity of deleting.
Lines 6000-6050 ("A") allow you or the sender of a message to edit it after it has been sent. This routine calls the Edit subroutine at 5550. K is used to measure how many lines of text are in the message.
Line 9000("R") is set aside for a command of your own design.
Lines 10000-10020 ("X") are the introduction to the File Transfer System. Line 10020 prints the instructions for File Transfer.
Lines 10030-10140 allow the user to send files to the ABBS. After verifying that the user knows the Upload password, which he must have learned from you, he is asked for a file name, and the file name is checked against other upload file names. (Make sure that you tell users not to use the name of another program on disk 2.) The user is also asked for the file type, which will affect how the program is downloaded.
The actual uploading process is done by line 10120. When the user sends a line consisting of "EOF" (End of File), uploading ends. If a line has less than 4 characters, i.e., shorter than the shortest valid BASIC or assembly language program line, it is ignored. Each valid line is written to disk as it comes in, so that it need not be stored in memory. When the upload is completed, two null lines are written (the second is as a safety precaution) and upload is concluded.
Downloading (lines 11000-11120) is automatic for a user with an Apple and a Micromodem. After offering the user a choice of files available (note that the first record of UPLOAD2 is the number of files available for downloading.) Line 11060 actually begins the downloading process. A ctrl-R is sent to the user's Micromodem to force it into remote mode. Now the ABBS is running the user's Apple. "FP" or "INT" is sent to clear memory and select the proper language. After a short pause in case Applesoft must be loaded off of a disk, the file is sent out. Downloading is terminated at the first occurence of a null line, although a null line at the outset will not terminate downloading. The "POKE PEEK . . . " line is used by the Micromodem to select full duplex so that the ctrl-T sent thereafter will return the user's ABBS to the proper state. The user is then sent an instruction on how to save the file.
OTHER ROUTINES:
Line 19000 prints a sign-off message prior to hanging up the telephone. Lines 22000-22060 print a message to people who fail to sign on successfully after three attempts. You should change this program to suit your situation. Line 22060 allows up to 9 messages to be sent to you by people without passwords. This is necessary to keep from overwriting the first character of the first message to you. (Also, without a limit certain unpleasant people might try to fill up your disk space with garbage.)
Lines 28000-28510 ("Z") are a security section. In order to access remotely certain system data, a caller must know your password, but even then they must first run the gauntlet of three or so questions to which you AND ONLY YOU should know the answers. I have set up 10 questions; you should use your own. If the answer is wrong, control passes to line 28500, which allows one wrong answer but makes you answer three more questions. The second wrong answer disconnects the caller. The questions are presented in random order so that a caller would have some difficulty setting up a program to call your ABBS repeatedly and try out answers.
The system information, which can be accessed remotely by "Z" or directly from the keyboard by entering "SYSOP" in response to the AWAITING CALL line, consists of two parts: the STARTUP file and housekeeping. The first part walks you through the STARTUP file, in the order of date (which is actually done by a routine at 4410), bulletin date, Upload password, T1$, and T2$. Hitting return by itself does not change the current entries. If any changes were made to STARTUP, they are recorded.
You are then shown any special messages that have been left for you (line 30090). You may delete these messages to clear the file for additional messages. You are then shown the number of free bytes. This is not done by the FRE(0) command, which does housecleaning before telling you the amount of free space; rather, this value is the amount of free space prior to doing any housecleaning. You will then see the number of people who have signed on, and you may clear this number if you wish. Next, the ABBS tells you if an error has occurred. If one has, you may request that the ABBS's screen be printed on your remote terminal. You may then have the option of rebooting the entire ABBS system. You should do this if an error has already occurred and you do not want the next error to shut the system down, or if some random byte has been changed erroneously. Note that resetting the system will cause the ABBS to ignore you for a few seconds, then disconnect you.
Errors are handled by lines 40000-41010. The ONERR GOTO line sends control first to line 41000, which checks for an END OF DATA error; this is not treated as an error and execution continues with the "COMMAND?" line. If this is not the cause of the error, the modem is turned off and the error number is printed on the screen. If no error has occurred before -- which will be the case if PEEK(34) is 0 -- certain key variables are printed as well. If the error were a DISK FULL or a bad response to an input statement or a ctrl-C interrupt, the ABBS continues execution with the "COMMAND?" prompt. Otherwise, the ABBS hangs up and awaits another call.
If the error is the second one to occur, line 40100 shuts down the system. You may wish to have the system reboot itself, because quite often the error will have been caused by a random glitch in memory, which can be cured by reloading DOS and WAPABBS.
Line 45000 is used as an exit by the part of ABBS1.OBJ0 that freezes up the system if program execution ends. Whenever the flashing "$33" appears, a ctrl-C from the keyboard will cause a jump to line 45000, which shuts down the modem and returns to BASIC.
AND IF YOU NEED HELP
If you require further assistance with this program, write to:
Thomas S. Warrick
ABBS SYSOP
c/o International Apple Core
908 George Street
Santa Clara, California 95050
You may also try writing me through Washington Apple Pi at Post Office Box 34511, Bethesda, Maryland, 20817, although this address may change in the future. In either case, please enclose a self-addressed, stamped envelope. (If you are a member of Washington Apple Pi, you will get our journal, which will have our current address. Membership will also entitle you to use our ABBS, which will allow you to send messages to me directly.)
SELF-IMPROVEMENTS
This program is intended to be tinkered with and improved upon. If you make any improvements or modifications, please pass them on to your fellow Apple users through the address above. An IAC member club using WAPABBS should send its name and address, its SYSOP's name, and the club ABBS phone number so that you can be informed of updates and revisions of this program as they become available.