C I T A D E L - 8 6 V3.40 INSTALLATION MANUAL Copyright 1989 - 1991 by Hue, Jr. C-86 Test System Sysop (612) 470-9635 91Oct07 Table of Contents I. Introduction & Requirements . . . . . . . . . . . . . . . . 2 I.1 ... but first, a caveat. . . . . . . . . . . . . . . . . 2 I.2 Introduction . . . . . . . . . . . . . . . . . . . . . . 2 I.3 Requirements . . . . . . . . . . . . . . . . . . . . . . 3 II. Installation . . . . . . . . . . . . . . . . . . . . . . . 4 II.1 Tickling DOS configurations . . . . . . . . . . . . . 4 II.2 Making your modem do the right thing . . . . . . . . . 4 II.3 Citadel-86 Operating Procedures (and other epic fantasies) . . . . . . . . 5 II.3.a Who's this masked Temporary file, anyways? . . 6 II.3 (con't) . . . . . . . . . . . . . . . . . . . . . . . 6 II.4 Other Data Files . . . . . . . . . . . . . . . . . . . 7 II.5 EASE . . . . . . . . . . . . . . . . . . . . . . . . . 8 II.6 The ole' configuration file . . . . . . . . . . . . . 8 II.6.a But first, a word on moral values ... . . . . . 9 II.6.b Section 1 of CtdlCnfg.Sys . . . . . . . . . . . 10 Part 1 of Section 1: Meaningless Miscellanea . . . . 10 Part 2 of Section 1: Required Odd Stuff . . . . . . 12 Part 3 of Section 1: Data File Sizes . . . . . . . . 13 Part 4 of Section 1: Data File Locations . . . . . . 14 Part 5 of Section 1: Policy Options . . . . . . . . 15 Part 6 of Section 1: Modem Handling . . . . . . . . 18 Part 7 Video Options . . . . . . . . . . . . . . . 22 II.6.c Section 2 of CtdlCnfg.Sys . . . . . . . . . . . 22 II.6.d Section 3 of CtdlCnfg.Sys . . . . . . . . . . . 32 II.7 The Big Step -- Your first experience with CONFG . . . 36 II.8 CTDL -- That Childhood Experience . . . . . . . . . . 37 II.9 When the inevitable happens . . . . . . . . . . . . . 38 II.10 Installation -- Advanced Topics . . . . . . . . . . . 38 II.10.a Command Line options . . . . . . . . . . . . . 38 II.10.b BAT files and program termination ERRORLEVELS. 40 II.10.c Making BAT files and command line options work for you . 41 II.10.d Result Code and Call Progress Detection . . . 43 II.10.d.1 Restrictions on Result Codes . . . . . . . . 46 II.10.e Extreme options in CtdlCnfg.Sys . . . . . . . 46 III. Zenith Z-100 Notes . . . . . . . . . . . . . . . . . . . . 48 III.1 Introduction . . . . . . . . . . . . . . . . . . 48 III.2 Scary but Innocuous Behaviors . . . . . . . . . 48 III.3 Result Codes . . . . . . . . . . . . . . . . . . 48 Appendix -- Exhibit copy of CtdlCnfg.Sys. . . . . . . . . . . . 50 -1- I. Introduction & Requirements Hi. This is the Citadel-86 Installation Manual. This manual comes in three parts. In the first part we hope to present a very short intro- duction to Citadel-86 and give you an idea of the requirements of running Citadel-86. The second part of the Manual will contain a comprehensive (we hope!) discussion of general operation of Citadel-86 and a step-by-step installation guide. The third section contains notes specific to the Zenith Z-100, as contributed by both the author of this manual and System Operators using Z-100s as their hardware platform. If you are looking for documentation covering the day to day operations of Citadel-86, please read OPER3.MAN. Just ignore the blood spots in there ... I.1 ... but first, a caveat. Citadel-86 has a number of eccentricities in it; in fact, some people might describe it as one giant eccentricity, and an explanation is, perhaps, in order. One of the authors of this manual, Hue, Jr., is also the principal porter and caretaker of Citadel-86. Citadel-86 derives directly from the version 2.10 of Citadel written by Cynbe ru Taren for CP/M, and contains a number of the apparent oddities that originally appeared in Cynbe's code. Hue, Jr., feeling there may have been certain reasons in Cynbe's mind for what he did, has been somewhat loathe to change how certain things worked. This may indicate a certain lack of ambition on his part; if so, so be it. Whatever the case, he has chosen to leave them in, due to his faith in Cynbe knowing what he was doing. I.2 Introduction Citadel-86 is part of a growing family of BBSes characterized as "room-based" systems. These systems are excellent messaging systems in which the message base is partitioned into various 'areas', enhancing the focus of the topics on the installation (if well-managed); the areas are usually termed 'rooms' in order to provide a highly familiar metaphor for the common user. Some room-based systems have an additional structure added on to them, known sometimes as 'hallways' or 'floors', which give addition focus. Citadel-86 has a 'floor' capability, which is optionally available to the users. Floors allow the sysop and aides to partition the collection of rooms into 'subject floors' (or 'topical floors'), so rooms may be grouped as needed. Room-based systems normally feature an extremely streamlined set of commands, in which those used the most often are mnemonic 'single-stroke' commands whereby the user supplies the first letter of the command to execute and the system provides the rest of the command. The speed and ease-of-use of such a command set, in conjunction with the room concept, has combined to make room based systems extremely popular and heavily used in several sections of the United States. Citadel-86 also has file upload and download abilities, integrated with the room metaphor, and a network capability. -2- I.3 Requirements There are a number of requirements connected with running a Citadel-86 system. The most important one, though, is perhaps the most ignored, and that is experience with Citadel-86 or similar BBS software from a user standpoint. It can't be stressed enough that you should have at least a month of day-to-day experience with Citadel-86 as a normal user, learning the various commands relating to messages and files, and in general becoming not only familiar, but comfortable with the Citadel-86 style of bbsing before descending into sysopdom. More formally, Citadel-86 is capable of running on two classes of machine. The first is the Zenith Z-100, an 8085/8088 machine. The second category contains the IBM PCs, ATs, and close clones (note a Z-100 does NOT constitute a close clone, although it is supported). These two classes are similar enough that we do not need to discuss the requirements for each class separately. However, please note the two different machines require different executable files (unlike earlier versions of Citadel-86). o Operating System: PC- or MS- DOS 2.x or 3.x is required. While not every single version of DOS between 2.x and 3.x range has been tested with Citadel-86, we have not had any reports of problems with those versions of DOS. Version 1.x of MSDOS is a NO NO! o RAM: We suggest at least 350K RAM be made available to Citadel-86. This is in addition to RAM for MS-DOS, TSR programs, etc. o Disk storage: A hard disk is, naturally, highly desirable. However, you can run Citadel-86 on a two floppy system, but if you must do so, you should also try to make sure you can have a relatively large RAM disk available; due to Citadel-86's structure, disk access is quite frequent. While hard drives (and RAM drives!) do not mind frequent disk accesses, floppy drives have been known to burn out under constant usage unless certain options concerning RAM drives are taken advantage of within Citadel-86. o An auto-answer modem and the hardware (cables, etc.) requisite to hook it up to your computer: While a Hayes or compatible is by far the most popular modem in usage, Citadel-86 can be configured to use several other types of modems. o A copy of the Citadel-86 software: Typically, Citadel-86 comes in the form of three archives. The first is called RUNTIME.LZH, and is absolutely necessary. It contains the required executables to bring Citadel-86 up, various help files, and a configuration file. The second is called SUPPORT.LZH, and contains what little documentation is available for Citadel-86. It is not strictly necessary, but useful (or at least comforting). The third is called UTIL.LZH (and sometimes comes as two archives), and contains the utilities available for Citadel-86. (If you don't have these, they may possibly be on Test System in a room called Necessities].) o Some patience! -3- II. INSTALLATION In this section we explore the installation procedure for Citadel-86, investigating territory ranging from a general overview of the operating procedures of Citadel-86 to the details of setting up a system. We'll begin with a very short section on DOS and modem configuration. Then we get to the red, raw meat of Citadel-86: a description of how to prepare and operate Citadel-86, and a discussion of the data files Citadel-86 needs or generates. Next will be a walk-through of actually setting up a basic Citadel-86 installation, at the end of which you should have a working Citadel-86 system. Easy, right? II.1 Tickling DOS configurations First comes the only required DOS configuration you must perform. You must place the line "FILES=20" in your CONFIG.SYS file on your boot disk. If such a line already exists (or more than 20 is specified), then you don't need to worry about anything. If such a line doesn't exist, then please put it into CONFIG.SYS, save the file, and reboot your system so it'll take effect. IF YOU DON'T, CITADEL WILL BE VERY PEEVISH! If you don't understand what we're gabbing about, then please consult your DOS manuals. CONFIG.SYS is an important part of the DOS system; it will do you good to learn what it's about. We AREN'T going to discuss DOS batch files in here. We'll leave that for a later advanced section, because Citadel-86 exits with different ERRORLEVELs; the exact levels vary with the reason Citadel-86 exited. We feel it would be better not to cause excess confusion now, because you'll be confused soon enough as it is. We AREN'T going to discuss Citadel-86 command line parameters here, either. While such things exist, we deem these to be the subject of an advanced section, and so we leave them for later attention in this manual. II.2 Making your modem do the right thing The Citadel-86 basic requirements in the area of modems are: o Modem can be hooked up to the computer o Modem can auto-answer the phone o Modem supports true carrier detect (very preferably on pin 8) o Modem can be hung up That sounds pretty darn basic, and it is. However, if you want to take advantage of some of the default configurations of Citadel-86 for the modem, here's what we suggest for your modem in terms of characteristics: o Hayes or (semi) compatible or o Carrier detect on pin 8 (normal for most modems) o Carrier hangs up modem when DTR is dropped -4- Like we said, Citadel-86 is not restricted to Hayes/compatible modems, although they are of course the most popular modem used. But other modems, such as TransModems, have been used successfully with Citadel-86. This makes our job, as the manual writers, substantially more difficult. Due to the overwhelming popularity of the Hayes compatible modems, we're going to confine most of our advice on modem configuration to Hayes and compatibles. The first thing to bear in mind is "compatible" is often a slippery term. Our advice is based on our own experience with our Hayes compatible modems; if what we say doesn't seem to jibe with your modem's documentation, then use a little imagination and search the manuals. Hayes modems are not normally correctly configured fresh from the factory, so you must configure yours. Usually, a combination of two methods are used to achieve the correct configuration. First, DIP switches on the modem usually control several different functions, including auto-answer mode. However, on some Hayes compatibles they don't exist; the functions they usually serve are then either accessed via software, or not at all. Second, (as you might have guessed), software can be used to configure the modem, through the use of AT commands. We strongly suggest you have your modem manual available at this point. First, you want to make sure your modem will drop carrier when DTR is dropped; the opposite of this is sometimes called the "forced DTR" function, and can be found in the DIP switches. Make sure the modem does not have "forced DTR" on. Next, you need to ensure the modem is not "forcing carrier detect". Instead, it should only have carrier detect true when there is actually a caller online; otherwise your Citadel-86 will not work correctly. Finally, you want to make sure the modem will auto-answer when Citadel-86 is up. This can be selected either by DIP switch or through software. If you have a modem with a DIP switch controlling this function, you may want to use software instead, for finer control of how your modem acts. You'll find later in this manual you can specify a string of commands to be sent to the modem when Citadel-86 first comes up, which you can use to activate auto-answer mode. The above comments apply equally well to non-Hayes compatible modems, although the details of how to initialize the modem will differ greatly. More detail on initialization of the modem will appear later in this manual in Section II.6.b: Part 6 of Section 1: MODEM HANDLING. II.3 Citadel-86 Operating Procedures (and other epic fantasies) Citadel-86 comes with a whole mess of files. However, only three of these files are important, because they constitute the beginnings and necessities of Citadel-86. They are: -5- o CtdlCnfg.Sys. This file will contain your description of how you want your system set up. Decisions concerning the location of important data files, system policies, and other semi-arcane things are described for Citadel-86's use. The CtdlCnfg.Sys accompanying your system is a template of a very generic system, and we plan to guide you through it later in this manual. o CONFG.EXE. This executable program digests CtdlCnfg.Sys, converting the information contained therein into a form far easier to digest by computer programs. It is also responsible for generating new data files when necessary (typically only when a new system is first built!) and analyzing old data files. It produces a highly temporary yet necessary file called CTDLTABL.SYS. o CTDL.EXE. This is the main executable program of Citadel-86. It expects to find CTDLTABL.SYS (remember the name?). If it finds it, it reads it, erases it, and then continues to try to bring up the rest of the system, using the information it found in CTDLTABL.SYS. If there are no severe abnormalities during CTDL.EXE's use, it will write a new version of CTDLTABL.SYS for use the next time you bring up CTDL.EXE. II.3.a Who's this masked Temporary file, anyways? CTDLTABL.SYS has been passed off so far as a temporary file, generated by CONFG.EXE from digesting CtdlCnfg.Sys, and required by CTDL.EXE. However, for a mere temporary file it merits more discussion. We said CTDL.EXE expects to find it; you may have figured out if it's not there, then CTDL.EXE won't function properly. This is correct, and the proper corrective action is to run CONFG.EXE. DON'T TRY TO USE AN OLD VERSION OF CTDLTABL.SYS THAT YOU MAY HAVE SAVED IN CASE OF A CRASH! Yes, we know running CONFG.EXE to generate a new CTDLTABL.SYS can take a while if you're running a big system. We mentioned CONFG.EXE analyzes data files; as it happens, the results of this analysis is also placed in CTDLTABL.SYS, and used to enhance access to various parts of Citadel-86, such as the log. If you use an old version of CTDLTABL.SYS, the older information can cause Citadel-86 to look for messages that no longer exist, lose track of new rooms and log accounts, and other behaviors a sysop generally finds disruptive to domestic tranquility. So, really, "Just say no." Run CONFG.EXE if you lose your current CTDLTABL.SYS through a crash or power loss. (This can be automated. See section II.9 for advice on batch files.) II.3 (con't) Back to the subject. We now know the purposes of the three primary files of Citadel-86. CtdlCnfg.Sys contains information only the sysop can supply; CONFG.EXE processes CtdlCnfg.Sys, producing CTDLTABL.SYS and other data files; CTDL.EXE requires CTDLTABL.SYS, and constitutes the main executable of Citadel-86. So, in short form, here's how you run Citadel-86: o Modify CtdlCnfg.Sys to taste. o Run CONFG.EXE. o Run CTDL.EXE as many times as desired, as long as each run is terminated normally. If you crash, either from a fatal bug or power loss or whatever, just run CONFG.EXE again. -6- II.4 Other Data Files When you run CONFG.EXE for the first time, a number of data files are created, and they're what we're going to talk about in this section. These files contain the information -- accounts, rooms, messages, and other things -- making up any BBS. The capacities of these files are selectable by the sysop, and once selected they remain the same size as CTDL.EXE runs (don't panic, though -- they can be changed through the use of Citadel-86 utilities!). And with no more delay.... o CTDLMSG.SYS. This file contains all the messages in the system. o CTDLROOM.SYS. This file contains information about the rooms in your system. The size of this file is given later in this manual. o CTDLLOG.SYS. This file contains all the accounts for users on your system. The size of this file is given later in this manual. o CTDLNET.SYS. This file, if it exists, will be 0 bytes long when initially generated by CONFG.EXE, and will grow as the network grows (NETWORK3.MAN talks about C86Net). o CTDLFLR.SYS. This file contains information about the floors in your system. It grows as you add floors to your system. Don't panic, though. Each floor only takes 21 bytes. These, however, are not the only data files associated with Citadel-86. CTDL.EXE may, on occasion, generate data files also. These files, unlike those generated by CONFG.EXE, are not static; however, they are almost always very small. o CTDLARCH.SYS. This file contains data about auto-archiving of rooms (an advanced topic covered in OPER3.MAN.) o CTDLNET.SYS. This file, created by CONFG.EXE, will be expanded by CTDL.EXE if you are participating in a network. o CALLLOG.SYS. This file, an optional text file, is updated as each caller hangs up. See #AUDITAREA. o CTDLDIR.SYS. This file contains data about the directory rooms on your system, specifically the name of the DOS directory associated with each directory room on your system. o CTDLMODR.SYS This file contains data about the room moderators on your system. o CTDLFWD.SYS This file contains information about mail forwarding by individual users if you are on the net. o FILELOG.SYS. This file, another optional text file, is updated as users upload and download files. See #AUDITAREA. o DOORUSE.SYS. This file, another optional text file, is updated as users use your doors. See #AUDITAREA. o Net Files. CTDL.EXE also generates a variety of small network files, both temporary and permanent, for internal use. See NETWORK3.MAN for more information on these files (Appendix B). There are also the collection of help files accompanying Citadel-86, which we talk about in OPER3.MAN. -7- II.5 EASE! Released sometime in the last half of June, 1989, Citadel-86 Sysops have an alternative to the normal method of both constructing a new Citadel-86 installation and modifying the system. This is the EASE utility program, which should be in its own archive, EASE.LZH. As we indicated above, Citadel-86's description file is CtdlCnfg.Sys which the Sysop must modify before installing a new system. Although not a particularly wearisome task in itself, it can still be something of a pain to a new sysop as well as the more experienced sysop. For this reason, and, hey, just for the fun of it, the EASE program has been provided. EASE is just what it's named: it will ease both the installation and modification processes. At this point we'd like to urge you to do two things if you have EASE. First, read, perhaps swiftly, section II.6 below to get a feel for what is in CtdlCnfg.Sys, but don't try to modify the generic CtdlCnfg.Sys, nor should you try to initialize a new system, despite the suggestions below. Second, copy EASE.EXE, EASE.HLP, EASE2.HLP, MODEMS, CONFG.EXE, CtdlCnfg.Sys and CTDL.EXE into the directory in your system which will be the home directory for your installation. Once you have done so, simply type EASE and follow the directions. At the end of EASE, the system will hopefully be initialized with a complete CtdlCnfg.Sys and most of the data files you need, and you'll be ready to start playing -- far faster than the traditional form of installation for Citadel-86. To summarize, and if you have a hard drive: o Make a directory on the drive where you want your Citadel-86 installation to reside. o CD into that directory o Copy CONFG.EXE, CTDL.EXE, EASE.EXE, EASE.HLP, and the generic CtdlCnfg.Sys file into the directory (or deARC, or whatever it takes to get them into there). o Type EASE at the command line. Follow the directions. Be ready to refer to this documentation if you become confused. And remember. EASE is not only for installation, but for modification as well. Explore! II.6 The ole' configuration file So... we're done with the dull, but necessary, overview. Now we get down to the fun stuff, the screechy details of deciding those system policies that can be enforced through the Citadel-86 software, where certain data files or groups of data files will be kept on your system, and some other details. We do this by editing the file CtdlCnfg.Sys mentioned earlier in this manual, so you may want to haul out your editor. Or you may not. Instead, it might be better to first read through this section along with a printout of CtdlCnfg.Sys, (we've included a copy of it in this file as well; see pages 35-42) comparing, taking notes, understanding what is required and what questions you will have to answer in order to set up your Citadel-86. Or -- and we recommend this -- you may wish to use EASE, the Citadel-86 installation and modification program. -8- We've decided to divide the CtdlCnfg.Sys file into four sections in this manual. The first section covers the utter necessities which must be set correctly for Citadel-86 to come up, options you cannot shut off, and some miscellaneous doodads not strictly required for a basic system, but we'd like you to set anyway. This first section makes up the bulk of the CtdlCnfg.Sys parameters, and is the only one you must fill out in order to bring up Citadel-86; the rest of the sections contain options unnecessary for a basic Citadel-86 (although, of course, they ARE useful!). If you're using a 'virgin' copy of CtdlCnfg.Sys, the options in the rest of the sections have been set to what we feel are harmless values. The second section is made up of options useful, but not necessary, for the operation of Citadel-86. The third section is made up of options related to Citadel-86's C86Net support. The fourth section covers extremely optional parameters designed to make modem handling very flexible when necessary. (Don't read this unless you have a captive, well-fed assembly-language programmer nearby.) II.6.a But first, a word on moral values ... There are two methods values are set in CtdlCnfg.Sys. One method is related to our reference to the fourth section, above, and will thus be covered in that advanced section. The other method for setting parameter values, used with the rest of CtdlCnfg.Sys, looks like this: # The '#' MUST be in the left-most column of the file in order for CONFG.EXE to recognize it as a parameter. Indenting this line a space provides an easy way to disable or save an old value when experimenting and causes CONFG.EXE to ignore the line. A parameter value will usually either be a numerical value or a string value, and we'll tell you for each parameter whether your selection should be numerical or a string. When it is numerical, always use decimal (with the exception of the mysterious fourth section). String values are always enclosed in quotes. Most string values are used to indicate where to find certain files, but some string values are special in that certain hard-to-express codes may need to be used in order to accomplish something; this occurs almost exclusively when communicating with odd modems (such as TransModems). Therefore, certain parameter string values in CtdlCnfg.Sys will allow formatting "directives" to be placed within them, which will be interpreted during the execution of CTDL.EXE to do special things. The general format of a directive is a backslash ('\') followed by a either a character indicating a specific action, or a sequence of three digits representing an OCTAL value you may need to be in this particular position to accomplish what you wish to accomplish. Here is the list of characters that perform special actions when following a backslash: n: CR-LF t: Tab character b: Non-destructive Backspace -9- r: CR f: Formfeed ": Put out a quote (allows quotes to appear in your strings) \: Backslash So, if you wanted to insert a CR/LF into a string value, you would type "...\n..." If you needed to have the binary value of 6 in a string value, you would type "....\006...." Not all parameter string values accept these formatting directives; those that don't will simply ignore them. We have marked those parameters accepting them both in this manual and in CtdlCnfg.Sys. (OCTAL values, you say! Well.... the gentleman who donated the code to do the formatting directives, a certain Dalnefre' of SynTel, is a C hacker, and did it that way. We feel it might be worth changing sometime in the future, too.) Please keep in mind that the '\r' has an added implication when placed in a CtdlCnfg.Sys string being sent to the modem. Citadel-86 will pause for a full second after sending it in most situations. This allows the sysop to send multiple commands to those modems using carriage returns as command delimiters, since the one second pause will give the modem time to digest the command. For instance, "ATZ\rATS0=1\r" sent to Hayes-style modems would cause Citadel-86 to send "ATZ\r", pause for a full second during which the modem would reset to its power-up state (or at least for most Hayes clones it will), and then send the "ATS0=1\r", which activates the modem's auto-answer mode. Please note this special processing of '\r' only applies to modem initialization and reinitialization strings, not to all strings. One more note. Certain of the string values in CtdlCnfg.Sys end up being printed to the users via Citadel-86's formatter. In these cases, when you use the CR/LF formatting directive ("\n"), remember to have a space follow it -- otherwise, Citadel-86's formatter probably won't send a CR/LF to the caller's terminal! Finally, you'll find a couple of parameters affect your installation simply by their very existence in your CtdlCnfg.Sys. So that makes three ways to set values. II.6.b Section 1 of CtdlCnfg.Sys We're finally looking at CtdlCnfg.Sys. The file starts (or at least our virgin copy does) with a short introduction to itself, which basically tells you to consult this manual if you find it too terse. A short list of supported formatting directives is also included. Part 1 of Section 1: MEANINGLESS MISCELLANEA We're going to start Section 1 with some miscellaneous parameters. -10- ------ #nodeTitle The first parameter you should find is called nodeTitle. It is a string value obeying formatting directives, and is subject to formatting considerations. nodeTitle is the title of your installation printed when carrier is detected on your system. More precisely, nodeTitle will show up in the following place on your system: Welcome to <#nodeTitle> Running ... However, nodeTitle may not necessarily be printed at this point. After successfully bringing your system up, please consult OPER3.MAN's section on Help Files for more information on banner options. EXAMPLE: #nodeTitle "Test System\n Truly a Heaven in Reverse" The #nodeTitle is printed out on .Read Status commands, also. There is no formal limit on the length of this parameter. ------ #nodeName nodeName is, in reality, purely a network parameter, and if you have no plans to ever join a C86Net, then there is no need to fill in this parameter. However, it has always been traditional, even before there was a net for any Citadel system anywhere, to fill in this and the next parameter (and, so, sentimentally we feel this belongs in this Miscellaneous section). nodeName is a string value which does NOT accept formatting directives (i.e., formatting directives will be ignored). It can be no longer than 19 letters long. It should be a short, mnemonic name for your system. An EXAMPLE of a reasonable value: #nodeName "ODD-DATA" -- The original Citadel If you ever do join a C86Net, messages from your system appearing on another Citadel-86 node will look something like this 82Nov23 from Cynbe ru Taren @ODD-DATA except ODD-DATA would be replaced with your value for #nodeName. ------ #nodeId As mentioned, this parameter is a network parameter that has traditionally always been set, even for non-network Citadels. If you have no plans to ever be on a C86Net, then you don't have to set this string value parameter to anything important. If you do plan to join one, though, (we'll go over this in more detail in the section on the network), then you do have to set this parameter correctly. The format of this parameter is "" all of which applies to the phone your system resides on. Country code is a two letter sequence indicating what country you live in (US is the United States, CA is Canada. Other country codes may be found in COUNTRY.DOC). Area code is the area code of your system (yes, -11- we are aware there is a clear bias towards US-style telephony). And Phone number is, of course, the phone number your system is on. You can put punctuation (such as parenthesis and dashes), but please be conservative with them. This string value does not obey formatting directives. Here's a fairly generic example: #nodeId "US (612) 470 9635" -- Some system somewhere ------ Part 2 of Section 1: REQUIRED ODD STUFF ------ #baseRoom OK, now we're out of the miscellanea and into parameters you have to set, starting with baseRoom. Citadel-86 always has a minimum of three rooms, the Aide> room for housekeeping, the Mail> room for private correspondence, and the , which is the room a caller is always initially placed in. (Historical note: the old CP/M Citadel called this room the Lobby>; we've only made the name of the Lobby> selectable by the sysop.) This parameter is a string value obeying formatting directives and goes through the Citadel-86 formatter, and you must limit yourself to 19 characters or less for this value. And one more note -- Citadel-86 will append the '>' to this name when it prints the room prompt for this room, you don't have to put it in yourself. If you wished to emulate the old CP/M Citadel, you'd set baseRoom thus: #baseRoom "Lobby" There is no default for this parameter. ------ #MainFloor MainFloor is analogous to #baseRoom. Any Citadel-86 V3 has a base floor, just as it has an Aide> room, etc. This parameter allows you to name this base floor. This parameter is a string value which cannot be longer than 19 characters, and specifies the name of your base floor. So, if you want to name your base floor MAIN FLOOR, you'd have #MainFloor "MAIN FLOOR" There is no default value for this parameter. ------ #CRYPTSEED Citadel-86 automatically encrypts all sensitive data files. While the algorithm used can, of course, be broken by the determined, particularly since the code is available for perusal, the encryption does provide protection against casual eyes, mistakes, and amateur system breakers. We do encourage you to take precautions of your own, such as not opening directory rooms into sensitive data areas. CRYPTSEED is an encryption seed Citadel-86 uses to encrypt your data; if someone should acquire of all of your data files but for CtdlCnfg.Sys, then they still won't have access to your system until they figure out what your CRYPTSEED is. DON'T EVER CHANGE THIS VALUE WHILE RUNNING A CITADEL-86, OR EVERYTHING WILL BECOME MESSED UP! -12- We do not know of any value you can select which will "deactivate" the encryption process (to be frank, we don't understand the encryption algorithm ourselves). Pick a value at random; the value should be a value less than 65536. Here's an example: #CRYPTSEED 69 -- a little hubris for the shy ------ #UNLOGGED-WIDTH This parameter is used for users who have not logged in yet to specify the width of their screens. If not present, it will default to 40. Remember this applies to your login banners. #UNLOGGED-WIDTH 79 - makes it all look normal Part 3 of Section 1: DATA FILE SIZES ------ #MESSAGEK MESSAGEK defines how much disk space you wish to allocate for messages on your installation. There is no way to define how many messages you want in your system, or how fast they turnover. All the messages in your system will reside in CTDLMSG.SYS, and thus the number of messages in your system at any given moment will depend on the length of the messages being entered into the system by your users. The turnover rate of your messages will depend on how busy your system is. As an example, Test System has a 611K message base, which holds 2100 messages +/- 300, of which some are of fairly good length. Turnover seems to between 3 weeks and a month, since 80-160 messages are entered a day. However, Test System is also a busy system. The sysop of an installation should also keep in mind that very large systems, with many new messages, can be intimidating to new users, so large message spaces should be approached with caution. Remember, there is a utility for expanding the message base, but not for shrinking it. This is a numerical value which you specify in 'K', which is actually 1024 bytes/K. So, for example, to specify a 250K message file #MESSAGEK 250 -- 250K message base ------ #MSG-SLOTS This numerical parameter specifies how many messages per room will be used on this system (the lone exception is the Mail>, which is covered by the following parameter). If you wanted to use Citadel-86's traditional number of messages per room, you'd have #MSG-SLOTS 58 ------ #MAIL-SLOTS This is a numerical parameter specifying how many messages per log record you wish to reserve for Mail. The Mail> room is the only room in the system whose data is not kept in CTDLROOM.SYS. Instead, the file CTDLLOG.SYS contains the "Mail>" room, reserving for each account -13- enough room for MAIL-SLOTS Mail messages. Therefore, this parameter gives you the ability to decide the maximum number of Mail> messages per user they can access. Please remember if a user gets more messages in Mail> than there are MAIL-SLOTS between two successive logins, then they will lose the earlier messages sent to them. Another consideration is many users like to review old Mail when engaged in an in-depth private conversation. Therefore, setting MAIL-SLOTS to a low value may not be the attractive alternative it first seems. However, it should go without saying a high MAIL-SLOTS value may eat up more room than necessary on your drives. The section on LOGSIZE will give an exact formula for how much space your log will take up. If you wanted to use what Citadel-86 used before V3, you'd have #MAIL-SLOTS 58 ------ #MAXROOMS This numerical parameter specifies the maximum number of rooms your system will support. Since the baseRoom, Aide>, and Mail> room are necessary, the smallest value you can give is 3. The largest number is 65536 (probably). If you wanted to have a 64 room system, you'd have #MAXROOMS 64 You can use the following formula to estimate the number of bytes a room file will take up on your system: # of bytes = MAXROOMS *(50 + (6 * MSG-SLOTS)) ------ #LOGSIZE This numerical parameter gives you the ability to decide how many accounts will be available on your system. If you run a system in which more accounts are used than there are accounts reserved, then new accounts are generated by killing old accounts. Accounts are recycled by finding the account who's last use is the oldest of all the accounts in the system, under the assumption such an account is no longer active. All space is reserved immediately for these accounts. The size of this file can be estimated from the formula # of bytes = LOGSIZE * (82 + MAXROOMS + (6 * MAIL-SLOTS)) so if you are operating in a restricted environment, plan accordingly. If you need to, you can expand the size of the log through the use of the DATACHNG utility, but the log cannot be shrunk. This is a numerical value. Here is an example: #LOGSIZE 180 -- Usually adequate. Part 4 of Section 1: DATA FILE LOCATIONS Now we discuss where you want the data files to be located on your system. These parameters are all specified in the same way, as a string value (which does not obey formatting directives, naturally) telling Citadel where on your system the given data file or files associated with the given parameter is located. -14- Simply use the MSDOS relative directory specification. You can ONLY specify a subdirectories of the current directory on the disk you specify (if you don't specify a disk, then the current disk will be assumed). So, some sample valid specifications would be "c:", "a:system", "b:msgs", and "i:bark". Some sample INVALID specifications include "c:\citadel\msgs" (an absolute specification, rather than relative), "a:\audit" (ditto), and "i:.." (".." is technically not a subdirectory, but a parent directory). If CONFG.EXE cannot find the directory you specify, it will attempt to create the directory, after asking permission. ------ HELPAREA This parameter specifies where all of your Help files will be located. These files are *.HLP, *.BLB, and *.MNU. Normally, you should create this directory and place the help files in the directory before bringing up Citadel-86, since help files are usually online at all times. #HELPAREA "c:helps" -- helps subdirectory on drive C: ------ LOGAREA This parameter specifies the location of your CTDLLOG.SYS file (this file is sized by your LOGSIZE parameter). #LOGAREA "c:system" -- put it in a general system dir ------ ROOMAREA This parameter specifies the location of CTDLROOM.SYS, CTDLARCH.SYS, and CTDLDIR.SYS. #ROOMAREA "system" -- another general system dir ------ MSGAREA This parameter specifies the location of CTDLMSG.SYS. #MSGAREA "c:msg" -- give msgs there own place in the sun ------ FLOORAREA This parameter specifies the location of CTDLFLR.SYS. #FLOORAREA "floors" Part 5 of Section 1: POLICY OPTIONS Now we enter the POLICY part of the CtdlCnfg.Sys file. The parameters discussed here represent the parts of your policy enforceable via the Citadel-86 software. -15- ------ #AIDESEEALL This parameter is a toggle giving you some power over the scope of your aides' "vision". If you set this parameter to 1, then your aides have access to all public AND private rooms (but not invite rooms, unless the have been invited). If this parameter is set to 0, then aides only have access to public rooms, plus those private and invite rooms they've been invited to. So, if you want your aides to see all public and private rooms, you would have #AIDESEEALL 1 -- See all but invite rooms if you don't want your aides to be so nosy, then you'd have #AIDESEEALL 0 -- See only public rooms. ------ #LOGINOK The LOGINOK parameter controls whether your system is an "open" or "closed" system. If you set LOGINOK to 1, the system will allow anyone to log in as a "new" user; i.e., it will ask a caller who uses an unrecognized password if they wish to login as a new user. If LOGINOK is set to 0, the system will simply tell the caller without a valid password there is no record of their password, and they should leave Mail> to the sysop (but see OPER3.MAN's section on the various Help Files for another option); the only way to enter new users into the system is from the system console. If you want an open system, for example, you would have: #LOGINOK 1 -- let the riff-raff in! ------ #ENTEROK ENTEROK controls whether a caller who is not logged in can enter messages or not. If ENTEROK is 1, then a caller who has not logged in can enter messages; if it is 0, then they must log in first, except for Mail to the sysop. Setting ENTEROK to 0 can reduce vandalism; setting it to 1 gives your callers the privilege of anonymity. #ENTEROK 0 -- log in first, folks! ------ #READOK READOK controls whether an unlogged caller can read messages. If READOK is 1, then they may. If READOK is 0, then an unlogged caller can only read the policy statement available in the Mail> room (POLICY.HLP), and the help files. Setting READOK to 0 can discourage unwelcome callers from using scarce system time. #READOK 0 -- gotta login to read these gems... -16- ------ #ROOMOK ROOMOK controls who can create new rooms on your system. If ROOMOK is 1, then any logged in user of the system may create new rooms. If ROOMOK is 0, then only aides may create new rooms on your system. #ROOMOK 1 -- a liberal policy ------ #ALLMAIL ALLMAIL controls who can use the Mail> room. If ALLMAIL is 1, then any user may use Mail> to send private messages to any other user on the system. If ALLMAIL is 0, then only Aides may use the Mail> room in a general manner; regular folk can only use Mail> for messages to Sysop. Setting ALLMAIL to 0 may be appropriate on tightly focused systems operating in a small environment. #ALLMAIL 1 -- the normal policy ------ #DoorPrivs DoorPrivs lets you decide if new users should automatically be given door privileges or if they should ask you for them. #DoorPrivs 1 -- they get them automatically #DoorPrivs 0 -- they have to ask. ------ #ANON-MAIL-LENGTH When this numeric parameter is present, all anonymous Mail> to sysop is limited to the specified number of characters. When a message is sent exceeding this limit, the user loses carrier and the message is appended to a file named ANONMAIL, just in case the Mail was valid. This option is useful when a vandal is attempting to scroll the message base and is being very persistent, to the point where even closing open logins just causes him to leave anonymous Mail to sysop, since that's the last vulnerable point in the system once login access is lost. This would let you let limit anonymous Mail> to 300 characters. #ANON-MAIL-LENGTH 300 If this parameter is not present or the value is 0 then there is no limit on anonymous Mail. ------ #LOGIN-ATTEMPTS This parameter lets you control how many unsuccessful attempts an unlogged user can indulge in before the system will drop carrier on them. For instance, the following lets a user try four times before carrier is dropped. #LOGIN-ATTEMPTS 4 -17- ------ #FILE-PRIV-DEFAULT File privileges may be set for new users en masse. #FILE-PRIV-DEFAULT, a numeric parameter, lets you set whether the average new user can have file privileges. Use 1 to indicate they may, 0 to indicate they may not. #FILE-PRIV-DEFAULT 1 means you're a generous soul. If this parameter is not present, it will default to 1 (on). You may also assign file privileges individually using LOGEDIT or the ser Administration menu hanging off of the Sysop Menu. File privileges do not apply to uploads. ------ Part 6 of Section 1: MODEM HANDLING We now enter into defining the essential details of your communications hardware. ------ #IBM You use this parameter to tell your Citadel-86 if your system is running on an IBM PC/XT/AT or compatible, or if it is running on a Zenith Z-100 (set it at 0). If you have an IBM, you'd have #IBM 1 -- Big Boo ------ #COM This parameter is meaningful only for IBMs, and selects which COM port the modem is attached to (on Z-100s only J2 ports are supported). For IBMs, only COM ports 1, 2, 3, and 4 are supported. #COM 1 -- If you are using COM1. ------ #SYSBAUD The SYSBAUD parameter is used to tell Citadel-86 what baud rates your hardware will support. Citadel-86 cannot normally be configured to run high baud rates while excluding lower baud rates (i.e., operate correctly at 1200 baud but not at 300 baud). Here's the mapping: 0 => 300 1 => 300/1200 2 => 300/1200/2400 3 => 3/12/24/48 4 => 3/12/24/48/96 5 => 3/12/24/48/96/14.4 6 => 3/12/24/48/96/14.4/19.2 #SYSBAUD 1 -- A 3/12 system. -18- ------ #modemSetup This parameter is used to initialize your modem. It is a string value parameter obeying the formatting directives; however, you should be warned Citadel-86 automatically appends a "\r" to the end of this string before sending it to the modem. And when is modemSetup sent to the modem? It is automatically sent while Citadel-86 is initializing, and it will also be automatically sent to the modem whenever the einitialize command is selected from the Sysop Menu (i.e. privileged function:). The value you use for this string should cause the modem to be put into a mode where it will function suitably with Citadel-86. This includes auto-answer and response to DTR, at the very least. Other options you may wish to consider include turning the modem speaker off (if you have one); consult your modem manual for details. The example we have here is biased towards Hayes/compatible modems. You may have to do some research if you're using an odd modem. Our example turns auto-answer on and turns off the speaker on a Hayes modem; note the lack of "\r". #modemSetup "AT S0=1 M0" -- Surely an exercise in aesthetics... ------ #REINIT As faster and faster modems appear on the scene, some of these modems are displaying odd characteristics which did not appear in the early 300/1200 modems. Chief amongst these is that some modems, after accepting a call at a baud rate lower than the modem's highest, will not accept calls at higher baud rates without being reinitialized at the highest baud rate. If your modem is one of these types, then you will wish to use this parameter. Also, we have observed that some modems, although capable of accepting calls at high baud rates directly after low baud calls have been accepted, are not as reliable in the area of Result Codes as we might like. Since Citadel-86 can use Result Codes (see Section II.9.d), we would like to see this improved, and, fortunately enough, we have observed using #REINIT with such modems actually increases their reliability. So, even if you have a good modem, you may wish to use this parameter. When this parameter is present, it causes Citadel-86 to reinitialize the modem at its highest rate with the string you specify in this parameter. This parameter accepts format directives. For most Hayes compatible modems, the string "AT" is usually more than acceptable. -#REINIT "AT" -- disabled, but recommended value -19- ------ #DISABLE-MODEM #ENABLE-MODEM Usually, when Citadel-86 needs to "disable" your modem (that is, cause it not to answer the modem), it "drops" the DTR pin (electrical stuff, don't worry about it), which usually causes the modem to stop answering the phone. The modem is disabled whenever you, the sysop, uses the system at the system console. Some sysops, however, would prefer the modem go "off-hook"; that is, the modem should hold your phone line open and thus cause a busy signal for all callers while you're on. These optional string parameters, when present, are sent to the modem when disabling and enabling the modem, thus making it easy to force a busy signal when you're on if you know what command to send to your modem. For example, "ATH1" will put most Hayes-type modems "off-hook", and "ATH0" will put them back on-hook. In the following, we've disabled the parameters since we don't particularly recommend the use of these parameters ourselves, but the values are what we'd probably recommend if we used them. Note the use of "\r" at the end of each! Citadel-86 will not! automatically append the carriage return needed to force the modem to process the command, so you must do that yourself! -#DISABLE-MODEM "ATH1\r" -#ENABLE-MODEM "ATH0\r" ------ #LOCK-PORT This advanced parameter is used for "locking" your com port at the baud rate you specify. This parameter is primarily useful when you are using a USR high speed modem (HST, Dual-Standard, etc.) and you want to have the callers, when they are calling in with compatible modems, to enjoy the highest possible throughput, which is achieved by having the modem talk to the computer at a specific (and high) baud rate, regardless of what the caller is connected at. As we said, this is an advanced option. If you plan to use it, you must make sure your modem knows about it and is fed the correct modem commands so it knows what baud rate it should talk at. You should use the #REINIT parameter to tell it this information. The parameter you specify to #LOCK-PORT should be a number indicating what speed you want the computer to talk to the modem. Use the same scheme as for #SYSBAUD, i.e., 300 = 0, ... 4 = 9600, 5 = 14400, and 6 = 19200. For example, if you have a good enough serial port to handle 19,200 baud with your USR modem, you would want #LOCK-PORT 6 in your CtdlCnfg.sys. -20- ------ Part 7 of Section 1: VIDEO OPTIONS ------ OLDVIDEO This parameter is difficult to categorize, so we'll just lay the cards out on the table. Basically, every once in a long while we run across some computer that hangs when Citadel-86 is run, and it has something to do with the video portion of Citadel-86. (We haven't actually seen this happen in quite a while, but ...) Therefore, if you place #OLDVIDEO in CtdlCnfg.Sys, Citadel-86 will use its old video routines for display, rather than the new. -#OLDVIDEO -- disabled ------ FOREGROUND BACKGROUND STATUS-FOREGROUND STATUS-BACKGROUND These four parameters allow you to specify what colors will show up at the system console. FOREGROUND specifies the color of the characters themselves, except on the status bar. BACKGROUND specifies the background of the screen, except on the status bar. STATUS-FOREGROUND specifies the color of the characters of the status bar. STATUS-BACKGROUND specifies the background color of the status bar. You have the following colors to select from. This first list of colors may only be used as FOREGROUND selections: DARK GRAY, LIGHT BLUE, LIGHT GREEN, LIGHT CYAN, LIGHT RED, LIGHT MAGENTA, YELLOW, WHITE. This second list of colors may be used as either FOREGROUND or as BACKGROUND selections: BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHT GRAY. Please note on some color monitors not all colors are available, and on monochrome monitors you should probably select highly contrasting colors for Foreground/Background pairs. Here is an example: #FOREGROUND RED #BACKGROUND BLUE #STATUS-FOREGROUND LIGHT GREEN #STATUS-BACKGROUND BLACK Also note Citadel-86 is accompanied by a utility program named SCREEN.EXE which will help you select colors easily. Please see the Utilities manual when you are ready to play with your screen colors. The EASE utility is also capable of helping you select screen colors; in fact, SCREEN is classed as an optional utility, and you may not have it. -21- ------ CLOCK The status bar of Citadel-86 contains a clock, updated every minute, in the far right-hand corner. Some folk may not want this clock, however, while others only want to see the clock only when a user is on the system. Therefore, the parameter #CLOCK is available to control the behavior of the status bar clock. The value you place after #CLOCK controls the behavior of the status line clock. Here are the supported values: o "None" - If this is present, then you never have a status bar clock. o "Inuse" - If this is present, the clock is only displayed when the system is active. o "Always" - This causes the clock to be active all the time. So, for instance, if you want the clock to never be on display, #CLOCK None - No clock would do the trick for you. If this parameter is not in your CtdlCnfg.Sys, "Always" is considered the preferred value. ------ If you are a novice setting up Citadel-86 for the first time, please SKIP to Section II.7. This is the end of Section 1 of CtdlCnfg.Sys, parameters which must be set for Citadel-86 to run correctly. The other three sections of a virgin copy of CtdlCnfg.Sys (which we assume you are working with) have been given default values that shouldn't cause any problems with running a Citadel-86. If, on the other hand, you're just exploring what's available, continue on your merry way! II.6.c Section 2 of CtdlCnfg.Sys Now we enter into the realm of options which may prove useful to you in your particular environment, but which are not necessary for the correct operation of a Citadel-86. We're going to begin by discussing a general time-driven event-handler facility. Then we'll talk about some other miscellaneous parameters. ------ #event ... This is what we're calling a "time-driven event-handler", which we're going to define as the ability to cause Citadel-86 to do certain things at times you specify. So, for instance, you can have the system come down at certain times of the day to back itself up, or have it go into networking mode several times a week -- or several times a day. Or do whatever your imagination suggests. Any number of these #event parameters may appear in your CtdlCnfg.Sys file. This is the generic format of these parameters. #event