This is the main Searchlight documentation file. To read about Searchlight's RIP features, Press F10. Searchlight BBS Owner's Manual Version 3.5 Copyright 1993 Searchlight Software Contents: Introducing Searchlight..................................1 What Do I Need To Run Searchlight BBS?...................2 Searchlight Differences..................................2 User Interface.........................................2 Message System.........................................3 Electronic Mail........................................3 Bulletins..............................................4 Flow Control...........................................4 Doors..................................................5 Menu Editing...........................................5 Mouse Support..........................................5 Searchlight BBS Installation And Setup...................7 The CONFIG.SYS File......................................7 File Sharing.............................................8 Installing Searchlight From Your Distribution Disks......9 SLBBS Environment Variable...............................9 Upgrading From Older Versions............................10 Searchlight BBS Configuration............................13 Searchlight BBS General Setup Menu #1....................14 Searchlight BBS General Setup Menu #2....................16 Searchlight BBS Communications Setup.....................20 COM Port Setup.........................................23 Searchlight BBS Pathnames Setup Menu.....................25 Searchlight BBS Protocol Setup Menu......................29 Searchlight BBS Screen Colors Setup......................31 Searchlight BBS AutoDoors Setup..........................32 Searchlight BBS Function Attribute Setup.................34 Default Access Level Setup...............................35 Pitfalls And Errors......................................38 Overlay Setup............................................38 Text Files Setup.........................................39 Default Subboard Entry Messages........................40 Default File Directory Messages........................41 Color Codes And Macros...................................41 Multinode Setup..........................................43 Multinode Operation......................................44 Searchlight BBS Subboard Maintenance.....................47 Add Subboard.............................................47 Edit Subboard............................................48 Delete Subboard..........................................52 Subboard Utilities.......................................53 File Directory Maintenance...............................54 Custom Ordering..........................................56 Running Searchlight BBS..................................59 Auto ANSI Detect.........................................60 Things To Do When First Logging In.......................61 Using The Status Display.................................62 SLBBS Command Line Parameters............................62 Adding New Users To The System...........................64 Guest Account..........................................65 Configuring User Options.................................67 User/Info................................................67 User/Preference..........................................69 User/Stats...............................................70 User/Access..............................................71 Searchlight Message System...............................75 Entering Messages: The POST Command......................75 Retrieving Messages: The READ Command....................75 Mail/Subboard Disposition Prompts........................81 Message Threading: Using the THREAD Command..............81 Selecting Message Areas: The LIST and JUMP Commands......84 Reviewing Messages: The SCAN Command.....................84 Finding New Messages: The NEW Command....................85 Subboard Navigation with NEW...........................86 Maintaining Messages: The EDIT and KILL Commands.........88 Maintaining Member Files: The 1-Member Command...........88 Other Message Management Features........................90 Using Electronic Mail....................................91 Netmail................................................94 A Word about Mailboxes.................................94 Using The Bulletins System...............................96 Using Chat Mode..........................................97 Sysop-To-User Chatting.................................97 Internode Chatting.....................................97 Other Commands...........................................99 ANSI Command...........................................99 FILES Command..........................................99 GOODBYE Command........................................99 INFO Command...........................................99 QUOTES Command.........................................99 TIME Command...........................................99 USER Command...........................................100 VERSION Command........................................101 WHO Command............................................101 Sysop Functions..........................................102 The Status Line..........................................104 Hot Keys.................................................104 Output Logging.........................................105 Exit Key...............................................106 Hangup Key.............................................106 Command Keys...........................................107 Text Editing: Introduction...............................108 Using The Line Editor....................................109 Using The Full Screen Editor.............................112 Wordstar Compatibility...................................112 Screen Editor Subcommands................................113 Reply-Quote Line Selection.............................116 Message Uploading......................................117 Message Preview........................................118 ANSI Compatibility.....................................118 Embedded Color Codes.....................................119 Message Macros...........................................121 Using Prepared Text Files................................122 Searchlight BBS File Transfer System.....................125 Setting Up Directories.................................125 Setting A Default Text Message.........................126 Loading Filenames......................................126 Using The File Transfer System...........................126 Files System Commands..................................126 Protocols..............................................127 Uploading..............................................127 Downloading............................................127 Directory Listings.....................................128 File Maintenance.......................................128 Password Protection....................................128 File Names.............................................129 File Tagging...........................................129 Tagging and Ratios.....................................130 Sysop Functions........................................131 Setting Up External Protocols............................132 Download Commands......................................132 Upload Commands........................................133 Upload AutoDoor........................................133 Bi-Directional File Transfer...........................134 External Protocol Examples.............................134 Summary Of Files System Commands.........................135 Importing File Lists.....................................142 Searchlight Menu Editor..................................145 Components Of A Menu.....................................146 Commands.................................................147 Menu Header..............................................147 Editing Commands.........................................149 Edit Command Screen......................................152 Controlling Command Availability.........................153 Internal Commands........................................156 External (DOOR) Commands.................................157 Menu Commands............................................157 Changing Command Types...................................158 Guide To Menu Setup......................................159 Standard Menu Names....................................159 Menu Levels............................................159 Executable Menus.......................................160 Files System Commands..................................160 Searchlight BBS Doors Subsystem..........................163 Setting Up Doors.........................................163 Door Parameters..........................................164 What Programs Can Be Used As Doors?......................168 Using COMMAND.COM as a Door............................168 Using Batch Files as Doors.............................169 Passing Parameters to a Door Program.....................170 Using Command Line Metacharacters......................170 Running PCBoard Doors With Searchlight.................171 Direct Use Of Searchlight Files........................172 How The Doors System Works...............................173 Some Door Programming Tips.............................176 Searchlight Sysop Utilities..............................177 Change User's Name.......................................177 Purge User File..........................................178 Purge Message Files......................................181 Purge Member Files.......................................183 Mass Validate Users......................................184 Purge File Areas.........................................186 Sysop Utility Notes......................................187 Introduction To Netmail..................................189 What is Netmail?.......................................189 Who can use Netmail?...................................189 How Searchlight Handles Netmail..........................190 Netmail Import & Export..................................194 Nodelist Index...........................................195 Using Searchlight Netmail................................197 Receiving Netmail......................................197 Replying to Netmail....................................197 Originating Netmail....................................198 Sending Netmail to a Sysop.............................198 Sending Netmail to Others..............................199 Creating an Explicit Netmail Command...................199 Creating Netmail Routing Addresses.....................200 Routing Address Edit...................................201 Additional Netmail Considerations........................201 Netmail Scope..........................................201 Bad Messages...........................................202 Listed vs. Unlisted Addresses..........................202 Origin Addresses.......................................202 Introduction To RIP Graphics.............................203 What is RIPscrip?......................................203 How Searchlight Supports RIP...........................203 How can I create RIP files?............................204 Setting up Searchlight for RIP Support.................204 RIPscrip Guidelines....................................205 Additional Comments....................................205 Using Searchlight With DESQview..........................207 Environment Setup......................................207 Interrupts.............................................207 DESQview Setup.........................................208 Program Setup..........................................208 Memory Issues..........................................210 Performance Issues.....................................211 Fine Tuning............................................211 Appendix A: Using The Activity Log.......................213 Appendix B: Guide To Error Messages......................217 Errors 2 and 3 (File/Path does not exist)..............217 Error 4 (Too many open files)..........................217 Error 100 (Disk read error)............................217 Error 101 (Disk or Directory is full)..................218 Error 202 (Stack Overflow)Error 203 (Heap Overflow)....218 SHARE Errors...........................................218 Other Errors...........................................219 Appendix C: Automatic Events.............................221 Appendix D: Modem Configuration..........................223 Remote Baud Detection..................................224 Modem Output Buffering.................................225 COM Port Addresses.....................................225 High Speed Modems......................................226 Recommended Modem Init Strings.........................227 Appendix E: Using Alias Names............................229 Appendix F: The SLMAIL Command Line Utility..............231 Syntax...................................................231 Reading and Sending Text Files...........................232 Reading Personal Messages..............................233 Reading New Messages...................................233 Importing and Exporting Echomail Messages................235 Fido Export............................................235 Fido Import............................................236 SLMAIL Configuration File..............................237 Echomail Network Addresses.............................237 Appendix G: Internal Command Reference...................239 Common Parameters........................................240 Message (Main) System Functions..........................241 Main Command Options.....................................243 Files System Functions...................................246 Directory Jump Command (301)...........................246 Tag List Management....................................247 Appendix H: Digiboard Installation and Use...............249 DigiBoard Hardware Installation........................249 DigiBoard Software Installation........................249 Using DigiBoard With Searchlight.......................251 System Checkout........................................252 Index....................................................253 Introduction INTRODUCING SEARCHLIGHT The Searchlight Bulletin Board System (SLBBS) is a powerful software package that allows you to set up and run an online electronic service right from your PC. Using your computer, a modem, and the Searchlight software, you'll have a complete bulletin board system that will: o Allow others to access your PC via telephone and exchange mail and other messages, even when you are not at your computer. o Provide password access and multiple levels of security, enabling you to control exactly who has access to information on your system. o Allow unattended, error-free transfer of programs and data files between your PC and other PC's via telephone. o Provide a complete, user friendly environment that's easy enough for most people to use intuitively, without the need for any documentation or assistance from you. Those familiar with the BBS community, and especially those who have used other BBS software, will appreciate Searchlight's long list of advanced features: o Full screen text editor for easy entry and editing of messages, mail and text files, even from a remote terminal. o Unique user interface with built in Online Help facility provides both you and your users full access to the system's documentation. Complete menu editing function allows total customization. o ANSI and RIP graphics support for flexible screen displays. o Advanced "lock and key" access system providing thousands of security profiles. o Powerful messaging system including message threading, NEW message scans, search functions, and unlimited message areas. o SYSOP utilities allow you to adjust most aspects of the system to your liking and give you powerful mass deletion commands. You can control the entire system from a remote location. o FILES system featuring alphabetical and date sorted directories, passwords and access levels, up to 12 file transfer protocols, ZIP, ARJ and LZH file directories, etc. FAST file transfers with advanced buffering techniques. o DOORS system gives you infinite expandability: run almost any program from within your BBS, write your own commands (in any language), even give DOS commands from a remote terminal. Searchlight is compatible with most popular door programs. 1 Introduction WHAT DO I NEED TO RUN SEARCHLIGHT BBS? The answer: o An IBM compatible personal computer (XT,AT,PS/2,386 or 486) with a hard disk drive; o A Hayes compatible modem; o RS232 serial port(s) and modem cable(s) (for external modems only); o At least 250K of available memory; o DOS Version 3.1 or higher (for multiuser systems, DOS 3.3 or higher). Although Searchlight has been successfully tested on many compatibles (and, indeed, has not yet proved incompatible with any of them), we cannot guarantee that it will run on every computer. In particular, you need IBM hardware-compatible serial ports if you want to use Searchlight's built-in modem drivers; if you have nonstandard hardware (such as multiport COM cards), you must provide a FOSSIL compatible software interface (FOSSIL Driver). (Searchlight also works with DigiBoard hardware and Digiware software drivers). You will need a telephone line, preferably a separate line devoted entirely to your computer. Avoid lines with "call waiting" or other features that might interrupt a call in progress. If you will be running a multinode BBS system, you'll need either a multitasking program such as DESQview, Windows, or OS/2, or a local area network (LAN). Although not stated in any manual, also required for running a BBS is a somewhat fanatical ability to spend your hard earned time and money for the pleasure of having strangers (often in faraway lands) use your computer with seemingly little or no gratitude. If you feel as though you don't have this capacity, don't worry about it because it usually develops soon after your BBS first goes on line. DIFFERENCES BETWEEN SEARCHLIGHT BBS AND OTHER BBS SYSTEMS Before you begin using Searchlight, we'd like to provide a short explanation of some of the major design features of the system and show you how these compare to other BBS systems. It seems that all of the common BBS systems that we can think of are based on a similar set of standards, and we have noticed a lot of people become confused when Searchlight does things they don't expect. A quick look at some major features of Searchlight will clear up most questions. If you come to a point where you can't figure out how to do something that you know Searchlight can do, there's a good chance that you are simply going about it the wrong way. User Interface Most BBS services still use a "teletype" style interface -- the kind of line by line, unformatted output that dates from the days when most people 2 Introduction used terminals that printed on paper or didn't offer any screen formatting options. This raw command-line style interface is what's most often associated with "non user friendly" software. Searchlight BBS is different. We take full advantage of the formatting capabilities of modern terminals and terminal emulation software to provide you with a friendly, screen oriented interface, complete with moving menubars, highlighted menu choices, and a full screen editor that uses the standard PC keystrokes you already know. Using Searchlight, whether you're right in front of your PC or at a remote site thousands of miles from home, is just as easy as using any modern PC application program. Message System Many BBSs have a "flat" message system structure; that is, all the messages on the BBS are viewed as one long list, with the oldest messages at the beginning of the list, and the newest messages at the end. Still others have message sub-sections (often called Conferences or Subboards) that provide you with, essentially, several smaller lists of messages rather than one long list. Searchlight is, for the most part, similar to these systems. On Searchlight the message subsections are called Subboards, and you can have as many of them as you like, each with a different name and access requirement. In addition, you can assign a "Subsysop" to each message section who acts as a moderator for the discussion and has special privileges to edit and delete messages under his or her domain. Unlike most BBS systems, Searchlight uses short alphanumeric names, rather than numbers or single letters, to designate its message bases and file areas. We think you'll find it much more convenient to refer to areas by name than to memorize a numeric list, particularly when your BBS contains a large number of message and file areas. Electronic Mail On most systems, sending a private message to another user is possible by specifying the name of the user to whom the message is directed. Such a message cannot be read by others, but it still appears on the message subsection with the other messages. Typically, you can find messages directed to you by performing an automatic search of all the messages in the system, looking for ones with your name on them. Searchlight uses a different approach. Rather than placing private messages in with the general message base, you send messages directly to another person on the system. This operation is called Electronic Mail, and it is similar to the way real mail works. When you decide to send a personal message to someone, the system looks up their name and places your message into that user's personal "mailbox". To read a personal message, you inquire into your own mailbox to see what mail other people have sent to you. This method is a lot faster than the traditional approach and gives you an easy way to manage your own messages, separate from the main stream of things. 3 Introduction Searchlight's public message system does, in fact, have to fields on messages and supports an extremely efficient personal mail search -- so you really have the best of both worlds with Searchlight BBS. Be sure to understand the distinction between public messages and private mail, though, in order to get the most out of using Searchlight. Incidentally, writing a public message on Searchlight is known as "Posting" the message, and is done with a command called POST. Sending a private message is referred to as "Sending" the message, and is done through the MAIL command. Bulletins Searchlight BBS has user-definable bulletins. Unlike other systems, where the bulletin feature is defined by the sysop, users can post bulletins (if you choose to allow it). The bulletin function is actually a special message base with features that make it ideal for posting announcements and urgent messages. Complete details on how it works follow in the body of this manual. Flow Control The term "flow control" refers to the flow of characters between your computer and a remote terminal, and it's very important on an interactive system like Searchlight BBS. During almost all operations, you can pause the output from Searchlight by pressing control-s, and abort a message or listing by pressing the letter "S", the spacebar or control-c (to enter a "control" character, you hold down the key marked "Ctrl" on your keyboard and press the desired character, then release both keys. In this manual, control keys will generally be indicated with the ^ symbol; in other words, ^C means control-c). Whenever you request a message, display or listing in Searchlight that's larger than a single screen, you'll usually see Searchlight pause at with a prompt that has the options "Continue" and "Stop", allowing you to view that page of the output and then continue, or abort the listing. File listings also offer a "Tag" option that lets you mark particular files for later download. Although there is an explicit prompt for the continue and stop options, you can actually stop a listing at any time by pressing the "S" key or the other keys noted above. In addition, Searchlight features intelligent command type-ahead that lets you bypass most menus when you already know the command you want. For example, if you press "N" while a message is being displayed, or while the message submenu is being drawn on your screen, Searchlight will stop its output immediately and proceed to the "Next" message. This feature works while reading messages and mail, in the Bulletins area, on subboard and file directory listings, on all submenus such as the Mail and User command menus, and even at the "more" prompt. It's an extremely valuable and time saving feature, especially when using Searchlight from a remote location at slower baud rates. 4 Introduction One final word about flow control: in practically every situation where Searchlight requires you to answer an input prompt with a single character response, you need only type the desired character, NOT type the character and then press RETURN. You only need to press RETURN after typing a whole line of input. If you forget, and DO press the return key, it will be stored in memory (all input is fully "buffered") and used as the response to the NEXT input prompt. This can be quite undesirable and confusing, if you do not understand what's going on -- so be a little careful at first. Doors In contrast to other BBS systems, Searchlight provides full modem support when running external "Door" programs. That means you don't need to use external support programs, batch files, or device drivers when running Doors; Searchlight handles the modem internally, while consuming less than 30K of memory above DOS (leaving the rest free for your Door). And Searchlight makes it easy for you to run almost any program as a Door, including existing programs not designed for use with a BBS, and programs you write yourself (in any language). Plus, Searchlight is compatible with most of the programs written for the other BBS systems -- giving you access to thousands of the most popular games and utilities written for BBS use! Menu Editing Virtually every menu you see when using Searchlight BBS is user definable; that means you can change the appearance, commands and even the entire structure of our menus if you wish. If the default menus we've provided don't suite your needs, you'll be able to modify the menus, or even create brand new menus from scratch. You can also change the names we use for commands without affecting their function, and even change the text and messages that appear in the software. Mouse Support Searchlight features mouse support. If you have a local mouse attached to your system, you can use it in many places in the main program and CONFIG program instead of the keyboard. Some places that mouse usage is supported include: o Selection of items from menubar style menus o Selecting fields in Options type screens, and changing field values o Moving the cursor around during full screen message editing o Tagging lines when using the reply-quoting feature Mouse usage is supported in most other areas of the program where a menu choice or command choice is displayed on the screen. You can also click on the commands that appear when doing a "Help" command on a word type menu (like the default main menu). The right mouse button acts like an Enter or ESC keypress and can be used to exit most menus and as a substitute for pressing Enter or ESC at many textual prompts. 5 Introduction Remote callers can also use mouse functions when calling Searchlight BBS with a RIP graphics compatible terminal. Remote mouse functions are similar to local mouse functions, except that the right mouse button is not used with RIP. Mouse functions are not available to remote callers with standard ANSI or non-ANSI terminals. And More! There are many more interesting Searchlight features, but rather than go into detail here, let's get started with the installation instructions. These are the major points we want you to keep in mind as your system unfolds, and we'll get to the rest of the goodies in turn. 6 Installation SEARCHLIGHT BBS INSTALLATION AND SETUP Searchlight BBS requires an IBM PC or compatible, running DOS version 3.1 or higher. You need a Hayes compatible modem, a serial (RS232) interface (if your modem is external), and about 1.5MB of hard disk space. If you are setting up a multinode system, you'll need a serial port and modem for each node in your system, as well as the appropriate multitasking or network operating system software. Multiuser systems will also require DOS version 3.3 or higher. Make sure your modem is installed and turned on before you install Searchlight; refer to your modem's documentation for more information. If you are using a new modem or computer, you should verify that the modem is working correctly by running the modem software that came with your modem. This way, if you have trouble setting up your BBS, you'll know whether the modem itself might be at fault. Some sort of text editor or word processor will generally be required for creating/editing text files used by Searchlight. Since most people already have their favorite, we'll assume you know how to "edit" text files (such as CONFIG.SYS) on your system. Please note that Searchlight BBS software is available in both single and multiuser configurations. This manual covers both single and multiple user usage. If you purchased a single line version, the multiuser information does not apply to you. THE CONFIG.SYS FILE Somewhere in the root directory of your hard disk, there should be a file called CONFIG.SYS. This file is used to configure various aspects of your computer as it boots. Using a text editor or word processor, examine the CONFIG.SYS file and make sure it contains at least these three lines: Files = 30 Buffers = 20 Device = ANSI.SYS These commands ensure that your computer allocates enough file buffer space for the BBS, and that the ANSI.SYS driver is loaded. If your CONFIG.SYS file already contains lines like those shown above, make sure the values for Files and Buffers are at least as large as those shown; otherwise, change them to the above values. If your disk does not contain the CONFIG.SYS file, create it, and add the three lines shown above. If too few file buffers are allocated when you try to run Searchlight BBS, the program may crash with an I/O error. If this occurs, check to make sure your CONFIG.SYS file contains the appropriate commands. If you continue to see file errors (usually Error 100, Error 103 or Error 104) you may need to increase the value of "Files" in your CONFIG.SYS; this is particularly true 7 Installation if you run a multitasking operating system, network driver or similar resident software. The ANSI.SYS driver is not required by Searchlight, but it is necessary if you wish to display text files which contain ANSI escape sequences. While we recommend running with ANSI.SYS installed, we strongly recommend that you do NOT use one of the many ANSI.SYS replacements (commonly found on BBS systems and as commercial products) designed to speed up screen output. Many of these drivers bypass the BIOS level of I/O, which will make it impossible to run the DOS command shell and other programs through our built-in Doors system (see the Doors Setup section for details). FILE SHARING Multiuser versions of Searchlight BBS perform file sharing in order to control access to data files by several users at the same time. File sharing requires that SHARE.EXE, or its equivalent, be available when Searchlight runs. If you run multiple copies of Searchlight BBS on one machine using DESQview, Windows or a similar multitasking system, you will probably need to run the DOS program SHARE.EXE as you boot your system. Make sure the SHARE.EXE file is available on your disk, then load it by entering the command "SHARE" into your AUTOEXEC.BAT file (and rebooting your system). Because of its low memory requirements and overall efficiency, Quarterdeck's DESQview is the recommended multitasking operating software with which to run Searchlight BBS. You can also run Searchlight with Microsoft Windows or IBM OS/2. If you run Searchlight on a local area network, your LAN probably provides the Share function automatically. Do not load SHARE.EXE unless your LAN documentation instructs you to do so, or you receive a share related error message when you run Searchlight BBS. Please see Appendix B, Guide To Error Messages, for more information about loading Share and the share related error messages provided by Searchlight BBS. More information on the CONFIG.SYS, ANSI.SYS and SHARE.EXE files can be found in your DOS manual. 8 Installation INSTALLING SEARCHLIGHT FROM YOUR DISTRIBUTION DISKS Installing Searchlight BBS into your computer is a simple procedure, thanks to the easy to use INSTALL program we've provided. If your computer's floppy disk drive is drive A:, simply insert the Searchlight disk and type: A:INSTALL Of course, if you're using the B: floppy drive, type "B:INSTALL" instead. When the installation menu appears, just select "New Installation" if you're a first time customer, or "Update Installation" if you already have a copy of Searchlight on your system. Proceed with the installation process by following the instructions that appear on your screen. The INSTALL program automatically creates appropriate directories on your hard disk, loads the Searchlight program files, and creates Searchlight data files for you. When the installation is complete, your DOS prompt re-appears. Searchlight contains a number of optional components, such as an external version of the Zmodem protocol, which may be installed if you choose after the main programs are installed. Each optional component that you load contains its own documentation (.DOC) file that you can read to find out more about using that option. You're now ready to run Searchlight BBS! There are two main commands you'll need to know right now. To start Searchlight itself and begin waiting for an incoming phone call (or initiate a local session), type at your DOS prompt: SLBBS To access Searchlight's configuration menus and sysop utilities, enter this command: CONFIG We recommend running CONFIG first, in order to set Searchlight's options to your own preferences before you actually run your BBS. We'll talk more about the configuration program's features in the next few chapters. SLBBS ENVIRONMENT VARIABLE In most cases, you'll be located in Searchlight's "home" directory every time you start the main program or run one of the utility programs. While you should always be in the home directory when you enter the command to start Searchlight, you can run utilities (like the CONFIG program or the auxiliary programs found on your distribution disk) from any directory, as long as you set up a DOS environment variable to tell Searchlight where the home directory is loaded. 9 Installation To set up the environment variable, type "SET SLBBS=" at your DOS prompt, like this: SET SLBBS=C:\SLBBS You need to set this variable BEFORE running Searchlight or any Searchlight utilities. It's best to put the command into a startup file (like AUTOEXEC.BAT) to save you the trouble of having to enter it every time you boot your system. If you run a multiuser system, be sure that each node has its own 'SLBBS' environment variable pointing to its own home directory. UPGRADING FROM OLDER VERSIONS All versions of Searchlight BBS provide an upgrade path that allows you to upgrade to newer versions of the software without losing any messages, user records, or setup information stored on your system. You can upgrade to the latest version even if you are currently using as old a version of Searchlight as 1.28, which was released in 1988. Upgrading From Searchlight 2.x If you are upgrading from Searchlight 2.x to 3.x (for example, from version 2.25 to 3.0) the upgrade is automatic: simply select Upgrade Installation when you run the INSTALL program. New versions of the Searchlight program files will replace your existing files. Since the data files for all 2.x and 3.x versions of Searchlight are compatible, there is no data file upgrade procedure necessary, and all of your existing information will be retained. If you are upgrading from Searchlight 2.15, the upgrade program will also install the MENU FILES that are used by Searchlight version 2.25 and later. The menus files provided emulate the built in menus that were incorporated into Searchlight 2.15, but now you can change them: see Menu System (p. 145) for more information. Upgrading From Searchlight 1.x Upgrading from versions of Searchlight older than 2.0 requires the use of a special UPGRADE program, which converts your existing data files to the new formats. Before you begin, you will need to download the upgrade program, which is distributed as UPGRADE.ZIP on our main BBS in New York. (If you cannot access our BBS or cannot download the file, please call our technical support line and we'll send you a copy of the upgrade utility on disk). The recommended upgrade procedure is to first create a new Searchlight 3.0 installation by following the New Installation instructions, taking care to use a different directory name than the one containing your old installation. Fill in the information required by the installation program, but don't run the CONFIG program or modify any of the additional 10 Installation configuration fields (they'll be filled in automatically when you run the upgrade program). Once Searchlight is installed, run the UPGRADE program to convert your existing data. (See the upgrade program's included documentation file for more details). 11 Configuration SEARCHLIGHT BBS CONFIGURATION Searchlight's CONFIG program allows you to add, edit and delete message and file transfer sections and menus, and edit a variety of available options as needed. You can run CONFIG whenever you want to modify system options, such as default access levels, modem setup strings, external protocols and screen colors. If you're just starting out, you'll almost certainly want to use the CONFIG program to set preferences like the name of your BBS before you start using Searchlight. You should always be located in the "home" directory -- the directory where your Searchlight BBS data files are located -- when you run CONFIG.EXE. Run the configuration program by typing CONFIG at your DOS prompt. For example: C> CONFIG If you see a message indicating that your Searchlight files can't be found, you should either make sure you are located in the directory that contains the files (the directory you specified during the install process), or set an SLBBS= environment parameter. Your screen should now show Searchlight's main configuration menu. CONFIG divides the setup procedures into several categories, as follows: A. General Configuration B. Message Subboard Maintenance C. File Directory Maintenance D. User/Subboard/File Utilities E. Searchlight Menu Editor Begin by selecting the first item, General Configuration, by pressing the "A" key on your keyboard (don't press RETURN -- just press "A"). The screen now shows a new menu that looks like this: A. General Setup Menu #1 B. General Setup Menu #2 C. Communications Setup D. File Pathnames Setup Menu E. Xfer Protocols Setup F. Screen Colors Setup G. AutoDoors Setup H. Command Access Setup I. Default Access Levels We'll begin at the top with General Setup Menu #1, so press "A" at your keyboard again (or, if you prefer, "click" on the first menu line with your mouse), and follow along with the menu options as we describe them in the following pages. 13 Configuration SEARCHLIGHT BBS GENERAL SETUP MENU #1 1. System Name ................... Searchlight 2. Allow New Users ............... Yes 3. Initial Help Level ............ Novice 4. Min. Access Needed to Log In .. 0 5. Node Number ................... 1 6. Number of Active Nodes ........ 1 The first field, System Name, is highlighted by a reverse-video bar. To change the value of a field, you can type over the existing string, or edit it with the cursor keys. To switch to other fields, press the up and down arrow keys, or use your mouse to highlight the desired value. Numeric values are entered by typing a number within the allowable range, which is indicated to the right of the field when the field is selected, or by clicking the arrows with your mouse. Other fields can be changed by pressing the spacebar/backspace keys or left mouse button to display the available options. When you are done editing the above fields, press the ESC or ^Z (control-Z) key or the right mouse button to exit back to the CONFIG main menu. You may now go on to the next screen of configuration options, or exit the program by pressing ESC or the right mouse button again. Here is a detailed description of the functions of each option. As you move down the list, change the options as necessary or desired for your particular system. 1 -- System Name This is an alphabetic field that you can use to enter an identifying name for your BBS. This name is used at the login message, on the help screen display, at the top of the Bulletin listing, and in the logoff message. 2 -- Allow New Users This option, normally set to "Yes", determines whether your system will allow new users to register their names and passwords. When set to "Yes", new users will be allowed to register by typing "NEW" at the login prompt. If changed to "No", your BBS becomes a closed system, allowing only those users with passwords already on file to log in. If you decide to run a closed system, you must still set this option to "Yes" initially to allow users to register. You can either allow your users to register themselves or you can register the names yourself by logging in locally and typing "NEW" at the login prompt. (You can also create new user accounts with Searchlight's User Editor software; contact us for more information). 14 Configuration 3 -- Initial Help Level This field can be set to "Novice", "Intermediate" or "Expert", and it determines the default help level assigned to new users. We suggest that you use Novice if most of your new users will be people who are, for the most part, unfamiliar with BBS systems or Searchlight BBS, and Intermediate or Expert if most of your new users are expected to be familiar with BBS systems and Searchlight BBS software. 4 -- Min. Access Needed to Log In This field defines the minimum access level that a user needs to log in via this particular node. You can use this feature on multinode systems to set up a system where some nodes are public access, and some are restricted to users with a certain access level. Normally, at least 1 node should have a minimum access level of 0 (allowing public access). 5 and 6 -- Node Numbers These fields determine the node number of the current node and the total number of nodes in the system. When you copy your CONFIG.SL2 file to a different directory and change the node numbers, you can create additional nodes that allow multiple users to access your BBS at the same time. For more information, see Multinode Setup (p. 43). The maximum number you can type in lines 5 and 6 depends on the product license level you purchased when ordering Searchlight BBS. For example, if you own a 1 to 10 user license, you can enter a maximum value of 10. If you'd like to upgrade your license level at any time, please contact Searchlight Software for upgrade information. 15 Configuration SEARCHLIGHT BBS GENERAL SETUP MENU #2 1. Screen Write Method ........... Direct 2. Idle Time Limit ............... 15 3. Quotes File ................... On 4. Return to DOS on Logoff ....... No 5. Hangup Phone on Logoff ........ Yes 6. Allow Console Hotkeys ......... Yes 7. Date Format ................... USA 8. Time Format ................... 12 Hour 9. Upload Time Repay Rate ........ 1 10. ROM File Handling ............. Direct 11. User Log Status ............... Public 12. Clock Tick Source ............. Direct 13. Use Session Time Limits? ...... No 14. Expired User Action ........... None 15. Enable RIP Graphics ........... Yes Option screen B displays some more configuration switches for customizing your setup. Adjust your options as follows: 1 -- Screen Write Method This can be set to either BIOS or Direct. In BIOS mode, Searchlight will use BIOS calls to send all its output to the screen. In Direct mode, the BIOS is bypassed and screenwriting occurs via direct access to your computer's video hardware. In general, Direct mode is faster than BIOS mode. BIOS mode offers compatibility with standard system I/O functions, and is preferable when running Searchlight in a windowed environment (such as DESQview or Microsoft Windows). If you use a multiple window environment and you have a problem with Searchlight overwriting other windows on your screen, select BIOS mode; if you run only a single copy of Searchlight on any given machine, use Direct. 2 -- Idle Time Limit The value in this field determines the amount of time, in minutes, that Searchlight will wait for keyboard input. If Searchlight stops to wait for input and no keys are pressed after this amount of time has passed, Searchlight will abort the call and recycle back to the Login screen. Please note that the idle time limit is NOT enforced during a local login. 3 -- Quotes File Searchlight's user quotes feature (the "Please leave us a quote" prompt displayed at logoff time) can be enabled or disabled with this option. If enabled, users are able to enter short quotes each time they access the 16 Configuration system, and the Quotes command (on the main menu) can be used to browse through the quotes left by others. 4 -- Return to DOS on Logoff This option controls the behavior of the system when a user logs off, hangs up, or is otherwise disconnected from your BBS. In the default mode, with Return to DOS set to "No", the system will reset the modem, recycle to the Login program, and begin waiting for the next call. If "Yes" is selected, Searchlight will return to DOS when a user logs off. Return to DOS is provided to enable Searchlight to be used with a "front- end" program. Typically, such a program will monitor and answer the telephone, start Searchlight BBS when a call is received, and regain control of the system when the call is finished. These programs are used for special purposes such as the interception of network mail. If you will not be using this type of program, leave this option set to "No". If Return to DOS is used, Searchlight will return a nonzero return code (errorlevel) if ALT-X is pressed by the Sysop or if there is an error encountered while running the BBS. The front end program should be set up to terminate to DOS when this happens, rather than recycle. If this option is selected, the only way to start Searchlight is with command line parameters for the baud rate and maximum time limit. See Command Line Parameters (p. 62) for more information. 5 -- Hangup Phone on Logoff This option controls whether you want Searchlight to hang up the phone when a user logs off. Normally, select "Yes" to hang up the phone and recycle the system for a new user. Use "No" if you are running your copy of Searchlight BBS as a door or from a front end program which requires that the connection be maintained after Searchlight completes. 6 -- Allow Console HotKeys This switch controls whether the special "HotKey" functions (ALT-L, ALT-S, etc.) will be available at the local keyboard. Normally, leave HotKeys enabled if you or other Sysops will be the only people with access to the local PC. If you're running Searchlight in a situation where non-Sysop users will be logging into the system in local mode (such as in a local area network), turn HotKeys Off to disable unauthorized use of sysop functions. 7 and 8 -- Date and Time Formats These switches control the format in which dates and times are displayed. Dates may be displayed in the USA format, MM-DD-YY, or the European format, DD/MM/YY. Notice that Searchlight uses the "-" character as the separator in the USA format, and the "/" in the European format; this is done to help 17 Configuration distinguish the different formats. Inputting of dates, where required, must be done in the selected format. Times can be displayed in 12-Hour or 24-Hour formats. The 12 hour format includes an "am" or "pm" indicator. 9 -- Upload Time Repay Rate This option determines the amount of "repay" time that the system will give for uploaded files. If the repay rate is set to 1, users will be credited with the same amount of time that it took to upload a file, so that if a 10 minute upload occurs, an additional 10 minutes of time are granted when the upload completes. If the repay rate is 2 to 1, an additional 20 minutes of time would be granted for a 10 minute upload, etc. If the repay rate is 0, then no additional time is credited for uploads. Searchlight will reduce the amount of additional time granted after an upload if the additional time would interfere with a scheduled event, or exceed the maximum session time limit. 10 -- ROM File Handling This switch specifies whether files which reside on read-only devices, such as CD-ROM drives, will be accessed directly off the ROM device or copied to hard disk first. When this option is set to "Copy", Searchlight handles all files on read- only devices (those file directories for which the "Path to DIR File" is different from "Path to Files") by copying files from the ROM device to the DIR file path when Download or View commands are used. The directory containing the DIR file, rather than the ROM device itself, is made the active directory when external protocols are invoked. After the command is completed, Searchlight removes the copied files from your hard disk. File copying should be used if you experience sluggish operation or compatibility problems when accessing files on a CD-ROM or similar device. Please see the File Transfer System section of this manual for further details. 11 -- User Log Status This option allows you to designate the status of your user list and caller logs as either Public or Private. When Public is selected, the USER command on Searchlight's main menu is available to all callers and can be used to search and display your user log and last 75 callers log. If you select Private, your user logs are kept private and the USER command is made unavailable to all callers except the Sysop and Co-Sysops. You can also restrict or eliminate the USER command, or any other command, by editing your menus directly with Searchlight's menu editing features. 18 Configuration 12 -- Clock Tick Source This option controls whether Searchlight uses a DOS call, a BIOS call or a direct memory read to obtain real-time clock information. Use "Direct" unless it conflicts with your operating system, otherwise use "DOS" or "BIOS" methods. If you experience problems such as system lockups, extremely short or long time delays, or inaccurate system dates, change this option. 13 -- Use Session Time Limits? Searchlight supports the ability to limit a user's time limit per session (per login) as well as per day. If you'd like to use this ability, set this field to "Yes". Otherwise, leave it set to "No". If you do choose "Yes", you must be sure to set your user accounts up so that they have the desired Session Time Limit attributes. You can adjust accounts manually (via 2-Sysop/Options command on Searchlight's main menu), or you can perform global changes with the Sysop Utilities menu in the CONFIG program. 14 -- Expired User Action This field determines what to do with user accounts which have "expired" -- in other words, which are older than the expiration date specified in the account. The default action is "None", which means that nothing happens to these accounts (in effect, expiration dates are not used). If you'd like to use expiration dates on your system, set this field to either "Reset Access" or "Delete Account". The former setting will cause the user's access level to fall back to the New User level when their account expires. The latter will cause the account to be deleted. In both cases, users receive a 30 day warning message before the action occurs (the warning message appears as part of their log-in sequence). Expired user actions only take place if and when a user with an expired account attempts to log in to your BBS -- no action is taken if such a user never calls back. 15 -- Enable RIP Graphics This switch lets you enable or disable Searchlight's RIP graphics support. RIP is a terminal protocol that can be used to provide features like mouse support and VGA graphics to your callers. For more information, see page 203. 19 Configuration SEARCHLIGHT BBS COMMUNICATIONS SETUP 1. COM Port ...................... 1 2. Support 300 Baud .............. Yes 3. Support 1200 Baud ............. Yes 4. Support 2400 Baud ............. Yes 5. Support 4800 Baud ............. No 6. Support 9600 Baud ............. No 7. Support 19200 Baud ............ No 8. Remote Init String ............ ATH0M0&C1&D3S0=1! 9. Local Init String ............. ATH1! 10. Baud Detect Method ............ Modem Msg 11. Locked Baud Rate .............. None 12. Hardware Flow Control ......... Off 13. Output Buffering Factor ....... 32 14. Buffer Door Programs? ......... Yes 15. COM Port Setup [...] The modem setup screen is very important. Please read the following information carefully. Additional information about modems can be found in Appendix D, Modem Configuration, later in this manual. 1 -- COM Port This controls which communications port, 1 through 4, will be used to communicate with the modem. Make sure you set this option to the correct value for the modem in your system. If you have no modem or serial port, you may give a value of zero for COM Port; this prevents Searchlight from attempting to initialize or otherwise access the modem and allows you to run the system in local mode only. The COM Port number is really an index into a table of communications ports, which you can customize by using the COM Port Setup option in line 15. If you are using a port other than a standard COM1 or COM2 port, you'll probably need to customize your port setup; see below. 2 to 7 -- Baud Rate Searchlight recognizes modem speeds of up to 19200 baud, depending on the modem used. The default setting, as shown above, is for a 2400 baud modem. In lines 2 through 7, specify which baud rates you'd like your BBS to support. Be certain that you do not enable any speeds higher than the highest speed your modem actually supports. You can disable or "lock out" lower baud rates, in particular 300 baud, if you do not wish to support them even though your modem is capable of doing so. Users who attempt to communicate at a "locked out" speed will be not be allowed to access your BBS in any way. If you have a high speed modem, or any modem faster than plain 2400 baud, pay particular attention to lines 11 and 12 in order to get maximum performance from your modem. 20 Configuration 8 -- Remote Init String This field defines the string of characters that will be sent to your modem whenever Searchlight begins running or resets itself after completing a call. You can use this string to send whatever initialization commands your modem requires before being able to accept a call. Besides regular letters and numbers, there are two special characters that you can insert into the modem init string: ~ .................. Provides a 1/2 second delay between characters ! .................. Sends a carriage return (CR) to the modem NOTE that it is important to end the string with a ! character if you want it to terminate with a carriage return keystroke. The ! can be used several times within the string, allowing you to send several commands to the modem. In the above example, the string ATH0M0&C1&D3S0=1 followed by a carriage return is send to the modem for initialization. Various modems may require additional commands for proper operation. Check the manual that came with your modem and Appendix D of this manual for more information. The init string is sent to the modem at the highest speed indicated in options 2 through 7. For many modems, it is essential that at least some command is sent to the modem after each call in order to initialize the modem to the proper transmission speed. Therefore, we recommend that you always have something in this field, even if it's just the empty modem command (AT!). Please read Appendix D, Modem Configuration, for more information about modem setup. 9 -- Local Init String This string is similar to the Remote Init String, except that it is sent to the modem whenever you initiate a "local" logon to the system (by pressing the return key at the keyboard while the system is waiting for a call), or when the system goes off line to execute a scheduled event. In the above example, ATH1 is sent. This command places the phone "on hook", that is, it tells the modem to make the telephone line busy. This is very useful, since any users who attempt to call your BBS while you are logged on locally will receive a busy signal, rather than no answer. 10 -- Baud Detect Method This option determines how Searchlight will set the baud rate for a remote call. When set to "Modem Msg", the software will set the baud rate by the Modem Message method; that is, it expects the modem to send a message that says "CONNECT xxxx" (where xxxx is the baud rate) upon answering a call. Searchlight reads this message and uses it to set the baud rate. 21 Configuration If this field is set to "Key Hit", the program will determine the baud rate via the Keystroke method. It will cycle through the defined baud rates until the user presses the RETURN key on the remote end. If you use this method, you must press the RETURN key several times upon connecting with the BBS in order to establish the proper baud rate. "Modem Msg" is the default and preferred method. This topic is discussed further in Appendix D. 11 -- Locked Baud Rate This field can be used to select a fixed baud rate of up to 38,400 baud for use with high performance, buffered modems that allow a fixed baud rate. When a locked baud rate is selected, that baud rate is used for all communications with your modem regardless of the actual baud rate used by a remote caller. Locked baud rate should only be used with modems which can support this feature; set this option to "None" if you are using a standard 1200 or 2400 bps modem. See Appendix D for more information about locked baud rates and high speed modems. 12 -- Hardware Flow Control Hardware flow control enables Searchlight to perform I/O handshaking with your modem. Normally, hardware flow control is required when a locked baud rate is used and can be left "Off" for standard 1200/2400 baud modems. Be aware that turning flow control "On" when your modem is turned off, disconnected, improperly configured of improperly connected can cause Searchlight to freeze during operation or behave erratically. Locked Baud Rate and Hardware Flow Control should always be used together, and only with modems that support fixed baud rate (fixed DTE rate) with hardware handshaking (also called CTS handshaking). Be sure that your modem is properly configured for handshaking before you turn these options on. Most 9600 & 14,400 baud modems require an &K3 command in the modem init string for proper operation. 13 -- Output Buffering Factor This value controls the size of Searchlight's output buffer during interrupt driven communications. The default value is 32. On slower systems, or when multitasking, setting the output buffering factor to a higher value increases the total speed of the system. Output buffering tends to place a larger interrupt overhead on your system; therefore, if you use multitasking or extensive background processing on your computer, and you experience problems such as lost data over your communications port, set this value to a smaller number or 0. The actual buffer sized used is scaled according to the baud rate and is equal to the output buffering factor * (baud rate/300). Notice that this 22 Configuration value affects the output buffer only, not the (more important) input buffer, which is fixed in size at 512 bytes. This option is strictly for "fine tuning" the performance of your BBS and it will not affect performance greatly in either direction. 14 -- Buffer Door Programs This option determines whether output buffering (if defined in option 13) remains in effect during execution of DOOR programs. In general, you should buffer door programs. However, be aware that buffering such programs can result in sluggish reaction to the ^C key if the Door program uses it to interrupt output. Also, if you have problems with door programs such as lost characters, try turning Buffer Door Programs off. 15 -- COM Port Setup To select this option, place the cursor on line 15 and press Return, or click line 15 twice with your mouse. A new options screen appears which allows you to custom configure four communications ports for use with your BBS: 1. Port 1 Type ................... Standard 2. Base Address .................. 3F8 3. Interrupt ..................... 3 4. External Port Number .......... 1 Port Type The port type can have one of three values. Standard enables Searchlight to talk directly to a regular IBM compatible serial port, like COM1 or COM2, using built in communications drivers. FOSSIL lets Searchlight use a serial port defined by an external FOSSIL driver program. If your system contains a serial port which cannot be accessed directly by Searchlight, but which has a FOSSIL driver program available, you can access that port through its driver by setting the port type and External Port Number appropriately. It is usually not necessary to use FOSSIL drivers unless you want to use a non-standard device, like a multiport communications card. DigiBoard allows you to use a DigiBoard multiport communications card. For more information about this setting, see Appendix H, Digiboard Installation and Use. 23 Configuration Base Address Interrupt Because there are no hardware standards for COM ports beyond COM2, Searchlight allows you to customize the hardware base address and interrupt for all com ports on your system. If you use ports other than the standard IBM compatible COM1 and COM2, find the base address and interrupts used by your ports in the hardware manuals that came with them, and input those values into these fields. If you run a multinode system on a single PC (using a multitasker such as DESQview), it is important that each node uses a unique interrupt and base address for its serial port. For example, many COM3 ports available actually use Interrupt 3 with a different base address than COM1. Such a serial port cannot be used simultaneously with your COM1 port since they share the same interrupt. When purchasing hardware to expand your system beyond COM1 and COM2, purchase serial ports that can be configured to use interrupt 2, 5 or 7. (Note: it is only necessary to supply base address and interrupt data for the COM port actually being used by a particular node). Base Address and Interrupt have no effect if you are using a FOSSIL or DigiBoard type or port. Be aware that the standard base address and interrupt for COM1 is 3F4 and 4, and COM2 is 2F8 and 3. We suggest you do not alter these unless you have a specific requirement. If you do not know the hardware base address and interrupt of the serial ports on your system, run another application that uses those ports (like a terminal program) and check that software's configuration menus for the proper values. External Port Number When you use the FOSSIL or Digiboard port type, use this line to specify the actual physical COM port number you want to use. The value entered here is what is actually sent to the FOSSIL or Digiboard software driver to indicate which port should be used. The External Port Number has no effect when using Standard port types. 24 Configuration SEARCHLIGHT BBS PATHNAMES SETUP MENU 1. Primary Program Path .......... C:\BBS 2. Alternate Program Path ........ 3. Data Files Path ............... C:\BBS 4. Text Files Path ............... C:\BBS\TEXT 5. Include Files Path ............ 6. Mail Files Path ............... 7. Default Log File .............. 8. Activity Log Filename ......... ACTIVITY.LOG 9. Files Log Filename ............ FILES.LOG 10. Default Passwd for Uploads .... 11. DOOR Parameters Filename ...... 12. Chat File Path ................ C:\BBS 13. Primary Menu Path ............. C:\BBS\MENU 14. Alternate Menu Path ........... These options select path and filenames that Searchlight will use when accessing your disks. Flexible pathname selection is provided so that you may make the best use of available disk drives. If you just installed Searchlight, these fields will contain the proper values for your system. We recommend that you do not alter any of these fields until you are familiar with the field's function. 1 -- Primary Program Path This option determines where Searchlight will look for its executable (.EXE) files, overlay (.OVR) files, and the STRINGS.SYS file. If no pathname is given, it defaults to the current directory. Use this field if you wish to have some or all your program files located on a different drive or directory than your data files. You can use this option to place your .EXE files into a high-speed RAM-disk for faster access. 2 -- Alternate Program Path If an executable file can't be found in the Primary location, Searchlight looks to this path for the file. For example, if you use a high-speed RAM disk as your primary program path, but not all of your program files fit on the ramdisk, store the most important ones there and store the rest in another location specified by the Alternate program path. We recommend storing the following files in a high speed disk drive (as specified in your Primary path) if available: BBS.EXE, BBS.OVR, BBS.INT; FILES.EXE, FILES.OVR, FILES.INT; STRINGS.SYS; and LOGIN.EXE. The remaining EXE files are not accessed directly by Searchlight and would not benefit by being placed in high speed storage. 25 Configuration 3 -- Data Files Path This option provides the path that the system with use to access its data files (all files ending in .SL2 and .DEF, except for CONFIG.SL2 and EVENT.DEF, which are always located in the current directory). On multiuser systems, you use this option to create multiple nodes which reference the same database (see the following pages for additional multinode setup information). 4 -- Text Files Path The Text Files path is the directory where Searchlight will look for all of its text files. These include the user-defined login and info files, subboard and file directory signon messages, help files, and any files referenced in messages via the @@FILENAME directive. Note: Text files ending in "DEF" (i.e. EVENT.DEF) should be located in the current or data file directory, rather than the text directory. For security reasons, we recommend that the Text directory be different from the current directory and the Program File path. This is because the @@FILENAME command can access any file in the text path, and can lead to unwanted access to system or other private files (@@FILENAME is discussed further in the Text Editing section of this manual). 5 -- Include File Pathname This pathname allows you to specify a directory which the users of you BBS can access for the purpose of "including" text files in messages (via the "%%FILENAME" directive, as discussed in the Text Editing chapter). Normally, if you use this pathname, you'll also have a file transfer directory set to the same path. See File Transfer System for more details. 6 -- Mail Files Path The directory specified by this path is used for mail logging. The mail logging option, which can be turned on or off for each user in the system (via the 2-Sysop/Options command), provides an automatic log of all mail sent and received by users who have mail logging enabled. Searchlight stores each user's mail in a separate file; these files will have filenames created by a concatenation of the user's first and last name (for example, SYSOP.LOG or FLAROSA.LOG). The mail files path is where these files will be written. If no mail file path is given, it defaults to the current path when Searchlight is loaded. 7 -- Default Log File Default Log File is a default name that will be shown whenever a log (ALT- L) or forward to disk operation is selected. A default name is not required, and is only a convenience that allows you to log messages and information to one file without having to enter its name each time. 26 Configuration 8 -- Activity Log Filename 9 -- Files Log Filename These options provide the filename, and optionally drive letter or pathname, for the text files which will hold your system's activity logs and files system logs. As shown above, the default filenames are ACTIVITY.LOG for the login activity logs and FILES.LOG for the files system log. These filenames can be changed (or redirected to devices such as PRN) if desired. No logging takes place if these filenames are left blank. Note that by default, each node on a multinode system will generate a separate set of log files for each node (located in each node's home directory area). 10 -- Default Passwd for Uploads This field, if filled in, defines a default password that will be assigned to each new file that is uploaded to your BBS via the File Transfer system. The purpose behind having a default password is to allow you to have control over new files. Once a file is uploaded and assigned the default password, no one will be able to download the file until you remove the password, thus giving you the opportunity to check each new file before you allow it to be downloaded by your users. Most sysops leave this field blank, allowing all new files to be downloaded without having to be cleared. If you do set this field, remember that you, or a co-sysop, must reset the passwords on all new files before they can be accessed (see File Transfer System for more information). 11 -- DOOR Parameters Filename This field can be used to set the filename, including drive and/or path, of the PCBoard parameter file created by the DOORS system when an external program is run. The DOOR Parameters File is a file containing information about your BBS that can be accessed by an external program; it is provided primarily for compatibility with PCBoard door programs. The format and use of this file is discussed further in the Doors Subsystem section of this manual. This field should specify a full filename, like "C:\SLBBS\PCBOARD.SYS", not just a path. If you leave this field blank, no parameter file is generated. 12 -- Chat File Path This option determines the drive and path where the file CHAT.SL2, used to hold the messages transmitted via the system's internode chatting facility, will be created. Since the messages in this file are short and of a temporary nature, and since the chat function accesses this file frequently, we recommend that you create a small RAM-disk or other high speed drive in your system for the purpose of containing this file, in 27 Configuration order to maximize the speed and efficiency of the chat system. Chat File Path has no effect in single user installations. Unlike Searchlight's other data files, CHAT.SL2 need not be present in the designated path when the system is started, and will be created if not available. Thus, you will not need to back-up or copy CHAT.SL2 to or from temporary disk drives each time your system is reset. 13 -- Primary Menu Path 14 -- Alternate Menu Path These fields specify the path where Searchlight will find its menu files. Menu files are the external files (ending in .MNU) that describe the menus used by the system. When you install Searchlight, the default menus are loaded onto your system and the path where they are located is placed in the Primary Menu Path field. If you wish to change the location your menu files, type the new location here, after moving the MNU files to the correct path. When both a primary and alternate menu path are provided, Searchlight first checks the primary path when attempting to load a menu file. If the file is not found in that directory, then the alternate path is used. This allows you to create alternate menus for a particular node without providing two different copies of all your menu files. Notice that when you run the CONFIG program and select the Menu Editor option, only those menus in the Primary menu path are displayed. In a multinode system with several menu paths, switch to the home directory of the desired node in order to edit its menus. Relative Versus Absolute Pathnames As absolute pathname is a pathname that contains a drive letter and begins at the root directory. A relative pathname is one which begins at the current directory or omits a drive letter. For example, a pathname such as "C:\SLBBS\TEXT" is absolute; whereas "SLBBS\TEXT" is relative. We recommend that you use only absolute pathnames when configuring Searchlight BBS. The reason for this is that some Searchlight BBS programs and utilities can run from outside your "home" directory, and therefore will require absolute pathnames to locate your data files. This is especially true for multiuser systems, and systems which run in a local area network environment. If you do run a LAN, we further recommend that you use the same drive letters on each workstation to refer to the drives on which your Searchlight files are stored. Otherwise, nodes on other workstations may not be able to locate message subboards, file directories and DOORS defined in the Node 1 directory. 28 Configuration SEARCHLIGHT BBS PROTOCOL SETUP MENU Searchlight BBS provides a total of 15 "slots" for the designation of file transfer protocols. Protocols can be either internal (supplied by Searchlight BBS) or external. An external protocol is a program which is capable of transferring files to or from a remote system via modem. Typically, such programs are written to be used from the DOS command line or as part of a BBS like Searchlight, where they can provide new transfer protocols such as Ymodem, Kermit, Bimodem, etc. in addition to Searchlight's built-in protocols. Each protocol consists of a name (which is displayed by the Files system), a type, and for external protocols, a send command and a receive command. To add or change a protocol, select one of the protocol slots from the list of 15 possible slots displayed by the Protocol Setup menu. Searchlight will display a setup screen with these options: 1. Protocol Name ................. Zmodem (Internal) 2. Protocol Type ................. Zmodem 3. External Send Command ......... 4. External Receive Command ...... In line 1, enter the name of the protocol. Line 2, Protocol Type, selects whether a particular protocol is an external protocol (like DSZ) or one of Searchlight's built in protocols. The built in protocols include Xmodem, Xmodem/CRC, Xmodem/1K, and Zmodem. To select which type of protocol you want, toggle this line to the appropriate value. For internal protocols, no further action is necessary. For external protocols, you need to supply the appropriate commands needed to implement that protocol on your system. In general, commands should include the full pathname to the DOS file containing the command to execute, including the COM, EXE, or BAT file extension. Searchlight metacharacters can be used to provide information such as baud rate, COM port, etc. on the command line (see Doors Subsystem, page 170, for more information on metacharacters). Where external protocols that require filenames on the command line, two special parameters, "%F" for single filenames and "%W" for wildcards, can be used to specify the filename(s) to send or receive when these programs are invoked. Protocols which support the use of an indirect file can specify it on the command line as "@Filename". Press ESC when done. To review or change external protocol setups later, just select the protocol you wish to view or edit from the External Protocol setup screen. Please consult External Protocol Setup in the File Transfer System section of this manual (page 132) for further details and examples of external protocol command lines. Notice that lines 3 and 4 apply only to external protocols, and are ignored unless "external" is selected as the protocol type in line 2. 29 Configuration 30 Configuration SEARCHLIGHT BBS SCREEN COLORS SETUP 1. Normal Text Color ............. Blue 2. Normal Background Color ....... Black 3. Inverse Text Color ............ White 4. Inverse Background Color ...... Blue 5. Command Color ................. Magenta 6. Subboard Highlight Color ...... Yellow 7. Heading Color ................. Lt Cyan 8. Input/Chat Mode Color ......... Green 9. Prompt Color .................. Lt Magenta 10. Special Messages Color ........ Red 11. Error Messages Color .......... Lt Blue 12. Alternate Color ............... Magenta The sixth selection on the Setup menu is used to set screen colors. When a color CRT is used, Searchlight can display up to ten different foreground and two background colors, selected from a palette of 16 colors. The colors you enter into the above fields are used when run on a computer with a color display, or when color mode is selected by a remote terminal. In order to see the colors, the remote terminal must have a color CRT and it must recognize the ANSI escape sequences used to create colored text (the specific ANSI sequences used to create each of the above colors can be found in your DOS manual). Normal Background Color (field #2) affects only the background color of the local PC. The background color of the terminal is always black, except when highlighting input fields. Searchlight is capable of supplying color or monochrome text to the remote terminal independently of the local PC. That is, if the local PC (the computer running the Searchlight BBS Software) has a color CRT, but the logged-in user selects Monochrome graphics, color will still be displayed on the local screen, even though only monochrome codes are being sent to the terminal. Similarly, if the system is run on a Monochrome display, only monochrome graphics are sent to the screen even though color graphics are being sent to the terminal. Note that while the colors sent in Color mode can be adjusted, the monochrome mode is fixed and will always appear the same regardless of the colors selected for Color mode. If you don't own a color display, it is suggested that you leave the colors set to their default values. Experience has shown that it is difficult to estimate how a particular color combination will look without actually viewing it on a color CRT. 31 Configuration SEARCHLIGHT BBS AUTODOORS SETUP The AutoDoors setup screen lets you specify "automatic doors", or door programs which execute automatically rather than on command as regular doors are used (see Doors Subsystem later in this manual for more information about door programs). Four AutoDoor settings are provided: New User AutoDoor, Login AutoDoor, Logoff AutoDoor and Upload AutoDoor. The Login and Logoff AutoDoors, if specified, execute automatically when a user logs in or logs off. The New User AutoDoor executes immediately after a new user registers with your system. Upload AutoDoor is a function that executes after any upload of a file to your BBS. Typically, it's used to scan uploaded files for viruses, repack files into selected formats, and so on. Please see File Transfer System later in this manual for more information. 1. Command ....................... 2. Directory Path ................ 3. Communications Support ........ None 4. Abort Method .................. None 5. Write Protection .............. No 6. Parameter File ................ None 7. Pause After Door .............. No The parameters for AutoDoors are very similar to the parameters used in regular doors; please see the Doors Subsystem section of this manual for more information. Here is a brief summary: 1 -- Command This is the command name used to start the AutoDoor, including any command line parameters or Searchlight metacharacters necessary to start the program running. Programs other than batch files or DOS commands should include the .COM or .EXE extension on the program filename. 2 -- Directory Path This parameter specifies the directory which will be made active before the AutoDoor command is executed. If you wish to remain in the current directory, specify "." for this parameter. 3 -- Communications Support For this field, specify "Standard" if the AutoDoor does not provide its own RS232 serial support, "None" if it does. "Force-Color" may be used to force a program which uses color to run in color mode on a monochrome system. 32 Configuration 4 -- Abort Method This field specifies the action to take if a carrier loss is detected during the execution of the door. Select "Terminate" for a normal program exit, "Reboot" to reboot the computer, or "None" to take no action in case of a carrier loss. 5 -- Write Protection A value of "Yes" forces software write protection of all drives during the execution of the door. You must use "No" for any program that needs to write to disk. 6 -- Parameter File This option lets you create a "drop" file, such as a DOOR.SYS file, for use with this door program. 7 - Pause After Door If set to Yes, Searchlight will pause with the "Press any key to continue" prompt after running the door. You can also set up programs to auto execute during Searchlight's login or logoff sequence, or at other times, by adding the commands directly to Searchlight's menus. See Menu Editor later in this manual for more information. 33 Configuration SEARCHLIGHT BBS FUNCTION ATTRIBUTE SETUP 1. Forward Messages .............. 0 2. Internode Chatting ............ 0 3. Editor Text Quoting ........... 0 This CONFIG program selection lets you regulate, by security attributes, several important functions. 1 -- Forward Messages This field regulates the ability to forward messages. Forwarding messages means being able to copy a message from one place (such as a subboard or a mailbox) to another place, via the Other/Forward command. If you want to restrict this activity, specify security attributes here. Only users who have all of the attributes listed here will be able to forward messages. 2 -- Internode Chatting If you want to regulate the use of internode chatting, place specific attributes here. Only users who meet these attribute requirements will be considered available and able to use chat functions. This field actually controls the prompts that appear during the login sequence, and access to the "Chat" command from the message disposition line. The main "Chat" command (on the main menu) is regulated separately (you need to use the menu editor, described later in this manual). In most cases you will want to make sure that the attributes listed here match the ones listed in the main menu for the "Chat" command. 3 -- Editor Text Quoting Text Quoting means the ability to copy the contents of a message into the editor screen when making a reply to that message, via the F4 or ^KG command sequence. If you wish to regulate who has the ability to perform such quoting, list the desired attributes here. Searchlight BBS provides much more extensive customization of main menu and submenu functions using the Menu Editor, which is described in more detail in section 11 of this manual. 34 Configuration DEFAULT ACCESS LEVEL SETUP This configuration option lets you define up to 12 default access levels. Although each user in a Searchlight BBS system can be individually assigned access levels, time limits, attributes and so forth, often you will want to group sets of these items together into default groups. For example, you may have default groups for New Users, Validated Users, Adult Users, Members, and so forth. Default Access Levels gives you a way to predefine the parameters for these groups and quickly assign them to individual users. The first two items on the Default Access Levels menu are predefined as "New User" and "Validated User". Although you can change the name and definitions of these access levels, Searchlight will always assign access level "A" to new users, and will always assign "B" to users when you press the ALT-V (validate) key. To define a new access group, go to the first "Unassigned" selection and press Return. The following menu items appear: 1. Name .......................... New User 2. Message/Doors Access Level .... 2 3. Files Access Level ............ 2 4. Security Attributes ........... ABC 5. Download:Upload Ratio ......... 3 6. Daily Time Limit .............. 40 7. Session Time Limit ............ 40 8. Days Until Expiration .........365 1 -- Name This field defines a descriptive name for the access level. This is the name that appears when you use the 2-Sysop/Validate or Other/Validate commands from Searchlight BBS. 2 -- Message/Doors Access Level This field is the numerical access level (from 0 to 255) that is used for access to message areas and DOORS. In Searchlight BBS, access levels and security attributes work together to define which users have access to particular features. In order for a user to access a subboard, for example, that user must have at least the access level required to access that subboard, and all the security attributes required for it. (You determine what those requirements are when you create the subboard). The only access levels which have absolute meaning in Searchlight are levels 254 and 255, which define cosysops and Sysops respectively (Sysops and cosysops have general access to all features on the system). 35 Configuration 3 -- Files Access Level This field defines the user's access level in the Files section of the BBS. 4 -- Security Attributes Security attributes are letters from A to X which work in conjunction with access levels to provide a more flexible level of regulation. Security attributes are non-hierarchical in nature: whereas an access level of 100, for example, grants a user all the privileges of access levels 0 through 99, security attribute 'X' does not automatically grant a user access to attributes 'A' through 'W'. Security attributes can be thought of as individual "keys" that a user most possess in order to open (access) a particular item on your BBS (that item can be a subboard, file directory, DOOR, or a command, like POST). Suppose a particular item has "locks" (attributes) A,B and C associated with it: then in order to "unlock" that item, a user must have keys A,B and C. A user who has, for example, keys B and C, but not key A, can't use the item, even if the user has many other keys. Security attributes give you the ability to mutually exclude groups of users from areas of your BBS. For example, if one group of users has attribute "A" only and another, attribute "B" only, no users from the first group will have access to subboards that have the "B" attribute, and none from the second group will have access to subboards with the "A" attribute. Of course, if you might wish to assign some user attributes A and B, in which case that user would have access to both areas. Keep in mind that you can define security levels using any number and combination of the 24 attribute levels. You're not limited to 24 security levels: the actual number of combinations available is in excess of 16 million. 5 -- Download:Upload Ratio This field defines a user's maximum downloading privilege as a ratio to the amount of data uploaded. For example, a value of 2 in this field would mean that the user could download twice the amount of files uploaded. Ratios are computed from the total amount of KBytes uploaded and downloaded, without regard to the actual number of files transferred. For greater control over uploading and downloading, you can also define a downloading "grace period" for new users, and value multipliers to individual directories. See File Transfer System for more information. 6 -- Daily Time Limit This field defines the user's maximum daily time limit in minutes. Values can range from 0 to 1440 (the total number of minutes in one day). 36 Configuration 7 -- Session Time Limit This field defines the maximum amount of time a user may spend in any one particular session (log-in). Values can range from 0 to 1440 minutes. Note that the value in this field means something only if Session Time Limits are enabled (see General Setup Menu #2). 8 -- Days Until Expiration This field defines the number of days until the account "expires". Actually, this number is used to compute an expiration date for the user account. The expiration date is set by adding this number of days to the current date when validating the user, or to the current expiration date if one exists for that user. Expiration dates are used only if they are enabled (see General Setup Menu #2). 37 Configuration PITFALLS AND ERRORS Searchlight 3.0 requires a minimum of 250K of free memory to operate. If you were running an earlier version of Searchlight in which less than 250K of RAM was allocated to any node, you will need to rearrange your system resources to allow at least 250K for each Searchlight 3.0 node. If you receive error messages such as "Error 202", "Error 203" or "Program too big to fit in memory" when you attempt to load Searchlight, it usually indicates that there is insufficient free memory for Searchlight to operate. Searchlight 3.0 opens and manages many files, and therefore uses more file handles than the average program. In order to accommodate this, we recommend that you use the command FILES=30 in your CONFIG.SYS file (located in the root directory of your boot drive) for single node systems. For multinode systems running under DESQview -- or for systems running large TSRs like network drivers -- more file handles will be necessary. If you encounter problems such as inability to access subboards, file areas, or menus, or if you receive "Error 004" or "Error 103" messages, you should try increasing the FILES= value in your CONFIG.SYS file. Lack of available file handles is one of the most common causes of problems that involve opening and accessing files. If you encounter a message that says "Error Loading Menu" when you first start Searchlight 3.0, it's probably because the Menu Files Path set in Pathnames Setup is incorrect, or points to a directory which does not contain your menu (MNU) files. If you upgraded a multiuser system from Searchlight 2.15 to 3.0, you need to update each node's CONFIG file with the menu file path. If you still get this message after confirming that the menu files have been installed and their path properly specified, increase the FILES= value in your CONFIG.SYS file. OVERLAY SETUP Searchlight's main executable file, BBS.EXE, uses and overlay file. The overlay contains additional program code which is loaded from disk to memory as a program runs. Overlays are primarily used to reduce the amount of memory that Searchlight requires to run, in exchange for some loss of execution speed as modules are loaded from disk. However, if your computer contains ample memory, you can increase Searchlight's execution speed by allocating a larger overlay "buffer" area, or loading the entire overlay file into expanded memory. A text file called BBS.INT is used to adjust these options. If you have conventional memory available, you can improve Searchlight's execution speed by increasing the overlay buffer area within the program. Edit the file BBS.INT with a text editor and locate the line containing a decimal number: this is the overlay buffer size in bytes. The minimum buffer size is 15,000 bytes. Since Searchlight requires approximately 250K of conventional memory to run, any available memory you have beyond 250K can be used to expand the overlay buffer. The maximum buffer size you should use is the size of the overlay (OVR) file. 38 Configuration If you have expanded (EMS) memory available, Searchlight will load the entire overlay file into EMS, which is much faster than loading overlays from disk. You enable this option simply by typing the command "EMS" in the BBS.INT or FILES.INT file. If insufficient expanded memory is available at runtime, Searchlight will not load its overlay into EMS but will continue to operate by reading it from disk. You can examine the actual size of your overlay buffer, EMS usage and available free memory anytime SLBBS is loaded by pressing the F8 key several times until a memory status line appears at the bottom of your screen. Use the memory information to determine the available resources on your system and make appropriate adjustments to your INT files. TEXT FILES SETUP Searchlight provides you with a way to customize your BBS by defining your own messages that will be displayed by various parts of the program. You can define a "greeting" message that will be shown to all users when they connect with your system, a message to be shown to new users, a general information message, etc. In addition, you can set up separate messages for RIP, ANSI and non-ANSI terminals, or use the same message for all. Setting up text files is not required, but most people will want to do so before running their system. If you're in a hurry, you can skip this section of the manual and set up your text files later. The messages you define will be saved in files. To write them, you must use a word processor or text editor that can write standard ASCII files to disk. You can use the Searchlight's built-in text editor for this purpose, provided that it is adequate for the files you intend to produce. Files that end in .TXT are "standard" text files. These should contain only ASCII text. The standard text file will be used when ANSI graphics capability is not selected. Files ending in .ANS are ANSI files. These can contain ANSI escape sequences, as well as IBM character graphics (i.e. eight-bit character codes). The ANSI version of the file is used when ANSI graphics are enabled. Files ending in .RIP are RIPscrip files; RIPscrip is a special terminal protocol that encompasses ANSI but includes graphics primatives, fonts, icons and other feautres. RIP files are displayed only if Searchlight detects RIP compatibility on the remote terminal. For more information about RIP files and RIP graphics, see page 203. You do not need to create three versions of a file if you don't wish to send separate text to RIP, ANSI and non-ANSI users; simply create one file with the TXT extension, and it will be used in all cases. All text files should be located in the "text" directory, as defined in your configuration file. The following files are defined: 39 Configuration LOGIN (.TXT/.ANS/.RIP) This file is displayed immediately after the "Select Graphics" prompt during the login sequence. It normally contains a welcome message with the name of your BBS, etc. NEWUSER (.TXT/.ANS/.RIP) This file contains information for new users. It is displayed when someone logs in as NEW and attempts to register their name. You can use this file to communicate any requirements or rules to new users of your system. Each user sees this file only once, when first registering with the BBS. INFO (.TXT/.ANS/.RIP) The "info" file can be used to enter a short description of your system. It is displayed whenever the INFO command is used. FILES (.TXT/.ANS/.RIP) This text file is displayed whenever you enter the FILES system. Use it to provide news and information about your file transfer directories. LOGOFF (.TXT/.ANS/.RIP) Similar to LOGIN, these files contain a short message to be displayed on the screen when a user logs off (disconnects). Default Subboard Entry Messages For each message subboard, you can define a text message that will be displayed upon entry to the subboard. To define a message for a subboard, create a file using the name of the subboard and the extension ".TXT", ".ANS" and/or ".RIP". For example, the files GENERAL.TXT GENERAL.ANS GENERAL.RIP would contain text messages to be displayed upon each access to subboard 'GENERAL' (the .TXT file is displayed if ANSI graphics are not selected, the .ANS file is displayed if they are, and the .RIP file only if RIP mode is enabled). You don't have to define text messages for any subboard. If no message file exists, no message is printed upon entry to that subboard. 40 Configuration Default File Directory Messages You can define a default text message to be displayed upon each entry to a file directory in the FILES section of the BBS. To do so, create a text file with the directory's name followed with a ".TXT", ".ANS" and/or ".RIP" extension. For example, if you have a directory called UPLOADS, the file UPLOADS.TXT would be used to contain the message to be displayed each time the UPLOADS directory is accessed. Note that the file directory text messages should be in the text directory, as with the other text messages; not in the directory containing the uploaded files for that directory. COLOR CODES AND MACROS Searchlight supports a set of mnemonic, two-character color codes and macros that can be embedded into any message or text file used with the system. For more information, see the section on Embedded Macro Codes later in this manual. EVENTS In addition to "Door" programs, which can be set up to run on-demand from the BBS system's menus (see Doors Subsystem later in this manual), Searchlight supports automatic or timed "events". An event is a program, DOS command, or batch file that executes automatically at a certain time and date, usually late at night when the system is unattended. You can create automatic events that happen once or events that execute on a daily, weekly, or monthly basis. For a full explanation of events, refer to Appendix C, Automatic Events. MENU EDITING Searchlight BBS has a full featured menu editing system that allows you to modify or replace the menus that are included with the package. You can't modify the CONFIG menus described in the previous section, but you can examine and change most of the menus that appear in Searchlight BBS itself, and you can create new menus. Please be aware that the majority of this manual describes Searchlight using the default menus that come with the system. If you make changes to these menus, you won't see the same screen displays or use the same keystrokes to access Searchlight's features that are described in the 41 Configuration documentation. However, the behavior of the commands themselves is the same, regardless of how they are executed. For more information, see Menu Editor later in this manual. 42 Multinode Setup MULTINODE SETUP With multiuser versions of Searchlight BBS, you have the capability of setting up two or more "nodes". Each node runs as a separate task or on a separate PC (using a local area network), but accesses a common set of data files, thus enabling you to have two or more people logged in to your bulletin board at the same time. To run a multinode Searchlight, you need two things: a multinode version of the SLBBS software, and a multitasking operating system. Multitasking systems are programs that allow you to run two or more programs at the same time on your PC, or allow two or more PCs to access the same database of files (as in a local area network). Common systems are DESQview, Microsoft Windows, OS/2, Lantastic, and Novell. After installing your system for a single node (Node 1), follow these steps to bring additional nodes online: [1] Each additional node you set up requires its own directory and its own copy of the CONFIG.SL2 file. You do not need to copy any other files. To create node #2, make a second BBS directory and copy your existing CONFIG.SL2 file into it; for example, at the DOS prompt enter MKDIR C:\BBS2 COPY C:\BBS\CONFIG.SL2 C:\BBS2 Before copying the file, you should check to make sure that complete pathnames are specified in the Pathnames Setup portion of the CONFIG program. Repeat the process for each additional node, using C:\BBS3, C:\BBS4, etc. [2] Each node must be assigned a unique, sequential node number. To do the setup, you run the CONFIG program for each node, including the original node. Since CONFIG looks for the file CONFIG.SL2 in the current directory when it runs, you must switch to each node's directory, run CONFIG, set the required options, then exit CONFIG and go on to the next node. To configure node 2's options, you might type this: CHDIR C:\BBS2 C:\BBS\CONFIG Notice that we typed "C:\BBS\CONFIG" as the command to run the CONFIG program; this is because CONFIG.EXE no longer resides in the current directory. However, you can avoid having to type an explicit pathname if you use DOS's PATH command to set the search path to the directory containing the Searchlight program files (see your DOS manual for further assistance). [3] Select the first CONFIG item, General Setup Menu #1. The screen will show the last two menu items as follows: 5. Node Number ................... 1 6. Number of Active Nodes ........ 2 43 Multinode Setup Each node should be assigned a different node number. Use 1 for your original node, 2 for the second node, etc. In addition, each node must know the total number of nodes in your system. If you will be running a two-node system, for example, each node must have item #6 set to 2. If you add or remove nodes, each node's CONFIG file must be updated. [4] Each node on the same machine must access a separate serial port. Be sure to configure the "Communications Setup" parameters correctly. If you will be running one or more nodes in "local" mode only, set the COM Port to a value of 0. Each node can have its own separate baud rates, modem init strings, COM port setups, etc. [5] Each node, with the exception of the original node, must be programmed with the appropriate program pathname and data pathname in order for it to locate and use the original node's files. To do this, execute the CONFIG program and select item #D, Pathnames Setup. As an example, if your original node is in C:\SLBBS, you would set up your additional nodes as follows: 1. Primary Program Path .......... C:\SLBBS\ 3. Data Files Path ............... C:\SLBBS\ In addition, you will want to update text, mail, include, and log file pathnames if necessary. Also, be sure that the "Chat File Path" option is set to the same value for each node; this will enable users to communicate using the chat facility (see additional information about the Chat File Path in the preceding configuration instructions). [6] To begin running a node, change to the node's directory and execute the SLBBS program. Again, you should set a search path to your program directory or give the full pathname to SLBBS.EXE. Each node must be started up separately (your multitasking system or network should already be in place, enabling you to start two or more processes running at once). MULTINODE OPERATION Here are some notes and tips on running in the multinode environment: When logged in to a particular node, you can use the Who command from the main menu to see the names of users logged on to other nodes. A user cannot be logged on to more than one node at a time. The login program will reject you if you try to log in and your name is already active on another node. If two or more users attempt to save, delete, or edit messages at once, the system will process the requests in order; as a result, you may have to wait several seconds for your request to be honored. This is normal. File locking: If your computer crashes while one or more nodes are engaged in a disk-writing operation, the system may remain permanently "locked" in 44 Multinode Setup such a way that no node can save a message. If this happens, shut down all remaining nodes and reboot your computer(s). This will return your system to normal operation. Certain sysop commands (such as Subboard Repair facilities) should not be used while other users are on the system. You must shut down all nodes and leave them down while running these commands. Use complete pathnames to designate directories in Searchlight BBS. By "complete" pathnames, we mean a pathname that contains a drive letter and starts at the root directory, such as "C:\BBS\NODE1", rather than a pathname which omits the drive letter or which doesn't contain a leading backslash. Complete pathnames are important because the paths pointed to should be accessible from anywhere in your system. LAN Setup: If you are running Searchlight with a local area network, you must make sure that two users do not attempt to access the same node at the same time. This will usually mean constructing a node for each PC on the network. Alternately, a batch file or other front end program can be written to automatically select the proper home directory when starting SLBBS. On a LAN, we strongly recommend that each workstation use the same drive letters to refer to drives that contain Searchlight BBS files. This is necessary in cases where all nodes refer to a common setup file (like the SUBBOARD.SL2 and FILEDIR.SL2 files) in order to prevent ambiguity which might arise if workstations used different drive letters to refer to the same volume. If it is impractical for you to assign the drive letters directly in your LAN operating software, use DOS's SUBST facility to create substitute drive letters. To run Searchlight in a local-only mode, you can set the "Return to DOS on Logoff" feature (found in the CONFIG program) and start the system with the command "SLBBS Local". You may want to disable the system hotkeys if allowing non-sysops to run the program in local mode. If you run multiple nodes on a single PC (using a multitasking operating system such as DESQview), each node must use a unique hardware interrupt value for its serial port. Normally this will not be an issue if just 2 nodes are run, but will need to be considered when you expand to a third node and beyond. Be sure to purchase communications hardware which is capable of addressing unique hardware interrupts. On most PCs, interrupts 2,3,4,5 and 7 are available for use with modems. Searchlight has special support for the DigiBoard brand of multiport hardware. If you are using a DigiBoard product, consult Appendix H, Digiboard Installation And Use. Selection of a unique interrupt is not necessary for nodes that do not use a modem (i.e. local use nodes with the COM port designated as 0). Of course, if you use a LAN, each PC on the network can use whatever local COM 45 Multinode Setup port is available without regard to interrupts used on other PC's in the LAN. Chatting: Inter-Node Chatting (the ability to exchange short messages with users at other nodes) is available in multiuser systems. See "Using Chat Mode" later in this manual for details. 46 Subboard Maintenance SEARCHLIGHT BBS SUBBOARD MAINTENANCE Message Subboard Maintenance, the second choice on Searchlight's CONFIG program main menu, provides you with a way to create, change, and delete message areas or subboards. Searchlight subboards are independent message areas that contain public or semi-private group discussions: they're equivalent to forums or conferences used in other online systems. To access the Subboard Maintenance screen, simply select item "B" from the CONFIG main menu. You can also call Subboard Maintenance up directly from the DOS command line by typing: CONFIG B You'll see a list of the subboards that are available on your system, along with these options: Edit Entry Add Delete Utilities Exit Except for the Add option, these commands operate on the subboard that's pointed to by the cursor position. To edit, delete, or perform utilities on a subboard, move the cursor to the desired subboard by pressing the direction keys (Up/Down arrow, PgUp, PgDn), then press , F2 or F3. Or, if you have a mouse, simply point to the desired subboard and "click" the left mouse button once to move the cursor, or twice to edit the subboard. You can scroll the list or operate any of the F key options by "clicking" on the names of the commands as they appear on your screen. To quickly locate a subboard when your subboard list is large, press the first letter of the subboard name. This will move the cursor to the first entry that begins with that letter. Since the CONFIG program always displays the subboard lists in alphabetical order, the desired subboard will then be either at or very near the cursor position. Searchlight creates three default subboards, MAIL, BULLETIN and GENERAL, when you first install it. MAIL and BULLETIN are "hidden" subboards that are generally not used directly by your callers; we recommend that you do not change or delete these subboards. GENERAL is intended to be a "general purpose" subboard for use by callers; you can edit or remove it if you wish, however, be sure that there is always at least one subboard available for callers to use when they log in to your BBS. ADD SUBBOARD Press F1 to create a new subboard. Searchlight will prompt you for a subboard name, and a path in which to store the data files for the subboard. The subboard name must be a unique, 1 to 8 character, legal DOS filename. The path must refer to an existing drive and directory (it defaults to the current directory, but may be changed). We suggest you create one or more subdirectories for storing your subboard files, rather than keep them in the default current directory. Create the directories from DOS, using MKDIR, before running the CONFIG program. 47 Subboard Maintenance If the name or path you enter contains an error, Searchlight will prompt you to enter new information. Otherwise, it creates the data files for the new subboard. Each subboard you create will have three files: a header file, a message text file, and a member file; the filenames for these files are the subboard name followed by the extension .HDR, .MSG and .MBR. For example, if you created a subboard called "BUYSELL" on your system, the following files are created on disk: BUYSELL.HDR BUYSELL.MSG BUYSELL.MBR As you can see, the subboard name "BUYSELL" is used as the actual filename for the subboard data files, which is why the subboard name is required to be a legal DOS eight character filename. Subboard names may contain numbers (as is allowed by DOS) and a few symbols (such as "-" or "!") but may not contain blank spaces, back or forward slashes, periods, or other reserved characters. New subboards are created with a number of default options that can be changed to suit your needs. Once the file creation sequence is complete, the Add Subboard procedure moves directly to the Subboard Edit screen, where you can enter a descriptive name for your subboard and edit the default options as needed. EDIT SUBBOARD Whenever you create a new subboard, or edit an existing subboard, the following input screen will appear: 1. Subboard Name ................. GENERAL 2. Subboard Description .......... General Messages 3. Data Files Path ............... C:\BBS 4. Required Access Level ......... 0 5. Join Attributes ............... ABC 6. Post Attributes ............... ABCD 7. Subboard Sysop ................ 8. Max. Messages ................. 1000 9. Max. Message Size ............. 400 10. Anonymous Messages ............ No 11. Auto Purge Old Messages ....... No 12. Compress Message Texts ........ Yes 13. Allow Users to Join ........... Yes 14. Display on Subboard Lists ..... Yes 15. Echomail Zone Number .......... 0 16. Echomail Net Number ........... 0 17. Echomail Node Number .......... 0 18. Echomail Point Address ........ 0 48 Subboard Maintenance As with the general configuration options, edit these fields by moving the cursor to the appropriate location and entering or editing the data within. Here is an explanation of each field: 1 -- Subboard Name The DOS filename for the subboard. This is the name by which you will refer to the subboard whenever you access it in Searchlight BBS, SLMAIL or other Searchlight utility programs. 2 -- Subboard Description This is a long description which you can use to further describe the message subboard. Your description is displayed with the List command from Searchlight BBS. 3 -- Data Files Path This is the path that contains the data files (header, message and member files) for the subboard. It must be a legal DOS pathname that exists on your system. 4 -- Required Access Level This is the access level that users must have to use the subboard. Users who have at least this access level, along with any required attributes, may Jump to and read messages on this subboard; otherwise, the subboard does not appear on the subboard list and is not accessible. 5 -- Join Attributes This field defines the security attributes (keys) needed to access and join the subboard. Attributes defined here must match those defined in the user's information record in order for that user to be able to use the subboard. 6 -- Post Attributes This field defines the attributes required to Post a message on the subboard. Those users who have attributes sufficient to Join a subboard (line 5) but not Post, will be able to read messages on the subboard but will not be able to write messages. This includes replying to messages, and forwarding messages to the subboard. 7 -- Subboard Sysop If filled in, this field defines the name of the person who is Subboard Sysop for this subboard. The Subboard Sysop has the ability to moderate the 49 Subboard Maintenance subboard discussion by editing or deleting any messages on the subboard. Be sure to spell the Subboard Sysop's name exactly as it is spelled in your User file. 8 -- Max Messages on Subboard This field defines the maximum number of messages that can be posted on the subboard at any given time. The maximum value that can be defined is 32767; or you can define a lower value if you wish to limit the number of messages. (Note: see Auto Purge Old Messages below). 9 -- Max Message Size This defines the maximum message size in lines that may be input and posted on this subboard. The maximum value that can be defined is 400. Use a lower value if you wish to limit the length of messages posted. Max Message Size only defines the maximum size that will be allowed for messages entered directly through Searchlight's built in editors. Messages posted via external utilities like SLMAIL or an offline message reader, or messages Forwarded to the subboard, can be longer. 10 -- Allow Anonymous Messages If set to Yes, Searchlight allows messages to be posted anonymously (i.e. without indicating the name of the author in the message header). A "Post Anonymously? Yes/No" prompt will appear each time a new message is entered. Otherwise, this prompt does not appear and anonymous posting is not allowed. 11 -- Auto Purge Old Messages If set to Yes, Searchlight will delete the oldest unprotected message on the subboard when the subboard is full (that is, when it reaches the maximum messages value defined in line 8) and someone tries to post a new message. If set to No, Searchlight will not allow a new message to be posted once the maximum value is reached. You can protect individual messages from being deleted as part of the Auto Purge sequence. Use the Edit command to edit the desired message, and change the protection status when prompted. 12 -- Compress Message Texts If set to Yes, Searchlight uses its built in text compression algorithm to reduce the size of message data as it is saved to disk. Otherwise, message data is not compressed. Compression reduces the overall size of your message text (MSG) file by about 30%, but requires additional time when saving and reading messages. 50 Subboard Maintenance We recommend turning data compression off if you have an extremely slow PC, if you have a large amount of storage space and desire the fastest possible operation, or for instances where you need to save a lot of messages at one time (such as during a Fidonet message import via SLMAIL). Otherwise, turn data compression on to achieve optimal storage space. You can turn data compression on or off at anytime, however, only messages that are saved after making a change will be affected by the new setting. 13 -- Allow Users to Join If set to Yes (the default), users can join this subboard by using the 1- Member/Join command. Otherwise, users may not join the subboard. Joining a subboard is a requirement for use of the New command and is generally recommended for anyone who plans to read the subboard regularly. You may wish to disallow joining for special subboards (such as BULLETIN) or for subboards with a private membership. 14 -- Display on Subboard Lists If set to Yes (the default), Searchlight displays the subboard when the List command is used, provided that the person using the command has access to the subboard. Otherwise, the subboard is not displayed (but may still be accessed via the Jump command). The No setting is primarily designed for special subboards like MAIL and BULLETIN, which are accessible to Sysops but which you may desire not to appear on regular subboard listings when you use your BBS. 51 Subboard Maintenance 15 thru 18 -- Echomail Network Numbers These fields define the echomail network numbers used on Fidonet systems. If you are a member of Fidonet or a Fidonet compatible network, use these fields to fill in the proper values for the subboard if this subboard is to be used for echomail. Searchlight's SLMAIL software uses these values to construct the origin line when it exports messages from the subboard. Additional Information If you run a multinode system and you change subboard information while other users are online, the new information may not take effect until the current users log off. Occasionally, you may wish to add a subboard for which you already have data files (for example, if you have obtained a copy of a subboard from another Searchlight BBS and wish to install it on your own). Searchlight supports this. Be sure the files are installed in the proper directory, then proceed to add the subboard with F1. Searchlight will read the existing data files rather than create new ones. Because Searchlight's subboard files (the HDR, MSG and MBR) files are designed to be independent of the main *.SL2 files, you can back up, restore, and transfer message subboards as independent units. However, within each subboard, the three subboard files should always be moved as a unit: that is, do not mix the HDR file from one subboard with the MSG file from another, nor should you combine one file from a backup disk with your main files or files from a different backup disk. DELETE SUBBOARD To delete a subboard, position the cursor at the desired subboard and press F2. The CONFIG program will prompt you as follows: Delete From Subboard List? Yes/No Erase Files From Disk? Yes/No Assuming you really want to delete the subboard, select "Yes" as your response to the first question. The file is removed from your subboard list (SUBBOARD.SL2) file. You can choose whether or not you wish to delete the data files (HDR, MSG, MBR) from disk or retain them. If you delete these files, your subboard data is erased and may not be recovered. However, if you retain them, you will be able to reinstate the subboard later by adding it back to the subboard list. 52 Subboard Maintenance SUBBOARD UTILITIES The Subboard Utilities menu provides several options for use in maintaining your subboard files. Position the cursor at the desired subboard and press F3 for the utilities menu: A. Repair/Rebuild Header File B. Repair/Rebuild Text File C. Repair/Rebuild Member File Repair Header File This option performs an integrity check on the header (HDR) file and rebuilds the indexes in the header file, repairing any damaged areas. Use this option if you are having a problem with a subboard (such as unreadable or garbled messages, lock ups when saving or reading messages, etc). Invalid index information, which may have gotten into the header file as a result of a disk error, a system crash, or other abnormal situation, will be corrected. Repair Text File This option verifies and repairs the text (MSG) file. Unless you are sure that a problem is in the header or the text file, we suggest running option A, B and C in that order so that a subboard is fully repaired. Repair Member File This option verifies and repairs the member (MBR) file. In addition, the member file is rebalanced (placed in an optimally sorted order) which reduces the time necessary to lookup member names in the file. 53 File Directory Maintenance FILE DIRECTORY MAINTENANCE To create or modify file directories (areas from which your users can upload and download files), select option C, File Directory Setup, from the CONFIG program main menu. (You can also type CONFIG C from your DOS prompt). File directory maintenance is similar to subboard maintenance: to edit or delete a filedir, select it with the cursor, and press to edit or F2 to delete. F1 is used to add a new directory. A Searchlight File Directory or "Filedir" is a special file that contains information such as descriptions, number of times downloaded, etc. about files on your system that are available for download. The filedir contains the names of available files, but not the files themselves. It is important to realize that most of Searchlight's file library management commands deal with the filedir, and not the physical DOS directory itself; you need to create filedirs, and create entries in them, before any file on your computer can be downloaded. Here are the options available when adding or editing a subboard: 1. Directory Description ......... Recently uploaded files 2. Path to DIR File .............. C:\BBS\UPLOADS 3. Path to Files ................. C:\BBS\UPLOADS 4. Required Access Level ......... 2 5. Required Attributes ........... ABC 6. Read Only Directory ........... No 7. Write Only Directory .......... No 8. Duplicate File Scan ........... Yes 9. Free Files (K) ................ 100 10. File Value Multiplier ......... 10 Directory Name This is the 1 to eight character name for the directory. As with subboards, directory names must be legal DOS filenames and may not contain spaces or other illegal characters. The data file used to hold the file descriptions and other information for a directory is created by using the directory name with an extension ".SL2". 1 -- Directory Description In this field, enter a verbose description of the file directory. The description appears whenever you use the List command in the files system. 54 File Directory Maintenance 2 -- Path to Dir File This is the path to the directory that contains the directory data file (*.SL2 file). By default, this is the same as "Path To Files", but may be changed. In this example, the file C:\BBS\UPLOADS\UPLOADS.SL2 contains all of the filenames and descriptions for the files in this directory. 3 -- Path to Files This is the path to the data files that will be uploaded and downloaded. Be sure that this pathname exists before you attempt to create a new directory. In most cases, "Path to Dir File" and "Path to Files" are the same. The primary instance in which they will be different is in the case where "Path to Files" refers to a read-only device, such as a CD-ROM. Since the directory SL2 file needs to be on read/write media, it would be necessary to place this file on a different drive. This is also useful when making file directories that reside on floppy disks. 4 -- Required Access Level 5 -- Required Attributes These are the access level and attribute requirements needed to use the file directory. As with subboards, a user must meet both the access level and attribute requirement before he or she can use the directory. 6 -- Read Only Directory If set to Yes, the directory becomes read-only; that is, users are permitted to download files from the directory, but may not upload new files (or move files from another directory). The Sysop and those with sysop level privileges can place new files into a read only area. 7 -- Write Only Directory If set to Yes, a write only directory is created. Write only directories allow users to upload files, but do not allow them to download, type, or view other files in the directory. Write only areas are useful as a means of sending private files to the Sysop or for screening files before moving them to another directory where downloading is permitted. 8 -- Duplicate File Scan This options lets you exclude directories from the duplicate file search that normally takes place before a file is uploaded. This is desirable with systems that have a large number of directories which do not need to be 55 File Directory Maintenance checked against new files for duplication. Excluding multiple directories from the upload scan helps speed up the scan. 9 -- Free Files (K) The "Free Files" field is a value, expressed in Kilobytes, that determines the amount of files that a new caller may download before their upload:download ratio takes effect. If you use ratios on your BBS, this allows you to create a "grace period" during which new users can download files before being required to upload files in order to maintain a ratio. Although a different free files value may be expressed for each subboard on your BBS, the decision to allow a new user to download is based upon the total size of files they have downloaded from all directories in the BBS as compared with the Free Files value for the directory from which the download is requested. 10 -- File Value Multiplier This field defines a multiplier for the size of files in a directory as recorded in user downloading statistics. The multiplier is actually equal to this field divided by 10; therefore, a value of "10" is a multiplier of 1.0. The value multiplier lets you make certain files more or less valuable in terms of the way they will affect the upload:download ratio when downloaded. For example, if a directory contains a value multiplier of 2.0 (field 10 equal to 20), then files in that directory will register as twice their actual size in Kilobytes when downloaded. A 100K file will count as 200K, 150K as 300K, etc. In a directory where the value multiplier is .5 (field 10 equal to 5), files downloaded would register as half their actual size. To make files completely free (i.e. no impact on download ratio), set the value multiplier to zero. File Value Multipliers can range from 0 to 9.9 (i.e. 0 to 99). CUSTOM ORDERING By default, Searchlight lists your file areas and subboards in alphabetical order when you use the List command. However, you can define the order in which you would like subboards and directories to appear by creating a customization file. Customization files are just text files containing a list of subboards or file directories, one per line. To customize the display of your subboards, create a file named MAIN.SUB, and place it in your Searchlight BBS home directory. MAIN.SUB should contain a list of your subboards in the desired order. To do the same for your file directories, create a file called MAIN.DIR. 56 File Directory Maintenance In addition, it's possible to create a custom directory list for any subboard on your system, so that when the Files system is invoked from that subboard, only the directories associated with the subboard are available. Create a text file with the name of the subboard and the extension .DIR, and place this file in the directory that contains the other data files for the subboard. As an example, if you wanted to create a custom dir list for the GENERAL subboard, it would be called GENERAL.DIR. If you use a custom subboard or directory file, remember that new directories and subboards must be added to the custom file as they are created; otherwise, the new areas won't be available from your BBS. 57 Startup, Login & New Users RUNNING SEARCHLIGHT BBS: LOGGING IN FOR THE FIRST TIME Once Searchlight BBS is set up and configured according to the previous instructions, running it is a relatively simple matter. Once again, make sure that you're in the same directory as the Searchlight data files (the "home" directory) and also make sure that your .EXE files are available in the directory you've defined for the program path (if you left this field blank, then the program files should be in the current directory as well). Run Searchlight by typing the command SLBBS and pressing RETURN. In a few seconds, your screen will clear and you will see a status box showing your system's name, the current time, and other information. At the bottom of the box it will say, RETURN for Local Login ESC to Toggle Display On/Off ALT-X to Exit along with the letters "sacnl" in the lower right hand corner of the screen (these are status indicators; we'll get to them later). There are a couple of other ways you can start Searchlight by adding parameters to the command line -- we'll outline these in a moment. If your computer beeps at you and puts the words "No Response" on the screen in reverse video, check the modem -- it indicates that the modem did not respond to the modem init string with an OK message. Check to make sure that o the modem is turned on o the modem is connected to the proper COM port o Searchlight is configured for the proper COM port o the baud rate(s) selected correspond to the modem's speed If all else fails, please reread the Communications Configuration section of this manual and consult Appendix D, Modem Configuration. Assuming you now see the status box, strike the RETURN key on your keyboard to initiate a local login session. Searchlight will look for the text file called LOGIN.ANS or LOGIN.TXT, if it exists, and display it on your screen, followed by the prompt Enter your name, or type NEW > If you had called Searchlight from a remote location with a modem, you'd see a message like this upon connecting: ANSI Auto-Detected. (Press D to disable ANSI). Do you have a Color Screen (Yes/No/Disable)? In response to this question, you would type Y if you were using a color CRT, N otherwise. You can also type D here to disable Searchlight from sending ANSI codes -- this causes Searchlight to work in a simpler mode without full-screen text controls. Non-ANSI mode is suitable for older 59 Startup, Login & New Users terminal emulators which don't support the full ANSI specification. More information on this topic is presented below. Since ANSI is always available when logging in locally (it will operate correctly even if you don't boot DOS with the ANSI.SYS driver), Searchlight doesn't ask this question for a local login (and it determines whether to use Color or Monochrome mode by looking at your system's video card). Now, back to that "Enter your name" prompt. Searchlight is asking you to type the name of a valid user account. Since your system is new, there are only two valid accounts on file: one called SYSOP and one called GUEST. The SYSOP account is provided as the default "superuser" account. Many sysops will want to use the SYSOP account as the account they use to log into Searchlight regularly, whereas others will want to set up an account with a different name for themselves; we recommend using SYSOP, because most people recognize that as the name they can use to reach the operator of the BBS. If you choose to use another name, you might want to delete your SYSOP account. For now, respond to the "Enter your name" prompt by typing SYSOP. Searchlight now executes its standard login sequence. First, you'll see a greeting message that displays some information about the system, the previous caller, and total number of callers to the system. On multiline systems with more than one node defined, a list of other concurrent users is shown. Next, the Login Autodoor, if one is defined, is executed. Many sysops use the Login Autodoor to display additional system information, daily news, quotes, etc. After pressing the RETURN key, as prompted, you will enter Searchlight's Bulletins menu, where new and important messages will usually be displayed to callers as the log in. However, since there are no Bulletins on file yet, this section is skipped. Finally, a check of your mailbox is made. Searchlight displays the total number of messages and number of new messages in your mailbox, and gives you the opportunity to read new messages if they exist. In this case, you'll see a message indicating that you don't have any mail, and the system will deposit you at the main command prompt, which looks like this (the underscore shows your cursor position): [GENERAL] Command: Help _ You are now ready to use the Searchlight BBS system. The login sequence described above, like most aspects of Searchlight, is configurable; you can modify or replace the commands used at login by editing the STARTUP menu. See Menu Editing in this manual for more information. AUTO ANSI DETECT 60 Startup, Login & New Users Searchlight has an auto ANSI detect feature. Each time a caller connects to your BBS, Searchlight sends a special sequence of commands to their terminal to determine whether the caller can support ANSI graphics and screen controls. If ANSI is detected, Searchlight displays this prompt: ANSI Auto-Detected. (Press D to disable ANSI). Do you have a Color Screen (Yes/No/Disable)? Since Searchlight cannot determine whether a caller has a color or monochrome screen, it prompts the caller to enter Yes for color, or No for monochrome. "D" may also be pressed to disable ANSI screen controls and operate Searchlight in non-ANSI mode; users may wish to select this option if they do not wish to use ANSI even though it may be available in their terminal. For compatibility with previous versions of Searchlight, callers can also press "C" at the above prompt to select color ANSI mode, or "M" to select monochrome ANSI mode. If Searchlight fails to detect ANSI, it displays this prompt: Select Graphics Mode: [C]olor, [M]onochrome, or [N]one? Since some ANSI compatible terminal software does not support the auto- detect feature, users can still manually select color ANSI, monochrome ANSI, or non-ANSI mode with this prompt. Because of its many full screen oriented display modes (such as the full screen editor, options fields, and reply-quote editor), Searchlight operates properly in ANSI mode only when the remote terminal uses an 80x24 screen size. Although Searchlight cannot force a terminal into 80x24 mode, it can usually detect whether a terminal is not set to this mode during the ANSI detect sequence. If it does, the following informational message is displayed: Searchlight requires a standard 24 line screen for full screen ANSI mode. Switch your local terminal to 24 lines now, or press D to disable ANSI. It is recommended that callers make sure their screen is set to 24 lines by 80 characters before continuing in ANSI mode, if this message is displayed. If a larger screen size is desired, callers may proceed in non-ANSI mode, which does not require a 24 line screen. Incorrect screen size on the remote terminal is the cause of many common display problems, such as lines overwriting other lines or messages appearing in the wrong location on the screen. Note that some terminal software allows you to disable the status line, providing an 80x25 line screen. With such software, the status line should always remain enabled so as to provide the correct 80x24 line screen size. THINGS TO DO WHEN FIRST LOGGING IN 61 Startup, Login & New Users Here's a quick checklist of some of the things you should do the first time you log in to your new Searchlight BBS system: o Familiarize yourself with the user interface. It's quite easy to use. Try selecting different commands, and reading the online help text by pressing the F1 or ? key. o Use the OPTIONS command to assign a password to your SYSOP account. This is very important! If you forget to assign yourself a password, others will be able to use the SYSOP account and that can compromise the security of your system. Don't forget the password you choose; write it down if you must. o Post a few messages and bulletins. This will not only help you learn how the text editor works but it will give your first users something to read when they call your BBS. To post a bulletin, Jump to the BULLETIN subboard and use the Post command. USING THE STATUS DISPLAY The status box displayed on your screen between calls shows some important information. The first line displays your BBS's name and node number (in multinode systems). Line 2 shows the modem's baud rate and COM port. If an error occurred when Searchlight attempted to set-up the modem using the modem init string, the phrase "No Response" is printed here, otherwise "Ok" is displayed. The third line shows the last caller to the system, and the right-hand part of the screen displays the current time, and the time that the LOGIN program started waiting. If you use preprogrammed events (via the EVENT.DEF file), line 4 shows the name and execution time of the next event. See Appendix C, Automatic Events, for complete instructions. If a call is not received within five minutes, Searchlight will blank the screen. This is done to prevent screen "burn-in" that can be caused on some CRT's when the same image is displayed for a long time. To restore the display, just press the ESC key. SLBBS COMMAND LINE PARAMETERS Normally, you type the command "SLBBS" from the DOS prompt to load Searchlight BBS, initialize the modem, and begin waiting for a call. However, under certain circumstances you may wish to bypass the modem initialization and make a direct connection at a specified baud rate. Searchlight provides command parameters to allow you to do this. The complete syntax is: SLBBS [/C] [-uUsername] [-pPassword] To start Searchlight with a specific baud rate, just type the baud rate on the command line after SLBBS; for example, "SLBBS 2400" to start the system 62 Startup, Login & New Users up at 2400 baud, bypassing the modem init string. If you want to connect to a remote terminal but don't know the baud rate, enter "SLBBS K". This will cause Searchlight to connect and begin sampling keyboard input to determine the proper baud rate -- hit the RETURN key on the remote end a few times to establish a connection. Finally, a local login can be initiated with "SLBBS Local" or just "SLBBS L". Command line parameters are useful for two main purposes: to allow an external "front end" program to answer the phone, and to make direct connections without using a modem. In the first case, a separate program runs before Searchlight, monitors the phone, and makes a connection. Then, this program calls Searchlight, passing it the baud rate so that Searchlight can make a direct connection without resetting the modem. A direct connection involves connecting two computers or a computer and a terminal together with RS232 cables and "Null" modem connectors. To establish a direct connection, without requiring a "carrier" signal to be present, simply give the desired baud rate on the command line when starting SLBBS. When passing a baud rate on the command line, you'll usually want to follow it with a time limit. The time limit, expressed as a number of minutes, specifies the maximum amount of time that may expire during that session. The /C parameter forces carrier checking. As an example, the command SLBBS 2400 30 /C will load Searchlight at 2400 baud, limit the session to a maximum of 30 minutes, and force the system to check for carrier. The session time limit is useful if your front-end program needs to execute some event at a certain time, since it will ensure that Searchlight will return to the front end program in time for the event. It is recommended that the /C parameter be used under normal conditions when calling SLBBS from a front end program; omit it when a direct (modemless) connection is being used. Parameters -U and -P let you provide a username and password to Searchlight. When a username and/or password are provided in this way, Searchlight skips its usual "Enter your name" and "Password" prompts. Of course, the name given must match a valid username in your system and the password must be valid. Otherwise, a "Name not on file" or "Invalid password" message will appear (followed by prompts for the correct information). Note: If you use the /C, -U or -P parameters, you must specify a baud rate and time limit first. Use "L" or "Local" for the baud rate if you're doing a local connection; use "1440" for the time limit if you don't need to limit the session time to any particular length. If you wish to use the ALT-X hot key in conjunction with a front end program, your front end program should exit to DOS if Searchlight returns a nonzero error code (which it will do when ALT-X is pressed). An error code of 0 indicates a successful run. Finally, notice that if you have General Setup #2 option #4 (Return to DOS on Logoff) set to "Yes", then the only way to get Searchlight to run is to 63 Startup, Login & New Users call it with a command parameter! Otherwise, the system will simply exit, expecting a host to regain control of the line. ADDING NEW USERS TO THE SYSTEM New usernames and passwords are added to Searchlight BBS by typing NEW in response to the login prompt. In order to use this facility, you must have the "Allow New Users" option (in the CONFIG program) set to "Yes". Typing NEW will present the New User menu, which looks like this: Searchlight New User Menu [R] ..... Register as a New User [G] ..... Enter the system as a GUEST [C] ..... Call the SYSOP to Chat [E] ..... Re-Enter your Name [D] ..... Disconnect (Hang Up) Command ->_ To register his or her name in the user database, a new user would press the "R" key to access the Register option. Searchlight will o Display the new user message (NEWUSER.TXT), if it exists; o Prompt the user for their name, location, phone number, system type, and password; o Enter the user's info into the Searchlight database; o Execute the New User Autodoor, if one is defined; o Log the user in to the BBS system. New user information is entered via an easy to use, full-screen input system that works like the system you used to enter and edit information in the CONFIG program. Users can edit data and change fields with the standard cursor and editing keys (check the Text Editing section of this manual for a full description of Searchlight's editing functions). A new user is given initial access levels and time limit as defined in the CONFIG file. Duplicate user names or blank passwords are not allowed. If the new user tries to enter a name that already exists in the user file, or does not fill in a password, a warning message is printed. The user may re- enter the bad data or return to the New User menu. Other New User Options The "C" option will issue a page to the SYSOP (if the "Sysop Available" (ALT-A) flag is set). You can answer the page by pressing any key at the keyboard; after you're done chatting, press the ESC key to exit from chat mode. You may notice that the tone emitted from the speaker by the CHAT command is lower than usual when a new or nonvalidated user is paging. Thus, you can discern a new user's page without having to look at the screen. 64 Startup, Login & New Users An "E" option is provided to allow re-entry of your name. If the "NEW" command is selected in error, typing "E" will return you to the original "Enter Your Name" prompt. Finally, a disconnect option, "D", will disconnect the remote user and recycle the system back to the call waiting screen. Guest Account Searchlight provides a default account called GUEST, which is designed for people who want to use your BBS once or twice but do not wish to establish a password for themselves. New users can log on as GUEST either by typing "G" at the New User menu, or by typing GUEST directly at the login name prompt. Many sysops find the GUEST account useful for allowing casual callers to find out about their BBS. You can provide the GUEST account with any access level, security attributes, time limits, and other attributes you choose. GUEST users cannot change their own user information or preferences. The GUEST account may be deleted if you do not wish to allow this form of access to your BBS. If you delete the GUEST account, an attempt to use the "G" option will simply result in a message stating that the guest login is not available. GUEST can be restored later by re-entering the GUEST name as a new user; after doing so, remove the GUEST account's password via the Options command on the main menu (enter a blank space in the Password field). 65 Configuring User Options CONFIGURING USER OPTIONS When new users register with your BBS, Searchlight prompts them to enter a name, location, computer type, phone number, and password. These items, in addition to some others, can be changed by the user at any time by using the Options command on Searchlight's main menu1. When Options is executed, it displays a screen like this: Info Preference Stats Access Quit [?=Help] Each selection displays and/or allows you to edit various aspects of the user account. The "Access" setting controls user security levels, and is available only to Sysop level accounts. USER/INFO 1. Location ...................... Stony Brook, NY 2. System Type ................... IBM 386 3. Phone No. ..................... 516-689-2566 4. Password ...................... This selection controls demographic information about the user, and the user's password. Field numbers 1 through 4 can be adjusted. In ANSI modes, use the cursor keys to highlight and edit the desired data; in non-ANSI, a prompt appears and you can type the field number to change, then the new data. 1 to 3 -- Location, System Type, Phone No. These fields allow you to enter the described information. Location and System Type can be any alphanumeric characters, and are displayed along with your name in user lists and searches. The phone number field is strictly confidential and can be viewed only by the SYSOP. 4 -- Password This field lets you enter a new password. For the sake of security, existing passwords are not shown, and dots are displayed when typing a new 1Searchlight's Menu Editor system makes it possible to change the names of commands and their placement on menus. Throughout this manual, we use the command names that appear on the default menus that are included with Searchlight. You should be aware that if you change your menus, the exact screen display and key sequences used to access a particular function may be different than what is show in the manual, although commands themselves will function the same way regardless of how they are executed. 67 Configuring User Options password. To change your password, type the new password over the "" message. When you exit the Options command, Searchlight will ask you to verify the password by typing it again (if you mistype a password, the old password will not be changed). 68 Configuring User Options USER/PREFERENCE 1. Help Level .................... Novice 2. ANSI Compatibility ............ Generic 3. Screen Length ................. 24 4. File List Format .............. Prompt 5. Pause Between Messages ........ Yes 6. Subboard Disposition Prompts .. On 7. Mail Disposition Prompts ...... On 8. Preference Attributes ......... These fields display and edit user-controlled preferences. Each user can set his or her own preferences in these fields, in order to modify Searchlight's behavior. 1 -- Help Level Possible values for this field are Novice, Intermediate and Expert. In Novice mode, Searchlight displays the main command menu after each command, provides verbose descriptions of menu selections, and shows additional help text at several points in the system. Intermediate mode is similar to Novice mode, but does not provide the automatic main menu display or the NOVICE.TXT help file at login. In Expert mode, all help messages and menus are suppressed (but you can always display help and menus on demand with the F1 or ? keys). Choose Novice if you're new to Searchlight BBS, Intermediate or Expert once you've become more accustomed to the system. The actual behavior of these modes is determined by each menu in Searchlight, and can be changed by using the menu editing features. You can also create new menus or modify menu commands based on the help level switch. 2 -- ANSI Compatibility This field can be set to Generic, Procomm, or Full, and configures the Searchlight full-screen text editor for use with different types of ANSI terminals: Generic for minimally-compatible terminals, Procomm for the Procomm or Telix terminal software, and Full for fully capable ANSI terminals or terminal emulators. See the discussion of ANSI terminals in the Text Editing section of this manual for further information. 3 -- Screen Length This field describes the length in lines of the remote user's screen, and is used for placement of the "more" message during text output. If Screen Length is set to zero, "more" prompting is disabled. 69 Configuring User Options The maximum supported screen length is 24. We recommend that you use Searchlight only with terminal software that supports a 24 line screen. 4 -- File List Format This option controls the display of long file descriptions in the Files system. If set to "Long", Searchlight always displays long file descriptions with the Files and New commands in the Files program. If set to "Short", the Files system always displays short listings. If set to "Prompt", the Files program will prompt you as to whether you want long descriptions displayed at the beginning of each command that displays descriptions. 5 -- Pause Between Messages This option defines whether Searchlight stops between messages (i.e. displays the message disposition prompts) when reading messages. The default setting is "Prompt", which means that you are prompted with "Pause Between Messages?" each time you read messages or mail. Change this setting to "Yes" if you wish to avoid the "Pause Between Messages?" question, and always see disposition prompts between messages. Select "No" if you wish to have a non-prompted message read by default. 6 -- Subboard Disposition Prompts 7 -- Mail Disposition Prompts These options determine whether the subboard and mail disposition prompts (the "coNtinue, Post, Unmark" prompts) appear after reading subboards or mail. The default is "Yes". 8 -- Preference Attributes This field contains a series of user-selectable attributes that work in conjunction with Searchlight's menu system to allow users to choose between different menu systems. See the Menu Editing information later in this manual for details. USER/STATS This selection displays non-modifiable account statistics, as follows: Stats for SYSOP First Logon : 10-08-90 BBS Access : 255 Kb Uploaded : 1117 Last Logon : 11-19-92 Files Access : 255 Kb Downloaded : 2023 Total Calls : 4414 Time Limit : 1440 Xfer Protocol : Xmodem Security Attributes : ALL 70 Configuring User Options SYSOP-CONFIGURABLE SETTINGS In addition to the user-configurable options, there are additional data fields associated with each user record that may be accessed only by Sysop or CoSysop level users. These fields store the user's access levels, time limit, and other information. To view and/or change these protected values, you must log in as the Sysop, execute the "2-Sysop" main menu command, select "Options" from the menu bar, and type in the name of the user who's options you want to look at. Then pick "Access" from the menu bar. USER/ACCESS 1. Security Attributes ........... ABCDEFGHIJKLMNOPQRSTUVWX 2. BBS Access Level .............. 255 3. Files Access Level ............ 255 4. Daily Time Limit .............. 1440 5. Session Time Limit ............ 1440 6. Time Left Today ............... 1440 7. Expiration Date ............... 0-00-00 8. Download/Upload Ratio ......... 3 9. Mail Logging .................. Off 1 -- Security Attributes This field defines which of the 24 security attributes is associated with the user. Security attributes control a user's access to subboards, file areas, and other functions on the BBS. In order to access a secure feature, a user must have all of the attributes associated with that feature, in addition to meeting an access level requirement if there is one. You can specify security attributes either by typing the letters A to X, by typing subranges (such as A-D or G-P), or by typing the word ALL to indicate all security attributes. 2 and 3 -- BBS and Files Access Levels These numbers define the user's access levels for the main BBS and the Files systems. Basically, the function of the access level is to define which message subboards, file areas and menu choices a user may access. Normal access levels range from 0 to 253. Access level 254 designates a "CoSysop"; CoSysops have the power to access all message and file areas, edit or delete messages and files, and view or change the user accounts of other users with access levels of 239 or less. CoSysops cannot (for obvious reasons) change their own access level, or assign an access level of 240 or greater to any other user; they also are prevented from using the "2- Sysop/TextEdit" command, running Doors with access level 255, and downloading password-protected files (unless they know the password). 71 Configuring User Options Access level 255 defines the Sysop, who has ultimate power to perform all operations on the BBS without restriction. Extreme care should be taken in allowing users other than yourself to have 255-level access, since such users have the capability to not only delete messages, files, and users from your system, but also to edit text files and possibly access DOS itself.. We recommend that you use access level 255 only for yourself, and give 254-access where necessary to CoSysops. 4 -- Daily Time Limit This field defines the amount of time per day (in minutes) that a user may access your system. Values from 1 to 1440 minutes may be entered. Sysops and CoSysops are untimed, and may use the system for any amount of time regardless of the Time Limit value. 5 -- Session Time Limit This field provides a per-session time limit. This is the maximum amount of time that a user will be allowed to spend on any particular login. 6 -- Time Left Today This value is the number of minutes left in the user's allocation for today; it's equal to the daily time limit minus the amount of time the user has been online since midnight. You can view or manually adjust this option. 7 -- Expiration Date An expiration date defines the date when a particular user loses certain access rights, and may define a date when that user record is deleted altogether. A couple of special values are available. First, you can set any expiration date to "00-00-00", indicating no expiration (the account will never expire). Secondly, if zero is specified as the "Days Until Expiration" in the default access level setup, then the special "00-00-00" date is assigned to the user account, exempting it from any expiration. You can also use the Mass Validate procedure in the SYSOP program to specify these values. What Happens When An Account Expires? By default, nothing happens to a user account when it expires (i.e. when the current system date passes the expiration date specified for the user). If you don't wish to use expiration dates on your system, you do not need to make any modifications to your user files or default access levels; expiration date processing is turned "off" by default. To enable expiration dates so that they actually have an effect, go to line 14 on menu B in the CONFIG program. This switch can be set to one of three 72 Configuring User Options choices: "None", the default choice that does nothing; "Reset Access", and "Delete Account". If Reset Access is selected, Searchlight reduces the access level of an expired account to that of a new user (i.e. the first default access level choice) whenever that user tries to log in on a date that's past his expiration date. The user's expiration date itself is not changed. When the access level modification occurs, the user is told of the change and will continue to be reminded of it at each subsequent login, until you modify their expiration date (either manually or via an access level upgrade). If Delete Account is selected, then accounts are simply deleted from the user file when they expire. Both Reset Access and Delete Account options supply a warning message for 30 days prior to the expiration of the account, giving users the opportunity to contact you about extending their access rights before their account is terminated or reset. 8 -- Download/Upload Ratio This field defines the user's Download to Upload ratio. If, for example, a value of "3" is entered, it indicates that the user may download 3 Kbytes worth of files for every 1 Kbyte uploaded. If an attempt to download more than this amount is made, the Files program will not allow the download to proceed until the user has uploaded additional file(s). This field is initially set to the Default DL/UL Ratio entered in the CONFIG program, but may be changed for each user in the system. A DL/UL ratio value of 0 indicates that no ratio is to be enforced. 9 -- Mail Logging This switch activates Searchlight's Mail Logging feature. When turned On, Searchlight will generate a log (text file) containing the headers and text of all mail received and sent by a particular user. Each user's mail is stored in a separate file; the filename is generated by a concatenation of the user's name (for example, SYSOP.LOG or MSMITH.LOG). Mail files are stored in the directory specified as the "Mail Files Path" in the CONFIG program (or in the current directory if no Mail Files Path is specified). Mail log files are intended for your own use in archiving your mail, and should be periodically compressed or moved offline to prevent the log files from growing unreasonably large. Searchlight doesn't truncate or otherwise manage these files in any way. When mail logging is Off (the default), no mail log is generated. 73 Message System SEARCHLIGHT MESSAGE SYSTEM The heart of Searchlight BBS is its public message system. Searchlight handles multiple subboards or subtopics, each of which can have any number of active messages. You can read existing messages, enter or "post" new ones, list the available subboards and available messages, and search for particular messages or for all new messages. In addition, messages can be replied to, edited, deleted, and copied to disk or to other message areas. Finally, a powerful "Thread" command is included to allow related messages to be treated as a unit. In general, message base operations affect the currently active subboard. The "current sub" is the last subboard jumped to (with the Jump, New, or List commands); its name is displayed to the left of the command prompt and in the upper right hand corner of the screen at most times. When you first log in, the current subboard is either the last subboard accessed during your previous login, or the first available subboard. Searchlight's Menu Editor makes it possible to change the names of commands and their placement on menus. Throughout this manual, we use the command names that appear on the default menus that are included with Searchlight. You should be aware that if you change your menus, the exact screen display and key sequences used to access a particular function may be different than what is show in the manual, although commands themselves will function the same way regardless of how they are executed. ENTERING MESSAGES: THE POST COMMAND The Post command adds a new public message to the current subboard. To use it, enter Post and type in the name of the recipient (or press Return for the default "All"), and then a short title for the message. Then, you'll be placed into one of the system's message editors where you'll be able to enter the text of your message. If anonymous posting is enabled for the current subboard, you'll be prompted as to whether you wish to post your message anonymously. Reply with Y or N as desired. Use of the message editors (both a line editor and a full-screen editor are available) are discussed further later in the manual. It is possible to "import" text files into a message via several methods; this, too, is discussed later. When you SAVE your message, it is added to the subboard as the last available (highest-numbered) message. You can also post messages by replying to existing messages; this is discussed below. RETRIEVING MESSAGES: THE READ COMMAND There are a couple of ways to begin reading posted messages; the most straightforward of these is via the Read command. To use it, enter Read, 75 Message System then give the message number of the message where you want to begin reading. The Read command displays the message header, showing the subject, time, date, and person who posted the message, followed by the message text. If the text is longer than your "Screen Length" (set in user Options), the prompt "--more--" is displayed every screenful. Press any key to continue reading. At anytime, press the spacebar or ^C to abort a lengthy message. There is one additional prompt you may see displayed when you begin reading message and that is: Pause Between Messages? Yes/No Normally, select "Yes". After each message is displayed, the Read command presents a prompt such as this: Again Reply Mail Prev Next Goto Thread Other Quit In response, select the appropriate command depending on what you want to do next. You can select commands by pressing the first letter of the command you want, or by moving the menu bar to the desired command and pressing the RETURN key. If you do select "No" to the "Pause Between Messages" option, Searchlight skips the command prompt and displays messages continuously. This type of continuous message "dump" is primarily of use to remote callers who will be capturing the text to a local buffer for later digestion. The Read command options are generally available anytime you're reading messages, whether via the Read command itself, the Mail command, or as part of a New message scan. Here's a summary: Read/Again The "Again" option clears the screen and re-displays the last message read. Use this option when you want to review a long message; it is also useful for redisplaying a message in case the message is garbled by line noise. Read/Reply This option lets you reply to the message you've just read. The reply is either a public message or a private (electronic mail) message depending on whether the message is public or private. Replying to a public message is similar to Posting a message, except that the reply contains additional information in the message header indicating that it's a reply. When replying to a message, the sender and subject of that message are displayed as default responses for the reply (the designator "Re:" may be added to the subject if it was not already present). If you want to use those defaults, just press Return. To change them, type new information. After writing the reply, the current message is redisplayed. 76 Message System Read/Mail Sometimes you may wish to send a private reply to a public message; this option allows you to do so. Selecting Read/Mail is similar to Replying to a message, except that the reply is saved to the MAIL subboard as a private reply rather than to the current subboard as a public message. Read/Prev The "Previous" subcommand lets you read the preceding, or next lowest numbered, message. If there is no previous message, then the Read command exits. Read/Next The "Next" subcommand is used to proceed to the next message on the active subboard. If there is no next message, the command exits. With both the Next and Previous subcommands, if the messages being read are part of a set selected via a search string (Scan/Search command), or part of a message thread (see the Thread command below), then Next and Previous display the next or previous message in the set or thread being read, rather than the next or previous message in numerical order. Read/Goto The "Goto" command lets you ahead or skip backward to any message on the subboard, by entering the desired message number. Read/Thread You'll see this option on the menu if the message you're reading has been replied to, or is itself a reply to a previously posted message. What the Thread command does is to let you view some or all of the replies and original messages directly, ignoring (temporarily) other messages which are not part of that message "thread". This submenu appears when you use Thread: Next Prev Original First Quit To read the next or previous message in the thread, use N or P commands. "Original" takes you directly to the message to which the current message is a reply; "First" brings you to the very top of the message thread (the first message about a particular topic). Threading is discussed in more depth on the following pages. 77 Message System Read/Other This option presents a new menu of additional choices that are available, including: Download Forward Edit Kill Post Chat Validate Options Quit Read/Other/Download This function lets you download a message or a thread to your remote terminal, via one of the internal protocols. Select whether you wish to transfer the message or thread; then begin your download when prompted. See below for more information on global thread operations. Local use of the message "Download" commands are supported in Searchlight 3.0. Instead of sending the message to a remote user via a file transfer protocol, Searchlight saves the message as a file in your local node's home directory. The name of the file is the subboard name plus the message number modulo 1000 -- for example, if you were logged on locally and "downloaded" message number 1292 from the GENERAL subboard, it would be written to disk as a text file called GENERAL.292. Note that the same naming convention is used for remote callers who select Zmodem as their default internal protocol for message uploads and downloads. Read/Other/Forward The "Forward" subcommand is used to forward a copy of the message you just read to another place on the bulletin board. In general, messages can be forwarded to a public message subboard or to a particular user's mailbox; Sysops and Cosysops can also forward messages to Bulletins, and Sysops only can forward them to text files on disk. For public messages, the Forward command is available only to Sysops, cosysops, the subboard subop, or the person who posted the message; private mail can be forwarded by the recipient of the message. Pressing "F" prompts you with one or more of the following: Forward to: User Subboard Bulletins Disk Quit If you wish to forward the message to a public message board, press "S"; Searchlight will then prompt you to enter the name of the board you wish to use. To forward the message to a user, type "U"; you will then be prompted to enter the name of the user to whom you wish to send the message. "B" forwards the message to the Bulletins menu without further ado. When forwarding a message, you have the option to add comments to the message. When you add comments, the result is a message which contains the text of the original message below a line of dashes, and your comments above that line. Notice that if you choose to add comments, the resulting message contains your name and the time you entered your comments in its message header; otherwise, the message's original header is retained. 78 Message System Selecting Disk allows you to write the message directly to a text file on your disk. It will prompt you to enter the filename, which may include a drive letter or directory path. If the file exists, the message is appended to the end of the file, otherwise a new file is created. The Disk option is only available to Sysop level users. Read/Other/Edit This option lets you edit the message at hand. You can change both the header information and text. For more information, see the Edit main menu command. Read/Other/Kill This command deletes the current message, after verification. Kill and Edit subcommands are only available to Sysops, the subboard Cosysop, or the person who posted the particular message. Read/Other/Post This option lets you post a new message on the current subboard. If you are reading mail, this option appears as Send instead of Post, and lets you send a new mail message to another user. Read/Other/Chat This command is available on multiuser systems. It lets you chat with other users without exiting from the Read command, or losing your place in the current message area. Read/Other/Validate This command lets you validate the sender of the message by assigning one of the default access levels set up in the CONFIG program. This is the same as 2-Sysop/Validate (see that command for more information). Read/Other/Options This command lets you edit a user's options screen, as with 2- Sysop/Options. Of course, this command and the Validate subcommand are available to Sysops only. Read/Quit Select this option when you wish to quit reading messages and exit back to the main system prompt. 79 Message System Notice that in addition to being able to abort messages with ^C, you can type the first letter of one of the above subcommands while the message is being displayed, at the "more" prompt, or while the menu is being drawn on your screen. Searchlight will immediately stop and execute the desired command. This intelligent command type ahead feature works in most other situations, such as Mail, Bulletins, and subboard lists, as well. In addition to these READ command options, there are several other commands available for listing, selecting, and updating messages and message bases. These operations are described in detail on the following pages. 80 Message System MAIL/SUBBOARD DISPOSITION PROMPTS A prompt is available whenever you exit from reading a public message subboard or reading mail; it's called the Mail Disposition or Subboard Disposition prompt. The choices are: Subboard Disposition: coNtinue Post Unmark The default choice here is "Continue". Notice that "N" is the hotkey for this choice; Searchlight permits a key other than the first key of a choice to be the hotkey. "Continue" simply exits back to the previous menu (if you were using a Read or Mail command) or continues to the next subboard (if you were using a New command). If you read new messages on that subboard, then your new message pointer is updated. Unmark lets you exit a subboard without updating your new message pointer for that subboard (or without marking new mail messages as read), thus causing any new messages there to continue to appear in the next New message scan. This can prove useful in a variety of circumstances; for example, you might wish to "browse" through the new messages on a subboard with the intention of returning to them later for a more thorough reading and reply. Selecting "Unmark" after the initial browse lets you do that without the need to remember a specific message number Continue automatically "joins" users to a subboard if they were not already subboard members. Joining and unjoining subboards can also be accomplished manually via 1-Member. Post lets you post a new message on the current subboard. On Mail commands, Post is replaced with Send, which lets you send a mail message to any user. Both commands appear only if the user has access to perform the associated action. Both subboard and mail disposition prompts can be disabled on a user by user basis. The switch to turn these prompts on and off is located in the Options/Preference command. When the prompts are disabled, the default choice, "Continue", is executed. MESSAGE THREADING: USING THE THREAD COMMAND Message Threading is a powerful concept that lets you display and follow "threads" of message replies within a message area. Searchlight's Thread command is unique in that it gives you the option to read a thread from several different places. You can read forward or backwards through a thread, and use all of the regular message subcommands (Again, Reply, Forward, etc.) while reading a message thread. Selecting the Thread command after reading a message brings up a submenu with options Next, Prev, Original, First and Quit. You can begin reading the thread at the Next message, backward to the Previous message, from the Original message (relative to the current message) or the First message in the entire thread. A reply thread contains all the original messages leading up to the current message (including originals of the originals), 81 Message System and all replies to that message (again, including all replies-to-replies). Notice that as you read a thread, the Next and Previous commands now deliver the next or previous message in the thread being read. When you're done reading the last message in the thread, or you select Sequentl from the menu, you'll return back to the original message (the message you were reading when you first pressed "Thread"). Threading scans a chain of replies recursively; ie. if a reply has replies, those additional replies are scanned, and so forth. Therefore, the message thread will not necessarily be in numerical or chronological order, but will list all replies to a message in sequential order right after that message. Of course, only messages which were posted as replies to an original message (via the Reply message subcommand) can be considered as part of a thread. When reading a thread, Searchlight keeps track of which messages you have read. After exiting from the thread, when you continue reading messages in order, messages you've already looked at (as part of a previous thread command) are skipped. These message markers are cleared when you exit the Read command back to the main menu prompt. Although the previously read messages are skipped when using the Next command, you can back-up and read them again with the Previous command if desired. Threading is usually used when you read a message that has replies (as indicated in the message header) and you want to see those replies immediately, or when you're reading through a subboard with a large number of messages and want to restrict yourself to reading only messages belonging to a particular topic. Global Thread Operations Searchlight features commands that allow you to treat a thread as a unit, and perform actions on all the messages in a thread (or a specific part of a thread) with a single command. In particular, you can forward, delete, or download and entire group of related messages. The ability to forward or delete more than just a single message is available only to the Sysop, a CoSysop, or the Subboard Sysop of a particular message area. Downloading of threads is available to any user. Whenever you are reading a message and you activate the Kill, Forward or Download option from the message disposition menu (ie. Other/Kill, Other/Forward or Other/Download), the following new prompt will appear: Message Replies Thread Quit If you want to delete, forward or download only the one message you have just read, select the default choice, Message. If you want to include the current message, plus all of the direct replies to that message, select Replies. This choice is different from selecting the entire thread, because it does not include any messages previous to the current message, nor does it include later messages except those that were entered directly as replies to the current message. 82 Message System Finally, the third choice, Thread, selects every message in the current message thread, starting at the top of the thread. 83 Message System SELECTING MESSAGE AREAS: THE LIST AND JUMP COMMANDS Searchlight supports an unlimited number of independent message areas or subboards. To get a list of the message areas available, use the List command. When List is done displaying the available areas, it supplies a prompt that enables you to enter the area of your choice (by keying the area name). The selected area then becomes the active area, and you are able to read, scan, and post messages to that area. If you just hit RETURN, the active area is unchanged. In general, you do not need to type the entire subboard name of the area you wish to access; in most cases, the first two or three letters of the area name will suffice. It is also possible to select a subboard area by entering any combination of letters found in its area name; however, be sure to type in enough letters to avoid ambiguity, which can result in selecting the wrong subboard. If you want to switch message areas without viewing the list of available areas first, use the Jump command. By default, Searchlight displays all available message subboards in alphabetical order when the List command is used. However, you can change the list order and contents by specifying a text file called MAIN.DIR. For more information, see Custom Ordering on page 56. REVIEWING MESSAGES: THE SCAN COMMAND While the Read command is versatile, Searchlight provides additional commands that give you a brief summary of the messages on a subboard, allow you to search for particular messages, and allow you to check for new messages posted since the last message you've read. Use the Scan command to list or search the current message area. Scan presents a submenu with these options: Forward Reverse Search Personal Quit To list messages in ascending order, hit Forward; to display them in the opposite order, use Reverse. The listing shows the message number, date, person posting the message, and the message title for each message. You can abort the listing early with ^C. The Search option operates a little bit differently; it allows you to find specific messages by giving a search string. For a quick search, the search string you type can match any part of a message's title or a sender's name; you can also search the entire message (text as well as header information). After selecting Search, you will be prompted with: Enter Search Key: > 84 Message System Enter the text for which you wish to search. The search is always case insensitive (all combinations of upper and lowercase will match). Next, you will see: Search Text of Messages? Yes/No If you choose "Yes", Searchlight will search the headers and text of all messages for your search string. If you want to search only for messages from a particular author or about a particular subject, you can answer with "No", and search only the message headers. A header-only search takes much less time than a full-text search. You can abort the search at any time by pressing ^C. The Personal subcommand searches the current subboard for messages which are addressed to you. Note that the personal search can only find messages which were posted after you joined the current subboard (and it will not work at all if you haven't joined the subboard). After a successful search, this prompt will appear: Read Matching Messages? Yes/No If you press Y, you'll be transferred to the Read command, where you'll be able to read the first of the matching message. When you use the Next and Previous subcommands on the message menu, Searchlight will display the next or previous message in the list of messages matching your search string, rather than the next or previous messages in numerical order. Thus, you can easily view some or all of the messages you've searched for without having to key in the individual message numbers. FINDING NEW MESSAGES: THE NEW COMMAND Searchlight provides a powerful New command that can automatically take you to new messages each time you log on to your BBS. The New command uses the high message pointer that's saved in each subboard member file (when you Join that subboard) and accurately finds all new messages, regardless of the date you last logged in. To begin the new message scan, enter the New command. These suboptions appear: All Joined Subboard Personal Quit Here's a rundown of the New subcommands: New/All This function scans for new messages on all available, subboards, whether or not you are a member of the subboard. Because Searchlight BBS only keeps a new message pointer for subboards in which you are a member, any non- member subboards will indicate that all the messages on the subboard are 85 Message System new; however, you will have an opportunity to join these subboards as you encounter them, and start reading at a later message if you wish. New/All is the recommended command for new callers to use in order to familiarize themselves with your BBS and "tour" the message areas available to them. New/Joined This command scans for new messages only on subboards which you have joined, skipping those in which you are not a member. Experienced callers can use this command to selectively read those subboards on your BBS that interest them while ignoring others. All that is required is that users join those subboards which they are interested in, and not join (or unjoin) the others (we'll explain how to join and unjoin subboards in a moment). New/Subboard This command performs a new message scan only on the current subboard. Searchlight lists the new messages on the subboard, then allows you to read them. New/Personal The personal subfunction lets you scan either the current subboard, or the entire BBS, for new messages that are addressed specifically to you. New/Personal is similar to Scan/Personal, except that it scans only new messages, and gives you a choice to scan either the current subboard or all subboards. Subboard Navigation with NEW The global New functions (those that scan for new messages on all subboards) provide several options for reading messages. At each subboard in which new messages exist, you'll see the subboard name and (except in the case of personal scans) the number of new messages available. Following this, another menu choice appears: Read Goto Next Join (Unjoin) Quit 86 Message System Here, select the appropriate choice depending on what you wish to do about reading the new messages on that subboard. Read If you select Read, you'll begin reading from the first new message on the subboard. As you read messages, the various message disposition commands (discussed in detail on the previous pages) are available to you. If you select Quit while reading, the new scan resumes and goes to the next available subboard (press 'Q' at the next submenu to exit from the New command entirely). The first time you read messages, this prompt may appear: Pause Between Messages? Yes/No If you want Searchlight to provide a continuous dump of the new messages on this subboard and all subsequent subboards, select "No". Otherwise, select "Yes". The "Pause Between Messages" prompt does not appear if you have your preference option for Pause Between Messages set to Yes or No. See page 70 for details. Goto This command lets you skip to any message on the subboard by entering its message number. Goto is often convenient when you encounter a subboard with many new messages, and you desire to skip ahead and read only the most recent messages instead of reading them all. Next Select Next if you want to skip this subboard. The New command continues to scan for the next available subboard with new messages. Join If you are using the New/All command and you are not a member of the subboard shown, you can use the Join command to become a member. Remember that joining a subboard is required if you wish Searchlight to remember the highest message you have read on that subboard and be able to identify new messages each time you log on. When you join a subboard, Searchlight will prompt you to enter a high message number. If you want to read messages on the subboard from the beginning, just press Enter to accept the default value. When a subboard has many messages, you may want to set your high message pointer to a higher value, thus skipping ahead to a more recent message at which to begin reading. 87 Message System Searchlight automatically joins you to a subboard if you read messages there, and select "Continue" from the message disposition prompt when leaving the subboard. Unjoin If you want to discontinue membership in a particular subboard, use this command. Searchlight will confirm that it is your intention to unjoin, and remove you from the subboard's member list. Unjoining a subboard will prevent that subboard from appearing when you select the New/Joined command in the future. Remember that Searchlight determines new messages based on the high message pointer kept in your subboard member files. This number points to the highest message you've read, and Searchlight assumes that all messages above that value are new, and all below it are old. When you read messages nonsequentially -- if you use the Goto command, or perform personal message scans, for example -- your high message pointer may be set higher than some messages which you have not actually read. If you want to reset your high message pointer at any time, use the 1-Member/HighMsg command. New is Searchlight's "workhorse" command. It is the one command you'll use most often to read messages on your BBS and keep up with the activity on your subboards. MAINTAINING MESSAGES: THE EDIT AND KILL COMMANDS These two commands on Searchlight's main menu facilitate the editing and deletion of messages. To edit or delete a message, you must either be the person who posted the message, or a Sysop, CoSysop, or Subop of the current subboard. The Edit command lets you edit the title and text of a message, using the system's text editors. When you save the changes, the new message replaces the old. If you use the Abort editor command, no changes take place. Edit allows you to assign a "protected" status to messages. Protected messages can be edited and can be deleted on an individual basis, but a protected message will not be deleted during any mass message deletion. The Kill command lets you delete a message or a range of messages. Only Sysops, CoSysops or Subops can specify ranges with Kill. Normally, each message's header is displayed before it is deleted and you can opt to delete or keep the message. With range delete, it is possible to kill all messages in the range without verification (you are prompted for this option). MAINTAINING MEMBER FILES: THE 1-MEMBER COMMAND 88 Message System The 1-Member command is used to maintain the member (.MBR) file for the current subboard. The member file is primarily used to hold high message pointers for use with the New command. On the MAIL subboard, the member file contains user "mailboxes". These subcommands are available with 1-Member: HighMsg Search List Join Unjoin Quit 1-Member commands are generally available to both Sysops and regular users. However, Sysops can perform these commands for any member in the member file (by typing the name at the prompt), whereas regular users can only perform these commands on their own member account. 1-Member/HighMsg This subcommand lets you view or directly modify your high message pointer (the value used with the New command) for the current subboard. Although Searchlight normally maintains this value on its own, you may wish to modify it manually under certain circumstances. 1-Member/Search 1-Member/List The list and search commands operate similarly to User/List and User/Search; List allows you to list the members of the current subboard, while Search lets you search for a particular member name. The list or search result shows members' high message pointers and date of last subboard access. Please refer to the User command in the next section of this manual for a little more information about these suboptions. 1-Member/Join This command joins you (or any specified user, if you're a Sysop) to the member file for the current subboard. Upon joining the subboard, Searchlight prompts you to enter a value for the highest message read. You can press Enter to accept the default value or, if you wish to skip older messages in the subboard, you can enter a different value. Subboard member files can contain entries that are not users in your main user file; the most common example is Searchlight's SLMAIL program, which inserts a member record for itself when used to read new messages on a subboard, even though 'SLMAIL' is probably not a valid login name on your BBS. As the Sysop, you can use 1-Member commands to examine the member record for SLMAIL or any other specialized entry in your member files. 89 Message System 1-Member/Unjoin This is the complementary command to 1-Member/Join, and allows you to remove yourself (or if you are the Sysop, remove any user) from the subboard membership file. Searchlight confirms the deletion request with a Yes/No prompt before removing the member. OTHER MESSAGE MANAGEMENT FEATURES Searchlight's CONFIG program contains other useful message management facilities, including the ability to purge old messages and member files. See Sysop Utilities later in this manual. 90 Electronic Mail USING ELECTRONIC MAIL Searchlight BBS provides a complete electronic mail facility, in addition to the public message base. Some features of electronic mail are: individual, private mailboxes for each user; read, list, search, and new mail commands; message reply and forwarding; automatic message logging; and unlimited number of messages per user mailbox. What is the difference between private mail and public messages? Although Searchlight BBS allows you to designate a recipient for both public and private messages, the Mail command is specifically designed for sending private mail to a particular user. The main advantage to Mail is that your private messages are separate from the main public message sections of Searchlight and easily accessible at any time, from any subboard, by using the Mail command. In actuality, Searchlight stores mail messages in a subboard called "MAIL". If you examine this subboard, you'll find that it looks exactly like any other subboard on Searchlight BBS; you can even Jump to it and execute regular subboard commands like Read or Post. However, because the MAIL subboard contains private messages, you will want to prevent any users except authorized Sysops from accessing the mail area in this manner (by default, the MAIL subboard is set to access level 255). In addition, we recommend that you press the ALT-I hotkey anytime you jump to MAIL as a subboard (doing this prevents your actions from affecting the number of times read indicators in the mail headers). Think of the Mail command as a special way in which you access the subboard called MAIL: special because it allows users to read only those messages which are directed to them, while allowing them to send messages only to users who are actually valid members of your BBS. When you log in to Searchlight, a check of your mailbox is automatically made and the number of messages displayed. If you have any new mail, the system lets you enter the Mail/New command immediately. All other Mail operations are selected via the Mail command on the main menu. Mail presents this submenu: Read Send List New Find Inquire Purge Quit Select a command as follows: Mail/Read The Read command lets you read your private messages sequentially, beginning with the first message in your mailbox. Those messages which are new (have never been read before) are presented with this prompt: Read Now? Yes/No/Quit You can press Y to read the message, N to skip it and go on to the next message, or Q to abort the mail command. 91 Electronic Mail As you read messages, the standard message disposition commands (Next, Prev, Reply, etc.) are available from the command line. Note that the Goto command is not available when reading mail. The Delete Prompt After reading each message in your electronic mailbox, and responding to it with one of the above subcommands, an additional prompt appears: Delete this message? No/Yes Press "Y" if you wish to delete the message you just read; or "N" if you don't want to delete the message. Because private mail is only readable by the person to whom it's addressed, the software encourages you to delete messages after you've read them. That's why this prompt appears when reading mail. Mail/Send Send is the command to use when you want to send private mail to one or more users. Remember that mail is strictly for private messages, and you cannot send mail to "ALL" users (although you can send the same message to a small group of users). Send prompts you with: Send To : Enter the name of the person to whom you would like to send mail. You must enter a valid username that exists in Searchlight's database. However, you do not need to type the entire name; typing the first few characters of the name is sufficient to locate the correct user. If you type a partial username and there are several possible matches, Searchlight will prompt you for the correct one. Next, the prompt cc To : will appear. If you wish to send mail to more than one person, you can type the name of the next user here; if you have more usernames, more "carbon copy" prompts will appear to take them. When you're done entering names, just hit RETURN without typing anything. When sending mail to multiple recipients, Searchlight automatically includes a "CC:" line in the editor when you enter the message, listing those names. If you wish, you can modify or delete this line before you save the message. You may now enter a title and text for the message you want to send using the system's text editing facilities. When you're done, the message is added to the mailbox(es) of the designated recipient(s). 92 Electronic Mail You can also type "alias" names and "group" names in response to these prompts. For more information, consult Appendix E, Using Alias Names. You can also create Mail Send commands that send mail to a particular person, disallow carbon copy, or override certain access privliges. For more information, see Appendix G. Mail/List The List option provides a sequential list of the messages on file in your mailbox. The list shows the message number, date, sender, and subject of each message. Searchlight prompts you for a "Start Date" with the list command; if you press RETURN, it will list all messages in your mailbox. If you provide a date, only messages posted on or after that date are displayed. When the list is complete (or ^C is pressed), you can read a specific message by keying in the message number at the prompt. Mail/New The New subcommand lets you search for new (unread) messages in your mailbox. This command is similar to Mail/Read, except that only the new messages are displayed for reading. Note that the Mail/New command decides a message is new solely based on the number of times read indicator in the message's header, not via a high message pointer. Therefore, it does not matter if you skip around when reading mail. Mail/Find The Find option lets you search for specific messages by sender or subject text. In response to the prompt, enter the information to be searched for. Find then operates like List, except it displays only messages which match the search text. Mail/Inquire This subcommand is used to check, or inquire into, the status of messages you have sent to other users. When you use Mail/Inquire, you are prompted with: Search All Mailboxes? Yes/No If you choose "Yes", Searchlight will look at all the mail you have sent and which still exists (i.e. has not been deleted), starting with the last message sent and working backwards from there. If you choose "No", Searchlight will prompt you for a specific user name, and a start date, and 93 Electronic Mail will display mail sent to that person on or after the specified date, working forwards. After each message is displayed, this prompt appears: Again Next Forward Edit Kill Quit You can choose Again to view the message again, or Next to proceed to the next message. Use the Forward option if you'd like to forward a copy of this message to another person, a subboard, a text file, etc. If the message has not yet been read by the person to whom it is addressed, you can Edit or Kill it. These options don't appear if the message has already been received. Mail/Purge The final Mail command is Purge. It lets you delete some or all of the mail in your mailbox automatically, based on these suboptions: 1. Start Date .................... 1-01-87 2. End Date ...................... 5-24-92 3. Purge New Mail? ............... No 4. Purge Unanswered Mail? ........ No The Start Date and End Date define a range of dates for which you would like to purge messages. If "Purge New Mail" is set to No, then new (unread) mail won't be deleted, regardless of its date. Similarly, "Purge Unanswered Mail", if set to No, will preserve any mail which has not been answered. Press ESC when you have filled these fields in with the desired settings. Before any purge takes place, Searchlight confirms the command by asking "Begin Mailbox Purge?"; to continue, press Y, or press N to abort the command. Netmail Searchlight supports Netmail -- the ability to send private messages via Fidonet or a similar network using Fido technology. Sending and receiving netmail is similar to sending and receiving regular mail, with some exceptions; for more information, please refer to page 189. A Word about Mailboxes Having a mailbox on Searchlight BBS is the same thing as joining the MAIL subboard. However, it isn't necessary for any users to explicitly join MAIL -- it's done automatically, the first time someone sends mail to a 94 Electronic Mail particular user. In general, new users won't have a mailbox until someone sends them a message. Some Mail commands will report "Mailbox not available" when used by someone who has never received mail and therefore doesn't have a mailbox, however, this doesn't mean that user cannot send mail, nor does it mean they can't receive mail if some is sent to them. You can regulate the sending of mail, though, by setting the post attributes field in the MAIL subboard (use the CONFIG program to do this). Users who do not have these specified attributes won't be able to send mail messages (but can still read any messages sent to them). If for any reason you wish to manually create or delete someone's mailbox, Jump to the MAIL subboard and use the 1-Member commands. Notice that deleting a user's mailbox does not delete any of the messages in that mailbox, it only removes the user's access to those messages. 95 Bulletins USING THE BULLETINS SYSTEM Bulletins are a small, special group of messages maintained by Searchlight. These are the messages that are listed when a user first logs in, or when the Bulletin command is executed from the main menu. As you may have guessed, bulletins are actually stored in the BULLETIN subboard that was created by default when you installed Searchlight BBS. Although Bulletin is a subboard, the Bulletins command is a special way to read that subboard: it lists the messages in reverse chronological order and allows you to select them with a sequential number (regardless of the actual message numbers). Reading Bulletins To read bulletins, simply execute the Bulletins command and enter the number of the bulletin you want to read. This menu is also displayed as part of the login sequence. Maintaining Bulletins To post, edit, delete, or otherwise maintain your bulletins, simply Jump to the BULLETIN subboard. Use Searchlight's standard message commands to modify or enter new information. Don't worry about the message numbers that are assigned to new bulletins, as the Bulletins command automatically assigns sequential values to your bulletins. By default, BULLETIN is a high access level, protected message area that is accessible only to you as the Sysop. However, you might want to allow some or all of your users to access the BULLETIN subboard and perform modifications. To do that, just edit the access levels and attributes of the bulletin area via the Setup utility program. If you do allow your users to post bulletins, you will usually want to insure that the number of bulletins available doesn't go beyond a certain value (say 15 bulletins). We recommend setting this as the maximum number of messages via the CONFIG program. As well, use the "Auto Purge" feature to automatically purge old bulletins after the limit is reached (protect important bulletins by editing them and setting the protect flag on). 96 Using Chat Mode USING CHAT MODE "Chat Mode" is a feature which allows you to "talk" to, or exchange short messages with, a user logged on to your BBS. There are two kinds of chatting: Sysop-To-User chatting, which enables the SYSOP to talk to a logged in user, and Internode chatting, which allows two logged-in users to communicate. Sysop-To-User Chatting The Sysop-To-User chat feature is invoked when the Sysop responds to a "page" by a logged-in user, or by the Sysop by pressing ALT-C anytime at the local console. The local chat mode simply lets you type messages back and forth, and provides word-wrapping; the conversation may be logged by using the ALT-L logging facility. To exit chat mode, the Sysop presses the ESC key. Internode Chatting A more powerful Chat command, available only with multiuser versions of Searchlight, allows two or more logged-in users to communicate directly, instead of just being able to chat with the SYSOP. An internode chat session is initiated when one user enters the Chat command from the main menu. Chat displays the list of available nodes, and prompts the user to enter the desired node number to chat with. If you enter 0, Chat performs a local Sysop-To-User page, as with single-user systems. If you enter a nonzero node number, however, Chat prints the message Entering Chat Mode. Enter a period (.) to exit, .H for Help. followed by a right-bracket prompt. You may now type a short text message, pressing RETURN when you are finished. At another node, the user to whom your message is directed will continue to work. However, the next time the user's screen is cleared, Searchlight will display the message from you. If this user wishes to respond to you, he or she will then enter Chat mode from the main menu and begin sending messages to you (your terminal will display the sent messages either immediately, if your cursor is just to the right of the ">" prompt and you haven't typed anything, or immediately after you finish typing the current line). When you're done talking, just type a period at the ">" prompt and hit RETURN. The chat facility can buffer up to four lines of text. After four lines are sent, you cannot send any more text until the receiver has received the four buffered lines. When this happens, you must either wait for a response, or give up trying to chat. Notice that since messages sent to a user are only displayed when the screen clears, a user may not receive your message immediately; you should wait several minutes after sending the initial message before you can expect a reply. 97 Using Chat Mode At anytime during the chat, you can get a list of currently logged in users by typing ".W" at the prompt. To switch nodes and chat with another user, you can enter ".n" where "n" is the node number you want to chat with next. Messages are exchanged through a file called CHAT.SL2, which will be created on your disk if it does not exist. Since the messages in CHAT.SL2 are of a temporary nature, and since interactive chatting is disk- intensive, we strongly recommend that you use a small RAM-disk to hold the CHAT.SL2 file. You can specify the drive and pathname where CHAT.SL2 will be created using the option in the "Pathnames Setup" section of the CONFIG program. If you do so, however, remember that each node in your system MUST be set to the exact same chat path. Otherwise, chatting between some nodes won't work. The amount of disk space needed for the CHAT.SL2 file will be 512 bytes plus 512 times the number of nodes in your system. Since Searchlight will create CHAT.SL2 if it does not exist, there is no need to copy this file to or from your RAM-disk when the computer is reset. 98 Other Commands OTHER COMMANDS Here's an outline of miscellaneous Searchlight BBS main menu commands that were not covered in previous chapters: ANSI Command The Ansi command can be used at any time to change the current ANSI mode to Color, Monochrome, or None. Normally, this selection is made before logging in, but it can be changed afterwards. FILES Command Files transfers you to the Searchlight File Transfer system, a program used to upload, download, and maintain libraries of files. Before you can use the Files system, you must set up directories using the CONFIG program. For more information see File Transfer System in this manual. GOODBYE Command Goodbye logs you off the system, resetting Searchlight for the next call. If the "quotes file" is enabled, Searchlight will prompt you on logoff: Please leave us a quote: > You can type up to 72 characters. The message you leave is stored in the quotes file and can be viewed by later callers with the Quotes command. INFO Command This command looks for a file called INFO.TXT (or INFO.ANS for ANSI users) in your text directory area, and displays it if it exists. You can use the Info file to provide a brief description of your system, an editorial, etc. QUOTES Command Quotes looks into the QUOTES.SL2 file and displays the quotes entered at logoff (when the quotes file is active). TIME Command This command shows you the current time and date, the time you logged in, your elapsed time, and the amount of time left in your current session. 99 Other Commands USER Command The User command is used to list or search for users in the user database or to get a log of the last 75 callers. It has these subcommands: CallLog Search List Find Delete Balance Quit To get the list of the last 75 successive calls to the system, select the CallLog option. You can abort the list with ^C if desired. Search lets you enter usernames to search for. If the user is found, the system displays his or her location, system type, total calls, and dates of first and last login. You can specify partial user names here; for example, typing TOM would display all users on your system named Tom. The List function gives an alphabetical list of users on your system. You can start the list anywhere, by typing the first few characters of the name you want to begin with; or press RETURN to view the entire list. If you are the Sysop or a co-Sysop, Searchlight prompts you: Enter Min Access Level [ 0]: Enter Max Access Level [255]: If you press RETURN (to use the default values in brackets), all users are displayed. If you specify an access level range, however, only users who's access levels fall within that range are displayed. The Find option works like List, but allows you to specify an arbitrary search string. Only users who's user records contain the search string in the name, location, or system type fields are displayed. You can abort the search with ^C. Notice that the List and Find commands display user access levels, but only when used by a Sysop or co-Sysop. Use the Delete option if you want to delete a user from your user file. Naturally, this command is only available to you as a Sysop, and not to your regular callers. Deleting a user in this manner does not delete any mail or messages on the system for that user. The sysop utilities menu in CONFIG can be use to purge these items if desired. Balance performs an optimization and repair function on your user file. Balance sorts your user file to make sure that names are placed in an optimal order for retrieval, and can also repair any errors within your user file. Use this function if you suspect a problem with the user file (for example, if an error occurs when you try to access usernames) or periodically to ensure that your userfile is in top shape (an especially good time to balance the user file is right after making extensive changes to it, like deleting or adding users). 100 Other Commands VERSION Command This command displays: the version number of Searchlight BBS being used, the public portion of your software registration number, and the user license level (single user, three user, etc.) that you purchased. WHO Command In multiuser systems, you can use the Who command to display the number of active nodes and the names of the users logged in to each node. On single user systems, this command displays the current user's name and location. 101 Sysop Functions SYSOP FUNCTIONS A special command is provided on Searchlight's main menu that's available to Sysops and CoSysops only. This is the "2-Sysop" command and it lets you change access levels and options, read other users' mail, edit text files, and more. When you execute it (type "2" at the main menu and press RETURN), this subcommand menu appears: Options Adjust Validate Mail TextEdit DosShell Relog Quit Select "Quit" to abort the command, or select one of the command options as follows: Sysop/Options This option lets you edit a user's record, including user information, preferences, access levels, attributes and time limits. Complete details are given in the Configuring User Options section of this manual (see p. 67). Sysop/Adjust The Adjust feature is similar to Options, but allows you to edit four fields which are normally system-maintained: a user's upload and download amounts, first login date, and last login date. Normally, you will not need to change these fields as they are updated by the system; however, you may wish to do so in special circumstances, such as to correct inaccurate upload/download ratios. Sysop/Validate This command lets you "validate" a user by assigning one of the 12 preset access levels to that user's record. When you select Sysop/Validate and enter a username, Searchlight displays a list of the default access levels; choose one by pressing the appropriate letter. Default access levels are configured by using option "I" on the CONFIG program's main menu (see p. 35). Validating a user assigns the values associated with the selected access level to that user's account. You can individually adjust user records, though, by using the Sysop/Options facility. You can also invoke the Validate command by using Other/Validate from any message disposition line. Updating a particular default access level (via CONFIG) does not automatically update users to whom that access level has been assigned. Use the Sysop Utilities portion of the CONFIG program to effect such changes when required. 102 Sysop Functions Sysop/Mail The Mail subcommand lets you access the mailbox of another user. You can read, list, or search the user's mail, purge or delete messages, and write mail to other users "as" that user. First, pick the desired operation from the options displayed; then enter the desired user name. You can also access user mail by JUMPing to the "MAIL" subboard. Note that when you read a user's mail in Sysop/Mail mode, the "number of times read" indicators do not increment. Sysop/TextEdit This command loads a text file from disk and puts it into the Searchlight text editor. You can edit the file and resave it to disk, thus giving you the ability to edit files used by Searchlight (such as ALIAS.DEF) or other short text files without exiting from Searchlight or using another editor. Searchlight's full screen editor allows you to edit lines longer than 76 characters by appending an underbar character to the end of long lines and continuing them on the next line. If you edit such lines, you must manually maintain the position of the underbar at the end of the line. Do not use TextEdit to edit files longer than 400 lines or files which contain non- ASCII characters. Only the Sysop (access level 255) is allowed to use TextEdit. Sysop/DosShell This command calls up a shell to the operating system (DOS) by running the COMMAND.COM program. This is similar to pressing ALT-D, but it's also available from a remote login (limited, of course, to Sysops with the highest access level). Sysop/Relog Relog can be used during a remote call to log off of Searchlight but return the system to the "Select Graphics Mode ..." prompt instead of hanging up the telephone. By doing this, you can allow someone else to log on to the system without having to redial and make another connection. Additional sysop utilities that let you purge messages, users and files are available in the CONFIG program. See "Sysop Utilities" on p. 177 for more information. 103 Status Line & Hotkeys THE STATUS LINE Whenever someone is logged into your BBS from a remote terminal, the local PC screen will display a status line in inverse video at the bottom of the screen. The status line gives you information about the currently logged in user. It looks something like this: Online: USER NAME Access: AAA/BBB Time: XXX/YYY Node N sacnl USER NAME shows you the name of the person who is logged in. AAA and BBB are the user's BBS access level and FILES access level, respectively. XXX is the amount of time (in minutes) that the user has been logged in, and YYY is the user's time limit for this session. Node indicates the node number (in multiuser systems) of the node you are looking at. The lowercase letters to the right are status flags, as explained below. HOT KEYS As the SYSOP, there is a group of operations that you can perform through the use of what we call "hot keys" at the local keyboard. A "hot key" is a special key that can be pressed at almost any time the Searchlight is running, without disturbing the call in progress. For example, ALT-V is the hot key for validating users. If you press ALT-V while a new user is logged in, that user will be instantly validated, and the status line on the bottom of the screen will be updated to show the user's new status. Pressing ALT-V while a validated user is online results in un-validating the user, or returning the user to the defined new user access levels and time limit. The user at the remote terminal doesn't see any of this happening. The F9 and F10 keys can be used to adjust a user's time limit. Pressing F9 adds five minutes to the currently logged in user's time limit, and pressing F10 subtracts 5 minutes. The new time limit is in effect only for the current call. The F8 key is a status line toggle. Pressing F8 changes the format of the status line, swapping the above access level/time limit display with one of three others showing the user's location, computer type, phone number, and current baud rate, or the system's memory usage. The letters "sacnl" on the lower right hand side of the screen are flags, and they are controlled with hot keys as well. The "S" flag is called the superuser status flag. When the flag is OFF, a lowercase s is displayed. When it is ON, an uppercase S is shown. You toggle it on or off by pressing the ALT-S key on the local keyboard. When superuser status is ON, any user who is logged in is granted full SYSOP privileges. Normally, you use this command in order to allow yourself to execute sysop commands while someone else is logged in. You can also use it to grant temporary SYSOP access to the logged in user. Note that if you turn this switch ON, it remains ON until you turn it off, or until the current user logs off (or hangs up). 104 Status Line & Hotkeys The "a" and "c" flags control the operation of the chat command. The "a" flag is the Sysop Availability flag. When it is ON, an uppercase "A" is displayed, and paging is enabled; that is, the system will beep to inform you of an attempt by a user to call you with the "Chat" command. If availability is turned OFF, the computer will remain silent, and inform all users attempting to chat that no sysop is available. The sysop availability mode is turned on and off by pressing ALT-A. The "c" flag tells you whether or not the current user has attempted to page you since logging on. If a capital "C" is displayed, it means the user attempted to Chat. This is true regardless of the setting of the "A" flag. ALT-C is the chat hotkey. At most times when the Searchlight is running, you can "break in" to chat with the logged user by pressing ALT-C. This causes you to go into chat mode immediately, suspending any operation in progress. When you exit the chat mode (by pressing the ESC key), Searchlight restores the original screen display and returns the user to the exact place where he or she left off. The "n" flag and the ALT-N function key toggle Searchlight's Sysop-Next option. Sysop-Next is a flag which you can set to indicate that you would like to system to revert to a local login immediately after the current user logs off, thus giving you the opportunity to log onto the BBS yourself or take the BBS down to perform maintenance functions. When the ALT-N flag is set, Searchlight will, upon recycling back to the call waiting screen, immediately issue the local init string to your modem, sound a short alert tone from the speaker, and go into a local login mode. You can turn the Sysop-Next flag or off by pressing the ALT-N key at any time. A capital "N" indicates that it is on, while a lowercase letter means that it's off. If a front-end program is being used (that is, if Searchlight is set to Return to DOS on Logoff), it will exit with a result code of 3 when the Sysop-Next flag is set. It is up to the front end program to recognize this as a request to allow the sysop to log in next; if your front end software cannot do this, then you won't be able to use the ALT-N feature. ALT-I is Searchlight's "invisible" hotkey. Actually, what ALT-I does is allow you to read messages on any subboard, or in your mailbox, without updating your high message read counter, or the "number of times read" counters in message headers. (An uppercase I appears on the status line when you press ALT-I and disappears when you press it again). ALT-I is particularly useful when you want to review private messages by Jumping to the MAIL subboard, without affecting the counters for those messages. Output Logging The "L" status flag and the ALT-L command control output logging. Logging allows you to capture all of the text being sent to and from your BBS and output it to a disk file or device. For example, you could use this feature to record a conversation with a user while in CHAT mode, or to make ASCII text files containing listings of your upload/download directories, or to 105 Status Line & Hotkeys get a printout of almost any listing, message, or display that Searchlight normally sends to the screen. To begin logging, press ALT-L; you are prompted to enter a filename. If you defined a default log file in the CONFIG program, it is displayed, and you can use it by pressing RETURN. Otherwise, enter the desired filename. Logging begins, and continues until you press ALT-L again, change from one program module to another (i.e. run the Files program or quit from Files to the main menu), log off, exit via ALT-X, or execute a DOOR program. All text normally displayed on the screen is copied into the log file. If you wish to obtain a hard copy (printout) of BBS activity, use PRN as the output filename. PRN is the printer device file, and it will cause subsequent output to go to the printer. Backspace characters are processed out of the logged output, and ANSI escape sequences are removed. Also, the "-- more --" prompt is disabled during logging. Exit Key ALT-X can be used to temporarily exit Searchlight and return to DOS. When you press ALT-X (from the local keyboard only), all files are closed, Searchlight terminates, and you return to DOS. When you re-run Searchlight (by executing SLBBS.EXE), you are returned to your BBS and positioned at the main menu. If you use ALT-X while a remote user is online, the modem will not hang up the telephone, but the remote user will cease to receive output or be able to give input to the system until you return to the BBS. You don't have to return to Searchlight after ALT-X: it is safe to shut your computer off, or run another program. However, the next time you run Searchlight it will return to the current session. You must log off (using the GoodBye command) in order to allow Searchlight to receive new calls. ALT-X will exit with a return code (errorlevel) of 1. This allows an external front-end program, if used, to distinguish between an exit to DOS and a normal logoff. Pressing ALT-X loses your current menu position and may make it impossible to return to previous menus, if you have made changes in your menus. If you encounter menu-related problems after using ALT-X, we recommend you either avoid using ALT-X (use GoodBye instead), or, when re-starting Searchlight, type "SLBBS Local". Hangup Key The ALT-H key has been provided to enable you to terminate a user's session immediately. If you press ALT-H from the console while a user is logged in, the modem will hang up on the user and Searchlight will recycle to accept another call. 106 Status Line & Hotkeys ALT-H will, of course, terminate a user's session abruptly and may cause that user to lose any message being typed. ALT-H is provided for use at your own discretion. If someone is on your BBS and you need to use your computer, we suggest you use ALT-C first to chat with the user, and ask him or her to log off normally. Command Keys Two special keys are provided to allow access to other programs while running Searchlight. The ALT-F key runs the Searchlight CONFIG program. To use it, your CONFIG.EXE program must be loaded into your SLBBS program directory. ALT-D provides a shell to DOS. It requires that COMMAND.COM be available in the path specified in the COMSPEC environment variable. To return to Searchlight, give the command EXIT at the DOS prompt. Both ALT-F and ALT-D will return you to the last menu you accessed before using the command. However, if you press ALT-F or ALT-D while entering a message, you will lose any text which has not been saved. You can also lose new message pointers and lose your place while reading messages or mail. We recommend using ALT-F and ALT-D while situated at a menu prompt, rather than while reading or entering messages. 107 Text Editing TEXT EDITING: INTRODUCTION Searchlight contains two text editors that are used whenever you enter a message or send electronic mail. The text editors, while not full-fledged word processors, contain many features and commands that allow you to easily compose, enter, and change short to medium length messages. In addition, you can use Searchlight's text editing capabilities to edit text files on disk, even from a remote terminal. A line-oriented text editor, similar in nature to the DOS EDLIN editor and to the editors found on many BBS systems, is provided for use with non-ANSI terminals. The line editor provides a fast and simple way of entering messages, with rudimentary editing facilities, and it works from almost any kind of remote terminal, from IBM PCs to older home computers to printing terminals. Searchlight also contains a full-screen text editor that resembles the types of editors most people are used to working with on the IBM PC. It gives you an exact representation on the screen of what your message will look like when read back, and it allows you to move the cursor anywhere on the screen and insert, change, or delete text with simple keystrokes. The commands used are a combination of standard PC editing keys and a subset of the popular "Wordstar" command set, so chances are you already know how to use Searchlight's editor. The main disadvantage of the full screen editor is that it's not compatible with all terminals -- you must have an ANSI (or vt100) compatible terminal (or terminal emulator) to use it in remote mode. Fortunately, software to emulate ANSI terminals is available for most microcomputers -- for the IBM PC, we recommend Procomm, Procomm Plus, and Telix. In addition, you'll find that certain operations, such as PageUp and PageDown, are inherently slower when running from a remote terminal than when executed on a normal word processor: that's because Searchlight can only send text at the speed of the modem being used, and cannot manipulate the screen at high speeds the way regular text editors can. However, Searchlight makes extensive use of ANSI control sequences to minimize the amount of text that must be retransmitted to the remote screen. In local mode, it operates at speeds comparable to most full screen text editors. Searchlight determines which editor to use based on the status of the ANSI graphics mode. When ANSI (color or monochrome) is enabled, the full screen editor is used; otherwise, the line editor is used. You can change the status of the ANSI flag from the main menu with the ANSI command. 108 Text Editing USING THE LINE EDITOR When ANSI mode is not selected, Searchlight uses a line oriented editor. The editor is invoked whenever you POST a message or bulletin, EDIT an existing message, or send a message via the MAIL command. When the line editor is running, you'll see the message Enter text; type a period (.) when done. Max NNN lines. followed by the number "001". NNN is the maximum number of lines that you may enter into the message (it can be anywhere from 5 to 400, as defined on the subboard definition screen in CONFIG). You would now begin typing your message. As you type, you can correct errors by pressing the BACKSPACE key. There's no need to press the RETURN key when you reach the end of a line; instead, the editor automatically performs "word wrapping", that is, it breaks the line at the nearest word boundary and moves the last word on the line down to the next new line. As you type, you'll see the line numbers to the left of your text increase. When you are done entering text, press the RETURN key once (so that the cursor is directly to the right of a line number). Then type a single period (.), and press RETURN again. This takes you out of the text insertion mode and places you at the line editor's subcommand prompt, which looks like this: Cont Edit Ins Del List Abort Save -? You can now enter an editor subcommand by typing the first letter of one of the above command words at the prompt. The commands work as follows: Save This is the command that saves the message you just entered (or edited) onto the disk. You use this command when you are done with the message, unless you've changed your mind and decided not to send the message at all. Abort The abort subcommand can be used to throw away the message in case you decide you don't want to send it. It will prompt you to make sure that's what you really want to do, in order to insure that you don't abort the message by mistake. Cont The cont, or continue, subcommand lets you continue entering lines at the end of the message. It places you back into the text entry mode at the next highest line number. 109 Text Editing List This command can be used to list, or review, the message just entered. It will prompt you for a line number; if you enter 1, or simply press RETURN, the message is listed from line 1 to the end. If you wish the listing to start at a specific line number, you can enter that line number. You can pause the listing with ^S, and cancel it with ^C. Ins This is the insert command. It lets you insert one or more new lines of text in between two existing lines. You are prompted to enter the number of the line that you want to insert BEFORE; for example, to insert between lines 11 and 12, you'd give line 12 as the target of the insertion. Once in insert mode, you can type as many new lines as you like. To exit back to the subcommand prompt, once again enter a period at the beginning of a new line. Del The delete command lets you delete one or more entire lines of text from the message. It prompts you to enter the starting and ending line numbers of the range of lines that you want to remove. Edit This command gives you a way to edit the individual characters on a line. It prompts you for the line number of the line you wish to edit, and gives you a choice: Change or Retype? Respond by pressing "C" to change the line, or "R" to retype it. Retyping simply lets you re-enter the entire line of text from scratch. You can only retype one line at a time. Change gives you the opportunity to edit portions of the line without having to re-key the entire line. It works by prompting you for a "source" and a "replacement" string. The "source" is a portion of the text, exactly as it appears in the line. The "replacement" is a string of text that will replace the source string. As an example, suppose we typed this into our message at line number 7: 07 Beethoven was bitten by a communist roach when he visited New York. 08 . Obviously, we meant to type the word "salmon" instead of "roach". To correct it, we would edit the line and enter "roach" as the source string, and "salmon" as the replacement: 110 Text Editing Cont Edit Ins Del List Abort Save -? E Line Number: 7 Change or Retype? C Source String: roach Replacement : salmon Although the corrected line is not displayed on the screen, we could view it by using the List subcommand. The new version of the line would look like this: 07 Beethoven was bitten by a communist salmon when he visited New York. Notice that you can replace a string with a string of a different length (or even a null string, in which case the original text is deleted entirely). However, the total length of the line cannot exceed 76 characters. EDITING EXISTING MESSAGES The line editor can also be used to edit existing messages via the "Edit" command on the main menu. When used in this fashion, it operates identically to the above description, except that you'll go right to the "Cont Edit List..." prompt rather than to the "Enter Text" prompt. Saving the message results in the edited version of the message replacing the old version on disk. If you abort the edit, the changes you've made to the message, if any, are not saved; the original message is left intact. 111 Text Editing USING THE FULL SCREEN EDITOR When using an ANSI compatible remote terminal, or when logged in locally, you'll be able to enter and edit text via Searchlight's full screen editor. The screen editor signs on by displaying an inverse video bar near the top of the screen that contains this message: Editing, max NNN lines | ESC/^Z Exit | F1/^J Help | F6/^P Color Codes If entering a new message, the lower portion of the screen will be clear and the cursor will be positioned at the top of the text entry "window" on the screen. If editing and existing message, you'll see the first few lines of the message, with the cursor positioned at the first character in the first line. You are now ready to enter or edit text. To enter text, simply begin typing. As with the line editor, you can correct single character mistakes as you type by pressing the BACKSPACE key. As you approach the end of a line, the text will "word wrap" down to the next line, so there's no need to press the RETURN key at the end of lines (unless, of course, you wish to type lines shorter than the width of the screen). Unlike the line editor, which has subcommands for performing editing, you can edit text in the full screen mode interactively, using the cursor position keys and control keys. As you change the text, your screen is updated instantly to reflect exactly what the file looks like. If you've ever used a word processor on your IBM PC, you're probably very familiar with this method of editing: you'll need only learn a few of the commands and keystrokes that are specific to the Searchlight editor. WORDSTAR COMPATIBILITY When we say Searchlight's editor is "WordStar Compatible", what we mean is that, in most cases, we've used the same key sequences to perform the same editing tasks as the Wordstar word processor. We picked Wordstar because its command set is a well-known standard, and because its use of control key sequences (rather than menus or function keys) is particularly suitable for use with modems and remote terminals. Searchlight doesn't support ALL of Wordstar's commands; in fact, it uses only a small subset of them. In addition, we've incorporated a few special commands and keystrokes that are unique to our editor. 112 Text Editing SCREEN EDITOR SUBCOMMANDS If you press either F2 or ^J (control-J) while in the editing mode, you'll see one of three help messages at the top of your screen. Press F2 again to see the remaining messages. The help text looks like this: ------------------------------------------------------------------------- ----- Left/^S - Cursor left ^A - Word left DEL/^G - Delete character Right/^D - Cursor right ^F - Word right ^T - Delete word Up/^E - Cursor up INS/^V - Insert mode ^Y - Delete line Down/^X - Cursor down CR/^N - Insert line ^B - Reform paragraph ------------------------------------------------------------------------- ----- ------------------------------------------------------------------------- ----- PgUp/^R - Page up ^QR - Top of file ^QY - Truncate line PgDn/^C - Page down ^QC - End of file ^QL - Restore line Home/^QS - Begin of line F3/^KO - View reply-text ^L - Redraw line End/^QD - End of line F4/^KG - Get reply-text ^W - Redraw screen ------------------------------------------------------------------------- ----- ------------------------------------------------------------------------- ----- OI - Toggle indent mode ^KP - Message Preview ^KU - Upload text via ^OC - Center line F5/^KS - Exit & Save XMODEM ------------------------------------------------------------------------- ----- These are the main editing commands. Many are self-explanatory, some need further study as we'll divulge below. The ^ character means CONTROL. To generate a control key, you hold down the key marked "Ctrl" on your keyboard, then press the indicated letter key, then release both keys. Notice that some commands have two ways of being entered, either via a control key or via a function key. This is done because some remote terminals don't configure the function keys the same way they're supposed to be set up on the true ANSI terminal. If a key such as F1 or HOME doesn't work on your terminal, you can always use the control key instead. Remember to press ESC (or ^Z) to exit the full screen editor. You can also exit by pressing F5 (or ^KS); this skips the "Continue, Save, Abort" prompt and goes directly into "save" mode. 113 Text Editing Cursor Movement To edit text, you must first move the cursor to the character, word, or line that you want to change. The cursor movement keys accomplish this. The four arrow keys (left, right, up, down) move the cursor one character in the indicated direction. If you move up or down past the top or the bottom of the screen, the screen will scroll to display the previous or next line of text. You cannot move the cursor past the beginning or end of the file, but you can append text to the end of the file. Press the HOME key to move the cursor to the beginning of the current line. The END key takes the cursor to the end of the line. The ^A and ^F keys move you left and right a word at a time. In local modes only, you can use ^LeftArrow and ^RightArrow as well. You can scroll a long message forward and backward one full screen at a time. Press the PgUp and PgDn keys for this. On a remote terminal, you must use ^R for pageup and ^C for pagedown. Finally, you can move directly to the beginning or end of the text. Press ^QR to get to the top of the file, ^QC to go to the bottom. Deletion You can delete text by characters, words, or lines. To delete the character under the cursor, press either DEL or ^G. Pressing the BACKSPACE key deletes the character to the left of the cursor. When you delete text, the text to the right of the cursor moves left to fill the gap left by the deleted characters. Text can be deleted a word at a time. Place the cursor on the first character in the word and press ^T. You can delete all the text on the current line from the cursor position to the end of the line. Press ^QY to perform this function. To delete an entire line, position the cursor anywhere in the line you wish to delete, and press ^Y. When you delete a line, the remaining lines in the message move up to fill the gap left by the deleted line. Insertion Searchlight's editor supports either insert or overstrike mode. In insert mode, text you enter in the middle of a line causes the text to the right of the cursor to shift, making room for the new characters. In overstrike mode, new text overwrites any text underneath it, and no scrolling occurs. The editor is in insert mode each time it starts up, but you can toggle between modes with the INS or ^V key. 114 Text Editing When insert mode is active, the indicator "Ins" appears at the top of the screen. When overstrike mode is selected, "Ovr" is displayed instead. In insert mode, an attempt to insert characters into a full line causes the line to be split in half at the cursor position. The message "Press ^B to reform paragraph" appears at the top of the screen. After typing your new text, press the ^B key and the subsequent text will move back up and reformat into a paragraph. In overstrike mode, press ^N to force a line break before entering new text. You can also press the RETURN key to enter a new line in the text. In this case, the cursor moves down to next line, rather than remaining stationary as it does with ^N. Error Recovery If you make a mistake, you can restore the contents of the current line provided the cursor has not left the line. Press ^QL for this function. Reformatting Text After performing many insert and delete operations, your text will no doubt have lost its original format: you'll have some lines that are shorter than others. Never fear; you can reformat any continuous piece of text back into neat paragraph form by using the ^B command. Simply move the cursor up to the first line in the paragraph and press ^B. The editor will format all the subsequent text into a paragraph, until it reaches a blank line or a line that begins with a space or another non-alphabetic character. Indent Mode Pressing ^OI activates Indent Mode (you'll see the letters "Ind" near the top of the screen when indenting is active). In indent mode, the editor will match your indent when typing lines -- for example, if you manually indent the first line of a paragraph by 5 spaces, then type some text, Searchlight will automatically insert 5 spaces before each new line as the text wordwraps or you press RETURN to end lines. This is useful, for example, when you want to indent an entire block of text. You can reformat indented text with the ^B command; Searchlight will continue to obey the indent, and format the text with the proper number of blank spaces before each line. Centering Lines A center line function is provided by pressing the ^OC keys. This command will center the current line of text, and move the cursor down to the next line. 115 Text Editing Reply Text Often, when you reply to a message by selecting the "Reply" option on the menu line, you'll want to be able to read the original message again while you're typing the reply. You may even want to insert a few lines of the original message into the message you're writing. Searchlight provides a way to do this with the "View reply-text" and "Get reply-text" functions. If, while typing a reply, you want to look at the original message again, press F3 (or ^KO). The screen will clear and the text of the message will be displayed. At the end of the message, you'll be prompted to press the RETURN key to go on; when you do so, the editor redraws the screen and returns you to the message you were typing at the exact spot you left off. Reply-Quote Line Selection The F4 (^KG) key lets you do even more with the original message. When you press F4, Searchlight places the original text into a selection mode that lets you review the text and tag specific lines for importing into your editing screen. To begin the reply-quote process, reply to a message and press F4 or ^KG. A full screen display such as this one will appear: Select lines to quote from original message |Greetings! | Received SLBBS today and am delighted! In only an hour I already have |the main makings of the BBS and a couple of friends are equally amazed |with what's been done in a small part of one afternoon!! | *| So far... not a single hitch in setting this thing up... of course I *|can see that my first problem is going to be resisting the urge to have *|ump-teen hundred different Subboards... they are almost _too_ easy *|to setup :) | | Congrats on an absolute DYNAMITE program! | |Regards, |Bob The full-screen display can be paged and scrolled by using the standard cursor control keys, including page up and down, home and end, and the arrow keys. To "quote" some lines, position the cursor to the left of the desired line, and press the spacebar. An asterisk appears to the left of the line, indicating that it is tagged; continue pressing spacebar to tag more lines in succession. In the example above, four lines starting with the text "So far..." have been selected for quoting. If a mouse is available, you can tag lines by clicking on the area to the left of the 116 Text Editing line. You can untag lines by clicking or pressing spacebar on the line again; or press F4 or F5 to automatically tag or untag all lines. Once the desired lines are tagged, press Enter or ESC. The tagged lines are imported into your reply: > So far... not a single hitch in setting this thing up... of course I >can see that my first problem is going to be resisting the urge to have >ump-teen hundred different Subboards... they are almost _too_ easy >to setup :) If desired, you can tag more lines later by pressing F4 or ^KG again, and repeating the process. Wise use of the reply-text function can aid you in replying to a long message with many specific points, and it can help end ambiguous electronic mail replies by reminding the original sender what question or statement is being addressed by your letter. Message Uploading Uploading a text file as a message to Searchlight BBS is accomplished by pressing ^KU. The text file to be uploaded should be a plain text file with lines of no longer than 76 characters, and the total length of the message should be no larger than the total number of lines that are permitted to be entered for the current message area. Upon pressing ^KU, Searchlight prompts you to begin sending the file. As in a normal file upload, the remote user should then activate the a file send procedure from his terminal program and begin transmitting the file. Upon completion of the transfer, Searchlight loads the text file into the editor. At this point, the text can be saved immediately or edited. If any text is already in the message editor prior to an upload (such as if you have typed some text in manually) then the uploaded text is appended to the text already present. If desired, two or more uploads can be used to create one large message from several smaller message files. Searchlight can use any of its internal protocols, including Zmodem, Xmodem, Xmodem/CRC or Xmodem/1K for message uploads. Select a default internal protocol on the Options/Preference screen. Searchlight automatically truncates lines longer than 76 characters, filters any non-text characters from an attempted upload, and truncates the entire message if it is longer than the maximum allowed message length. Should any of these modifications occur, a warning message appears following the upload to inform the user of the situation. 117 Text Editing Message Preview The ^KP key sequence provides a message preview feature (a display showing what the message will look like when it is read back later). The preview shows how color codes and included files will look (see the next two sections for information about color codes and file inclusion). ANSI Compatibility Searchlight's full screen editor actually has three modes of operation, designed to allow it to interface with a variety of popular terminal software. When editing remotely using an ANSI terminal, certain operations (such as inserting and deleting lines) require that the terminal software implement the appropriate ANSI escape sequences that will cause the remote screen to scroll appropriately. Unfortunately, many terminal programs are geared for more traditional BBS systems without full screen editors, and thus do not support the required commands. To work with such terminals, Searchlight includes a "Generic" ANSI mode. To select the editor's mode of operation, type the "Options" command (on Searchlight's main menu) and adjust option number 5, called "Ansi Compatibility Mode". There are three possible settings: Generic, Procomm, and Full. In Generic mode, the Searchlight editor minimizes the types of ANSI commands sent to the terminal to a small subset of the most widely supported ones. Instead of scrolling the screen and performing inserts and deletes directly on the terminal, Searchlight redraws portions of the screen when a change needs to be made. Of course, the time it takes to continuously redraw the screen can range from long to unbearable, depending on the speed of the modem used; but all of the supported features will work correctly. In Full mode, Searchlight will edit with the full set of ANSI commands for the fastest possible output, and will require a full featured ANSI terminal. The remaining mode, Procomm, is similar to Full but takes into account several quirks found in the Procomm (TM Datastorm Technologies) terminal software. The New User Registration procedure displays information about ANSI modes, and prompts each new user for the correct mode as they log in. Additional Thoughts On Full Screen Editing Notice that, when you're using Searchlight in ANSI mode, the above full screen editing commands are actually available everywhere in the system where a line of input is required. This includes entry of message subjects, user names, etc.; you can edit the line of text being typed with all of the commands that pertain to editing of the current line, including the ^L command to redraw the line. 118 Text Editing EMBEDDED COLOR CODES One command that appears on the full screen editor's menu bar that we didn't mention yet is the F6/^P command, Display Color Codes. If you press F6 (or control-p) while within the editor, Searchlight will display a menu of two-character color codes in the help window at the top of the screen. By typing these codes into your messages, you can make your text appear in different colors. Here are the color codes as displayed by the editor: ------------------------------------------------------------------------- ----- \BK - Black \RD - Red \DG - Dk. Gray \LR - Lt. Red \IV - Inverse \BL - Blue \MG - Magenta \LB - Lt. Blue \YE - Yellow \BI - Blink \GR - Green \BR - Brown \LG - Lt. Green \LM - Lt. Mag. \NO - Normal \CY - Cyan \GY - Gray \LC - Lt. Cyan \WH - White ------------------------------------------------------------------------- ----- If you have a color CRT, the menu will appear in 16 different colors. On monochrome screens, the first eight colors will appear as normal text, the remaining eight as bright or highlighted text. To use color, just enter the above sequences into your message text. For example, if you wrote Jim left the \BLblue\NO book by the \GRgreen\NO tree, The words "blue" and "green" would appear blue and green when you read the message back. The \NO code is used to reset the color back to the "normal" text color (as defined in the CONFIG menus). If you want to insert the "\" character itself into your message, enter "\\". The inverse code, \IV, reverses the foreground and background colors. On monochrome screens, \IV provides a black-on-white display. With a color CRT, you can create any background/ foreground combination; for example, \BL\IV\WH This text will be printed white-on-blue. \NO Searchlight translates embedded color codes according to the ANSI graphics mode selected at login. If monochrome mode is selected, only normal, highlight, inverse, and underline attributes are used. In non-ANSI modes, no colors or attributes are used at all, but the color codes are still removed from the text; therefore, text with embedded color codes will appear readable in any of the three graphics modes. If you'd like to see what the actual colors you are using will look like, use the message preview command (^KP). Finally, note that color codes are not restricted to the full screen editor. You can insert color codes into messages using the line editor, and 119 Text Editing you can also use them in login screens, include files, custom menus, and other text files displayed by Searchlight. 120 Text Editing MESSAGE MACROS Several message macros are available. These macros are special three character sequences -- very similar to color codes -- that can be inserted into messages, text files, and other places where color codes are allowed. When read back, these macros are expanded by Searchlight to display information. For example, the macro "\SB" stands for "Current Subboard". When this three character sequence appears in a message, text file, or menu prompt, it's replaced with the name of the current subboard. Searchlight's default main menu uses this sequence as part of its prompt. Here is the complete list of macros available: \SB Current Subboard \FD Current File Directory \%N Current User's Name \%U Current User's Name, with spaces replaced by underbars \%K Current User's First Name \%A User's BBS Access Level \%F User's FILES Access Level \%G ANSI Graphics Mode (C, M, or N) \%T User's time limit, in minutes \%M Amount of time left in current session (in minutes) \%L Time the user logged in (HH:MM) \%B Current Baud Rate \%P Active Communications Port (0-4) \%C Sysop 'Chat Available' status (Y or N) \%S BBS System Name \%O Node Number (Multiuser systems only) 121 Text Editing USING PREPARED TEXT FILES Sometimes, instead of typing a message by hand, you'll want to insert a previously written file of text into a message, bulletin, or electronic letter. There are several ways to accomplish this with the Searchlight's editors. Uploading The simplest way to insert a text file into a message is to log on from a remote location using a terminal that's capable of Xmodem file transfers. By pressing ^KU in the full screen message editor, you can begin an Xmodem transfer of your text file, which will be loaded into the editor upon completion of the transfer. There are a couple of things to look out for when using this method of sending text. First, the text file should not contain lines longer than 76 characters; if it does, Searchlight will try to wordwrap the text, resulting in a sloppy format. Also make sure the text doesn't exceed the maximum line length of the message. You can't send text that contains embedded ANSI escape sequences, such as text that moves the cursor around on the screen or effects color changes (although eight-bit IBM graphics characters CAN be used). If you want embedded control codes, use one of the other methods for inserting text into messages. Loading Files The text editors feature a special function, executable only by SYSOPs, that lets you load a text file directly into a message. To use it, press ESC and then "L" for the full screen editor, or press "F" at the subcommand prompt of the line editor. The editor will prompt you for a filename, and load the text of the specified file into the message. You can give a full pathname and drive letter if you want. The %%FILENAME Directive A third method of including text in messages is to use the '%%FILENAME' directive inside of a message. This method involves placing a special line within the message. It doesn't matter which editor you use to create the message. Let's suppose we have a text file called "PHONE.TXT" that we wish to include in a message we're sending to someone. We could write the following: 01 Bill, 02 Here's that phone number list I promised you: 03 04 %%PHONE.TXT 05 122 Text Editing 06 Enjoy. When we list, save, or edit this message later on, it looks exactly like the six lines shown above. However, when the message is read by Searchlight's read routines, something special happens when line 4 is encountered. Instead of printing line 4 verbatim, Searchlight looks into a special directory for a file called PHONE.TXT, and displays the contents of that file on the screen. When the PHONE.TXT file is done, Searchlight goes back and prints out lines 5 and 6. The '%%FILENAME' directive is convenient because the included file doesn't take space in Searchlight's message file, doesn't have to be less than 400 lines long, and can contain any ANSI sequences that you desire. Notice, however, that you may give ONLY a filename with this directive, NOT a drive letter or pathname. The text file must reside in the directory you designated as the "include" directory when configuring your system via the CONFIG program. This is done for the purpose of security; since anyone can enter a '%%' directive into a message, you want to ensure that users don't try to read files which they don't have access to. It is assumed that anything in the "include" directory is public knowledge. The '%%' characters must be in the first column on the line, and the line must not contain any other text after the filename. You can have more than one include file in a particular message, however. If you only use file inclusion yourself, it doesn't matter what you choose as your "include" directory, as long as you store all the files which you want to include in messages there. However, if you want your users to be able to upload files to the system and include them in messages, make the "include" directory accessible via the FILES system; that is, define a file directory that uses the include directory to store the uploads. This way, your users will be able to upload files to the include directory, and access them in messages they post or send. Using include files this way, for example, is the only way to allow users to post messages containing ANSI escape sequences on your BBS. The @@FILENAME Directive In addition to including files in the "include" directory, we've also provided a way to access files in your "text" directory from within a message. It's similar to the "%%filename" construct used above, but you type "@@filename" instead. This directive lets you access any of your system's text files -- including custom menus, help files, login screens, etc. -- from within a message. We don't recommend letting your users have upload access to your TEXT directory, however, since these text files are used by Searchlight BBS and you'll want to remain in total control of their contents. 123 Files Subsystem SEARCHLIGHT BBS FILE TRANSFER SYSTEM Introduction One of the most valuable features of the Searchlight BBS is its file transfer system. With file transfer, Searchlight gives you the ability to transmit files of any type from one computer to another over the telephone, with the capability to check for errors. It lets you set up multiple directories where users can "upload" a file or choose from a selection of files to "download". You can have as many file directories as you need, and, if desired, you can use a different set of directories for each message subboard on your system, giving you thousands of possible directory setups. As the sysop, you can assign different access levels to control what users have access to what files. The Searchlight file system has many useful features: alphabetical and chronological directory listings, wildcard directories, global directory scans, three built-in plus nine external transfer protocols, password protection, and private file transfers. Batch uploading and downloading are supported. Users can view the internal directory of ZIP, PAK or LHARC files while online. Sysops can delete files, move and copy files between directories, and import filenames from existing files on disk quickly and easily. You can modify file descriptions and other information after it's been entered. Plus, Searchlight's file transfer programs are the fastest available, due to advanced two-way interrupt driven RS232 handling. Setting Up Directories Before you can use Searchlight's file transfer system, you need to set up directories from which to transfer files. Directory setup is accomplished via the CONFIG program, as covered at the beginning of this manual (see p. 54). Although the directory setup facility is easy to use, it's worth noting that you should create the actual DOS directories you want to use with Searchlight before defining them in CONFIG. A word about what we mean by "file transfer directories". You are undoubtedly aware that the DOS operating system uses directories and subdirectory structures. For the purposes of Searchlight, however, we will be defining our own directory structure, partly to afford a greater level of security than is available with DOS, partly to extend the functionality of the directory beyond what DOS provides. Still, your upload/download directories can, and should, be constructed so that they correspond to actual DOS directories. One directory that almost every BBS has is called UPLOADS, and it's used to contain all the "new and recently uploaded" files on the system. As an example, we will create this directory in the "root" directory of the C: drive. The proper command, from the DOS prompt, would be: MKDIR C:\UPLOADS Next, we have to configure the FILES program to use the new UPLOADS directory. Run CONFIG and select option C at the main menu; then press F1 125 Files Subsystem to add a directory. At the prompts, enter 'UPLOADS' as the directory name, and 'C:\UPLOADS' as the path. Searchlight creates an UPLOADS.SL2 file (which holds such information as file descriptions). Repeat this procedure to create other directories as needed. Setting A Default Text Message You can create a message that will be displayed automatically each time the FILES program is run. This message can contain any instructions or comments that you wish to give each time someone enters the file transfer system. The FILES default message is a text file called FILES.TXT and/or FILES.ANS. It must be located in your user-defined "text" directory. As with BBS text files, you can either provide both a .TXT and an .ANS version of the file, or just the .TXT version, which will be delivered to everyone. The FILES text message is optional; if you don't provide one, no error message will be generated. Loading Filenames Normally, Searchlight enters new filenames and descriptions into its directories as files are uploaded to the system. However, you may have an existing library of files which you wish to include in your BBS directories. Searchlight provides two commands, 2-Sysop/Get and 2- Sysop/Import, which facilitate the loading of existing files from disk and the importing of existing filename/description lists. These commands are described in more detail below. USING THE FILE TRANSFER SYSTEM To use the file transfer system, log in to Searchlight and execute the FILES command from the main menu. You'll see a message indicating that the files system is active, followed by your text message (if you created one), and finally a command prompt similar to Searchlight's main menu prompt. From here, you can execute the FILES system commands, as we'll describe in a moment. If no subboard-specific .DIR file exists for the subboard you're using when you execute FILES, all accessible directories defined in CONFIG are available. If a particular subboard's .DIR file is available, it is loaded, and the message "Loading Subboard Directories" appears, informing you that a special group of file directories, available only from that subboard, is becoming available (please see File Directory Setup on page 54 for information about custom file directory setups). Files System Commands Accessing the FILES system presents you with a new command prompt and a new set of commands. The new prompt works the same way as Searchlight's main 126 Files Subsystem command prompt; it allows you to enter commands by typing the first letter of the command or by scrolling through the commands with the SPACEBAR and BACKSPACE keys, it will list available commands via the "Help" command, and it will display an explanation of each command when the F1 key is pressed. The name and letter of the currently active file directory is displayed to the left of the prompt. To return to the message system, use the "Quit" command. Protocols You can select an upload/download protocol using the Xproto command. Xmodem, CRC Xmodem, and Ymodem protocols are available; in addition, up to 9 external protocols can be selected, as described below. Uploading Use the Upload command to upload files to Searchlight. "Uploading" means to send a file from the remote terminal to the BBS. The remote terminal must support one of the file transfer protocols used on the BBS system. For upload protocols which support only single file uploads, you must enter the exact filename of the file you wish to send. External protocols which have been configured to allow for "batch" uploading will allow you to specify anywhere from zero to 40 filenames and descriptions before uploading begins. If no filenames or descriptions are specified prior to a batch upload, you'll be prompted for a description when the upload completes. Before an upload begins, Searchlight checks available directories to see if any file of the same name already exist on your BBS. If the file is a duplicate, the message File already exists. will appear. For non-batch uploads or for batch uploads where all of the specified files exist, Searchlight will abort the upload at this point. Note that the upload is not aborted when one of several filenames in a batch upload is found. In this case, the uploader should simply not send the duplicate file(s). A properly configured external protocol command should not accept duplicate files in the same directory, but may accept duplicates if the duplicate is in another directory area. Don't attempt to use the Upload command when logged in to the system locally. Instead, you can use the 2-Sysop/Get or 2-Sysop/Import commands to load existing files into your BBS's list of files available for downloading. Downloading Files in the currently active directory can be downloaded, or sent from your BBS to a remote terminal, via the Download command. Don't use Download during a local login. 127 Files Subsystem If a user's download/upload ratio exceeds the maximum value assigned to them, no downloading is allowed until the user has uploaded enough to reduce his or her ratio to within the allowed range ("free" downloads are exempted). Multiple file downloads are allowed for external protocols if the external protocol supports it. To specify multiple files, give one or more filenames or wildcard specifications when inputting the name of the file to be downloaded (use blank spaces to separate filespecs). All files must reside in the same directory. The approximate time for the download is computed before the file transfer begins. If the time to download the file exceeds the amount of time left in the current user's session, the download is not allowed. Directory Listings There are several types of directory listings that can be obtained using the Files and New commands. Wildcard, alphabetical, and date-sorted listings are available. To switch from one download directory to another, use the List command for a list of available directories, and Jump to move between them. File Maintenance Sysops and co-sysops can delete files, move files from one directory to another, rename files, and change the description associated with a file. The commands to execute these functions are Kill, Move, Rename, and Edit. These operations can also be performed by the user who uploaded the file. Password Protection Passwords can be assigned to files on an individual basis using the Passwd command. Once a file is assigned a password, it cannot be downloaded or deleted without giving the password. Even cosysops must know the password of a protected file to download it; only the SYSOP can access the file without using the password. A typical use of passwords would be to allow two users to exchange a file privately. The sender would upload the file and assign a password to it. He or she would then communicate the password to the intended receiver (by sending a private message), who would then use the password to download the file. If more than one user needs to access the file, the sender gives the password to each person who needs to be able to download it. Another way password protection can be used is via the "Default Password for Uploads" field in the CONFIG file. If this field is filled in, each new file that is uploaded to the system is assigned the default password. Thus, newly uploaded files cannot be accessed by the general user population; only the SYSOP, and those who know the default password, can access a new file. Typically, you'd use this option to give yourself the opportunity to 128 Files Subsystem check all new files before they can be downloaded by the users of your BBS. After confirming that the file is OK to download, you would remove the password (by using the Passwd command). A "+" sign appears in the directory listing of a password protected file. This allows you to identify such files easily. File Names The filenames used by Searchlight are in the same eight characters with three character extension format used by DOS. In addition, Searchlight allows the use of wildcards with most commands. You can enter "*" and "?" wildcard characters, and you can enter two or more filenames or wildcard masks by separating each with a space. In general, you do not need to enter the full filename when entering filenames for the Download, View, Move, and other commands. Just enter the first few letters, and Searchlight will pick the correct file, filling in the remainder of the filename right on the screen. File Tagging Searchlight 3.0 includes file tagging, a shortcut method of selecting a list of files for downloading (or other operations) while viewing file listings. File tagging lets you conveniently select files with just one keystroke whenever filenames appear on the screen. File tagging is available with the Files, New and Zippy commands. These commands display files in a new format that includes a one letter "tag" to the left of the filename: A F2DIRM2.ZIP 16k 35 10-24-92 Import 'files.bbs' to Searchlight Faster! No longer needs DIRMAINT! Import from text file lists such as provided by Tick, Flea, and other BBS types. B FARMRAT3.ZIP 38k 23 12-31-92 UP/DWN ratio checking program. Uses DOOR.SYS file and shows up/dwn ratio, security level, ect. C FD-SLBBS.ZIP 4k 3 3-02-93 Batch files for SLBBS and Front Door! D FIAUDIT.ZIP 10k 61 3-29-92 File Area Audit trail program lists file area name & security aspects More... Continue Tag Stop Notice the Tag option available at the "More" prompt; it's used to select any of the files on the current screen. For example, suppose we wanted to select the files F2DIRM2.ZIP and FD-SLBBS.ZIP from the above listing. Simply select "Tag" from the prompt above. Searchlight responds with: 129 Files Subsystem Tag Items: Now simply type the letters A and C -- the "tag" letters associated with the desired files. Searchlight adds those files to an internal list, and continues with the file display. You can tag additional files, and even run other listings and tag more files there. Later, you can download the entire list of tagged files by giving the Download command. Searchlight prompts you with: Select 2 Tagged File(s)? Yes No Edit Enter "Yes", and Searchlight will select the two files tagged earlier and place them into your download list. You can then enter additional filenames, or just press Enter to begin downloading. If you select "No", Searchlight disposes of the previously tagged file list, and allows you to enter new filenames manually. The "Edit" option shown above lets you edit the list of tagged files. A full screen display appears showing the files currently tagged. You can scroll through the list with arrow keys, PgUp and PgDn keys, etc.; press F2 to remove a file from your list. You may wish to use the edit option if you decide against downloading a particular tagged file, or if more files were tagged than may be downloaded given your current file ratio or time limit (see below). You can also edit the tag list at any filename input prompt by typing L and pressing Enter. Regular users can use the tag option to select files for downloading. In addition, Sysops and co-sysops in the file areas can use file tagging with the Kill, Copy and Move commands. Tagging and Ratios The file tag command allows you to select any files that you can view -- including files that may be password protected, located in write-only directories, or that would exceed your download limits. However, the Download command will never allow a user to actually download such files: the entire tag list is always scanned immediately prior to a download, and any files which cannot be downloaded because of the above conditions are removed from the list (the remaining files may be downloaded). To aid users in deciding how many files should be selected for download, Searchlight displays a running total of the number of kilobytes selected, and the number of kilobytes available to download, at the top of each file listing screen (see the example above). The same numbers are also displayed to the left of the prompt that is used for traditional filename inputs when selecting files for download: You may enter up to 40 Filenames. Press F for File List, ? for Help, ENTER when Done: ( 0k Total/ 1540k Avail) : Total Kilobytes is the total number of K selected for download. Available Kilobytes is the total number of K that may be downloaded in the current 130 Files Subsystem session. This number is computed based on the user's file ratio, baud rate, and time left in the current session (note that since time is part of the computation, available kilobytes decreases as time goes on). Although the Tag command while viewing file lists will accept tags on files which might cause total K to exceed available K, when typing filenames in manually, they will be rejected if they cause the total to exceed the available number. Available Kilobytes is also based on the "Free Files" and "File Value" parameters associated with the current directory. Because of this, it is possible that a file in another directory may be selected for download even if its size exceeds the displayed K Available number, since the displayed number is only accurate for the current directory. The tag list can hold up to 40 filenames. The list itself is "global" and remains available in memory until a successful download, kill, move or edit command uses the list. The list is also cleared if a door is executed. Sysop Functions A 2-Sysop command in the Files section gives you additional Sysop commands to load or import filenames from disk, update file sizes, and "balance" the directory tree. These are discussed further in the following pages. 131 Files Subsystem SETTING UP EXTERNAL PROTOCOLS An external protocol is a program which is capable of transferring files to or from a remote system via modem. Typically, such programs are written to be used from the DOS command line or as part of a BBS like Searchlight, where they can provide new transfer protocols such as Ymodem, Batch Ymodem, Kermit, etc. in addition to Searchlight's built-in protocols. To set-up external protocols, run the CONFIG program and access the "Protocol Setup" section. Each of the 15 possible protocol choices has a submenu which looks like this: 1. Protocol Name ................. 2. Protocol Type ................. External 3. Protocol Send Command ......... 4. Protocol Receive Command....... Each protocol consists of a name (which is displayed by the Files system), a type (set this to "External" to install external protocols), a send command, and a receive command. Send and receive commands are the commands normally used to execute the required external program from the DOS command line, including all parameters. You should specify the exact filename and path (including COM, EXE or BAT extension) to the external program. Where a filename is required on the command line, Searchlight provides three special character sequences which are substituted with actual filenames when the command is used. The special characters are: %F ................. Specifies a single filename (for uploads or downloads) %W ................. Specifies one to three filenames (downloads only) @FILENAME ............... Specifies an "indirect" file (download only) You don't have to specify both a send and receive command for each protocol. If a receive command is missing, then the protocol can be used only for sending (downloading) files, and vice-versa. Note that since the directory from which an external protocol is "launched" can change, it is recommended that a full pathname be specified for each protocol (i.e. "C:\BIN\DSZ.COM ..."). Download Commands Download commands should contain either the %F, %W or @FILENAME parameters in the command line where filenames are required by the external protocol. The %F parameter specifies a single filename; %W specifies one to three filenames. Each filename will be passed to the command line in sequence separated by a blank space. Wildcard characters are not passed to the command line, but are expanded to their full filenames. The @FILENAME parameter provides an alternate means of passing filenames to a download command (for use with those programs that support it) and allows multifile transfers of up to 40 files at a time, from any number of 132 Files Subsystem directories. The @FILENAME parameter (where "FILENAME" is any filename, optionally including a drive letter/drive path) writes an indirect text file to disk. The indirect file contains a list of the files requested for download by the user, including full pathnames and drive letters. Many external protocols -- such as DSZ.COM -- can use such a file list instead of command line parameters. All download commands are launched from the Searchlight home directory area; the indirect text file is created in the home directory unless a specific drive/path is specified. Searchlight creates a file called FILELIST.BBS in your home directory during external download procedures. This is a temporary file and need not be backed-up (it will be created again if missing). Upload Commands Searchlight supports single-file or batch uploading (uploading two or more files with one command) in conjunction with external protocols that allow it. Batch uploading is assumed if no filenames (i.e. no %F parameter) is specified on the command line for a given upload protocol. For nonbatch protocols, add the %F parameter where a filename is expected. When performing a batch upload, Searchlight can accept up to 40 filenames and descriptions before the upload begins. After uploading is completed, Searchlight locates the actual file(s) sent, and matches them to the descriptions provided prior to the upload. Should any files lack a description, the system will prompt for one after the upload. A default message of "description not available" is used if no description is provided by the user. Searchlight executes all external upload procedures from a temporary directory called UPLOADS.BBS, which is created as a subdirectory of your BBS home directory if it does not already exist. After each external upload procedure completes, Searchlight checks the UPLOADS.BBS directory to locate all uploaded files, then moves these files to the appropriate files area. (Please note that if an uploaded file already exists in the current directory, Searchlight will delete the duplicate file). The UPLOADS.BBS directory is expected to be empty before uploading begins, so do not store any files in this directory. Searchlight creates a temporary file called UPLIST.BBS during external upload procedures. Upload AutoDoor You can add procedures to Searchlight that process files immediately after uploading by using an Upload AutoDoor. The upload autodoor is a program or batch file you can set up in the CONFIG program (see p.32). Upload autodoors can process newly uploaded files in the UPLOADS.BBS directory before they're registered in Searchlight: you can scan new uploads for viruses, repackage archives, remove unwanted file types, etc. Whatever 133 Files Subsystem files remain in the UPLOADS.BBS area after the autodoor processing is complete are the files actually seen by Searchlight as the new uploads. Since upload autodoor processing takes place while a user is online and waiting, autodoor processing should be brief, or else it should send progress messages to the COM port. Bi-Directional File Transfer Searchlight actually checks the UPLOADS.BBS directory for newly uploaded files after executing either upload or download commands. Thus, Searchlight supports two-way file transfer via such programs as BiModem, as long as all uploaded files are stored in the UPLOADS.BBS directory. To perform such a transfer, configure the protocol driver to direct all uploads to the UPLOADS.BBS directory, then install it as a download protocol via the directions outlined above. Should a remote user choose to upload files when executing a download command, Searchlight will recognize these files upon completion of the download and will prompt the user for descriptions (note that it is not possible to prompt for descriptions prior to the file transfer when using a bidirectional protocol). External Protocol Examples The popular program DSZ (Omen Technology Inc.) can be used to add protocols like Ymodem Batch to Searchlight. With the DSZ.COM executable file installed in the root directory of drive C:, you can use it like this: 1. Protocol Name ................. Ymodem Batch 2. Protocol Send Command ......... c:\dsz.com sb -k @c:tempfile.txt 3. Protocol Receive Command ...... c:\dsz.com restrict z pr1 rb Here we're using DSZ.COM to implement the Ymodem protocol by specifying the "sb -k" and "rb" command line parameters. Filenames are passed via an indirect file called "c:tempfile.txt" (note that the drive letter is required by DSZ in order to recognize an indirect file). Searchlight will allow you to enter up to 40 filenames and will allow filenames from multiple directories to be selected when you use this command. These commands are specific to DSZ; other software will use different commands. In general, any program can be set up to run as a protocol. It is up to you to install programs with the correct parameters for the transfer desired. As a final thought, note that external protocols can do other things besides straight uploading and downloading of files. For example, an external protocol could perform processing, such as extraction of PKZIP files, before performing a file transfer. External protocols gives you a way to interface custom file handling procedures with Searchlight. 134 Files Subsystem SUMMARY OF FILES SYSTEM COMMANDS Here's a printout of the File System's main menu of commands, followed by an explanation of what each command does. ----------------[ Searchlight Files Command Summary ]---------------- Copy ...... Copy File to New Dir Passwd .... Assign/Change Passwords Download .. Download File Quit ...... Return to BBS Edit ...... Edit File Descriptions Rename .... Rename File Files ..... Directory of Files Status .... Ratios & Disk Space Goodbye ... Log Off System Type ...... Read Text Files Jump ...... Jump to Directory Upload .... Upload File Kill ...... Delete File View ...... View Compressed Files List ...... List of Directories WideDir ... Brief File Listing Move ...... Move File to New Dir XProto .... Change Xfer Protocol New ....... New Files by Date Zippy ..... Zippy Dir Scan Owner ..... Show Add'l File Info 2-Sysop ... Sysop Command Menu ------------------[ Press F1 or ? for Online Help ]------------------ Files/Copy The Copy command copies files from one directory to another. The disk file, as well as the file's description, are copied to the new location. Copy is similar to Move, except that Move removes the original file after copying it, whereas Copy does not. You may specify a single filename or multiple filenames with this command. Files/Download The Download command is used to transfer files from the BBS to you. Your computer or terminal must be capable of receiving the file using one of three internally supported transfer protocols (Xmodem, CRC Xmodem, 1K Xmodem) or an externally supplied protocol (use the Xproto command for a list). If no protocol has been previously selected when you give the Download command, you will be prompted for a protocol; otherwise, the protocol used last is used. To begin downloading, enter the name of the file you wish to receive. You need not type the full filename. When Searchlight displays the message "Ready to send", the file transfer is ready to begin. However, before you can receive the file, you must give your terminal the proper command. Usually, this is done by selecting an option to receive files from a menu. Some external protocols allow you to specify multiple filenames and/or wildcard filespecs. The "*" and "?" characters may be used. All files specified must reside in the current directory. A file may be password protected. If you attempt to download such a file, you will be prompted for a password, and the download will proceed only if you provide the correct password. 135 Files Subsystem An auto-logoff feature is supported. If selected, the system will log you off after the download completes, allowing you to leave your computer unattended during the transfer. To get a directory of the files available for downloading, use the Files and New commands. Files/Edit This command allows you to change the one to three line description associated with a file. You can only change a file that you uploaded, unless you have sysop status, in which case you may edit any file's description. Files/Files The Files command displays a listing of files available for downloading. It prompts you to enter the "Starting Filename or Wildcard" of the directory you wish to view. There are three ways to respond to this prompt: Pressing RETURN without typing anything gives you a list of all files in the current directory. The list is in alphabetical order and shows the filename, date uploaded, size in Kilobytes, number of times downloaded, and a description of the file. Typing a filename, or the first few characters of a filename, WITHOUT a wildcard, lists files in alphabetical order starting with the filename entered. For example, if you enter "L", you will get a list beginning with the files that start with the letter L, and continuing to the end. Finally, you may type a wildcard (a filename containing one or more "*" or "?" characters). In this case, only those files that match the wildcard specification are shown. In addition, the prompt "Search all directories (Y/N)?" appears. If "Y" is selected, Searchlight will list all files in all directories that match the wildcard; otherwise, only files in the current directory are listed. A "+" sign displayed in the file listing indicates a password protected file. You can view or download such a file only if you know the password. Notice that Searchlight displays file sizes in terms of Kilobytes rather than bytes. One kilobyte equals 1024 bytes. You may abort any file listing at any time by pressing the or keys. Also, refer to the New command for information about date- sorted file listings. Files/Goodbye Use this command when you are ready to log off, or disconnect, from the BBS. The computer may prompt you to "Please leave us a quote". Type a short 1-line message and press RETURN. 136 Files Subsystem Note that is considered good practice to always log off properly by using the Goodbye command, rather than simply hanging up. However, hanging up will not cause any damage to the system. Files/Jump This command is used to access the various file directories available on the system. Type the name (or partial name) of the directory you want. To see the list of available directories, either type "?" in response to the Jump command's prompt, or use the List command. Files/Kill The Kill command deletes files. If you have Sysop or Co-Sysop access, you may delete any file; otherwise, you can only delete a file if you uploaded it. Kill can take a single filename, or one or more filenames and/or wildcard filespecs. The "*" and "?" characters are supported. SYSOP ONLY: You may delete files from Searchlight's list of files without actually deleting them from the disk. You will be prompted for this option. Files/List The List command gives you a list of available directories. In order to view or download files in a specific directory, you normally make it the current directory; do this by responding to the List command's prompt with the directory name, or by using the Jump command (see Jump). Files/Move Use the Move command to transfer, or move, files from one directory to another. The files are copied into the destination directory and then the original files are deleted. Both Searchlight's entry for the file, and the actual file on disk, are moved to the appropriate directories. Move can take a single filename, or one or more filenames and/or wildcard filespecs. The "*" and "?" characters are supported. Only one destination directory may be entered at a time. Note that the Move command performs a byte-by-byte file copy only when the source and destination are on different drives; otherwise, it performs an efficient file rename without a physical file move. Users with Sysop access can move any file. Otherwise, you can only move your own files (files you have uploaded) into directories to which you have access. 137 Files Subsystem Files/New The New command allows you to get a listing of "new" files since the last time you logged on, or since any specified date. To use the New command, answer the prompt with the desired target date. The date shown in brackets, which is the date you last logged on, is used as the default date if you press RETURN. A second prompt appears, "Scan all directories (Y/N)"- if you enter Y, all directories will be searched for new files, otherwise only the current directory is searched. Dates are entered in either USA (mm/dd/yy) or European (dd/mm/yy) format, depending on your Configuration (see CONFIG menu #2). You can use dashes, slashes, or any nonnumeric separators. If you don't include the year (e.g. "9/21"), it defaults to the current year. The new file listing appears in reverse date-sorted order. It is often useful to run the NEW command with a very early target date, as this gives you a chronological file listing rather than an alphabetical listing as with the FILES command. Files/Owner This command prompts you for a filename and it displays the file's owner (the name of the person who uploaded the file) and the number of times that the file has been downloaded. Files/Passwd The Passwd command lets you assign a password to a file. Once a password is assigned, only users who know the password are able to download the file. You can only assign a password to a file that you have uploaded. If the file already has a password, you can only change it if you can give the old password. Note that the SYSOP can assign an automatic password to all newly uploaded files, thus preventing anyone from downloading a new file until it has been cleared by the sysop. Files/Quit The Quit command returns you to the Searchlight BBS Main Menu. Files/Rename Searchlight's Rename command is similar to its DOS counterpart. It will rename a single file; you must be a SYSOP or the uploader of the file you want to rename. Both the directory entry for the file and the actual file on disk will be renamed. You cannot rename a file if the file resides on a read-only disk. 138 Files Subsystem Files/Status The Status command shows various information, including: the current time and date, time left in the current session, your current download:upload ratio and dl:ul limit, and the amount of free disk space remaining on the current volume. Files/Type The Type command allows you to read a text file. The output will pause every 24 lines and can be controlled with pause (^S) and break (^C) keys, just like when you read messages and other text. Files/Upload The Upload command is used to send files from your computer to the BBS. Your computer or terminal must be capable of sending the file using Xmodem, CRC Xmodem, 1K Xmodem, or one of the supported external protocols. If no protocol has been previously selected when you give the Upload command, you will be prompted for a protocol; otherwise, the previously selected protocol is used. To begin uploading, enter the filename of the file you wish to send. You must enter a legal DOS filename (8 character filename with optional 3 character extension). Do not include drive letters or directory pathnames. Before the file transfer begins, you will be prompted to enter a short and long description of the file to be displayed so that others will know what information the file contains. (Long descriptions are optional and may be 0, 1 to 2 lines in length). If less than 200K of disk space is available, Searchlight will display the amount of space left and ask if you wish to continue. Press "N" if your file is larger than the amount of space available, or "Y" to go on. Searchlight features an auto-logoff option. If this feature is selected, you will be logged off immediately after the upload completes. Thus, you may leave your computer unattended without worrying about terminating your session when the upload is finished. When Searchlight is ready to receive your file, it will display the message "ready to receive". What happens next depends on the terminal software that you use. In most cases, you must give a command to your software that tells it to load the file and begin sending it using the proper protocol. If the SYSOP has assigned a "default" password to the files system, your file will be password protected until it is cleared by the sysop. After a successful upload, Searchlight will increase your time limit for the day according to the amount of time required for the upload, multiplied by the Upload Repay Rate (set by the Sysop on CONFIG menu #2). 139 Files Subsystem Files/View This command displays the internal directory of a compressed file, such as a ZIP or ARJ file. You are prompted for the filename, which may be abbreviated. The directory of the compressed file is displayed in a format similar to that of the "verbose" directory option found in the compression utility programs. Searchlight's View command supports ARC, ZIP, LZH, ARJ, SQZ and GIF file types (for GIF files, Searchlight displays only the file dimentions and color depth). The View command determines the file type by looking at the data in the file, rather than by the filename; therefore, you can view compressed files even if the filename does not have the expected extension. The View command can also be used like the Type command to look at text files. Files/WideDir This command gives you a "wide", four-across file listing which shows only the filename and file size in Kilobytes. It is similar to the DIR/W command in DOS. There is no parameter for WideDir; all files in the current directory are listed. You may abort the listing with ^C. Files/XProto This command lets you change the transfer protocol used for uploading and downloading files. Searchlight supports three internal protocols (Xmodem, CRC Xmodem, and 1K Xmodem); in addition, up to 9 external protocols can be supplied by the Sysop. Once a protocol is selected, it is used by default for all subsequent transfers until you change it again with the XProto command. Files/Zippy The "Zippy Directory Scan" command searches one or more file directories for a specific search string. The search string can be any group of characters, and both filenames and descriptions will be searched. It is not necessary to use wildcard characters with Zippy, and the search is case- insensitive when searching file descriptions. Searchlight's Zippy command is dedicated as a tribute to the folks at PCBoard for creatively allocating the last letter of the alphabet as a command, and to comic artist Bill Griffith for the inspiration provided to this author via his Zippy The Pinhead comic strips. You can abort the search by pressing ^C. 140 Files Subsystem Files/2-Sysop This command allows you to access several subfunctions related to the maintenance of your file system. Only Sysops can access these commands. Get -- The Get command is used to load the names of existing files into Searchlight's directory, without having to upload them. To add files to a directory, first use DOS commands to copy the files to the appropriate disk and directory. When you execute GET, Searchlight reads the disk directory of the active drive and compares the filenames it finds to the filenames in its own internal directory list. When a new file is found, its name is printed and you are prompted to enter a description of the file. If you enter no description, the file is skipped; otherwise, it is added to Searchlight's list of files. To use GET, you must specify a filename or wildcard mask for the file(s) you wish to add. Enter "*.*" to search all the files in the directory. Import -- The Import command is similar to Get, but allows you to load filenames, descriptions, sizes and dates into Searchlight BBS from an external text file list. Import allows you to use generic directory listings, as well as directory listings from many other BBS programs, with Searchlight BBS. See the following section for more information. Update -- This command compares Searchlight's directory with the DOS directory of the current drive. It is used to update the sizes of files which have changed size since they were uploaded or added to the Searchlight directory. Update will place a "*" next to the directory listing of any files which have been deleted from the disk but remain in the system's file list. Balance -- Similar to the "Balance" function on the main program User command, this command reorganizes (and repairs, if necessary) the binary tree structure used to hold the filenames, descriptions, passwords, and other information associated with files. Use this command if you suspect that your "*.SL2" file has been damaged. 141 Files Subsystem IMPORTING FILE LISTS The 2-Sysop/Import menu option in the Files system is a flexible command that allows you to use filename/description lists from other bulletin board software with Searchlight BBS. Unlike most other systems, Searchlight BBS stores filenames and descriptions for its file transfer directories in binary rather than text files. This gives Searchlight the unique ability to maintain both alphabetical and date sorted indexes to its files, as well as file passwords, ownerships, and running download counts. One limitation of binary files is that file listings from other BBS software or generic file listings (such as those provided with CD-ROM systems) cannot be used directly. However, the Import facility converts such listings for use with Searchlight and also allows you to freely edit Searchlight directories by listing to a text file, editing the text file, and importing the results back into the system. The Import command expects to read a text file containing filenames in the following general format: [size] [date] [description] The filenames must begin in column 1, and can be expressed as NAME EXT or NAME.EXT The file sizes can begin in any column, and may appear in bytes or Kbytes: 153506 or 149.9K The date can begin in any column, can be parsed with either "-" or "/" characters, and can appear as "MM/DD/YY" or "MM/YY": 10/91 or 10/23/91 or 10-23-91 The remainder of the line after the date contains the description. If a date is missing, Searchlight substitutes the current system date. Additional fields, such as the "times downloaded" field used in Searchlight file lists, may appear but will be ignored. Any lines which do not conform to the above, such as blank lines or heading lines, will be ignored when the file is processed. Any lines which contain an invalid filename, size, or date will also be skipped. Files can be imported into an existing directory or a new directory. To begin, log into your Searchlight system as the SYSOP, enter the Files section, and Jump to the directory where you'd like to add the files. If you want to create a new directory for the imported files, you should do so in the usual manner before importing. 142 Files Subsystem Enter the 2-Sysop command from the Files menu, and select Import from the menu bar. The Import command will prompt you to enter the name of the text file containing the file names to be read. Next, you'll be prompted: Update Existing Files (Y/N)? If you answer "N", any files found in the import list which already exist in the Searchlight directory will be skipped. If you type "Y", then existing files will be updated with the file size, date, and description found on the import file list. Searchlight will proceed to read the import file list, and will report the number of files added and updated at completion. All newly added files will be assigned an ownership of SYSOP (or the name of whomever executes the Import command) and will have the times downloaded counter set to zero. Tips On Importing For best results when importing large amounts of new files, the import file should be sorted in ascending order by date. If your file list is sorted alphabetically, use the DOS SORT command to sort it by date or size before importing with that file. It is recommended that you run the 2-Sysop/Balance command after an import operation, to ensure that the directory is in an optimal tree sorted structure. Import does not check the file sizes of the files it reads. To do that, execute 2-Sysop/Update after importing. When specifying the name of the import file, Searchlight will be looking for that file in the DOS directory containing the files for the currently active file area. If your import file is in another directory, you can specify the drive letter and/or path. The Import command can read files created with Searchlight's SLDIR utility. You can use SLDIR to create a text file listing of your directory, then edit file descriptions, sizes, or dates with a word processor, and load the changes back into Searchlight by specifying "Update Existing Files" when you import the list. There is no need to remove the headings or blank lines from the SLDIR list, as these will be ignored when the file is imported. Importing works on the current directory only. If you want to import files from a large list into several directories, you'll need to split your list into several smaller lists and import each one into the appropriate file area. 143 Menu Editor SEARCHLIGHT MENU EDITOR Searchlight uses an externally stored menu system that directs the flow of commands, and forms most of the menus you and your callers will see when using the software. Because menus are stored externally in files, and because Searchlight's internal command structures include command-line style options, you have a tremendous amount of flexibility to decide how your system will look and work. With Searchlight and its companion menu editor software, you'll be able to: o Rename, rearrange, eliminate, or regulate by access level and attributes, any command on the default menus provided. Even translate commands (including the command names and their associated "hot key") into other languages. o Create new commands on any menu. Your commands can be internal Searchlight functions (like List Subboards or Read Messages), external DOOR programs, or other menus. o Create commands that do something different, depending on the access level, attributes, and/or help level of the user who selects the command. o You can even execute a list of commands (both internal commands and DOORS), creating commands that can perform complex sequences of events. USING THE MENU EDITOR The core of Searchlight's menu system is a series of menu (*.MNU) files located in a directory on your hard drive. The menu editor function (part of the CONFIG program) can be used to examine and alter existing menu files or to create new ones from scratch. Note that it is not necessary to use the menu editor to use Searchlight; the default menus provided with the system can be used as-is. You need to use the menu editor only if you want to alter, or add to, the stock menus. All of the command descriptions and examples in this manual assume you are using the default menus provided with Searchlight. If you change menus using the menu editor, you should be aware that the exact menu choices and keystrokes described in this manual may no longer be accurate for your system. However, commands themselves will operate the same. Starting The Menu Editor To start the menu editor, run CONFIG and select item E, "Searchlight Menu Editor". You can also type from the DOS prompt: CONFIG E 145 Menu Editor The menu editor starts up by displaying a list of available menus. The first time you run the menu editor, you will see a list of menus similar to this one: FILES 23 Searchlight Files System FSYSOP 6 Sysop Command Menu MAIL 8 Electronic Mail MAIN 25 Searchlight BBS Main Menu MEMBER 6 Subbd Member List/Options NEW 5 New Message Scans OPTIONS 5 Your Options & Stats SCAN 5 Quick Scan Messages STARTUP 7 SLBBS Startup Menu SYSMAIL 8 Electronic Mail/Sysop Access SYSOP 8 Sysop Options Menu SYSOPT 5 Sysop Options/Stats Access USER 7 User Lists & Information These are the default menus provided with Searchlight BBS. As you add your own menus, those choices will also appear. From the menu editor's main screen, you can select a menu for editing by placing the cursor on the desired menu and pressing Enter, or by double- clicking the menu name with your mouse. You can add menus by pressing F1 and delete menus with F2. If the list of menus is longer than one screen, you can scroll with PgUp/PgDn keys, arrow keys, or by using the mouse to click on the screen messages. The menu editor always uses the "Menu Directory" that's specified in the CONFIG file for the node in which you are working, and all menus are searched for (or created in) that directory. If you need to change the default menu directory, you can do so by accessing the Pathnames Setup portion of the CONFIG program prior to running the menu editor software. COMPONENTS OF A MENU Each menu file consists of two distinct parts: a "header" part which contains information about the menu as a whole, and a body part, which consists of a list of commands on the menu. Every menu has one header and menus may have up to 64 commands. There are three basic menu types, and several options that control how a particular menu is displayed. A Word style menu is the kind of menu that makes up Searchlight's default main menu and files menu. That is, it consists of a series of one word commands, which can be selected by pressing the spacebar or backspace key or the first letter of the command, and then pressing Enter. A list of all the commands on this type of menu can be displayed, typically by selecting a "Help" command; the listing can be generated by Searchlight or displayed from and external file. Character style menus are similar to Word menus, except that no scrolling list of options is displayed. Users select commands by pressing 1 key, and 146 Menu Editor the command is immediately executed. With this type of menu you'll normally want to display a list of the menu's commands every time that menu is used, although the exact behavior is up to you. MenuBar menus are the typical "Lotus 1-2-3" style menus found in areas such as the Mail or User command submenus. With MenuBars, the commands are always displayed, and must fit on a single line (typically there are between three and eight selections on any MenuBar style menu). COMMANDS Every menu contains a series of one or more commands. Commands consist of several components: a one to fifteen character command name, a "hotkey" that selects the command, a description of what the command does, access level/attribute information, and specific actions that Searchlight will take when executing that command. There are three basic command types: Internal commands execute a function that's built into Searchlight BBS; Door commands run external programs; and Menu commands transfer control to other menus. Menus can contain up to 64 commands. Not every command on every menu need be available to every person who uses the menu. Access level and attribute restrictions allow you to design commands that only certain groups of people can use -- you can even have two or more commands with the same name that perform different operations, provided that you arrange it so that only one is available to any particular user. You can also place commands in any order on the menu that you choose. Word, Character and MenuBar type menus all contain the same types of commands. The only difference is in how the menu is presented and how the command is selected. MENU HEADER The first screen that's displayed when editing a menu is its header information. Menu headers consist of 13 fields, as shown in this example: 1. Title ......................... Searchlight BBS Main Menu 2. Clear Screen? ................. No 3. Display Title? ................ Yes 4. Display Filename .............. 5. Display Menu (Novice) ......... Yes 6. Display Menu (Intermed) ....... No 7. Display Menu (Expert) ......... Yes 8. Prompt Type (Novice) .......... Word 9. Prompt Type (Intermed) ........ Word 10. Prompt Type (Expert) .......... Word 11. Prompt String 1 ............... \ye[\cy\sb\ye] \noCommand: 12. Prompt String 2 ............... 13. Prompt String 3 ............... 14. Use RIP Mouse Areas ........... Yes 147 Menu Editor Here's a description of each field: 1 -- Title The title field contains a title, or description, for the menu as a whole. For MenuBar type menus, this title is displayed before the menu is generated when field 3 is set to "Yes"; for Word and Character style menus, it's displayed whenever the menu is printed, unless and external file is used for menu display. 2 -- Clear Screen? 3 -- Display Title? These fields determine whether Searchlight will clear the screen, and display the menu title, before displaying a menu. With MenuBar menus, this is every time the menu is called; for Word and Character type menus, whenever a display of the menu is requested. 4 -- Display Filename (Optional) This is an optional field. For Word and Character style menus, this field allows you to name a file that will be displayed in place of the default menu generated by Searchlight. This file can be any text, ANSI or RIP file contained in your system "Text" directory. Notice that omitting the file extension causes Searchlight to select between ".TXT", ".ANS" and ".RIP" files as appropriate -- .TXT for a pure text file, .ANS for an ANSI graphics file, and .RIP for RIP graphics images. For MenuBar type menus, this file does not replace the default display, but contains a message that's displayed before the default menu is generated. 5 -- Display Menu (Novice) 6 -- Display Menu (Intermediate) 7 -- Display Menu (Expert) These three fields determine, for users with the three possible help level settings, whether or not a listing of all the commands on a Word or Character type menu is generated each time the menu is entered (or re- entered after executing a command). These fields have no effect on MenuBar menus. 8 -- Prompt Type (Novice) 9 -- Prompt Type (Intermediate) 10 -- Prompt Type (Expert) These fields determine the type of menu, Word, Character or MenuBar, that's generated from this menu file. It's possible to have one menu appear in several different ways, depending on the user's selected help level: although in most cases, you will design a menu to be displayed one 148 Menu Editor particular way, and thus will set all three of these fields to the same value. MenuBar style menus may not contain more choices than will fit in one screen line (80 characters). It is up to you to assure that menus will fit on a single line before selecting this type of menu. 11 thru 13 -- Prompt Strings These three fields provide you with one to three lines to create a prompt. A prompt is short text that appears right before the cursor pauses to accept keyboard input for the menu selection. For example, on the default main menu, the prompt string consists of the current subboard name in brackets, followed by the word "Command:". Notice that Searchlight color codes and macros are available for use in the prompt strings. "\sb" is an example of one of a macro code; it displays the name of the current message subboard or file directory. A complete listing of these sequences appears earlier in this manual (see p. 121). 14 -- Use RIP Mouse Areas Since Searchlight provides its own mouse support with built in menubar menus, and may support other RIP features internally, this command is included in the menu setup screen to disable Searchlight from producing mouse areas for its internal menus. Set this option to "No" if you are using RIPscrip files to generate your own menus with mouse areas. Otherwise, leave it set to "Yes". The "No" setting prevents Searchlight from interfering with mouse areas that may have been created by your external file. EDITING COMMANDS Once you have entered or changed the header information for a particular menu, you can move on and examine or create the commands for that menu. To access the command editor, press F1 from the header editing screen. Your screen will now show a list of the menu's commands, like this: Edit Add Delete Copy Move Exit Kill K Delete Messages INTERNAL 104 List L Subboard List INTERNAL 102 Mail M Electronic Mail MENU MAIL New N New Message Scan MENU NEW Command, Key, Description and Type are some of the parameters that are associated with commands. For now, we'll ignore the meaning of these fields 149 Menu Editor and concentrate on using the command editor's functions to manipulate the command list; individual command options will be discussed shortly. Command Editor To use the command editor, you select a command by positioning the cursor to the left of the command name. Use the up and down arrow keys to move the cursor; on menus where the number of commands exceeds the screen size, you may use PgUp and PgDn to view additional commands. You can also go directly to a command by pressing the first letter of its name (when there is more than one command with the same first letter, continue pressing that letter until you arrive at the desired location), or by using the mouse. Note that all menu editing takes place in RAM only. The actual menu file on disk is not updated until you exit the menu editor and save the file. Therefore, should you make a mistake when editing any part of a menu, and wish to go back to the original, simply exit the menu editor and choose NOT to save that menu back to disk. Editing Existing Commands To edit a command, simply press once the cursor is located on that command. You will be presented with the Edit Command screen, which is discussed shortly. You can also click twice on a command with your mouse to edit it. Adding Commands Press F1 to add a new command. You'll be asked to select the type of command you want to create, and then the Edit Command screen will appear, allowing you to enter the specifics for the command. When you add a command, it's added into the menu directly before the current cursor position. Therefore, you'll want to position the cursor to the desired location before pressing F1. To add a command to the end of the menu, place the cursor 1 line past the last command. Deleting Commands F2 is the delete command key. Press it to remove the currently selected item. The menu editor confirms the deletion with a Yes/No prompt. Copy Command The F3 key performs a copy function. It lets you create a new command by duplicating an existing command. This is useful when you want to create several commands that are similar, as it saves you from re-entering the elements that are common to each command. 150 Menu Editor To copy a command, place the cursor on the existing command and press F3. Then, move the cursor to the place where you'd like the new command inserted, and press . As with the F1 key, the new command is inserted before the cursor position. You can now press once more to edit the new command's parameters. Move Command Use the F4 key to move an existing command to a new position in the menu. Begin by placing the cursor on the desired command; then press F4. Now, move the cursor to the location where you'd like that command to be moved, and press . The command is moved, and the screen is redrawn to show its new location. Press the key when you are done editing commands. 151 Menu Editor EDIT COMMAND SCREEN Whenever you edit a command or insert a new command, the Edit Command screen appears, allowing you to enter specific information about the command. This screen consists of two parts. The first nine lines of the Edit Command screen are the same for any command. The remaining lines vary according to the type of command (Internal, Door, or Menu) that's being edited. For existing commands, the correct screen is selected based on the type of command. When entering new commands, a prompt appears allowing you to select the desired type: Select Command Type: Internal Door Menu Quit The first part of the Edit Command screen looks like this: Press F1 to Change Command Type 1. Command Name .................. Bulletin 2. Command Key ................... B 3. Description ................... System Bulletins 4. Minimum Access Level .......... 0 5. Maximum Access Level .......... 255 6. Required Attributes ........... 7. Exclude Attributes ............ 8. Require Preference Attrib ..... 9. Exclude Preference Attrib ..... 10. Help Levels ................... All The first three options on this menu control what the command will look like when it appears on a menu. The last six items control which users can access the command. Here's a line by line breakdown: 1 -- Command Name This is a short name for the command, of between one and 15 characters. This is the name that's displayed by Searchlight's default menu listing (for Word or Character style menus) or in the menubar for MenuBar type menus. If you use an external file to replace the default display for a Command or Character menu, then this name is not displayed, and is unimportant. 2 -- Command Key The most important attribute of a command is the key that needs to be pressed in order to trigger it. In almost all cases, this character is the first letter of the command name itself. However, it may be any other character (it is recommended that you use a character which appears somewhere in the name of the command, however). You may wish to use something other than the first character of the command name in order to 152 Menu Editor resolve the problem of having two commands on a menu which start with the same letter. Searchlight always highlights the appropriate letter when drawing a menu display or menubar. Notice that the menu editor does not check to see if you enter two or more commands with the same command key. In fact, this is not only possible but it's something you'll want to do often -- as long as you insure, through the use of options 4 through 9, that two such commands are never available to the same user. 3 -- Description The command's description is used on the Searchlight generated main menu display (for Character or Word type menus) and in the help field below the cursor, when selected, in Menubar and Word menus. CONTROLLING COMMAND AVAILABILITY Searchlight contains a rich set of configuration parameters that control which commands are available to a user whenever a menu is loaded or executed. Not only can certain commands be regulated by minimum access level and attributes, but you can omit low-access level commands from a menu when an experienced user logs on. In fact, you can even make the same command perform different actions depending on the user that executes the command. How is this done? Simply by having two or more commands with the same name, and same command key. Through proper configuration of access levels and other parameters, you set it up so that only one of the identically-named commands is available to any particular user. In exploiting these options, you may create menus which contain more commands than will ever actually appear at one time, and menus where the same command name and key appears more than once. That's not only OK, but recommended -- it lets you build very powerful menu systems. 4 -- Minimum Access Level 5 -- Maximum Access Level These two fields work to regulate which users "see" this command when the menu is displayed on screen. If a user has an access level between the two values, and meets the other requirements in lines 6-9, then this command is made available. Otherwise, it is not displayed, nor can it be executed in any way. 6 -- Required Attributes This line gives the required attributes necessary for this command to be executed. Similar to the way subboards and file areas use attributes, if a particular user has the attributes listed here, then the command is available; otherwise, it's omitted from the menu and can't be executed. 153 Menu Editor 7 -- Exclude Attributes This field specifies a set of attributes which -- if the user satisfies the condition of having all of the attributes specified -- causes the command to be omitted from the menu. Typically, this line is used the way the Maximum Access Level line might be used: to omit commands from a menu: not because a user does not have the privilege of using that function, but because the command is designed for someone with a lesser overall access level. For example, a command to request validation instructions might be omitted if the user is already validated, as determined by examining their attributes. 8 -- Require Preference Attrib 9 -- Exclude Preference Attrib These fields modify command access by user preference attributes. Preference attributes are a group of 24 flags that users can set to choose between two or more possible ways that your BBS will look or work. Preference attributes are like the security attributes that you assign to your users' accounts, except that a preference attribute is something that users themselves can set or clear using the OPTIONS command on Searchlight's main menu. Whereas security attributes are something you use to grant or deny access to particular areas of your BBS, preference attributes enable the user to select between two or more alternatives, all of which are equally accessible. Like security attributes, you can set up menus so that particular preference attributes are required for the command to appear, or you can set it up so that particular attributes exclude that command from being available. 10 -- Help Levels This field controls whether or not the command appears on the menu based on the help level of the current user. The default is "All", meaning that the command is available to all help levels (Novice, Intermediate, and Expert). By changing the value of this field, you can limit the command to only one or two of those help levels. As an additional note on the issue of command regulation, it should be stated again that ALL of the requirements presented in fields 4 through 9 must be satisfied before a particular command will appear on a menu. If a user fails to meet any of these requirements when the menu is loaded, then that command is omitted. The default values for these fields when entering a new command (and for most of the commands in the standard menus) is either blank, or the minimum or maximum value of the field, meaning that the command is available to everyone. Typically, only one or two of these fields are used at any one 154 Menu Editor time, although more sophisticated menu systems may of course take advantage of all of them. 155 Menu Editor INTERNAL COMMANDS Now that we've discussed how to specify command names and regulate who can use a command, let's get down to the business of discussing what commands do, and how to specify those actions on the menus. The three basic kinds of commands are Internal commands, Doors, and Menus. When you create a new command, you are prompted to select a command type. When you edit an existing command, the command type is automatically selected. Fields 10 and up on the Edit Command screen vary depending on what type of command you're looking at. For internal commands, you'll see these fields: 10. Command Number (1) ............ 11. Command Parameters (1) ........ ... 16. Command Number (4) ............ 17. Command Parameters (4) ........ Command Number is the number of a built in Searchlight function. Whenever someone selects this command choice off of a menu, what's actually executed is the internal function associated with the function number indicated here. For example, the function to read messages is function number 100; any internal command which specifies "100" in the Command Number field will cause the "read message" function to execute. This is true regardless of the name or key associated with the command. Command Parameters is an optional alphanumeric field that can be used to supply parameters to certain internal functions. Command parameters typically consist of either short strings of characters (such as a subboard name) or option flags, specified as a slash or dash followed by a letter, much as you would specify parameters for a command line program from the DOS prompt. For example, the parameter "/X" can be used with any internal function number to suppress that function from clearing the screen, and displaying its description, before it executes. A complete list of the internal function numbers and the parameters associated with them appears in Appendix G, Internal Command Reference. Internal commands let you specify up to four pairs of command numbers and parameters (fields with zero do nothing). When several functions are specified, they execute at once, in the order given, each time that command is selected. Therefore, it's possible for a single command that appears on a Searchlight menu to actually execute two, three, or four built in functions. (It's also possible to execute more functions than this, including external functions, by executing menus -- we'll describe that process shortly). 156 Menu Editor EXTERNAL (DOOR) COMMANDS The second major category of command that can be included on a menu is a DOOR command. This type of command, when selected from a menu, executes an external program, such as a database program, a utility like CONFIG.EXE, a BBS game, or other program. When the command is a door, these fields appear in the Edit Command menu: 10. Door Command .................. c:\command.com 11. Directory Path ................ . 12. Communications Support ........ Standard 13. Abort Method .................. Reboot 14. Write Protection .............. No 15. Parameter File ................ None The example above shows a typical "Shell To DOS" command that might be included on a Sysop function menu. For more information about the above parameters, please see the Doors Subsystem section of this manual. After a door is finished executing, control returns to the menu from which the door was selected; thus, doors can be integrated into any menu in a seamless manner. MENU COMMANDS The third type of command that you can place on a Searchlight menu is a Menu command -- basically, a link that starts up and displays a new menu. Menu commands are quite powerful, since you can use them to connect dozens, even hundreds, of menus together to form a comprehensive user interface. The options that appear for Menu commands are: 10. Menu Name ..................... MAIL 11. Execution Method .............. Display Menu Name is the eight-character filename of the new menu that you wish to load when this command is selected. Provide the menu name exactly as it appears in the menu editor. Note that the named menu must exist in your specified menu directory when the attempt is made to load it. Otherwise, Searchlight will exit with an error message. Therefore, it is recommended to test all menu commands at least once before placing your system online. Execution Method tells Searchlight what to do with the menu specified in line 10. The usual function is called Display, and it does what you might expect: displays the new menu, and allows the user to select a choice from that menu. 157 Menu Editor The other option available here is called Execute, and it's one of the most powerful aspects of the entire Searchlight menu system. When you Execute a menu, Searchlight does not display the menu and solicit a choice from the user. Instead, it automatically executes every command on that menu in sequence. By setting up menus for execution, you have the capability of running long sequences of commands one after the other: those sequences can include internal functions, DOOR functions, and even other menus. Menu execution can be used anytime you want to string a series of commands together. As a typical example, the first thing Searchlight does after a user logs in is it executes a special menu called "STARTUP". This menu contains a series of commands that tells Searchlight to perform its usual log-in sequence: display the bulletins, check for new mail, etc. Since that command sequence is a menu, it's completely modifiable. CHANGING COMMAND TYPES You can change the command type of an existing command by pressing F1 while on the Edit Command screen. You'll be prompted to pick a new command type from the command type menu (Internal, Door or Menu). You can abort the change and retain the current command type by selecting the current type (highlighted on the menubar) or by selecting "Quit". Be aware that all command parameters specific to a particular type of command (that is, all items on the Edit Command screen after line 9) are cleared if you change the command type. Changing the command back to its original type will not restore the original information. Therefore, be sure you want to change the command type before doing so, and save a backup of the menu file (or a printout of the Edit Command screen) if you wish to have a record of the previous settings. More information about menu execution, and menu setup in general, is provided in the following section. 158 Menu Editor GUIDE TO MENU SETUP In the previous sections, we described how you can create and edit menus using Searchlight's menu editor. Here, we'll talk more about what you need to know to actually create working menu systems, along with tips and pitfalls to watch out for. Standard Menu Names There are only two menu names that are hard-coded into Searchlight BBS, and therefore required for it to operate. Those names are STARTUP and MAIN. STARTUP is the name of the menu that's executed as soon as Searchlight completes the process of logging in a user, and transfers control to the BBS.EXE program module. The STARTUP menu is executed, not displayed; that means the commands it contains are run one after another. In the standard menus that are supplied with Searchlight, the last command in the STARTUP menu is a command to load the MAIN menu. Something to notice about the STARTUP menu: since it's always executed rather than displayed, the names of the commands in it don't matter too much, except perhaps as comments you can refer to when examining the menu. MAIN is typically the name of the menu called by STARTUP, although it doesn't need to be. The only time that a MAIN menu must be available is if you exit Searchlight by pressing ALT-X and wish to resume your current session by restarting the program from the command line. When you press ALT-X Searchlight loses track of the name of whatever menu you were using, and any previous menus that were loaded; therefore it resorts to loading the MAIN menu. If you use ALT-X often, you'll want to make sure that the primary menu file on your system is MAIN, to avoid confusion. Menu Levels Whenever one menu contains a command that calls for another menu to be executed or displayed, Searchlight keeps track of the name of the previous menu. This allows any menu to contain an "Exit to previous menu" command (internal command number 1). The level to which menus can be "stacked" in this manner is 40. That means that if 40 menus are loaded before any menu tries to exit back to a previous menu, Searchlight will not be able to keep track of any further menu levels. The limit of 40 includes menus from both the main system and the files system. Because of this behavior, you should always construct menu systems in hierarchical fashion; that is, in a way so that menus "exit back" to previous menus. Do not make two menus that both contain commands to load each other -- or any possible way for a circular path to be created where the same menus are loaded one on top of the other. Doing that will result in unpredictable behavior once the internal menu stack overflows. 159 Menu Editor Executable Menus When all the commands on an executable menu finish, control returns to the previous menu (i.e. the menu which called the executable menu). Should the STARTUP menu be allowed to finish (if a "Quit" command is placed on the main menu, for example) Searchlight will hang up and recycle back to the Login program. This may be used to provide a "quick logoff" function, if desired. Files System Commands In previous versions of Searchlight BBS, the file oriented commands were distributed as a separate executable program, FILES.EXE. One of the limitations of that design was the fact that an explicit command (internal command 153) was needed to load the files program, and only files system commands -- those with command numbers 300 and above -- could be used on file menus. For example, in Searchlight 2.25, it was impossible to put a Download command on the same line as a command to send mail to the Sysop. Searchlight 3.0 combines file commands and main commands into one program, eliminating this limitation. If you used previous versions of Searchlight, you may notice that there is no longer a FILES.EXE program distributed with Searchlight 3.0; instead, all files functions are contained in the main program, BBS.EXE. As a result, menus in Searchlight 3.0 can contain any internal commands. File commands, like the commands to list directories, download files, etc. may be freely placed on any menu wherever they are desired. No special command is needed to start the files program before executing a files command, and no special command is needed to exit the files program. However, Searchlight 3.0 still supports the old command sequences -- command 153 to enter the files area, and command 330 to exit the files area. Instead of loading a new program, Searchlight 3.0 emulates the actions of the old FILES.EXE program. Therefore, all existing menus are compatible with Searchlight 2.25, and no changes to your menus are required unless you want to take advantage of the new capability to have files and regular commands on the same menu. If you do decide to create combined menus, a few notes are in order: o Searchlight's internal command 153 performs a few special actions: it checks to see if a custom directory list for the current subboard exists, and loads it if available. It also changes the area name that appears at the top-right hand corner of the screen to the current directory name, and tells the menu display programs to search for help files ending in ".FH" instead of ".MH" if help is requested. If you load a files-oriented menu directly, without executing command 153, the commands will still work, but you should be aware that the above actions will not take place. (You can load subboard lists yourself using the new internal command 201, outlined below). 160 Menu Editor o Should you execute an internal command 153 which loads a particular *.DIR file with a list of available directories for the current subboard, be aware that this directory list remains in memory as the list of available directories until another 153 command is executed. This is important if you use internal command 153 in some places but not in others. o Command 330 (return from files area) performs the following actions in Searchlight 3.0: it changes the help file suffix back to ".MH", sets the on screen area name back to the current subboard name, and returns to the menu where the previous command 153 was executed. Use this command only if you used command 153 to enter a files menu (otherwise, just return to the previous menu with internal command number 1). 161 Doors Subsystem SEARCHLIGHT BBS DOORS SUBSYSTEM Introduction The Searchlight BBS DOORS system provides a method for linking external programs to your BBS. You can add additional features and capabilities to your system, such as games, user polls, sysop utilities, etc. DOORS can be programs provided by Searchlight Software, programs you write yourself, or programs written by others. In addition, many general purpose DOS programs and utilities can be used as DOORS. Most popular bulletin board systems provide only a means of executing a subprocess as the DOORS mechanism. This has led to a plethora of external programs, drivers, and other methods of directing a Door program's input and output to the COM port for use by a remote caller. By contrast, Searchlight BBS fully supports the COM port during Door operation; you can use almost any program directly as a door, without having to alter the program, load a serial port driver, or use a BATCH file. Even programs which use full-screen cursor manipulation, color, IBM type character graphics, and simple sound effects will work, as long as these programs use either the BIOS or DOS for their input and output. In addition, the Searchlight DOORS system monitors and handles loss of carrier; optionally write-protects disk drives while the Door is active; and consumes less than 50K of memory above DOS, freeing the rest of your RAM for use by the Door software. We've also included features that help make Searchlight compatible with many of the Door programs already written for other BBS systems. Searchlight's COM port support can be fully disabled, allowing you to run programs which provide their own COM support, and Searchlight will optionally generate a configuration file (normally called PCBOARD.SYS) which is compatible with the configuration file created by the PCBoard(tm) bulletin board system when running a Door. If you use an ANSI.SYS replacement which bypasses the BIOS level of I/O, you may be unable to run DOS shells and other programs that output through DOS on your system. We recommend switching back to the original DOS ANSI.SYS driver when running Doors with Searchlight. SETTING UP DOORS Doors are usually installed by adding a command to one of Searchlight's existing menus, or by creating a new menu. See the previous chapter on menu editing for more details about the process of editing menus and entering new commands. Searchlight BBS also supports an "old" style DOORS menu, created via a text file called DOORS.DEF. We no longer recommend using this method of DOORS setup, since menu entry is far easier and more flexible; however, if you wish to review the process, documentation for the old DOORS.DEF style setup file is available on your distribution disk. 163 Doors Subsystem If you are new to DOORS and Searchlight BBS, we suggest the following steps to create a menu in which to place your first DOOR programs: o Run the Menu Editor program (see previous section). Access the MAIN menu, and delete the "Doors" command that resides there. o Press F1 to create a new command. Make this command "Doors" (same name as the previous command) but have it be a Menu type command. Enter "DOORS" as the name of the menu to display. o Save the MAIN menu, then create a new menu called "DOORS". Enter your desired Door commands as entries in this menu. Finally, execute them by selecting the "Doors" command from Searchlight's main menu. You can, of course, add Door programs to existing menus or create other menu structures. The above is just a suggestion to get you started. DOOR PARAMETERS When you are editing a menu and you reach the place where you need to enter the commands for a particular Door program, you'll see this screen: 10. Door Command .................. c:\command.com 11. Directory Path ................ . 12. Communications Support ........ Standard 13. Abort Method .................. Reboot 14. Write Protection .............. No 15. Parameter File ................ None 10 -- Door Command This is the name of the program that will be run. It should look exactly like the command line you'd normally type when starting the program from DOS, including any parameters, with one exception: if the program is a COM or EXE file, you should specify the .COM or .EXE extension in the program's name (for example, use COMMAND.COM instead of just COMMAND). If you don't specify an extension of .COM or .EXE, Searchlight assumes the program you wish to run is a batch (.BAT) file or a DOS command such as DIR, TYPE, etc. In this case, Searchlight will first load a copy of COMMAND.COM, and then execute the command. If the command is really a COM or EXE file and you don't say so, it will still run, but you'll have an extra copy of COMMAND.COM in memory that doesn't need to be there. If COMMAND.COM must be loaded, Searchlight will try to find it by examining the environment table for the line "COMSPEC=". Failing to find this, it will attempt to load COMMAND.COM from the current directory. If COMMAND.COM (or the DOOR program itself) cannot be found, the door won't be executed and control will return to Searchlight BBS. 164 Doors Subsystem 11 -- Directory Path This is the drive/directory specification for the directory that will be made the "current" directory before the program is run. Since many programs require data files that reside in the current directory when they are run, you can specify the directory to switch to before the program is executed. Searchlight automatically switches back to its own directory when the door "closes". If you do not need to change directories when running an external program, or you wish to use the current directory, type a single period (".") as the directory name. 12 -- Communications Support Values for this field are Standard, None, and Force-Color. "None" specifies that no modem i/o support will be provided for this program; the program is expected to interface with the serial port itself. "Standard" indicates that the program does not contain serial i/o support, and serial support will be provided by Searchlight. Use "Standard" with most programs. "None" can be used with programs that use the serial port themselves, such as door programs written for use with other BBS systems which do not provide serial i/o support. Usually, "None" programs will require parameters to tell them which serial port and baud rate to use; they may read this information in the doors system configuration file, Searchlight CONFIG file, or via explicit command line parameters. The "Force-Color" switch is provided to allow Searchlight to correctly handle Door programs using color on a monochrome system. Normally, Doors determines whether you are using a color or monochrome CRT on your system, and interprets the door program's request to change screen attributes accordingly. However, with some programs, notably games written in BASIC, you will want to use color regardless of the fact that the local CRT is monochrome. Specifying "Force-Color" allows you to do this. 13 -- Abort Method This field specifies the action to be taken if the Doors system detects a carrier signal loss (i.e. if the user hangs up the telephone) during the operation of a door. If set to "None", the carrier is not monitored, and no action is taken. If set to "Terminate", the door system will attempt to terminate the running program via the DOS terminate procedure. If set to "Reboot", the doors system will reboot the computer when a carrier loss occurs. "None" should only be used with programs that do their own carrier loss checking, or with programs that must not be interrupted during processing. "Terminate" is the standard abort method; it will work with programs that abort normally through the DOS TERMINATE process. "Terminate" is the preferred way to abort a program. 165 Doors Subsystem Some programs, notably COMMAND.COM, will not abort via the standard DOS call, because they replace the return vector with a pointer back to their own code. Many games and other ill-behaved programs fall under this category. If a program will not return to the BBS via the TERMINATE call, an alternative is to set abort type to "Reboot", which will initiate a warm boot of the computer if a carrier loss is detected during the operation of the door program. If you use this method of abort, you must include in your AUTOEXEC.BAT file the commands necessary to start up Searchlight after the system boots itself up. Since it will be an unattended bootup, you must eliminate any programs from your AUTOEXEC that prompt you for input when they run. If you use a multitasker, such as DESQview or Windows, the reboot and terminate options may not operate correctly on your system. Try them before allowing callers to access your doors. Using "Reboot" is not recommended for multiuser systems, since it can interrupt other sessions in progress. It's also not recommended if you employ a write-buffered disk cache. 14 -- Write Protection This field determines whether the disk drives will be write protected during the execution of the door. If set to No, write protection is not in effect, and all disk i/o proceeds as usual. If set to Yes, software write protect is enabled on all disk drives. No disk writes will be allowed while this door is running. Write protection is useful when you wish to run a program that allows users to specify filenames to which data will be written. For example, a game program might have a "save game" option that asks the user to enter the name of the file to hold the saved game. If the user were to type the name of an existing file, he or she could easily destroy important data on your disk. The software write protect guards against this. Any attempt to write to a disk while write protect is in effect will result in the standard DOS "Write protect error writing drive" message. 15 -- Parameter File Searchlight 3.0 supports four kinds of parameter files (also known as "drop files") when launching a door program: PCBOARD.SYS version 12 and 14, DOOR.SYS, and DORINFOx.DEF. Parameter files are special files created by Searchlight just before executing a door program; they contain information that the door can read to find out the name of the person running the door, the current communications parameters, time limits and access levels, and many other items. Depending on what kind of file a particular door program expects, you can choose to create a DOOR.SYS file, DORINFOx.DEF file, or PCBOARD.SYS file when running a door by toggling the "Parameter File" field to the appropriate value. When DOOR.SYS is selected, Searchlight creates a text file called "DOOR.SYS" in the home directory of the current node. DOOR.SYS contains standard information about the current user and current status of the BBS. 166 Doors Subsystem If DORINFOx.DEF is selected, Searchlight creates a file called "DORINFOx.DEF", where "x" a the node number from 1 to 9. If the current node number is between 1 and 9, Searchlight writes the DORINFOx.DEF file to the node where the door is launched from, rather than from the SLBBS home directory. For node numbers greater than 9, Searchlight creates a file called "DORINFO1.DEF" in the node's home directory. When setting up door programs that use DOOR.SYS or DORINFOx.DEF, be sure to configure the program so that it looks for the drop file in the appropriate directory, as outlined above. Door programs have many different means of configuration; be sure to read each door program's documentation thoroughly before attempting to install it in Searchlight BBS. PCBOARD.SYS Files For backward compatibility, Searchlight 3.0 will still use the "Door Parameters Filename" in the CONFIG file as the target filename when creating a PCBOARD.SYS file. However, for convenience and for the sake of consistency with the new DOOR.SYS and DORINFOx.DEF options, Searchlight will simply create a file named "PCBOARD.SYS" in the home directory if the "Door Parameters Filename" is left blank. Unless you have a need to place the PCBOARD.SYS file in a particular directory or a need to have it named something other than PCBOARD.SYS, we recommend blanking that CONFIG field and letting Searchlight use its default behavior. If You Receive An Error Message... If you give the name of a non-existent program or directory when setting up doors you'll get an error message when you try to execute the command from within Searchlight. Check your setup screen and try to correct the error. Door programs can also fail to run if there's insufficient memory for the door to operate, or if Searchlight cannot locate the COMMAND.COM file when executing batch files or internal DOS commands. The latter situation can usually be corrected by examining your COMSPEC environment variable, or by placing a copy of COMMAND.COM in the SLBBS home directory. Of course, door programs can fail to operate correctly once they've been executed, even if the door is properly set up on Searchlight's end. If a door program runs, but displays error messages or seems to operate incorrectly, it's usually best to consult that program's documentation for more information (or contact the program's vendor, or others who use the program). 167 Doors Subsystem WHAT PROGRAMS CAN BE USED AS DOORS? The goal of the DOORS system is to enable you to run any program that uses the standard BIOS calls on a remote terminal. Since there are many ways of using the BIOS calls, and each program has its own quirks, it's not possible to guarantee that every BIOS and DOS compatible program will work correctly when used from a remote terminal with Searchlight. Programs that do not use the BIOS, but access the screen directly for fast screen updates, will not work under the DOORS system (this includes most word processors, for example). Programs that use high resolution graphics can't be used as DOORS, either. Some programs use the BIOS some of the time, and directly access the screen some of the time. These programs may run, but produce confusing results on the remote end. Finally, a few BIOS calls can't be adequately emulated on a terminal, and programs that use these calls won't be able to run correctly as DOORS. If you write your own DOOR programs, be sure to use the BIOS for all input and output; for example, in Turbo Pascal, when using the Crt unit, set the DirectVideo variable to "false". The easiest way to write DOORS compatible programs is to output only straight text, without using any cursor positioning, colors, attributes, etc. Such programs will be suitable for use on any remote terminal. Programs that use cursor positioning, etc. will work correctly only if an ANSI terminal is used at the remote end. Similarly, eight-bit IBM graphics characters can be used, but only if the remote terminal is expected to be an IBM compatible PC. A popular BBS utility program called Doorway(tm) enables direct screenwriting programs to be used on any BBS, including Searchlight. For more information about this product, check bulletin boards in your area or current BBS oriented publications. Using COMMAND.COM as a Door If you use COMMAND.COM as a Door, as shown in our example on page 164, you'll receive a DOS command prompt (i.e. "C>") at the remote terminal, and you will be able to enter DOS commands, such as DIR and CHKDSK, as well as execute other programs. Be careful when using this door; if you execute a program that uses strictly BIOS I/O, it should run at the remote terminal; if you attempt to run a program that ignores the BIOS, the program will still run, but you may be unable to see the output or provide input from the remote. In this case, all you can do is hang up the phone and wait for Searchlight to recover. The Reboot abort method is normally used with a COMMAND.COM door, since the new DOS shell points the abort return pointers back to itself and not back to Searchlight. Make sure you have your system configured to run your BBS when it is booted up (i.e. as part of the AUTOEXEC.BAT file) whenever you use a Reboot abort method. To exit back to Searchlight from the command shell, give the command EXIT. 168 Doors Subsystem Using Batch Files as Doors The use of batch files (files with the .BAT extension), as well as DOS direct commands (such as DIR and COPY), is supported by the DOORS system through the execution of a COMMAND.COM door. When you give a command line which does not specify a .COM or .EXE file to be run, Searchlight loads a COMMAND.COM shell and passes your command to it; this is necessary for the execution of DOS commands and batch files. In order to run COMMAND.COM, of course, it must be available on your disk. Searchlight finds COMMAND.COM by looking for the "COMSPEC=" line in the environment table. If no "COMSPEC" entry is found, it attempts to load the command processor from the current directory. If this fails, the message "Error running command" appears, and control returns to the BBS (you also get this error message if the command or program you're trying to execute is invalid or does not exist). Searchlight will assume that any command without a ".COM" or ".EXE" extension is a batch file. Therefore, when executing commands that are executable files, always include the extension in the command line. 169 Doors Subsystem PASSING PARAMETERS TO A DOOR PROGRAM Often, a program running as a DOOR will need to know something about the status of the BBS system at the time the program is run. Many programs will need to know the name or access level of the person who is using the door; others will need information such as the user's time limit or the active COM port and communications speed being used. Searchlight provides several methods for communicating this information to the Door process. Using Command Line Metacharacters The easiest and most portable way to pass parameters to a program is via the command line. Searchlight provides 14 system variables, or "metacharacters", which you can include on a command line in a menu or autodoor definition. When Searchlight executes the door, the metacharacters are replaced with specific information. Here is a list of the characters available: %N..............Current User's Name %U..............Current User's Name, with spaces replaced by underbars %K..............Current User's First Name %A..............User's BBS Access Level %F..............User's FILES Access Level %G..............ANSI Graphics Mode (C, M, or N) %T..............User's time limit, in minutes %M..............Amount of time left in current session (in minutes) %L..............Time the user logged in (HH:MM) %B..............Current Baud Rate %P..............Active Communications Port (0-4) %C..............Sysop 'Chat Available' status (Y or N) %S..............BBS System Name %O..............Node Number The time parameter, %L, is given in the format "HH:MM", as a 24-hour time. All other parameters appear as strings of characters or decimal numbers in the range 0 to 255. Baud rates appear as "2400", "9600", etc. The %N and %U parameters differ in that %N returns the user's exact name, including any spaces, while %U replaces spaces with underbars. Since the space character normally delimits command line parameters, many programs won't interpret a name containing spaces properly; you can use %U to send the full name as one word. %K returns the first name with all but the first character converted to lowercase. %P returns a value of zero if the current user is logged in locally; otherwise, it returns the value of the active COM port, 1 through 4. If %P returns zero, the value returned by %B is undefined and should be ignored. As an example of how to use metacharacters, let's say you have a game called SLOTS that you want to run as a door. SLOTS takes as a command line parameter the name of the person running the program; it uses your name to keep a high scores table. The command line syntax is SLOTS . 170 Doors Subsystem To make SLOTS accept the first name of the logged in user, without the user having to type his or her name, enter SLOTS %K as the command line for the door: SLOTS.EXE %K Now, if a user named JIM BARRY executes this door selection, the actual command line sent to DOS will look like this: SLOTS Jim The SLOTS program would run, and use "Jim" as the user name. Similarly, a %N parameter line would have produced "SLOTS JIM BARRY", using the entire name, and %U would return "SLOTS JIM_BARRY". Running PCBoard Doors With Searchlight Another way to pass parameters to a door program is via an external file. Searchlight can generate an external data file containing the same kinds of data as can be passed on the command line via the metacharacters. The format of this data file is equivalent to the format used in PCBoard(tm) bulletin board systems version 12 or 14. Thus, you can use many DOOR programs intended for PCBoard systems with Searchlight. Option number 11 on the "Pathnames Configuration" menu of the CONFIG program (see p. 27) allows you to enter a filename to which the DOORS system will write information before a door is invoked. If you do not specify a filename, no file is created. Note that you must enter the full path and filename in this field, not just the directory path; in other words, if you want to create a file called "C:\SLBBS\PCBOARD.SYS" when running a Door program, you must type that filename exactly. Two types of PCBOARD.SYS files can be created for compatibility with either PCBoard 12.0 or PCBoard 14.0 type door programs. The version you choose to create for each door program should correspond to the version of PCBoard for which that program is intended. PCBoard 12.0 is the default. To select the proper version, set line 15 in the menu definition screen (see p. 164). PCBoard compatible DOOR programs can read the PCBOARD.SYS file generated by Searchlight to get the current user's name, active communications port and baud rate, and other such information. The actual format of the PCBOARD.SYS file can be found in the PCBoard documentation. Searchlight does not support all of the fields used by PCBoard, therefore, not all of the information available in PCBoard systems will be available to door programs running under Searchlight. Many PCBoard compatible door programs will also look for a file called PCBOARD.DAT. In PCBoard systems, this is a static file containing information which is roughly equivalent to the information found in Searchlight's CONFIG.SL2 file. Since this information is static in nature, it is relatively easy to provide a "fake" PCBOARD.DAT file for PCBoard compatible door programs to use. There are several public domain utility programs available for doing just that. 171 Doors Subsystem Not all PCBoard compatible door programs will run under Searchlight. In particular, those door programs which require access to other PCBoard files, such as the PCBoard user or message files, won't work under Searchlight. In general, you can use doors which are well-behaved and don't rely on the presence of PCBoard data files (other than PCBOARD.SYS and PCBOARD.DAT) or PCBoard directory locations. Direct Use Of Searchlight Files As a final method of obtaining information, a DOOR program can access Searchlight BBS's binary data files (files ending in .SL2). Since Searchlight closes all of its files before DOOR processing begins, and reopens them when processing resumes, DOORS are free to read and/or write to these files, provided the proper data formats are retained. A program that reads Searchlight's data files can obtain everything Searchlight knows about its current state, including the ID of the current user, baud rates, configuration information, etc. If you want to be able to read in a message from the Searchlight data files, or post a message to a public subboard or mailbox, you can use the SLMAIL program provided by us rather than code your own message conversion functions. SLMAIL is discussed in Appendix F. The exact formats of the SLBBS data are provided on your distribution disk. Please refer to these files for commented type definitions and code examples. If you wish to write programs that do more than simply read configuration data, we strongly recommend you obtain our developer's toolkit (see p. 175 for more information). 172 Doors Subsystem HOW THE DOORS SYSTEM WORKS The code that enables you to run programs "online" is contained within the file SLBBS.EXE -- the program you actually run to start Searchlight from the DOS command line. When it runs, SLBBS, which requires under 50K of memory, actually loads and runs the program BBS.EXE "underneath" it as a subprocess. When you execute a DOOR, Searchlight records the request in the CONFIG.SL2 file, then terminates, returning control to SLBBS.EXE. At this point, SLBBS determines that a request for a door is in effect, and it does two things. First, it installs its own serial i/o routines on top of the BIOS i/o routines. Specifically, BIOS interrupts 10, 16, and 21 (hexadecimal) are intercepted by SLBBS and augmented with additional processing to handle the serial port. If software write protect is requested, interrupt 13 is also intercepted. Finally, the DOOR program is initiated as a sub-process underneath the SLBBS process. When the DOOR attempts to use the BIOS functions to do input and output, the SLBBS routines come into play, interpreting calls for input and output and linking the remote terminal into the system. The local screen and keyboard are still available; you can view the operation of the door while it is running, and you can type commands at the keyboard even while a remote user is typing commands. Exiting from the door returns control to SLBBS, which removes its code from the BIOS and restarts the main Searchlight program. Notice that this method of running the door off of a small "driver" program, rather than as a sub-process of the main program itself, provides you with a maximum amount of free memory in which to execute external programs. Since most of the memory needed to run Searchlight is deallocated before a door is run, the net amount of overhead is only the amount of code needed for the driver program. This amounts to about 47K, so you'll have about 47K less memory available when running programs as DOORS than you would if running them normally. If you use TSR (Terminate and Stay Resident) programs, such as SideKick, in conjunction with your BBS, these programs may cause problems for the DOORS system. If you have trouble, eliminate the TSR's when running DOORS on your BBS. Note that in the case of a door with Communications Support set to "None", i.e. a door which is presumed to handle its own serial i/o, no BIOS calls are intercepted, no additional processing is added to DOS, and the program executes exactly as it would normally. In this case it is up to the door program itself to make use of the serial port, if serial i/o is required. You should use this option when running Door programs that support their own serial i/o, such as games written for other BBS systems. Output Not all calls to the BIOS interrupts are interpreted literally. Searchlight performs commands with the least amount of i/o necessary. For example, many programs will issue a "cursor position" request after each character is 173 Doors Subsystem output. Since this would cause Searchlight to transmit an extra 6 to 8 characters for each output character, a check is made for this condition, and no characters are output. Similarly, requests to move the cursor to the next line or to column zero of the current line are transmitted to the remote as linefeeds and carriage returns. If a cursor position request cannot be resolved with control characters, an ANSI cursor position sequence is issued. This presumes you have an ANSI terminal at the remote end. No check is made; if you use door programs that require absolute cursor positioning or other ANSI features such as text highlighting, an ANSI terminal is required at the remote. If you have many non-ANSI terminal users, it is suggested that you use command descriptions or text files to identify those DOORS which require ANSI terminals. Be aware that some programs which use the BIOS calls that output to the screen without moving the cursor will not work. Also, some BIOS commands, such as those for horizontal screen scrolling, cannot be emulated on a terminal, and programs that use them won't run properly. Input The DOORS system attempts to convert ANSI escape sequences from the remote terminal into the IBM character codes that are generated by the BIOS. However, ANSI terminals don't support all of the keys provided on the PC keyboard, and some terminals handle control keys differently than others. This will mean that some programs won't interpret keystrokes from the remote terminal correctly. Generally, however, a good ANSI or vt100 terminal will be able to provide the four arrow keys, the Home and End keys, and at least the first five F-keys. Access To Original BIOS Vectors When Searchlight is in control of a door program's I/O, all standard BIOS output is sent to the modem, and all modem input is made to look like standard BIOS input. However, you may, on occasion, wish to write programs which write some output only to the local screen, or can distinguish between local and remote keyboard input. To allow for this, Searchlight provides access to a block of memory containing the original BIOS vectors and other useful information about the state of the SLBBS routines. To access the SLBBS information, call the MS-DOS interrupt dispatch routine (i.e. INT 21) with a value of $C7 loaded into the AH register. $C7 is an invalid DOS function and will have no effect if Searchlight is not loaded. If Searchlight is active, however, the register pair AX:BX will be returned with a far memory pointer to the SLBBS data block. You can use this far pointer to access the data, which will be in the format given below: Field Name and Type Contents ------------------- -------- PROGID: string[6]; { Program ID } carrier: boolean; { true if carrier check enabled } writeprotect: boolean; { true if disk write protected } aborttype: byte; { 0=no abort, 1=terminate, 2=reboot } 174 Doors Subsystem rsactive: boolean; { set if rs232 port is active } ansi: boolean; { user ANSI mode } color: boolean; { user COLOR mode } directvid: boolean; { system DirectVideo mode } curratt: byte; { current video attribute } commtype: byte; { run parameter (0, 1, or 2) } idletime: word; { idle time limit (seconds) } lastkey: boolean; { TRUE = last key from local kbd } OldVector: array[$00..$7F] of pointer; { old user int vectors } Notes: A 'boolean' variable is a one-byte variable which will be set to binary 1 if true, zero if false. Words are two-byte unsigned integers, and pointers are four-byte far pointers. The PROGID field contains the string 'SLBBS' to identify the presence of Searchlight (byte zero contains the string length, bytes 1-5 contain the characters, and byte 6 contains a binary zero [for the convenience of C programmers]). If the string SLBBS is not found here, Searchlight is not loaded and all other data should be considered invalid. If 'rsactive' is true, then interrupts 10 and 16 (hex) will point to the Searchlight code. If false, then these interrupts remain at their original BIOS addresses. Int 13 belongs to Searchlight only if 'writeprotect' is true. Int 21 always contains Searchlight code. If you wish to restore any interrupt belonging to Searchlight back to its original value, the original vectors can be found in the 'OldVector' array (which actually contains space for up to 128 pointers). Be sure to read the existing vector first if you plan to restore it. Don't set interrupts 10, 13 or 16 unless they actually belong to Searchlight. The 'lastkey' variable can be read to determine if the last keystroke entered came from the local keyboard or the remote terminal. 'Lastkey' is true if the last keystroke was local. Other variables can be read to obtain the information listed. The above table is not meant to be used to provide information such as the current user's name or baud rate to the DOOR; other methods for passing these types of parameters are given in the next section. Finally, although we advise against it, some of the above fields can be usefully written to. However, setting or resetting 'rsactive' and 'writeprotect' will NOT have any effect on the door's behavior. Searchlight Software is committed to assisting third party developers who want to write applications that interact with our BBS product. Much more detailed programming information, including a free Pascal language function library that can be used to create complex applications that access Searchlight message files and data files, is available from Searchlight Software. As of this writing, you may obtain the additional information and programming library free of charge by downloading the file SLTPU70B.ZIP from our support BBS. Since this filename will change when the code library is updated, check our BBS or contact us to obtain the latest filename and latest developer information. 175 Doors Subsystem Some Door Programming Tips Here are some tips for programmers writing Door programs: o Use DOS or BIOS calls for all input and output; don't write directly to the screen. Programs that do direct screen writes won't run as remote Doors, and may not work with windowing or multitasking operating system software. Most compilers default to or can be set for BIOS I/O. o Don't access the serial port. Searchlight will handle all modem I/O automatically when the door runs online. If you must access the local console independently of the remote, use the methods outlined above for accessing the original BIOS pointers from your program, or obtain our developer's toolkit for serial port access procedures. o Use command line parameters to pass information to your program when possible. Don't access Searchlight data files directly. Command line parameters are much faster and easier to use, and provide the advantage that your program can be distributed to and use by others who don't have a BBS. o Door programs should be as easy to run from the command line as they are to invoke from the BBS. Make parameters optional where possible; default username to SYSOP, baud rate to LOCAL, etc. o If you write a utility program that uses SLBBS files directly, bear in mind that the data file format is subject to change. Your program should document which version of Searchlight it is to be used with, and, if possible, be flexible enough to work with different versions. For best results, use our prepared developer's library rather than code your own data formats and file access routines. 176 Sysop Utilities SEARCHLIGHT SYSOP UTILITIES Introduction Searchlight's CONFIG program contains a rich set of utility functions that allow you to easily maintain messages, users, subboards, and other aspects of your BBS. With the sysop utilities, you can rename users with optional updating of messages, purge your user file by last login date, access level and/or attributes, purge messages by date or search key, purge undeliverable mail, purge subboard members and files, and effect mass validation changes. To access the sysop utilities, run CONFIG and enter option D: D. User/Subboard/File Utilities You can also type CONFIG D at the DOS prompt, or place the command on a menu that you can access from within Searchlight BBS. Please read this documentation thoroughly before attempting to use any of the purge or validate utilities. Due to the nature of these utilities, a mistake or misunderstanding of a feature could have disastrous results. If you aren't sure, BACK UP your files before doing anything. If you are running a multiuser BBS, please see the note about concurrent operation at the end of this section. The Sysop utilities main menu shows the following options: A. Change User's Name B. Purge User File C. Purge Message Files D. Purge Member Files E. Mass Validate Users F. Purge File Areas To select a command, type a letter from A to F, or highlight the desired command and press Enter. Here's a breakdown of each menu option: CHANGE USER'S NAME This option allows you to rename one or more users. Enter the name of the user you wish to rename, then press Enter, and type the new name you wish to assign to that user. Provided that the user is found and that the new name does not duplicate an existing name, the change will be made in the User file. If you wish to rename additional users, press Yes when prompted; otherwise enter No. If possible, it is advantageous to rename several users at once, rather than one at a time, since the message update phase of the rename operation may take some time. 177 Sysop Utilities After you have input all of the name changes you wish to make, this menu will appear: A. Update All Messages B. Update Personal Messages Only C. Do Not Update Messages During this phase, the Sysop program will scan your entire message base, or selected portions of it, in order to change the to and from names on any messages posted by, or sent to, one of the users that has been renamed. It is recommended that you use the "Update All Messages" option. If you choose option B, the update scan will take less time, but will still ensure that mail and personal messages are correctly addressed, as well as high message pointers in message areas. Be aware that if you skip the update scan, messages left by users that have been renamed will bear the user's old name, and subboard membership records will not be changed. After you choose option A or B, a subboard selection screen will appear. We recommend pressing ESC to accept the default settings here and update all subboards. If desired, you can select the subboards to be updated; see "Purge Message Files" later in this documentation for information about subboard selection. Those who write utility programs for Searchlight should note that the rename procedure may move the user record in question to a different record number in the user file. PURGE USER FILE This option allows you to purge many names from your user file at once, based on various criteria. When option B is selected off of the main menu, an input screen appears. Your responses to these input prompts determine which users will be purged. 1. Cutoff Date ................... 5-30-92 2. Min Access Level .............. 0 3. Max Access Level .............. 240 4. Maximum Calls ................. 0 5. Include Attributes ............ 6. Exclude Attributes ............ 1 -- Cutoff Date The cutoff date determines the age of users to delete. In this example, any user who has not logged on since April 30th, 1992 is eligible for deletion. (Whether such users are actually deleted depends upon the answers to the remaining prompts; a user must pass all eligibility requirements in order to be deleted). 178 Sysop Utilities By default, the cutoff date is set to 6 months prior to the current date. Change this field as desired. 2 -- Min Access Level 3 -- Max Access Level These fields determine the minimum and maximum access level that a user must have to be considered for deletion. Users that fall between the given access levels (inclusive of the minimum and maximum) are eligible to be purged. 4 -- Maximum Calls This field, if set to a nonzero value, lets you specify a maximum number of calls as part of your purge criteria. For example, a value of 2 specifies that users who have called your BBS 1 or 2 times may be targeted for deletion while users who have 3 or more calls are exempt. If this field is left as 0, number of calls is ignored. 5 -- Include Attributes 6 -- Exclude Attributes These two fields look at user attributes as part of the selection process. You can input attribute strings here (letters from A to X). If Include Attributes are specified, only users who have all of the attributes specified here are considered for deletion. Users who do not meet all of these attribute requirements are exempted from the purge. If Exclude Attributes are specified, users who have any of these attributes are exempted from the purge. In other words, a user must have all of the attributes listed in line 5, and none of the ones listed in line 6, in order to be eligible for deletion. For example, if you specified "AB" as the Include Attributes and "CD" as the Exclude Attributes, users who have attributes "AB", "ABX" or "ABFG" would be eligible for deletion, while users with attributes "AFG", "ABD" or "ABCFGX" would not be deleted. Purging Users Once all fields are filled, press Escape. This prompt appears on your screen: Purge user file based on above criteria? Enter "Yes" to begin purging users, or "No" to abort the operation. If you proceed, the program provides a display of its progress. The User Purge operation does not delete mail in the user mailboxes, nor does it delete the member information on subboards. However, the Sysop utilities provide special options in the Purge Message Files and Purge Member Files commands specifically for deleting mail and member records 179 Sysop Utilities after a user purge. It is recommended that these be run after purging the user file to delete unnecessary mail and member records. 180 Sysop Utilities PURGE MESSAGE FILES This command option provides for the mass deletion of messages from one or more message areas (including the MAIL area) based on age, search strings, or other criteria. When option C is selected, a new menu appears with these choices: A. Date Range & Options B. Search Key Specification C. Subboard Selection D. Begin Message Purge Date Range & Options Option A lets you specify the following criteria for purging messages: 1. Start Date .................... 1-01-87 2. End Date ...................... 5-30-92 3. Minimum Times Read ............ 0 4. Undeliverable Mail Only ....... No 1 -- Start Date 2 -- End Date These two fields let you specify the range of dates that you wish to include in the message purge. The default is all dates up to 6 months prior to the current date. Change these as necessary. 3 -- Minimum Times Read This field lets you select messages based on the number of times the message has been read. Messages which have been read less than the number of times indicated here are not deleted. The default value of 0 effectively ignores the times-read counter. This option is primarily of use for deleting mail, as it can be used to insure that unread mail is not deleted. 4 -- Undeliverable Mail Only If this field is set to Yes, only messages which are addressed to a user who is not in the system's user file, and thus cannot be received, are deleted. The main use for this feature is to delete mail addressed to users that have been deleted from the system with the user delete or purge commands. When this option is selected, Searchlight automatically selects the MAIL subboard, and only that subboard, as the default. You can change that by 181 Sysop Utilities using the Subboard Selection option. If other subboards are selected, Searchlight will delete public messages on those subboards that are addressed to nonexistent or deleted users, including messages addressed to "All" -- so it's not recommended that you run this kind of purge except on the MAIL subboard. Search Key Specification This set of options lets you select messages for deletion based on a search string, which can match the To, From, Subject, or Fwd From fields in a message header. 1. Search String ................. 2. Case Sensitive ................ No 3. Search To: Field .............. No 4. Search From: Field ............ No 5. Search Subject ................ No 6. Search Fwd From ............... No To use a search string selection, enter the text to search for (such as a username or a subject fragment) in line 1. If you want to do a case sensitive search, change the default on line 2. Fields 3 thru 6 determine where in the message header your search string should be found. You can select any combination of areas to search. At least one area must be specified if you wish to have a successful search. Only those messages in which the search string can be located in one of the indicated fields will be deleted. Note that the Search string works in conjunction with the date range and options in the previous menu. Only those messages which pass all of the tests indicated in the Date Range menu and the Search String menu (if a search string is used) are actually deleted from the system. Therefore, if you wanted to delete all messages containing a particular string, you should be sure to set the date range to the present day. Subboard Selection This menu choice lets you select the subboards which you want to purge. You can purge messages from all subboards, or any combination of subboards. When this option is selected, a subboard list appears, similar to the subboard list used in the Subboard Maintenance section of CONFIG. To navigate through the list, use your Up/Down arrow keys; PgUp and PgDn; or press the first letter of the subboard to which you wish to travel. Subboards can be marked and unmarked by pressing the when the cursor is to the left of the desired subboard. Marked subboards are indicated by an asterisk (*) in the left hand column. If you did not select "Undeliverable Mail Only" in the Date Range menu, all subboards will be marked by default; otherwise, only the Mail subboard will be marked. 182 Sysop Utilities Select the desired subboards by marking and unmarking. You can use the F4 key to mark all subboards or F5 to unmark all. When you are done, press the ESC key to exit. Begin Message Purge Select this option to actually begin the purge operation. The CONFIG program examines the selected subboards and deletes messages meeting the criteria specified. A status report displays the program's progress. If you decide not to purge messages, press ESC at the Purge Messages menu instead of selecting option D. PURGE MEMBER FILES This option provides for purging the member files associated with message areas. You can purge members who haven't accessed a subboard since a specified date, or via a number of other criteria. The Purge Member menu contains these options: A. Member Purge Options B. Subboard Selection C. Begin Member Purge Member Purge Options This input screen lets you select the criteria on which to purge member records. The fields are: 1. Cutoff Date ................... 5-30-92 2. Invalid Usernames Only ........ No 3. Inactive Members Only ......... No 4. No Personal Msgs Only ......... No Cutoff Date specifies the last access date to purge members. Those members who have not accessed the subboard (JUMPed to it or read messages as part of the NEW command) are eligible to be deleted. Invalid Usernames Only specifies that only members which are not valid names in the USER file are deleted. You would select this option primarily as a clean-up operation to delete member records after purging the user file. Inactive Members Only means that only members who are not active in the subboard are deleted. "Not active" means that the member's highest message read is lower than the lowest numbered message in the subboard. 183 Sysop Utilities No Personal Msgs Only specifies that the purge involves only users who have no personal messages on the given subboard. This is primarily of use in conjunction with the MAIL subboard, where it can be used to delete members who have no mail, and may be a useful option on other subboards as well. Note that as with other purges in the Sysop utilities, member records must meet all of the selected criteria in options 1 through 4 in order to be deleted. Subboard Selection This choice lets you specify the subboards to be included in the member purge. Select subboards by marking with the , F4 and F5 keys. See the "Purge Message Files" command above for more information about subboard selection. Begin Member Purge Select this option to actually begin the purge procedure. (Press ESC if you wish to abort instead). A progress display is generated. MASS VALIDATE USERS This command allows for making access level adjustments on many users at the same time. Users can be selected for validation by access level and attributes and can be affected by a variety of changes to access levels, attributes, time limits, and file transfer ratios. The term "Validate" is used loosely here to indicate changes to a user's security levels. Mass validation can involve changes in either direction to users' security levels. Option E calls forth the following submenu: A. Specify Target Users B. Specify Adjustments C. Begin Mass Validation Suboption A specifies which users are to be validated; option B specifies the changes to be made to their accounts. Use option C to begin the process (or press ESC at this menu to abort it). Specify Target Users The following input items appear after selection of this option: 1. Min Msg Access Level .......... 0 2. Max Msg Access Level .......... 240 184 Sysop Utilities 3. Min Files Access Level ........ 0 4. Max Files Access Level ........ 240 5. Include Attributes ............ 6. Exclude Attributes ............ Lines 1 through 4 determine by access level which users will be included in the validation. Users who have message access levels and file access levels within the specified ranges are included. Lines 5 and 6 specify by attributes which users are included in the validation. In order to be included, a user must have all of the attributes listed in line 5, and none of those listed in line 6. When both lines are blank, as in the default condition, no users are excluded based on attributes. For more information on the Include/Exclude Attribute fields, please see the example in "Purge User File" earlier in this section. As in other areas of the Sysop utilities, users must meet all of the requirements specified in lines 1 through 6 to be included in the validation operation. Specify Adjustments In this input screen, you specify what changes you want to make to the user records selected. The input lines are: 1. Msg Level Adjustment .......... No Change 2. Value ........................ 0 3. Files Level Adjustment ........ No Change 4. Value ........................ 0 5. Ratio Adjustment .............. No Change 6. Value ........................ 0 7. Daily Time Limit .............. No Change 8. Value ........................ 0 9. Session Time Limit ............ No Change 10. Value ........................ 0 11. Account Expiration (Days) ..... No Change 12. Value ........................ 0 13. Add Attributes ................ 14. Remove Attributes ............. Msg Level Adjustment and Value specify what adjustment is to be made to each user's Message Access Level. The options for line 1 are "No Change", "Change To", "Increment" or "Decrement" (press Spacebar to toggle between the choices). Line 2 can contain a value between 0 and 255. If "No Change" is selected, no change is made to the message access level. If you select "Change To", user message access levels are changed to the value in line 2, regardless of their previous value. If "Increment" or "Decrement" are selected, then the message access level is incremented or 185 Sysop Utilities decremented by the value specified in line 2. If the result is less than 0 or greater than 255, it is rounded off to 0 or 255, respectively. Lines 3 through 12 are used to effect changes to the files access level, upload ratio, time limits and expiration dates. As with lines 1 and 2, these fields work in pairs, with and action and a value. Time limit fields allows a maximum value of 14400. The Session Time Limit action (line 9) supports a value of "DailyLimit", which sets the session time limit equal to the user's daily time limit. Fields 13 and 14 add or remove attributes from the selected user accounts. Enter those attributes you wish to add into line 13, and those you wish to remove, in line 14. Begin Mass Validation Select this menu choice to begin the mass validation. A status display is generated as the validation operation proceeds. PURGE FILE AREAS The Purge File Areas option allows you to automatically delete files from your download libraries based on age, number of downloads, and other criteria. Use this option when your hard disk becomes nearly full, or anytime you want to clean out old files from your BBS. The file area purge works like the other purges, and presents this menu: A. Date Range & Options B. Directory Selection C. Begin File Purge Date Range & Options Use this screen to select the desired file purge options: 1. Start Date .................... 1-01-87 2. End Date ...................... 5-30-92 3. Minimum Size (K) .............. 0 4. Maximum Size (K) .............. 9999 5. Maximum Times Downloaded ...... 9999 6. Confirm Each Deletion? ........ Yes 7. Erase Files from Disk? ........ No 8. Remove Upload Credits? ........ No Start Date and End Date specify a date range for deletion. Files with an upload date between these two dates will be eligible for deletion. Note that Searchlight looks at the date the file was uploaded (date in the 186 Sysop Utilities directory listing), rather than the file's DOS date, as the basis for this selection. Minimum Size and Maximum Size specify a size range in kilobytes (1KB=1024 bytes). Only files which fall within the range will be deleted. Maximum Times Downloaded allows you to prevent deletion of files which have been downloaded more than a particular number of times. For example, if you enter 50 in this field, then files which have been downloaded more than 50 times are prevented from being purged. Only files with 50 or fewer downloads will be deleted. Confirm Each Deletion lets you decide whether you would like Searchlight to automatically delete files based on your specifications, or prompt you with a Yes/No prompt for each file. If you select "Yes" in line 6, you will be prompted; "No" initiates an automatic purge. Erase Files From Disk lets you decide whether Searchlight will erase entire files, or just remove the directory entries. Select "Yes" if you want to delete the files from disk and free up disk space. Remove Upload Credits selects the action Searchlight will take with upload credits. If "Yes" is entered, Searchlight removes upload credits from the uploader of each file it deletes. In other words, if a 50KB file is deleted, Searchlight deducts 50 from the upload count of the user who uploaded that file. Select "No" if you do not want to deduct upload credits. Directory Selection This option lets you select the directories on which File Purge will operate. Only those file areas you mark will be affected by the purge. Press F4 and F5 to mark and unmark all directories, or Spacebar to mark or unmark individual directories. Begin File Purge Searchlight shows you a running count of the number of files deleted and the amount of disk space freed up as it deletes files. SYSOP UTILITY NOTES Backups We strongly recommend performing purge and mass validation operations only when a recent backup of the data files being modified is available. Due to the far-reaching nature of these operations, a small mistake in specifying the target parameters can lead to the loss of many users or messages. A backup is by far the best way to avoid disaster. 187 Sysop Utilities Multiuser Operation If you run a multiuser BBS, it is recommended that you do not run lengthy purge or validation operations while other nodes are active. Since these operations keep the data files locked for long periods of time, and put a large load on the file system, they may cause unacceptably slow operation on other nodes. Therefore, we recommend you shut other nodes down while running these operations. 188 Netmail INTRODUCTION TO NETMAIL What is Netmail? The term netmail refers to any private electronic mail message, sent from one individual to another, that is carried across a network (hence network mail or netmail). The network that carries such a message can be any of the Fidonet(tm) technology networks that exist between bulletin boards, including Fidonet itself, SL_NET, or any of the other networks which use the Fido style message standards. Why use netmail? The answer is that is allows you to communicate with virtually any person who is a member of a bulletin board in the network to which you are connected, without placing a direct call to the particular BBS on which that person is a member. As an example, let's look at what happens when you send a typical, non-netmail message using Searchlight BBS. Suppose you call a local Searchlight BBS, Joe's World of Widgets, by dialing a local telephone number with your modem, and you leave a private message to your friend Walter, who lives in a different state. Of course, Walter won't be able to see that message until he calls Joe's World of Widgets himself -- which is something he does infrequently, since it's a long distance call for him, and he's not all that interested in widgets anyway. If your message is important, Walter may not get it until it's too late to be of use to him. With netmail, though, you can make long distance communication much faster and more reliable. Suppose you know that your friend Walter uses a BBS in his area called Phil's Faucet Emporium on a daily basis, and both Joe's World of Widgets and Phil's Faucet Emporium are members of the international Fidonet network. You could send a message from Joe's BBS in your area code, and address it to Walter at Phil's BBS. In a day or two, network traffic automatically carries your message from Joe's BBS to Phil's BBS, where it appears in Walter's mailbox. Since Walter calls Phil's BBS every day, he sees your message immediately. The result: you can exchange mail with your friend Walter, even though he lives in a different state and has much different interests than you, and neither you nor Walter has to dial a long distance phone number or use an out of state BBS. Of course, there were some long distance calls and charges involved with getting your message from Joe's BBS to Phil's BBS, but those charges were incurred during late night hours and only for the amount of time necessary to transmit a compressed version of your message between two bulletin boards, so they're significantly less than what you'd pay to call the out of state BBS and leave your message personally. In addition, netmail gives you the convenience of being able to originate and receive mail on one BBS instead of having to dial many different systems to communicate with all the people you'd like to reach. Who can use Netmail? Any Searchlight BBS which participates in a Fidonet-technology network can send and receive netmail messages. As the Sysop of a networked BBS, you can 189 Netmail regulate by security attributes which of your users has the ability to use netmail. If your BBS does not currently participate in a Fidonet style network, you'll need to establish a network link before you can begin using netmail. Network policies vary; however, the usual procedure is to obtain and install a Fidonet compatible front end mailer software package on your system, and then apply for membership by contacting another BBS in your area that serves as the central distribution point (Hub) for that area. Before you try to install netmail support on your BBS, confirm that you can send and receive netmail messages (via "MSG" files) to and from other systems in your network. Once you have that capability, you'll start to use Searchlight to read and create the MSG files, rather than a front end mailer or special editor. HOW SEARCHLIGHT HANDLES NETMAIL If you are already familiar with echomail, you'll find that netmail works in much the same way. If not, you may find the discussion below useful as background information. To send netmail from Searchlight BBS to another BBS, you start by entering a message through Searchlight's text editor, typically by selecting a command such as "Mail/Send" or by replying to an existing netmail message. When sending a new message, Searchlight will ask you for both the name of the person to whom you are sending the message and the netmail address of the bulletin board where you would like the message sent. All networked systems have a three part numerical address in the form "Zone:Net/Node"; for example, the address of Searchlight BBS in Stony Brook, NY is "1:107/252". (Some systems have multiple addresses and some have an additional number called the point address). In many cases, Searchlight will provide the netmail address itself (by looking at an address list) but you should always be prepared to type the address in yourself, if required. Once your message is typed and saved, it exists inside Searchlight as an ordinary mail message. The next step in the message's journey is to be exported from Searchlight BBS into a format that can be handled by network mail software. Exporting occurs when you run Searchlight's included NETMAIL.EXE utility program. The netmail utility turns netmail messages from your BBS into individual "MSG" files in a standard format that is recognized by Fidonet mail software. If you have a network mail system installed on your BBS, you most likely already have a directory where incoming netmail "MSG" files are saved and outgoing files are stored before they are sent. This is where you'll export your Searchlight netmail. Once your netmail is exported, your netmail software (third party products provided by other companies) can actually transmit the files to another BBS. There are usually two steps involved, called "tossing" and "polling". To find our more about these steps, you need to obtain a third party mail product (such as D'Bridge, Front Door or Binkleyterm) and follow its documentation. 190 Netmail To receive netmail, the procedure is reversed. Incoming mail is stored as "MSG" files by your front end software, which are then imported into Searchlight by the netmail utility program (NETMAIL.EXE). Once imported, you read the mail using Searchlight's usual Mail/Read or Mail/New commands. Of course, on most systems you'll want to automate the whole process by running the NETMAIL.EXE program as part of a mail event. The main difference between netmail and echomail is that each netmail message has a distinct from and to address provided by the person sending the message, whereas echomail goes to all addresses as determined by the network software. Two additional aspects of Searchlight's netmail implementation are nodelist indexing and mail routing. Nodelist indexing is the process by which Searchlight gains access to the information that is in your network node lists; it's important because Searchlight can use the nodelist to look up BBS names and addresses through the nodelist to help your users enter correct netmail messages. If you choose to restrict your users to sending netmail only to listed addresses, the nodelist index is essential since it's used to determine which addresses are considered valid. Searchlight includes a stand-alone utility program, INDEX.EXE, which compiles a nodelist index on demand. Mail routing allows you to associate a netmail address with a username on your system. By doing this, any mail sent to that person is automatically converted to netmail, even if the person entering the message does not type in the netmail address. Routing is useful when you want to simplify the process of sending netmail to certain people without having to remember their net address. It's also great when you have users who are infrequent callers, but frequently call another networked system. C C CONFIGURING ONFIGURING ONFIGURING S S SEARCHLIGHT FOR EARCHLIGHT FOR EARCHLIGHT FOR N N NETMAIL ETMAIL ETMAIL Searchlight's main netmail options are entered via the CONFIG program. To access the setup screens, run CONFIG.EXE from the DOS prompt, then enter the General Configuration menu and choose option J, "Netmail Setup". The following options screen is disclosed: 1. Primary Address ............... 250:500/1 2. Alias Address 1 ............... 1:107/252 3. Alias Address 2 ............... 4. Alias Address 3 ............... 5. Alias Address 4 ............... 6. Sysop's Real Name ............. FRANK LAROSA 7. Send Bad Messages To .......... SYSOP 8. Netmail Reply Attributes ...... 9. Netmail Originate Attributes .. 10. Unlisted Address Attributes ... WX 11. Send Crashmail Attributes ..... 12. Routing Address Edit .......... ABCDEFGHIJKLMNOPQRSTUVWX 13. Nodelist Configuration [...] 191 Netmail Fill in these fields as follows: 1 to 5 -- Primary & Alias Addresses These lines let you enter the primary and alternate netmail addresses of your system, which should be typed in the format "Zone:Net/Node" or "Zone:Net/Node.Point". You should only list one address for any given zone number here, and it should be the address you'd like to use as the origin for netmail originating on your BBS to a point within that zone. If you have additional addresses in the same zone, you can list these separately in a configuration file so that mail written to any address can be imported to your system. At least one address must be specified here in order for Searchlight's netmail features to be activated. If all of the address fields are left blank, Searchlight will not allow any netmail messages to be sent. 6 -- Sysop's Real Name Type your name in line 6. Searchlight uses your name to replace the word "SYSOP" on outgoing and incoming messages, so that if you use the name SYSOP to log onto your own BBS, you can still send netmail using your real name. 7 -- Send Bad Messages To In this field, type the name of the person to whom you'd like bad messages sent. A "bad message" is simply an incoming message which is addressed to a username that does not appear in your USER file. For example, if someone tried to send a netmail message to "Ronald Reagan" on your BBS, and your userlog did not sport the former president as a user, the message would be sent to you, or to whatever username you place here. On almost all systems, you'll want to put the name SYSOP here, or your own name if you do not use the name SYSOP to log on to your BBS. 8 -- Netmail Reply Attributes Fields 8 through 11 are security attributes that define which users on your BBS can perform netmail related functions. Field 8 specifies the security attributes required to reply to a netmail message. Any user who possesses these attributes can respond to a netmail message or an echomail message, but cannot necessarily originate a new message. As with all security fields, you can leave this field blank if you do not wish to restrict this feature. 9 -- Netmail Originate Attributes This field defines the attributes needed for a user to be able to create a new netmail message to anyone who is reachable on the networks to which you belong. Searchlight determines which addresses are valid primarily by 192 Netmail consulting the nodelists on your system. It also considers any pre-entered addresses to be valid. 10 -- Unlisted Address Attributes These are the security attributes required to send netmail to any address, even if the address is not listed in a nodelist. Be careful with this option; if you allow users to have unlisted address access, they will be able to send incorrectly addressed netmail which will never reach its destination. It is best to send such messages with care. 11 -- Send Crashmail Attributes These attributes define which users are able to send "Crash Mail". Crash mail is urgent netmail: instead of being routed through the network at night, it's sent directly to the destination BBS immediately. Since crash mail can cause your system to place long distance phone calls at any time, it is best to restrict this function to yourself and your most trusted users. 12 -- Routing Address Edit These attributes determine whether your users can supply their own routing address. A routing address is a netmail address associated with a user account: whenever any mail is sent to such an account, it becomes netmail. Normally, you will want to prevent your users from doing this, and assign such addresses yourself on a case by case basis. However, you can give your users the ability to change their own routing address (via Options/Info) if you specify appropriate attributes here. 13 -- Nodelist Configuration To access the nodelist configuration screen, press Enter here (or click here twice with your mouse). A new screen appears which allows you enter up to five nodelist filenames: 1. Primary Nodelist .............. C:\DB\FILES\NODELIST 2. Alternate Nodelist ............ C:\DB\FILES\SL_NETNL 3. Alternate Nodelist ............ 4. Alternate Nodelist ............ 5. Alternate Nodelist ............ A nodelist is a text file containing a listing of the names and network addresses of all bulletin boards in a given network. You should have at least one such file for each network in which you are a member. Type the filenames here, but leave off the extension part of the filename. Since the extensions change when nodelists are updated, Searchlight automatically searches for the most current filename. 193 Netmail Searchlight uses nodelist files to look up and display information about bulletin boards in your network, but it can only do so after it has compiled a special binary index file, called NLINDEX.SL2, that helps it find information quickly. The included utility program, INDEX.EXE, creates the index. You should run INDEX.EXE manually after inputting or changing your list of nodelist files. It's also a good idea to run it as a nightly event, to ensure that the index is kept up to date. NETMAIL IMPORT & EXPORT The way netmail messages move to and from your Searchlight BBS system to the rest of the network is through a special utility program called NETMAIL.EXE, which is included with your Searchlight 3.0 package. Any netmail created from within your BBS remains there until it is exported by running the netmail utility (which creates "MSG" files for the outbound mail). Similarly, incoming netmail is not available within Searchlight until the MSG files are imported. You can, of course, run the program NETMAIL.EXE manually from the DOS prompt to move your mail, or attach it to a menu inside Searchlight to be executed on demand. But the best way to run the netmail utility is as part of an event or batch file, so that importing and exporting of netmail is automated. For example, you could run a netmail import event after your system receives mail packets, or once per day, or even after each login or logoff to your BBS. The syntax for the NETMAIL.EXE utility is as follows: NETMAIL Command [Options] Command is "E" or "Export" to export messages, "I" or "Import" to import messages. Options are as follows: -a Import or export all messages (default new messages only) -l Make lowercase names on outgoing messages -c Allow color codes in messages -k Kill source messages after importing or exporting -o Optimize lock/buffer strategy -v Verbose progress messages -p Specifies path to CONFIG.SL2 -g Specifies path to *.MSG files The most basic Netmail command lines are NETMAIL E to export messages and NETMAIL I to import messages. If the MSG files are not in the current directory, use -G to specify their location. If your CONFIG.SL2 file is not in the current directory (or in the environment), type -P to give its path. The -A option can be used to force the netmail utility to import or export all available messages. By default, if -A is not given, only new messages are imported or exported. The utility determines which messages are new 194 Netmail when exporting by means of a high message pointer on the MAIL subboard keyed to the name "NETMAIL"; it determines which are new when importing by looking for its tagline in the source MSG files. It is not recommended that you use the -A switch except for special purposes. The -K or Kill switch is recommended. When used during an import, the netmail utility deletes the source MSG file after importing it. When used during an export, the utility deletes the source message from Searchlight's mail subboard after exporting it. It's especially important to kill messages after exporting because a netmail message that resides inside Searchlight BBS is generally inaccessible by any user, and therefore would simply take up space until removed during a mass message purge or manually deleted, if -K were not used. Other NETMAIL.EXE switches are similar to the SLMAIL echomail utility, and allow you to process lowercase name conversions and color codes. The -O switch optimizes the file locking strategy on multiuser systems by locking the entire MAIL subboard for the duration of the operation; this makes netmail operations faster, but locks other nodes from using the MAIL subboard during the Netmail operation. We recommend using the -O switch only if no nodes are active during the time that the Netmail command executes. Additional Alias Addresses for Import Earlier, we mentioned that you should specify only the primary address in a particular zone when typing your own netmail addresses into Searchlight's CONFIG program. As a rule, the NETMAIL utility will only import messages that are explicitly addressed to your system, which is determined by matching the destination address to your system's primary or alias addresses. If no match is found, the netmail utility won't import the message; this is an important feature, because your system may act as an intermediate storage area for mail that is destined for another BBS, and you don't want that mail to be imported into your BBS (and possibly deleted) by the netmail program. If your BBS has a number of alternate addresses in a particular zone, though, you need to tell the Netmail program about the other addresses so it can import all the mail that should be on your BBS no matter which alias was used by the sender. The way to list your additional addresses is to create a text file called NETMAIL.CFG. Type the additional addresses, one per line, using the standard Zone:Net/Node[.Point] format. Up to 40 addresses may be specified. You should place your NETMAIL.CFG file in your Searchlight "data files" directory (the same directory that contains your USER.SL2 file). Once the NETMAIL.CFG file is installed, the netmail utility will recognize the additional addresses as aliases for your system, and will import mail destined for those addresses. NODELIST INDEX 195 Netmail The nodelist indexing program, INDEX.EXE, is used to create a binary index that allows Searchlight to quickly access data within nodelist files. You should run INDEX once after setting up your nodelists, and again as a daily event so that any nodelist changes are recorded. Before running INDEX, run the CONFIG program and enter the filenames of your nodelist files as mentioned previously. Be sure to give only the filename of the "raw" or text file nodelist, not the name of any other indexed nodelist that might be used by your system. Only standard (also know as "St. Louis") nodelists may be compiled by Searchlight; do not specify point lists or non-standard nodelists as input. If you like, you can create a private nodelist in the same format as the standard nodelist and include it in your index (a private nodelist enables you to create alias names and/or lookups for usernames that don't appear in regular nodelists). To create the nodelist index, simply type INDEX on the command line. The program will display its progress and, when finished, will have created a file called NLINDEX.SL2 in your Searchlight data file directory. Note that the index utility checks to see if the current index is up to date by comparing the date it was last compiled against the dates of the nodelist files. If the index is up to date, the INDEX.EXE program will not recompile it. However, should you wish to force an index compilation when the index is up to date, add the parameter -F to the INDEX.EXE command line. You can eliminate certain netmail zones from a nodelist compile if you do not wish to have addresses in those zones available for lookup. To do so, specify one or more -N parameters, where N is the number of the zone you wish to exclude. For example, if you are compiling the Fidonet nodelist, but wish to exclude zones 2 through 6, you could type: INDEX -2 -3 -4 -5 -6 Performance A few notes on performance and disk space issues are in order here. The index utility creates a file which contains 24 bytes per node in the nodelist. The complete Fidonet nodelist, which typically comprises some 19 or 20,000 entries, will result in an index file of approximately 450K. The index program will require an area of disk space equal to the size of the final index file as a work area; therefore, at least 900K of disk space must be available in order to compile a Fidonet nodelist. The speed of the index utility may be important to you if you index large nodelists on a relatively slow system. The main factor that influences indexing speed is the amount of DOS memory available to the index program when it is run. For best results, run the utility in a DOS environment or DOS window with as much free memory as possible available. A typical 33mhz 386 PC with disk cache software installed and 640K of RAM available can compile a 20,000 entry Fidonet nodelist in about five minutes. 196 Netmail The source files (raw nodelists) must remain on your system for Searchlight's indexes to work. If the raw nodelist files are deleted, moved, or changed in any way, lookups via the index will become impossible until the index is rebuilt. Executing INDEX.EXE causes the index to be rebuilt only if there has been a change in the source files, so it's a good idea to execute the index utility nightly. Index Uses Searchlight's internal netmail procedures don't require that a nodelist index exist, but without the nodelist index you won't be able to see and confirm the names of the bulletin boards where netmail is being sent, so it's highly recommended that you do use an index. If you choose not to compile a nodelist index, you should be aware that Searchlight will only send netmail if the user sending the message has the "Unlisted Address" attributes, or if the netmail is a reply to an existing message. USING SEARCHLIGHT NETMAIL Once your netmail infrastructure is set up -- you've got events and procedures in place which use the NETMAIL.EXE and INDEX.EXE programs to transfer mail and build the appropriate index files -- it's time to run Searchlight 3.0 and actually read and create some netmail messages. The underlying goal of Searchlight's netmail system is simple: netmail is created and read with the same commands as regular mail in Searchlight BBS. In almost all cases, the same intuitive commands you already know how to use to send mail to other users on your system can be used to send netmail. The only time special commands are needed is when there is no way for Searchlight to make a determination itself as to what kind of message you are sending and where its destination is. Receiving Netmail Receiving netmail sent to you from a remote system is extraordinarily straightforward; in fact, no new procedures or commands are required at all. Searchlight simply presents netmail to you in your regular mailbox, along with your other mail, and you read netmail simply by reading your mail in Searchlight. You can easily end up with a mixture of regular mail and Netmail in your mailbox at the same time: Searchlight lets you deal with all of your mail the same way, regardless of its origin. Replying to Netmail In virtually all cases where you are reading a netmail message sent to you, you can reply in the usual fashion simply by selecting the "Reply" function from the menubar. At the "To:" prompt, where the name of the addressee appears, press Enter as usual, and then look for a netmail address and 197 Netmail bulletin board name to appear to the right of the name. For example, if you were replying to a message from Tim Rossiter on Searchlight BBS, you might see something like this: To : TIM ROSSITER @250:500/1 Searchlight BBS, Stony Brook, NY Notice that the netmail address (250:500/1) was inserted automatically and the name of the bulletin board was displayed for reference. If the name of the BBS were not listed in your nodelists (or if you did not create a nodelist index file), you might see the words "Unknown Address" instead; this usually doesn't indicate that there is a problem with the address, only that the name of the BBS is not known by Searchlight. If a netmail address does not appear, or if you get a message such as "User not on file", it's probably because your account does not have the required security attributes to send netmail replies. Either change your attribute level, or change the required attributes to send netmail in the CONFIG program. If you like, you can send carbon-copies of your reply to others, as with any reply. Then simply type your reply and save it. That's all that is required to reply to a private netmail message on Searchlight BBS -- the message is saved and will become netmail as soon as you run the NETMAIL.EXE utility to export it. You can also create private netmail replies to public echomail messages, and you do so the same way you send regular private replies to public messages: select "Mail" from the menubar when reading the public message. Again, you are able to press Enter at the "To:" prompt and will see the netmail address and bulletin board name if they are available. A few problems are possible when sending netmail replies to echomail. The way Searchlight determines the original address of an echomail message is by examining the "Origin" line on the message: in some cases, the origin line does not reflect a correct address. This is particularly true in conferences that have been gated from one network to another. You may not be able to enter an automatic reply to such messages, although you can still enter a netmail reply by manually typing the correct address with the "@" syntax, as we'll describe below. Originating Netmail There are several ways you can enter a new netmail message to someone that's not a reply to an existing message. In some cases, you will need to know the numerical netmail address of the BBS where you want to send the message, and in other cases, Searchlight can provide the address based on known data. Again, Searchlight's goal is to automate the process of sending netmail without requiring you to specify information explicitly. Let's look at various possibilities. Sending Netmail to a Sysop If the person to whom you are sending a netmail message is the SYSOP of a BBS, his or her name probably appears in your nodelist file, and 198 Netmail Searchlight can find the appropriate netmail address based on that name. If you select the "Mail" command from Searchlight's main menu and then select "Send" from the mail subcommands menu, and then type in the name of your addressee, you may see something like this: To : JOHN YOHE John Yohe @1:107:213 Fort Z BBS, Levittown, NY? Yes/No/Quit Searchlight discovered the name "JOHN YOHE" in your nodelist, and is asking you if this is the correct person and correct address. If it is, type "Y", and Searchlight will enter a message to node 1:107/213. If the information shown isn't correct, you can press "N" to see additional choices. What if John Yohe is also a member of your own BBS? The answer is that Searchlight will assume you want to send a local message. To override that decision, you need to tell Searchlight explicitly that you want to send netmail: you can do that either by using the "@" syntax outlined below, or by selecting a dedicated "Netmail Send" command from a menu, as we'll describe shortly. Sending Netmail to Others What if you want to send netmail to someone who is a user on a remote system, but not the Sysop? Searchlight won't be able to look up the person's netmail address, since their name doesn't appear in any listing. The only way to send netmail in such cases is to tell Searchlight what the netmail address is. One way to do that is to type an "@" sign after their name, followed by the address, like this: To : JOHN YOHE @1:107/213 The @ tells Searchlight that you are interested in sending netmail to the given address. You can use @ signs anywhere that you type a username, including carbon copy lines, and in the prompts that appear when you reply to messages or forward messages to users. You can also type the @ sign by itself, without an address after it: Searchlight will either try look up the address in the nodelist, or, if the lookup fails, will prompt you to enter an address on a separate line. (This is a good way to resolve conflicts when you have a local user with the same name as someone to whom you'd like to send netmail). Creating an Explicit Netmail Command While specifying netmail addresses via the "@" syntax is great for experienced users, an easy to use, menu driven program like Searchlight BBS should have a better way to ask for a netmail address. It does, and the way to access it is to set up a new command, "Netmail Send", on a menu within your BBS. Netmail send is a command you can use anytime you know you want to send a netmail message. The difference between the netmail send command and the regular send command is simply that the netmail send command assumes your message will be netmail; it doesn't check the local user database, and asks 199 Netmail you to type in a netmail address if no address can be found in the nodelist. The netmail send command is exactly like the regular send command with an "@" sign appended to the username, but doesn't require you to type in the "@" symbol. You can place a netmail send command anywhere you like in your menu structure, but the most obvious place to put it is on your MAIL menu, right after the regular send command. Here's an example: 1. Command Name .................. Netmail 2. Command Key ................... T 3. Description ................... Send mail via network 4. Minimum Access Level .......... 0 5. Maximum Access Level .......... 255 6. Require Security Attrib ....... 7. Exclude Security Attrib ....... 8. Require Preference Attrib ..... 9. Exclude Preference Attrib ..... 10. Help Levels ................... All 11. Command Number (1) ............ 131 12. Command Parameters (1) ........ /x /n You may notice that the only difference between this command and the regular mail send command is the /N, or Netmail, parameter given on line 12. When this command is executed and you type a name at the "To:" prompt, Searchlight immediately checks your nodelist file. If a match is found, Searchlight displays it and asks whether you would like to use the address shown. If no satisfactory matches are found, Searchlight prompts for a netmail address: Address: Type the actual address (Zone:Net/Node or Zone:Net/Node.Point) here. If the address is valid, Searchlight will accept it and display the name and location of the BBS if possible. Creating Netmail Routing Addresses So far we've seen that Searchlight can obtain a netmail address from another message, from a nodelist, or by asking you to type in an address manually. One other way that a netmail address can be supplied is by attaching it to a name in your Searchlight user file. Every user account on your BBS has room for an optional netmail address; by default, that space is blank for all users when you install Searchlight 3.0. Use the command 2-Sysop/Options/Info to associate an address with any user account, by typing the netmail address (Zone:Net/Node[.Point]) on the last input line shown. 200 Netmail Associating a netmail address with a user account in this way creates the effect of routing that person's messages to their netmail address automatically. That is, anytime someone tries to send a message or forward a message to that user, Searchlight automatically creates netmail to the user's address. This is true whether the message is entered via a normal Mail/Send command or a Netmail send command. Why set up a routing address? There are several reasons for doing so. If a particular person is a member of your BBS but calls infrequently, a routing address enables him to have his private mail sent to another bulletin board which he uses more often than yours. If a person has several different netmail addresses but one address is the preferable one, you could set up that address as his or her routing address. Then Searchlight will find the preferable address immediately instead of scanning through many options. A particular benefit of routing addresses is that it allows you to create known netmail addresses for users who don't appear in your nodelists. For example, if a user named ED SMITH had a netmail address of "250:500/1" associated with his username, Searchlight would automatically know where to send Ed Smith's mail. Otherwise, someone who wanted to send netmail to Ed Smith would need to know his netmail address and enter it manually each time. It should be noted that mail sent to a routed address exists inside Searchlight as regular mail until it is exported; Ed Smith could, for example, call your BBS and read any netmail messages to him that have not yet been exported to your netmail directory. Also, a user who doesn't have the required security attributes to send netmail can send Ed Smith a message, but that message remains local to your BBS and does not become a netmail message. Routing Address Edit Most sysops will prefer to assign routing addresses manually. However, if you prefer, you can enable your users to type their own routing addresses into your system. To do so, specify appropriate security attributes on line 12 ("Routing Address Edit") in the Netmail Setups configuration screen. ADDITIONAL NETMAIL CONSIDERATIONS Netmail Scope Netmail messages can only be created inside of Searchlight BBS. You cannot create a netmail message through an offline reader program or by sending a message with SLMAIL or a similar external utility. You can receive netmail messages through an offline reader, but replies to such messages will not become netmail replies. 201 Netmail Bad Messages Occasionally, you may see a message in your mailbox that starts with a line like this: ---- NETMAIL Message For Unknown User: The netmail utility generates this message when it tries to import netmail that is addressed to a user who is not a valid name in your user file. The unknown name is shown, followed by the entire text of the message. Bad messages are often the result of misspelled usernames, or titles (such as "Zone Coordinator") that may have been appended to a username. If possible, forward the message to the appropriate user. Otherwise, delete it or handle it as you see fit. Listed vs. Unlisted Addresses Searchlight considers any address which is found in an existing message or in the user file as a routing address to be a listed address. This distinction is important if you use security attributes to prevent your users from sending messages to random, unlisted addresses. It is possible, though unlikely, that an incoming netmail or echomail message contains an incorrect address or an address which has become obsolete since the mail was sent. In such cases, Searchlight will permit users to reply, which could result in an improperly addressed outgoing message. (Improperly addressed messages are normally not a problem in most networks as long as they are kept to a minimum). You should also consider the possibility of users entering unlisted or improper addresses into their user account, if you allow routing address editing. Origin Addresses When Searchlight's netmail utility exports messages, it automatically picks one of the addresses you specified in the CONFIG program as the origin address for that message. Which of your addresses are used depends on the zone number of the outgoing message: Searchlight tries to match the zone of the origin address to the zone of the destination address. If your system had an SL_NET address of 250:500/1 and a Fidonet address of 1:107/252, Searchlight would assign the former address as the origin to messages destined for zone 250 and the latter for addresses in Fidonet zone 1. If an exact match is not possible, but the destination address is somewhere inside Fidonet (zones 1 through 7), then Searchlight tries to pick as the origin address any address which is also in zone 1 to 7. If that fails, then your Primary Address is used as the default. 202 RIP Graphics INTRODUCTION TO RIP GRAPHICS Searchlight supports RIP Graphics, a new kind of terminal protocol that allows your BBS to take advantage of features like high resolution graphics, mouse support, fonts, icons, and more. RIP graphics are generated by a special language called RIPscrip. What is RIPscrip? One way to think of RIP graphics and RIPscrip is as an alternative to ANSI graphics. Most bulletin boards use some kind of ANSI graphics today; Searchlight, in particular, takes advantage of ANSI screen controls to a great extent. ANSI is what allows Searchlight to do full screen interfaces, menubars, colors, and cursor positioning on a remote terminal with ANSI support. You can also make your own colorful ANSI files using products like THEDraw(tm) or Laughing Dog(tm). RIP is a new kind of terminal protocol. While RIP is compatible with ANSI, it offers far more functions than ANSI alone provides. Among them are: o Full screen graphical primitives (Box, Circle, Line, etc.) o Specialized fill patterns o Full color manipulation o Multiple scalable fonts o Simultaneous text and graphics windows on the screen at once o Full mouse support for point and click operation o Remotely stored bitmap icons for detailed, high-speed graphics o Full clipboard copy and paste ability o Custom line-styles for technical drawings, etc. Using RIPscrip graphics on your Searchlight BBS, you can show visually stunning graphics, offer full point and click access to your system, and in many cases, speed up throughput of your user's on-line connect times. In other words, RIPscrip graphics can often be transmitted faster than ANSI graphics. How Searchlight Supports RIP RIP graphics can only be displayed when callers use terminal programs such as RIPterm, which support the RIPscrip language. Fortunately, RIPscrip is designed to be a standard platform for bulletin board systems, and will soon be available on a number of different terminal programs. Searchlight is RIP aware. When you call using a RIP compatible terminal program, Searchlight sends a special sequence of commands to the terminal that allows it to detect the fact that the terminal has RIP capability. There are two basic ways that Searchlight supports RIP graphics, once a RIP terminal is detected: o Searchlight uses RIP commands internally for certain features o Searchlight displays external RIPscrip files instead of ANSI files, when available 203 RIP Graphics Searchlight's internal RIP support allows it to set the terminal's fonts and screen size automatically. In addition, Searchlight supports remote mouse usage by sending RIP commands to the remote terminal that cause it to make mouse areas active. When using Searchlight BBS with a RIP compatible terminal, mouse support is available in most areas of the program including menus and full screen editing displays. Searchlight's internal commands do not generate high resolution graphics or use icons. However, Searchlight gives you the ability to use external RIPscrip files to add those features to your BBS, the same way you'd add advanced ANSI features. When RIP mode is enabled, Searchlight searches for text files ending in .RIP instead of .ANS or .TXT. You can make .RIP files for menus, include files, your login and logoff screens, and anywhere else that Searchlight displays a TXT or ANS file. In fact, since RIPscrip is plain text, you can even load RIP graphics into messages. If no RIP file is available for a particular menu or display screen, your existing ANS or TXT file is used instead. RIP graphics screens are displayed properly only on a remote RIP terminal. Your local screen will show only the RIP command sequences. Consequently, your BBS can support high resolution RIP screens even if your local terminal does not support graphics. How can I create RIP files? RIP graphics files are created with special programs such as RIPaint, available from TeleGrafix Inc. RIPaint produces text files ending in .RIP, which you can load into your BBS. Searchlight displays the .RIP files instead of text or ANS files when searching for an external text file. If you would like more information about software to create custom RIP graphics screens, or if you are a developer and would like information about adding RIP graphics support to your online product, please contact Searchlight Software at our technical support number. Setting up Searchlight for RIP Support By default, Searchlight does not check for RIP terminals or support RIP features. To enable RIP support, simply turn on a switch inside the CONFIG program (General Setup Menu #2): 15. Enable RIP Graphics ........... Yes Searchlight will now automatically detect RIP terminals and use RIP features when appropriate. 204 RIP Graphics RIPscrip Guidelines RIPscrip contains a rich set of commands that can make a RIP terminal display graphics, fonts, change screen sizes, relocate screen windows, and more. Since Searchlight operates in text mode when it is not displaying a RIP file, RIP files should, in general, avoid using commands that would render Searchlight's text unreadable (unless that effect is desired, such as in menu screens). In order to ensure that its text is readable, Searchlight always resets the RIP terminal's text window and font size whenever it clears the screen. RIPscrip files can contain mouse areas and mouse controls in addition to high resolution graphics, icons and other features. Typically, you will use mouse areas in menu display files, and have the mouse areas return a keystroke to Searchlight indicating the correct menu choice. For example, if F is the key to press to enter the files system on your main menu, you could generate a RIPscrip menu with a mouse button for files access; the mouse button would type the letter 'F' when pressed. It is best to use character style menus in Searchlight when using RIPscrip menu screens. Since Searchlight provides its own mouse support with built in menubar menus, and may support other RIP features internally, a special command is included in the menu setup screen to disable Searchlight from producing mouse areas for its internal menus: 14. Use RIP Mouse Areas ........... Yes Set this option to "No" if you are using RIPscrip files to generate your own menus with mouse areas. Otherwise, leave it set to "Yes". The "No" setting prevents Searchlight from interfering with mouse areas that may have been created by your external RIPscrip file. Additional Comments Searchlight provides RIP mouse support and gives you the ability to use Searchlight as a "front end" to display RIP graphics created with an external utility such as RIPaint. As we mentioned earlier, Searchlight 3.0 does not use graphical RIP features internally. However, future versions of Searchlight BBS will have much more internal RIP support, and will create graphics screens by default for many menus even without external RIP files. 205 Using DESQview USING SEARCHLIGHT WITH DESQVIEW Introduction DESQview is the multitasker of choice for use with Searchlight BBS, due to its low overhead and efficiency when running DOS based communications programs. By running DESQview on your 286, 386 or 486 PC, you'll be able to have multiple Searchlight nodes active at the same time, allowing your BBS to support multiple incoming telephone lines and providing you with a means of logging in locally while keeping your incoming lines active for calls. The following remarks will help you to set up an effective multiline Searchlight BBS system on a PC with at least 1 megabyte of memory. This is not an exhaustive review of DESQview's features, so please read your DV manual, especially the sections on memory usage and configuration, in order to get the most out of it. Searchlight also supports Windows and OS/2 multitaskers. If you prefer to use Windows or OS/2, this information will still provide you with general guidelines, but you'll need to follow your Windows or OS/2 documentation for exact commands and settings. You can also run multinode Searchlight BBS installations from a LAN; for more information, see p. 43) Environment Setup Before installing DESQview, it is best to remove any programs that use serial ports, especially serial mouse drivers. Even if your mouse uses COM3 or COM4, it can interfere with modems connected to COM1 and COM2. On 286 systems, run XDV (extended memory version), which loads DESQview into the first 64K of extended memory. If you do not have extended memory but you do have expanded memory, you can usually configure your RAM board to give some extended memory instead. For 386 systems, you need to install QEMM from your CONFIG.SYS file, then run DESQview; see your Desq manual for more specific installation information. Make sure your Searchlight nodes are set up as explained in the Multinode Setup portion of this manual (see p. 43). Note the locations of your CONFIG files for reference while setting up DESQview. Interrupts Interrupts are an important issue whenever 3 or more remote nodes are configured for use on one machine. The standard IBM PC has only 2 interrupts allocated for communications ports (COM1 and COM2, which use interrupts 4 and 3 respectively). In many cases, hardware adapters which support COM3 and COM4 simply re-use these interrupt lines, making those ports unsuitable for use in a multitasking environment. What you need is an adapter that's capable of selecting an alternate interrupt number, such as 2, 5 or 7. The Everex Magic I/O is one such adapter that's suitable for use with Searchlight. You can also overcome the 207 Using DESQview two-port limitation by means of an intelligent DigiBoard hardware product; DigiBoards work with their own on-board processors instead of interrupts, and are ideal for large installations. See Appendix H of this manual for more information on DigiBoard installation. Local nodes which do not use a modem or an interrupt line require no special treatment. DESQview Setup Access the DESQview setup program by typing 'Setup' from the DV directory. Select the advanced options. Of interest are the mouse and performance setup sections. Mouse: If you have a serial mouse, you may not be able to use it with DESQview since you will probably want to use your available serial ports and interrupts for Searchlight. A bus mouse can be used if available, as long as the bus mouse adapter does not use interrupts which you may need for COM ports other than COM1 and COM2 (on systems running 3 or more lines). Performance: We recommend you allocate between 4 and 8 clock cycles for foreground and background tasks. More cycles may increase efficiency, but also increase "choppiness". Fewer cycles reduce choppiness but decrease overall throughput. It is generally best to use the same value for foreground and background. The more nodes you install, the smaller you should make the performance numbers. On a 10 node system, we recommend using 1 or 2 clock ticks. Select "Yes" for "Optimize Communications". This will give you better performance for the BBS nodes. Select "No" for "Allow Swapping of Programs". Since communications programs are interrupt driven, they cannot be swapped to disk. Assuming you are interested primarily in running Searchlight, swapping can be turned off. (Note: When FOSSIL drivers or DigiBoards are used, it becomes possible to swap Searchlight in and out of memory. However, the performance penalty for doing so is usually too large to make swapping a practical option. If your computer is a '286, you may want to experiment with this option if you need to run more than 2 nodes). Program Setup Set up each Searchlight BBS node as a separate entry in DESQview, using DESQview's Add Program feature. DESQview presents a menu of Basic options as you create each entry, and provides Advanced options by pressing the F1 Key. Basic options should be configured as follows: Memory: Try to allocate at least 275K per node. You can use a minimum of 250K if necessary, but performance is somewhat better with more memory 208 Using DESQview available. Watch out for "out of memory" errors (code 202 and 203) if you allocate too little RAM. Program: Specify SLBBS.EXE as the program to run. If necessary, give the full pathname (such as C:\SLBBS\SLBBS.EXE). If you want to be able to see ANSI graphics locally, you need to run Searchlight from a batch file and load the DVANSI driver program before Searchlight. However, this uses significantly more RAM, and should not be done unless you have at least 240K available for the window. Directory: Give the home directory for that node (location of the CONFIG.SL2 file). Make sure each node has a separate home directory. Writes Text Directly to Screen: N Make sure all nodes are configured for BIOS screen writes. This will allow Searchlight to run in the background and in small windows under DV. On 386 PCs, direct screen writes can be used as long as you tell DESQview to Virtualize Text. Displays Graphics Information: N Virtualize Text/Graphics: N Choose "N" if you have Searchlight configured for BIOS operation. If you prefer to configure Searchlight for direct screen writes, you should enter "T" here. Uses Serial Ports: 1,2 or Y For each node, give the serial port (1 or 2) which that node will use. If the node uses a standard serial port other than COM1 or COM2, specify "Y" for this option. On nodes that use external drivers (i.e. DigiBoard or FOSSIL drivers) this setting is unimportant. Requires Floppy Diskette: N After configuring the Basic options, press F1 to access the "Advanced Options" screen. Of the fields on this screen, the majority should be left in the default state. Below are the fields that apply to Searchlight, and the recommended values for each: Can Be Swapped Out: N Interrupt driven communications programs should remain in memory at all times. Swapping is possible if you use a DigiBoard or FOSSIL driver, but is impractical; see note above. Uses Its Own Colors: Y Searchlight uses its own display colors. Runs in Background: Y Share CPU when Foreground: Y 209 Using DESQview These options will allow you to multitask and run all nodes at the same time. Uses Math Coprocessor: N Share EGA When Foreground/Zoomed: N Check your DESQview manual for more information about the other options that are displayed. Memory Issues Searchlight is one of the most memory-efficient programs you'll find in the BBS environment. With a mere 250K memory requirement, it's designed to run effectively in small DESQview windows. However, you may find that DOOR programs, front end mailers, utilities, and programs you run as events may require more memory than Searchlight. Since Searchlight requires about 50K for its in-memory kernel when executing a DOOR program, external protocol, or event, the actual amount of RAM available to those programs will be equal to the size of the DESQview window minus 50K, minus any RAM resident programs that might reside in that window (such as DVANSI or a front end mailer). On 386 and 486 PCs, DESQview is capable of running programs in extended 386 memory (which is actually converted to expanded memory by QEMM). That means that with a 386 or 486, you can increase the amount of RAM available to your windows simply by purchasing more system RAM for your computer. DESQview 386 automatically makes the RAM available and can open windows of up to about 600K in size. The only limitation is that DESQview cannot overlap any of your base 640K ram with expanded memory. That means that your first 640K of memory can be used to run either two very small windows, or one large window, or a combination of a large window and a memory resident program (like a RAMdisk or disk cache). Use DESQview's Memory Status (MS) program to assess your system's available RAM. On 286 systems your choices are more limited. In general, DESQview can run programs only in the 640K base memory, which normally limits you to two windows of around 250K each in size. Expanded memory can be put to good use as RAMdisks or disk cache memory; the first 64K of extended memory can be used to run DESQview itself. If you do need to run larger windows, it's possible if you have Enhanced Expanded Memory (EEMS) hardware. DESQview can run programs in EEMS memory, but generally you'll have to arrange your memory map so that your EEMS memory provides some of the base 640K RAM in your PC. Otherwise, there will probably not be a large enough mapping area to provide the 250K necessary to run Searchlight. For more information about this subject, see your DV manual. Performance Issues The more RAM that's available in your system, the better performance you can get out of Searchlight BBS. But just having the RAM available isn't 210 Using DESQview enough. There are three main ways to use additional RAM memory on your system wisely, and each can dramatically improve the speed of your BBS. o Allocate more RAM to Searchlight and increase the size of the overlay buffer. When Searchlight is given more than its minimum RAM requirement, it keeps frequently needed file information in memory and builds tables and buffers that help reduce the number of disk accesses required for many operations. Additionally, more DOS memory means you can increase the size of your overlay buffer, which decreases the amount of disk reads Searchlight needs to perform as it runs. Searchlight can profitably use approximately 70-80K of memory above its minimum requirement. Beyond that amount, the memory will be wasted unless you need it for doors or events. o Use a RAM cache and allocate as much memory to it as possible. RAM cache software is by far the most valuable utility you can add to your system. Even the smallest disk caches will improve performance a great deal; the larger the buffer, the fewer disk reads that need to be performed, and the faster your system will run. Cache software with a buffered (staged) write mode is ideal for use with Searchlight, and will speed up your system even more. Always use expanded memory, not extended memory, with disk cache and RAM disk software. It is best to avoid the use of extended memory entirely, except for running DESQview itself. That's because the procedure that is required for the CPU to access extended memory can cause it to lose track of pending interrupts, and thus pending data coming in from the serial ports. When purchasing memory for a 286, always buy an expanded memory board. The extended/expanded distinction doesn't apply to 386 and 486 PCs. o Install a RAM disk and use it to store frequently used files, such as Searchlight's EXE and OVR files. When storing Searchlight files on a RAM disk, be sure to update the data path lines in your CONFIG files to reflect the new drive/directory paths. Don't store data files (files that are written to and change during the program's execution) on RAM disks. The recommended files for RAM disk storage are STRINGS.SYS, CHAT.SL2, BBS.EXE and BBS.OVR, FILES.EXE and FILES.OVR, and the menu (*.MNU) files. Note that if your overlay (OVR) files are all on RAM disk, it's generally not necessary to load them into EMS memory, since disk access from a RAM disk is nearly as fast. Fine Tuning Best efficiency can be obtained if you use Searchlight's modem output buffering (Output Buffering Factor = 32) on all nodes that have standard serial ports. Output buffering lets Searchlight dump output into a holding area in RAM, which is then spooled out to the modem as a background task. The spooling takes place as an interrupt and is more or less independent of DESQview's task switching. 211 Using DESQview When using more than 2 nodes, we recommend an intelligent DigiBoard hardware device for communications. See Appendix H for more information. When you watch Searchlight locally, the output may appear "choppy" on screen; that is, it will start, stop, then start again, etc. However, the remote user will see a much smoother, steady flow of characters, especially at lower baud rates (2400 baud and below). So you should be aware that even if you see a choppy, hesitant display at your end, it does not mean your users are seeing the same thing. Either ask your users, or log in from a remote terminal yourself, to see the difference. Set "Buffer Door Programs" to Yes, for best performance when running doors. Should incompatibilities or system errors arise when running Door programs, you can disable output buffering during Door programs by setting this option back to No. If you use a high speed modem on one node and a slower modem on the other, you may want to adjust the performance (clock cycles) and allocate more CPU time to the quicker modem. ASCII uploading to the message editor places the largest load on the system in terms of input and output. That's because Searchlight echoes characters as they are typed, thus creating a two way flow of information. We recommend using Xmodem protocol uploads if ASCII uploads present a problem. Many RS232 ports are not designed for speeds greater than 9600 baud. If you plan to use high speed modems, you may want to purchase high speed UART chips (16550 chips). Some standard UART chips can lose characters at speeds above 9600. Note that the speed of output is also dependent upon your CPU speed. Slow computers may not be able to provide maximum throughput, regardless of the UART chips used. 212 Appendix A Activity Log APPENDIX A USING THE ACTIVITY LOG Searchlight's LOGIN program can be configured to generate a continuous record of all logins and logouts to the system. The generation of the activity log is controlled by placing a log filename in the CONFIG program (see "Pathnames Setup", p. 25) When logging is active, Searchlight generates a text log file (typically called ACTIVITY.LOG). Each time a user logs into the BBS, and each time the BBS resets the modem after a call, one line of data is added to this file. You can view the logfile with the TYPE command or with a word processor, or other software that displays text files. The data in ACTIVITY.LOG consists of lines of two types. The line generated when a user logs in to the BBS contains six or seven pieces of information, arranged in fields, and looks like this: Y 911015 1745 24 * MICHAEL KLEIN, Nissequoge, NY The leftmost character, Y or N, shows the status of ANSI graphics when the user logged in; N means no graphics, Y means color or monochrome graphics. This is followed by a six-character field containing the date of the login, in YYMMDD (year, month, day) format. The next four-space field contains the time of the login in the format HHMM (hour, minute). The time is given as a 24-hour time. The next field gives the baud rate for the logon; 3 means 300 baud, 12 is 1200, etc. An 'L' in this field, right-justified (i.e. preceded by one space) indicates that the login was from the local terminal rather than via modem. Immediately following the baud rate is either an asterisk (as shown above), a "+" sign, or a "-" sign. An asterisk indicates that this is the first logon by a new user; a "+" sign indicates an "invisible" login (by a Sysop or CoSysop), and a "-" indicates a regular visible login by an established user. The remainder of the line contains the user's name, terminated by an end of line character sequence (CR/LF). In the case of a new user, the user's name is followed by a comma and then the user's location, as show above. The location information is recorded only on a user's 1st call. Each of the fields is followed by a single blank space, as shown in the example line above. In the date and time fields, numbers less than 10 will appear with leading zeros. Upon resetting after a call, Searchlight logs a termination line to the activity file. The terminate line contains only the time and date fields, in the same format as above: 911015 1822 The data is preceded by two blank spaces. This serves to align the date and time with the dates and times in the login lines, and to mark the line as a terminating log entry. 213 Appendix A Activity Log These two lines together: Y 921015 1745 24 * MICHAEL KLEIN, Nissequoge, NY 921015 1822 indicate that a new user named MICHAEL KLEIN signed on to the BBS at 5:45pm on October 15th, 1992. He called at 2400 baud and selected ANSI graphics mode at login, and he logged off at 6:22pm. Here's a printout of what a small section of an activity log file might look like: ------------------------------------------ Y 921015 1745 L + SYSOP 921015 1757 Y 921015 1855 96 - EUGENE CHOI 921015 1924 N 921015 1943 24 * TABBY SHANK, Cleveland, OH 921015 1947 Y 921015 1952 24 - CLIFF HELLER 921015 2009 921015 2015 N 921015 2039 96 - GUEST 921015 2042 Y 921015 2046 24 - KYLE SILFER 921015 2104 N 921015 2113 96 * CHRISTINA MARSIELLO, Brooklyn, NY 921015 2144 ------------------------------------------ Note that it's perfectly possible, as shown in the example, to have two (or more) terminate-type lines in a row. Since the line is written whenever Searchlight resets, it can occur twice if a caller connects but hangs up before logging in. Terminate type lines not immediately preceded by login lines may simply be ignored. Using The Activity Log File There are many ways in which the ACTIVITY.LOG file can be used. As you've probably guessed, the format of the file is designed to allow it to be read by programs rather than humans, although it's not quite so cryptic that you can't read it directly. Programs which read the ACTIVITY.LOG file could compute many statistics about the operation of your BBS. Once you've accumulated several weeks or months worth of information, you could compute such things as: o total number of calls within a given period of time o number of new users added o percentages of callers calling at specific baud rates o average duration of calls o average number of calls per day or week o average number of users requesting ANSI graphics 214 Appendix A Activity Log A sample program which reads the ACTIVITY.LOG file, called SLSTAT, is included on your SLBBS distribution disks; you can also write such programs yourself, using the above information as a guide for reading the log file. ACTIVITY.LOG also gives you a permanent record of all calls made to your system. The DOS FIND command, or a similar utility, can be used to locate specific information in the log file. For example, the DOS command FIND "JOHN MURROW" ACTIVITY.LOG will search the ACTIVITY.LOG file and print out all lines which contain the name JOHN MURROW (this would be all the times that JOHN MURROW logged in to the system). The command FIND "*" ACTIVITY.LOG will show the first logins of all new users (since the last time the log file was cleared). FIND is a program that comes with DOS; it should be available on the DOS disk you received with your computer. Since the log file will grow continuously, you'll need to delete it every once in a while. The best scheme, if you wish to keep an ongoing record of calls, is to make a backup copy of ACTIVITY.LOG periodically (every month, six months, etc.) and store the backup on floppy disks or tape. Then simply delete the ACTIVITY.LOG file from your disk; a new file will be created with the next login. 215 Appendix B Error Messages APPENDIX B GUIDE TO ERROR MESSAGES Searchlight BBS is designed in such a way that the most common kinds of errors that occur are displayed on your screen in English, and don't cause your BBS to crash or go down. Occasionally, however, you may encounter a problem that causes Searchlight to produce a numeric error message, sometimes causing the software to terminate. You'll find that these types of errors are usually related to systemwide problems like bad DOS filenames or lack of file handles. If you encounter a numeric error message, you should write down both the error number and the error address, if it is displayed. Then consult the list below for further information. If you get an error message that's not on this list, or if you can't resolve the problem, contact Searchlight Software with the complete error message and description of the problem. Errors 2 and 3 (File/Path does not exist) This error indicates that Searchlight is trying to read a file on the disk, and the file does not exist. There are several possible causes: (1) The Program Path specified in the CONFIG program points to an invalid pathname, or the program files do not exist in the specified directory. (2) A pathname or filename specified in the CONFIG program does not exist, or is an illegal name. (3) An illegal or nonexistent pathname was specified in a menu file. Check all of your CONFIG settings carefully, especially those on the Pathnames Setup screen. A missing or misspelled pathname or filename is the usual cause of these errors. Error 4 (Too many open files) This message will occur the first time you try to execute Searchlight or the CONFIG program if your system doesn't have enough file handles available. The solution to this problem is simple; you must insert the line "Files=30" (or higher) into your CONFIG.SYS file, as discussed in the installation instructions (see p. 7). Be sure to reboot your system after editing your CONFIG.SYS, in order to install the new configuration. Error 100 (Disk read error) This error will occur if a data file on disk is corrupted or otherwise damaged. If Error 100 occurs when trying to log in, read a message, or access a user record, it indicates a problem with one or more of the Searchlight data files. Usually, you can recover your data files by taking the following steps: (1) Exit from Searchlight and type CHKDSK/F at the command prompt; 217 Appendix B Error Messages (2) For a problem that's related to Searchlight's user file, run Searchlight and use the User/Balance command; (3) For a problem that's related to a particular message subboard, run the CONFIG program and execute the subboard repair functions (see p. 53); (4) For a problem related to a file area, run the Files program and execute the 2-Sysop/Balance command. If you cannot run the SLBBS and log in normally, you will usually be able to run the BBS or FILES module directly by typing those commands at your DOS prompt. Error 101 (Disk or Directory is full) This error occurs if Searchlight must create a file (such as when you create a new subboard or file directory or when you first set up Searchlight BBS) and the disk or directory is full. The solution is to delete some files or create a new directory. Error 202 (Stack Overflow) Error 203 (Heap Overflow) These errors indicate an "out-of-memory" condition. Usually this is caused by a lack of available memory; to correct the problem, increase the amount of memory available by reducing the size of RAM-disks and other memory resident software. Stack Overflow errors sometimes occur when accessing the User file (in the main BBS program) or a file directory file (in the FILES program) if the binary tree structure is corrupted or badly "unbalanced". If you get this error, try "rebalancing" your user or directory files (using the Balance commands in the Files and BBS programs). If Stack or Heap Overflow messages persist, please contact us. SHARE Errors Multiuser versions of Searchlight BBS require that SHARE.EXE or an equivalent operating system function be loaded when running multiple nodes. If there is a problem with a Share call, Searchlight may report one of the following messages: Share not detected. Load SHARE.EXE or equivalent. Searchlight could not perform a Share call (DOS function 5C) successfully. The most likely cause is that SHARE is not loaded. Run the program SHARE.EXE from your AUTOEXEC file when you boot your computer, and before loading Searchlight BBS. SHARE.EXE is provided with DOS 3.1 and later. See your DOS manual for more information. 218 Appendix B Error Messages SHARE buffer overflow Share did not have enough memory to handle the lock requests made by Searchlight. Increase Share's memory allocation by using Share's /F: and /L: startup parameters (recommended values if you get this error message are /F:4096 and /L:50). LOCK error on file UNLOCK error on file These messages indicate a general breakdown of the lock/unlock system. This can happen if one node on your BBS locks a file, and then crashes, or otherwise keeps the file in a locked state. The recommended recovery is to reboot your system. If these errors are consistent, you may have a problem with the way Share calls are handled on your system. Other Errors Other errors in the range 5-6, 16-17, and 150-162 are DOS errors indicating disk or device access errors. Check your disk, files, and directories and try the command again. If other errors occur, please write down the exact error message as well as the exact conditions that caused the error, and contact us. Be sure to include your SLBBS version number, DOS version number, and the equipment you use. We will try to diagnose the problem as quickly as possible. 219 Appendix C Automatic Events APPENDIX C AUTOMATIC EVENTS Searchlight's Login program provides a flexible event feature. An "Event" is a DOS command, executable program, or BATCH file that's set to execute at a given time and date. Searchlight scans the list of events when you start it up, and executes them at the proper time. Events execute only when Searchlight is offline -- waiting for a call at the initial display screen. To ensure that the system will actually be waiting for a call at the moment that an event is to be executed, Searchlight will adjust the time limit of a user's session (but not a user's daily time limit) when necessary, and warn a user logging on if an event will occur shortly. While the event is in progress, Searchlight issues the "local init string" to the modem, causing it to keep the telephone off hook (busy) during the time it takes to execute the given procedure. Setting Up The EVENT.DEF File Events are configured by creating a text file called EVENT.DEF in your BBS system's home directory. The EVENT.DEF file takes three or four fields per line, separated by spaces, like this: [date]