_______ / / / ____/_____ ____ ____ _____ ______ _____ ______ / /___ / _ //___/ /__ / /___ //__ __//____//_____/ /___ // // /// //_// //__// // //___ //____ ____/ // // /// /___/ /___ / // /____//___ / / // // ///___ // || // // // //___ ____/ / /______//____//____/// // // // // /____//_____/ SOCRATES (tm) v1.10 (C) Copyright 1990 Mikronetics All Rights Reserved Documentation by Robert D. Swift Socrates BBS (v1.10) License and Distribution COPYRIGHT The SOCRATES program and all support programs described in this document and included in the SOCRATES system distribution files are copyrighted and all rights are reserved by Mikronetics and Michael A. Jacobs. THIS IS NOT FREE SOFTWARE! If you paid a "public domain" vendor for this program, you paid for the service of copying the program, and not for the program itself. Rest assured that nothing ever gets to the originators of this product from such a sale. You may evaluate this product, but if you make use of it, you must register your copy. We offer several inducements to you for registering. First of all, you receive the most up-to-date copy of the program that we have -- and we do update the product on a regular basis. You also receive support for SOCRATES -- which can be quite valuable at times. And finally, we have a few utilities not included in the evaluation package. Make no mistake, however - this is a fully functional version of SOCRATES and not "crippled" in any way. TRADEMARKS SOCRATES is a trademark of Mikronetics. Many product names found throughout this manual are trademarks of various companies. These include: BinkleyTerm Bit Bucket Software DSZ Omen Technologies Fido & FidoNet Tom Jennings and Fido Software IBM International Business Machines MS-DOS Microsoft Corp. Plato Nippon Electric Company (NEC) X.00 Raymond L. Gwinn WARRANTY AND DISCLAIMER The author makes no warranties, expressed or implied, as to the quality or performance of these programs. The author will not be held liable for any direct, indirect, incidental or consequential damages resulting from the use of these programs. Your use of these programs constitute your agreement to this disclaimer and your release of the author from any form of liability or litigation. - i - Socrates BBS (v1.10) License and Distribution DISTRIBUTION This is "user-supported" software. You are hereby granted a license to distribute this copy of SOCRATES and its documentation, subject to the following conditions: 1. SOCRATES may be distributed freely without charge in evaluation form only. 2. SOCRATES may not be sold, licensed, or a fee charged for its use. If a fee is charged in connection with SOCRATES, it must cover the cost of copying or dissemination only. Such charges must be clearly identified as such by the originating party. Under no circumstances may the purchaser be given the impression that they are buying SOCRATES itself. 3. SOCRATES must be presented as a complete unit, including this documentation. Neither SOCRATES nor its documentation may be amended or altered in any way. 4. By granting you the right to distribute the evaluation form of SOCRATES, you do not become the owner of SOCRATES in any form. Any other use, distribution or representation of SOCRATES is expressly forbidden without the written consent of Michael A. Jacobs. REGISTRATION Registering SOCRATES allows you to use the product after the trial period. Registered SOCRATES users get the current copy of SOCRATES on disk and priority when calling the SOCRATES Software support BBS (we guarantee no support to unregistered users). Most importantly, registered users know they are helping to make sure that high-quality software like SOCRATES continues to be sold in this low-cost way. SOCRATES registration costs $40 US. Payment may be in the form of check or money order in US currency. Payment should be made out to: Mikronetics 2114 Weatherton Dr. Wilmington, DE 19810 United States of America - ii - Socrates BBS (v1.10) Contents TABLE OF CONTENTS COPYRIGHT i TRADEMARKS i WARRANTY AND DISCLAIMER i DISTRIBUTION ii REGISTRATION ii TABLE OF CONTENTS iii 1. INTRODUCTION 1.1 Program Description 1 1.2 Why Socrates? 2 1.3 Acknowledgements 3 1.4 System Requirements 4 1.5 SOCRATES Files 4 2. INSTALLING SOCRATES 2.1 The SOCRATES Directory 6 2.2 Conditions, Signals and States 6 2.3 The Initialization File 7 2.4 Message Areas and Directories 10 2.5 File Areas and Directories 11 2.6 SOCRATES Program File 13 2.7 Bulletins And Display Files 14 3. SOCRATES PROGRAM FILE 3.1 Overview 15 3.2 Menus 15 3.3 Responses 17 3.4 Commands 20 3.5 File Lists 24 3.6 Shells and Parameters 25 3.7 Putting It All Together 26 4. RUNNING SOCRATES 4.1 Command Line Parameters 28 4.2 User's Special Keys 28 4.3 Running Stand-Alone 29 4.4 Running With A Front End 30 4.5 Re-Entering SOCRATES 32 5. THE SYSTEM OPERATOR'S ROLE 5.1 SysOp Commands 33 5.2 User File Maintenance 34 5.3 Message Area Maintenance 35 5.4 Socrates Type Message Linking 37 - iii - Socrates BBS (v1.10) Contents APPENDIX 1 - Use of Delimiters 38 APPENDIX 2 - Evaluating Conditions 39 APPENDIX 3 - Initialization File Settings 43 APPENDIX 4 - BBS Program Commands 72 APPENDIX 5 - Shell Parameters 144 APPENDIX 6 - TimeBanks & Multipliers 145 APPENDIX 7 - FidoNet 147 APPENDIX 8 - Registration Form 148 INDEX 149 - iv - Socrates BBS (v1.10) Introduction 1. INTRODUCTION 1.1 Program Description The SOCRATES BBS package has been designed to provide the ultimate in flexibility. It can be better described as a BBS "construction set" because all of the menus, user responses and system activities are defined by the SysOp. In a sense, the SysOp is actually a "system programmer" and SOCRATES executes the "programmed" configuration. In addition to the usual programmable menu choices found in other systems, SOCRATES even allows you to choose the format of the message bases used. These can be either sequential message bases such as used in most FidoNet style BBS programs, or you can choose to use SOCRATES' own message base format. The SOCRATES message base groups messages in an area by subject, thus allowing you to quickly access all messages related to a particular topic. SOCRATES is fully FidoNet compatible when used with a front- end mailer such as BinkleyTerm. In addition, the message areas can be set up Fido style so that existing message utilities can be used. Ease of operation, flexibility and compatibility are the major strengths of SOCRATES. If this is what you are looking for in a BBS, look no further... SOCRATES is here! - 1 - Socrates BBS (v1.10) Introduction 1.2 Why Socrates? I have never been one to easily fit into molds. Although many BBS systems out there are 'configurable', one could never make any real changes. Change the text in the menus, alter the messages, sure, but it was still the same thing. So, being a habitual programmer, I started work on my own BBS program. As all good programmers should do, I broke the problem down into its components. At first, I was just going be yet-another-custom-BBS, but it occurred to me, there must be many other malcontents out there as well, but who don't have the time to write their own BBS program. And thus became my vision of a meta-BBS system, where all the BBS functions would be there, and it could be up to the Sysop to decided how he/she/it wants to put it together. Individuality, what a concept! So now you're saying, 'Ok, that answers "Why Socrates?," but why "Socrates?"'. At the University of Delaware, (where I learn the underlying principal of this arcane art) there was this obscure mainframe system called 'Plato' (ah ha! a clue...). On it, there was a message system called 'notesfiles' which worked in a subject based system: each subject had a base note and a list of associated responses. I liked this system much better then the way Fido and the gang dealt with it. Even when using links, after reading a subject, you still had to wade through the notes again when you move on. But on Plato, if you weren't interested in a subject, just go on to the next one. So, I borrowed this idea and wrote myself a message reader. At the time, though, I wasn't very well studied up on Ancient Greece, and chose to called it Socrates, thinking it was Plato who taught Socrates. As it happened, I was wrong; Socrates taught Plato who taught Aristotle (who taught Alexander the Great who conquered Greece, Asia Minor, and Persia and was eventually declared ZC of Zone 2.) But Aristotle was 9-letters long, and Socrates was the magical 8-letters long, and .SOC made a good extension for my system files, so Socrates it was. - 2 - Socrates BBS (v1.10) Introduction 1.3 Acknowledgements I'd like to thank the academy, my family, the director, the producer, my good friend Jack Nicholson... The most thanks to goes to Bob Swift, the man who took the crap I wrote as documentation and turned it into this lovely work of art. I also appreciate the efforts of my beta-testers who, I'm assuming from their lack of responsiveness, found absolutely no bugs... ... and Mike Epler who told me what he wanted for files functions when I had no concept. And of course, Thomas Jefferson. Michael A. Jacobs aka Mike J (FidoNet 1:150/199) - 3 - Socrates BBS (v1.10) Introduction 1.4 System Requirements SOCRATES will run on an IBM PCjr, PC, XT, AT, PS/2, or true compatible with one hard drive and one floppy drive, or two floppy drives, and with at least 200k of free memory. For a few functions, such as the DOS Shell, more memory may be required. SOCRATES will also require that a FOSSIL program be loaded and, of course, a modem. To get full use of SOCRATES your modem must meet certain standards as well. The Carrier Detect signal should not be forced high (on) by the modem, so that SOCRATES can tell when you are on-line. This is usually controlled by the setting of a dip switch on the modem, or a modem command. The DTR (Data Terminal Ready) signal should not be ignored by the modem. 1.5 SOCRATES Files SOCRATES requires that the following files be located within the system PATH: RELOGIN.EXE - Re-enter Socrates after exit SOC-MSG.EXE - Maintains message areas SOC-SCAN.EXE - Maintains Socrates message areas SOC-USER.EXE - Maintains user file SOCRATES.EXE - The SOCRATES program itself In addition, the following files are used when setting up or modifying the BBS configuration and must be in the system PATH: CR-AREAS.EXE - Compile message area index CR-FILES.EXE - Compile file area index CR-INITS.EXE - Compile initialization file CR-SOC.EXE - Compile configuration file - 4 - Socrates BBS (v1.10) Introduction SOCRATES requires the following files to be in the current directory when the program is started. These files are created using the compile programs listed above: AREAS.SOC - Message area index COMM.SOC - Command list COMMINDX.SOC - Command list index FILES.SOC - File area index FLST.SOC - Files list FLSTINDX.SOC - Files list index INITS.SOC - Initialization data MENU.SOC - BBS menus MENUINDX.SOC - BBS menus index MULT.SOC - Download & Time limits MULTINDX.SOC - Multiplier index QUOTETRK.SOC - Quotes file pointer (if req'd) RESP.SOC - User responses RESPINDX.SOC - User responses index The following files contain the user data for the BBS and must be in the current directory when SOCRATES is started. If these files are missing, they will be created when a user logs onto the system or when SOC-USER is run: USERS1.SOC - User data USERS2.SOC - User data USERS3.SOC - User data The SOCRATES archive contains the following files: CR-AREAS.EXE - Compile message area index CR-FILES.EXE - Compile file area index CR-INITS.EXE - Compile initialization file CR-SOC.EXE - Compile configuration file READ_ME.1ST - Last minute release notes RELOGIN.EXE - Re-enter Socrates after exit SOC-AREA.TXT - Sample message area file SOC-FILE.TXT - Sample files area file SOC-INIT.TXT - Sample initialization file SOC-MSG.EXE - Maintains message areas SOC-PROG.TXT - Sample program definition file SOC-SCAN.EXE - Maintains Socrates message areas SOC-USER.EXE - Maintains user file SOCRATES.DOC - This documentation file SOCRATES.EXE - The SOCRATES program itself SOCRATES.REG - Registration form SOCRATES.REV - Revisions list SAMPLE.ZIP - Various example files - 5 - Socrates BBS (v1.10) Installing Socrates 2. INSTALLING SOCRATES 2.1 The SOCRATES Directory As with installing any new program on your system you have to start at the beginning. That is, "Where do I put it?" Although the Socrates programs can be placed anywhere in your path, it is strongly recommended that you create a separate sub-directory for the BBS. Throughout this document, we will use the example of the files installed in the C:\SOCRATES sub-directory. Okay, you have a directory. Now, what goes into this directory? First, copy all the files from the distribution disk (or archive) into the directory. This will provide you with much of what you need but there are still a few things that have to be done before you have a fully functional, working system. You will have to create sub-directories for the file and message areas that you want to keep, as well as customizing and compiling the configuration and program files. Sound complicated? It really isn't if you take your time and work through it one step at a time. 2.2 Conditions, Signals and States You're probably thinking to yourself, "what do they mean by conditions, signals and states?" Simply put, these provide the flexibility and programming power of the SOCRATES bulletin board system. Signals are like "keys" assigned to a user. The command files can check if a user has a certain signal enabled and perform differently depending on whether they do or don't. This is useful for setting conditions independent of a user's privilege level. There are 256 signals available, numbered from 0 to 255. States are similar to signals except that they are set by the system while a caller is on-line and are reset when the caller logs off. These are useful for setting conditions depending on what has happened while the user is on line, such as only allowing one time through a bulletin or only paging the SysOp once. There are 256 states available, numbered from 0 to 255. Conditions are constants, variables or formulae that evaluate to either a logical true or false state. These can then be applied to some of the lines in the initialization file and most of the lines in the program file to alter the way the SOCRATES engine deals with these command lines. See APPENDIX 2 for a complete list of the constants and variables used in defining conditions. - 6 - Socrates BBS (v1.10) Installing Socrates 2.3 The Initialization File This is the file that tells the SOCRATES engine a little about your system and how to communicate with your modem. This file is a straight text file and can have any valid file name. There is no default name but a commonly used name is SOC-INIT.TXT (pronounced sock-in-it). The initialization file commands include the following groups: Modem Settings PORT comm port BAUD default baud rate MODEMINIT initialization string MODEMHANGUP hang-up string Logon Settings NAMEPROMPT user name prompt string PASSWORDATTEMPTS maximum password attempts LOGONTIME maximum time to log on PRIVATESYSTEM no new users allowed FORGOTPASSWORDCOMM wrong password commands FORGOTPASSWORDMENU wrong password menu New User Settings NEWUSERPRIV privilege level NEWUSERHELP help level NEWUSERCOMM1 commands before password NEWUSERCOMM2 commands after password NEWUSERSCREENWIDTH screen width NEWUSERSCREENLENGTH screen length NEWUSERSIGNALS initial signals NEWUSERMENU first menu displayed Menu and Display Screen Settings WELCOMECOMM welcome file displayed INTROCOMM commands after logon FIRSTMENU first menu displayed FidoNet Settings ZONE zone number NET net number NODE node number POINT point number - 7 - Socrates BBS (v1.10) Installing Socrates Time Limit Settings TIMELIMIT time limits multiplier SESSIONTIMELIMIT default time limit for session DAILYTIMELIMIT default time limit for day EXCEEDEDDAILYTLIMCOMM commands after max time ONLINEUPLOADREFUND on-line refund multiplier ACTIVETIMEBANKUPLOADREFUND active time bank refund multiplier PENDINGTIMEBANKUPLOADREFUND pending time bank refund multiplier DAILYTIMEBANKROLLOVER daily pending to active timebank transfer Message Area Settings CLEARBEFOREMESSAGE clear screen before msg CUTATSEENBY don't show SEEN-BY lines READPRIVATE allow reading private msg WRITEPRIVATE allow writing private msg FORCEPRIVATE force msg to be private ALIAS use alias in FROM: field ANONYMOUS use anonymous name in msg ANONYMOUSNAME anonymous name to use FIDONET identify netmail area DEFAULTCRASHON default "crash" setting DEFAULTFILEATTACHON default "attach" setting DEFAULTKILLSENTON default "kill" setting SETCRASH allow changing "crash" SETFILEATTACH allow changing "attach" SETKILLSENT allow changing "kill" ALLOWQUOTING allow user to quote SKIPMESSAGEINPUT skip initial msg input APPENDORIGIN add ORIGIN: line ORIGINLINE ORIGIN: line string EDITOUTSIDEFILE filename for outside edit File Area Settings FILESLISTFILE name of file list file SHOWFILEDATE display file date FILESMULT files limits multiplier SESSIONBYTESTHRESHOLD max session d/l bytes DAILYBYTESTHRESHOLD max daily d/l bytes TOTALBYTESTHRESHOLD max total d/l bytes SESSIONFILESTHRESHOLD max session d/l files DAILYFILESTHRESHOLD max daily d/l files TOTALFILESTHRESHOLD max total d/l files SESSIONBYTESRATIO max session d/l:u/l ratio DAILYBYTESRATIO max daily d/l:u/l ratio TOTALBYTESRATIO max total d/l:u/l ratio SESSIONFILESRATIO max session d/l:u/l ratio DAILYFILESRATIO max daily d/l:u/l ratio TOTALFILESRATIO max total d/l:u/l ratio - 8 - Socrates BBS (v1.10) Installing Socrates Miscellaneous Settings HOTKEYS select hot key operation USEPAUSEKEY use new pause key PAUSEKEY new pause key to use USESTOPKEY use new stop key STOPKEY new stop key to use MOREPROMPT string for full screen LOGFILE system log filename INACTIVITYTIMELIMIT inactivity before logoff DEFAULTTIMESCALLEDTHRESHOLD base number for times called TIMESCALLEDMULT calls limit multiplier DEFAULTSINCELASTCALLEDTHRESHOLD base number for time since last called SINCELASTCALLEDMULT time since last call limit multiplier STARTCHATMSG string at start of chat ENDCHATMSG string at end of chat USERDELETE user deletion criteria See APPENDIX 3 for a complete description of the command settings and their use. Note that all blank lines are ignored as well as anything following a semi-colon (;) in a non-blank line. This will allow you to insert comments in your control files. The maximum line length allowed in the control file is 127 characters. Once the initialization file is complete, it will have to be compiled before SOCRATES can use it. This is done by executing the CR-INITS.EXE program which will read the initialization file and produce the compiled files MULT.SOC and INITS.SOC which SOCRATES will use. The CR-INITS.EXE program is executed as follows: CR-INITS Note that you will have to re-compile the initialization file each time after a change is made before the change will take effect. - 9 - Socrates BBS (v1.10) Installing Socrates 2.4 Message Areas and Directories Now that you have the initialization file completed, the next step is to set up your message areas. First, you should decide what areas you wish to have on your system and whether these areas will be used as Fido areas or SOCRATES areas. You will then need to create a sub-directory for each area. For our example, we will set up a general message area for all users, a private message area for higher priority users, and a Fido NetMail area. We would create the sub- directories: C:\SOCRATES\MSGAREAS\GENERAL C:\SOCRATES\MSGAREAS\PRIVATE C:\SOCRATES\MSGAREAS\NETMAIL Now that we have our directories, we have to tell SOCRATES about them. This is done in the areas definition file which is an ordinary text file. There is no default file name for this file but a commonly used name is SOC-AREA.TXT. This file is quite straightforward because each line defines a message area and only contains two entries, path to message area and message area type, separated by spaces. The path to the message area need not end in a trailing backslash. The message area type entry must be either Fido or Socrates. Remember that the Socrates areas differ from the Fido areas in that they are subject-oriented and special index files are maintained in the sub-directory. If the area type entry is missing, SOCRATES will assume that the area is a Fido area. Each message area listed in the definition file is assigned a number by SOCRATES, sequentially beginning with 1. This message area number is the number used for the "a=" comparisons when setting conditions. Note that all blank lines are ignored as well as anything following a semi-colon (;) in a non-blank line. This will allow you to insert comments in your control files. The maximum line length allowed in the control file is 127 characters. - 10 - Socrates BBS (v1.10) Installing Socrates Once the message area definition file is complete, it will have to be compiled before SOCRATES can use it. This is done by executing the CR-AREAS.EXE program which will read the definition file and produce the compiled file AREAS.SOC which SOCRATES will use. The CR-AREAS.EXE program is executed as follows: CR-AREAS Note that you will have to re-compile the message area definition file each time after a change is made before the change will take effect. 2.5 File Areas and Directories If you plan to have any areas for uploading or downloading on your system, you will have to set these up as file areas. First, you should decide what areas you wish to have on your system and then you will then need to create a sub-directory for each area. For our example, we will set up a public file area for all users, a private file area for higher priority users, and a Fido Network files area. We would create the sub- directories: C:\SOCRATES\FILEAREA\PUBLIC C:\SOCRATES\FILEAREA\PRIVATE C:\SOCRATES\FILEAREA\NETFILES Now that we have our directories, we have to tell SOCRATES about them. This is done in the areas definition file which is an ordinary text file. There is no default file name for this file but a commonly used name is SOC-FILE.TXT. This file is quite straightforward because each line defines a file area and only contains two entries, path to download area and path to upload area, separated by spaces. The paths to the areas need not end in trailing backslashes. If the upload path entry is missing, SOCRATES will assume that the upload path is the same as the download path. Each file area listed in the definition file is assigned a number by SOCRATES, sequentially beginning with 1. This message area number is the number used for the "FA=" comparisons when setting conditions. - 11 - Socrates BBS (v1.10) Installing Socrates Note that all blank lines are ignored as well as anything following a semi-colon (;) in a non-blank line. This will allow you to insert comments in your control files. The maximum line length allowed in the control file is 127 characters. Once the file area definition file is complete, it will have to be compiled before SOCRATES can use it. This is done by executing the CR-FILES.EXE program which will read the definition file and produce the compiled file FILES.SOC which SOCRATES will use. The CR-FILES.EXE program is executed as follows: CR-FILES Note that you will have to re-compile the file area definition file each time after a change is made before the change will take effect. Now that you have your file area control file compiled, you have one more thing to do before your system's file areas are ready. That is to build a files list file in each of the specified download areas. The name of this file list file is defined by the FILESLISTFILE entry in your initialization file. The files list file is a text file listing the files available for download in that area. Each file is listed on a separate line, followed by a description which will be displayed to the user when they ask for a list of the files. If the first character on a line is a space or an asterisk, then the line is displayed as is. If the first character is an at-sign (@), then the remainder of the file is not displayed. Otherwise, all characters up to the first space are considered a filename and the download directory is searched for that file. If the file is found, SOCRATES will display the filename, the file size and the remainder of the line. If the file is not found, SOCRATES will display the filename, a brief message that the file is unavailable and the remainder of the line. - 12 - Socrates BBS (v1.10) Installing Socrates 2.6 SOCRATES Program File This is the file where you get to let SOCRATES know the design of your BBS and how it should operate. The program file contains the code for all of the BBS menus, the valid user responses and the actions that SOCRATES should take as a result of the various responses. In short, this is where you get to program your BBS. The SOCRATES program file is an ordinary text file. There is no default file name for this file but a commonly used name is SOC-PROG.TXT. There are four types of modules in the SOCRATES program file. These modules are menu, response, command and filelist. Some of the modules have "special codes" associated with them as well as a set of commands. See APPENDIX 4 for a complete description of the program commands and their use. In addition, a sample program file is included to demonstrate some of the features of the system. Note that all blank lines are ignored as well as anything following a semi-colon (;) in a non-blank line. This will allow you to insert comments in your control files. The maximum line length allowed in the control file is 127 characters. Once the program file is complete, it will have to be compiled before SOCRATES can use it. This is done by executing the CR-SOC.EXE program which will read the program file and produce the compiled files MENUINDX.SOC, MENU.SOC, RESPINDX.SOC, RESP.SOC, COMMINDX.SOC, COMM.SOC, FLSTINDX.SOC and FLST.SOC which SOCRATES will use. The CR-SOC.EXE program is executed as follows: CR-SOC [filename] [filename] ... Note that you will have to re-compile the program file each time after a change is made before the change will take effect. - 13 - Socrates BBS (v1.10) Installing Socrates 2.7 Bulletins And Display Files The other files used by SOCRATES are files which are displayed to the user. These files can be either ASCII or ANSI (or just about anything else) and SOCRATES can be programmed to send the appropriate type of file depending on the terminal type defined by the user (or by screen width, et cetera). These files can be defined by the initialization, such as welcome files, or they can be defined in the program file. Some examples of display files defined in the program file are help screens or bulletins. These files need not be compiled for SOCRATES to use them. - 14 - Socrates BBS (v1.10) Socrates Program File 3. SOCRATES PROGRAM FILE 3.1 Overview As stated earlier, the SOCRATES program file is where you can design the way that the SOCRATES engine will execute your BBS. This file is comprised of a number of modules, each module defining part of the system. Each module may be a menu, response list, command list or file list, and is identified by the type and an assigned name. The lines that follow a module label form the module itself until the end of the file or the occurrence of the next module label. Each of the module types is described below. A complete list of the program commands can be found in APPENDIX 4. 3.2 Menus The menu module begins with a line like: MENU