Maximus System Operations Manual Version 3.0 Lanius Corporation Lanius Corporation, Kingston, Ontario, Canada Copyright (c) 1989, 1995 by Lanius Corporation. All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or by any information storage or retrieval system without the prior written permission of Lanius Corporation. Maximus and Squish are trademarks of Lanius Corporation. MS-DOS, Windows, Windows 95 and Windows NT are trademarks of Microsoft Corporation. IBM, PC-DOS and OS/2 are trademarks of International Business Machines Corporation. Hayes is a trademark of Hayes Microcomputer Products, Inc. V.FC is a trademark of Rockwell International. MD5 is a trademark of RSA Data Security, Inc. BNU is a trademark of Unique Computing Pty Ltd. X00 and SIO are trademarks of Raymond L. Gwinn. All other trade names are trademarks of their respective holders. Contents 1. Introduction ............................................1 1.1. About Maximus.......................................1 1.2. System Requirements.................................2 1.3. Typographical Conventions...........................3 1.4. Ordering a Printed Version of this Manual...........4 1.5. Ordering Maximus for Commercial Use.................4 2. Maximus Overview ........................................5 2.1. Waiting for Callers.................................5 2.2. Logging On..........................................5 2.3. Command Stacking....................................6 2.4. Guest Accounts......................................7 2.5. The Main Menu.......................................7 2.6. The Message Section.................................9 2.7. The File Menu......................................21 2.8. The Change Setup Menu..............................25 2.9. The SysOp Menu.....................................28 2.10. The Chat Menu.....................................28 2.11. The Off-Line Reader Menu..........................29 3. Installation ...........................................31 3.1. Step 1: Unpacking the Distribution Files...........31 3.2. Step 2: Running the Installation Program...........32 3.3. Step 3: Configuring your Modem.....................33 3.4. Step 4: Installing Communications Drivers..........34 3.5. Step 5: Editing Configuration Files................37 3.6. Step 6: About Control Files........................39 3.7. Step 7: Compiling the Control Files................40 3.8. Step 8: Starting Maximus...........................40 3.9. Step 9: Support for Remote Callers.................42 3.10. Step 10: Miscellaneous Information................51 4. Customization ..........................................53 4.1. Events and Yelling.................................53 4.2. Access Control: Classes, Privilege Levels and Locks55 4.3. Display Files: *.mec and *.bbs.....................62 4.4. Message Areas and File Areas.......................64 4.5. Maintaining File Areas.............................70 4.6. Barricades and Extended Barricade Files............77 4.7. Menus..............................................79 4.8. QWK Mail Packing...................................81 4.9. Multilingual Support...............................82 5. Maximus Subsystems .....................................85 5.1. Waiting for Callers Subsystem......................85 5.2. Local File Attaches................................86 5.3. QWK Mail Packer....................................88 Contents iv 5.4. RIPscrip Support...................................92 5.5. User Expiration and Subscriptions..................94 5.6. Message Tracking System............................95 6. External Programs .....................................105 6.1. Execution Methods.................................105 6.2. Swapping..........................................106 6.3. Errorlevel Batch Files............................106 6.4. Restarting After Errorlevel Exit..................107 6.5. External Program Translation Characters...........109 6.6. Running Doors.....................................112 6.7. On-Line User Record Modification..................114 6.8. Doors and OS/2....................................115 7. Multinode Operations ..................................117 7.1. Installation......................................118 7.2. Multinode Chat Operation..........................121 7.3. Master Control Program............................123 8. Utility Documentation .................................125 8.1. ACCEM: MECCA Decompiler...........................125 8.2. ANS2BBS/MEC: ANSI to MEC conversion...............126 8.3. CVTUSR: User File Conversions.....................127 8.4. EDITCAL: Call Modification Utility................128 8.5. FB: File Database Compiler........................129 8.6. MAID: Language File Compiler......................132 8.7. MAXPIPE: OS/2 Redirection Utility.................134 8.8. MECCA: Display File Compiler......................135 8.9. MR: Maximus Renumbering Program...................136 8.10. ORACLE: Display File Viewer......................137 8.11. SCANBLD: *.MSG Database Builder..................138 8.12. SILT: Control File Compiler......................141 8.13. SM: Session Monitor..............................142 9. REXX User File Interface ..............................145 9.1. Introduction......................................145 9.2. Function Descriptions.............................146 9.3. Accessing "usr." Variables........................153 10. Introduction to MEX Programming ......................161 10.1. About MEX........................................161 10.2. MEX Road Map.....................................161 10.3. Creating a Sample MEX Program....................162 10.4. Compiling MEX Programs...........................165 10.5. Running MEX Programs.............................166 11. MEX Language Tutorial ................................169 11.1. Program Development Cycle........................169 11.2. Elements of a MEX Program........................171 11.3. Variable Declarations............................174 11.4. Variable Scope...................................178 11.5. Preprocessor.....................................179 11.6. Calculations and Arithmetic......................180 Contents v 11.7. Displaying Output................................185 11.8. Flow Control.....................................187 11.9. Function Calls...................................194 11.10. Arrays..........................................206 11.11. Structures......................................214 11.12. Casts...........................................223 11.13. Further Explorations in MEX.....................225 12. MEX for C and Pascal Programmers .....................227 12.1. Comments.........................................227 12.2. Include Files....................................227 12.3. Blocks...........................................227 12.4. Function Definitions.............................227 12.5. Types............................................229 12.6. Variable Declarations............................229 12.7. Function Prototypes..............................229 12.8. Function Return Values...........................229 12.9. Strings..........................................229 12.10. Compound Statements.............................230 12.11. Arithmetic, Relational and Logical Operators....230 12.12. The for Statement...............................231 12.13. Arrays..........................................231 12.14. Pointers........................................231 12.15. Pass-By-Reference Arguments.....................232 12.16. Variable-Length Arrays..........................232 12.17. Structures......................................232 12.18. Run-Time Library Support........................233 13. Interfacing MEX with Maximus .........................235 13.1. User Information.................................235 13.2. Message Area Information.........................236 13.3. File Area Information............................237 13.4. Changing Message and File Areas..................237 13.5. Displaying Output................................237 13.6. Retrieving Input.................................238 13.7. File I/O.........................................239 13.8. Menu Commands, Displaying Files and External Programs .......................................................239 13.9. Download Queue...................................239 13.10. Other Functions.................................240 14. MEX Compiler Reference ...............................241 14.1. Command Line Format..............................241 14.2. Environment Variables............................242 14.3. Error Messages and Warnings......................242 15. MEX Library Reference ................................251 15.1. Global Variables and Data Structures.............251 15.2. Functions by Category............................262 15.3. Function Descriptions............................272 16. MEX Language Reference ...............................351 16.1. Operator Precedence..............................351 Contents vi 16.2. Language Grammar.................................351 17. MECCA Language Reference .............................355 17.1. Usage Guide......................................355 17.2. Color Token Listing..............................357 17.3. Cursor Control and Video Tokens..................360 17.4. Informational Tokens.............................362 17.5. Questionnaire Token Listing......................366 17.6. Privilege Level Controls.........................368 17.7. Lock and Key Control.............................369 17.8. Conditional and Flow Control Tokens..............370 17.9. Multinode Tokens.................................378 17.10. RIPscrip Graphics...............................379 17.11. Miscellaneous Token Listing.....................381 18. Control File Reference ...............................387 18.1. SILT Directives..................................387 18.2. System Control File..............................387 18.3. Language Control File............................420 18.4. Off-Line Reader Control File.....................421 18.5. Colors Control File..............................422 18.6. Message Area Control File........................424 18.7. File Area Control File...........................430 18.8. Menu Control File................................433 18.9. Access Control File..............................450 18.10. Protocol Control File...........................454 18.11. Event File......................................459 18.12. Language Translation File Reference.............461 Appendices ...............................................463 Appendix A: Common Problems............................463 Appendix B: Error Messages.............................465 Appendix C : Command Line Switches.....................468 Appendix D: Local Keystrokes...........................471 Appendix E: User Editor Keystrokes.....................473 Appendix F: AVATAR Colors..............................474 Appendix G: Sample BAT/CMD Files.......................475 Appendix H: Support Files..............................481 Index ....................................................485 1. Introduction 1.1. About Maximus Maximus is a flexible bulletin board package for the DOS and OS/2 operating systems. Maximus allows remote users to con- nect to the system by modem, read and write messages, par- ticipate in public conference areas, send and receive files, and much more. In addition to the standard message and file features found in most BBS programs, Maximus also includes: * MEX, an extension language that combines the best elements of the C, Pascal and BASIC languages. MEX includes support for advanced language features such as structures, arrays, dynamic strings, and pass-by-reference function arguments. MEX can be used to customize and extend Maximus in an infi- nite number of ways. * MECCA, an easy-to-use scripting language that can be used to colorize screens and add simple menus and prompts to display files. * Support for RIPscrip graphics. Maximus can detect RIPscrip capabilities, automatically size menu output based on the terminal window size, display most internal prompts using RIPscrip graphics, and much more. * Support for SM, a Presentation Manager LAN monitoring tool for OS/2. SM can be used to manipulate and examine multiple Maximus sessions running on remote workstations. * Full support for CD-ROMs and other slow filesystems. Maxi- mus will copy files to a staging area before a transfer and it will only access the drive when absolutely necessary. Areas can also be specifically excluded from new files searches. * A message tracking system for use in technical support en- vironments. Maximus can keep an audit trail of all messages in certain areas, assign "ownership" of messages to indi- viduals, and produce detailed reports regarding the status of various messages. * Support for an unlimited number of message and file areas. Maximus also supports "divisions" for constructing multi- level message and file area hierarchies. 1. Introduction 2 * Support for a REXX user file interface. This interface can be used to read from and write to the Maximus user database from any OS/2-based REXX program. * A powerful message "browse" feature that allows selection of messages based on user-defined search criteria. * A built-in QWK mail subsystem that allows users to read and compose messages while off-line. * Support for the Squish message format, a compact database for storing messages. * Optional support for user password encryption. This feature uses the RSA Data Security, Inc. Message-Digest 5 algorithm as a one-way hash for storing passwords in the user file. * Full multilingual support. The Maximus language file can be customized to support almost any language. Maximus also in- cludes special support for the Swedish 7-bit and the Chi- nese BIG5 character sets. * An internal multinode chat facility, including virtual CB channels and private chatting between two nodes. * An internal full-screen editor for composing messages. * Internal file transfer protocols, including Zmodem, Ymodem- G and other popular protocols. 1.2. System Requirements This chapter describes the minimum hardware requirements for a standard Maximus installation. 1.2.1. MS-DOS or PC-DOS Requirements The minimum system requirements for the DOS version of Maxi- mus are: * an IBM (or 100% compatible) personal computer with at least 450K of available conventional RAM, * MS-DOS or PC-DOS version 3.3 or greater, and * A FOSSIL communications driver (revision level 5 or higher). (Common FOSSIL drivers are X00, BNU and OpusComm.) 1. Introduction 3 1.2.2. OS/2 Requirements The minimum system requirements for the OS/2 version of Maxi- mus are: * an IBM (or 100% compatible) personal computer with at least four megabytes of installed memory, and * one of the following products: * IBM OS/2, Version 2.0, 2.1 or 2.11 * IBM OS/2 Warp, Version 3 or above * IBM OS/2 Warp Connect, Version 3 or above 1.2.3. Common Requirements Regardless of the operating system type, the following hard- ware is also required to run Maximus: * A Hayes-compatible modem, 1200 bps or faster. * A hard disk with at least 15 megabytes of free space. Addi- tional space is required to store the contents of file and message areas. 1.3. Typographical Conventions This document is provided in ASCII form for the convenience of noncommercial users. However, the master version of this document was designed and laid out for the bound version of the Maximus documentation. The content is identical in these two versions of the manual. However, a number of features and styles cannot be correctly translated into the ASCII version of the document. In spe- cific: * The ASCII version of this document includes no lines, bor- ders, boldface, italics, shading, or sidebars. * Indentation, table formatting, and hyphenation may not ap- pear correctly in the ASCII version. * Typographical quotes are replaced with the ASCII equiva- lents. * The ASCII version of the MEX and REXX documentation does not show the sideheads that appear in the printed version of the manual, including the "Prototype," "Arguments," "Return Value," "Description" and "Example" headings. 1. Introduction 4 Please see the printed version of the manual for the official layout and formatting. 1.4. Ordering a Printed Version of this Manual The commercial version of Maximus optionally comes with a printed and bound version of this manual. However, even noncommercial users can order a copy of the manual without purchasing the software itself. The printed manual is 466 pages long, perfect-bound (glued back binding), dimensions 7" by 9", with a black and red cover printed on glossy white card. To order a copy of the manual, please see the "MAXDOC" prod- uct in the ORDER.FRM file (included in the distribution pack- age). 1.5. Ordering Maximus for Commercial Use Maximus is completely free for noncommercial users. Most non- commercial and private users can use Maximus without paying a cent. To determine whether or not you are a commercial user, please see the program license (contained in LICENSE.DOC). However, to use Maximus in a commercial environment, you must obtain a commercial license from Lanius Corporation. For in- formation on ordering a copy of Maximus, please see the order form included in the Maximus distribution archive (called OR- DER.FRM in MAX300C.ZIP). You can also contact Lanius at: FAX: +1-613-634-3058 Post: Lanius Corporation email: sales@lanius.com 777 Downing St. Kingston, Ont. CANADA K7M 5N3 2. Maximus Overview This chapter provides a brief list of the commands and fea- tures supported by Maximus 3.0. This list is by no means com- plete, but it serves as a useful introduction to those System Operators (SysOps) who are unfamiliar with Maximus. 2.1. Waiting for Callers When Maximus is set up to handle remote callers, it enters "Waiting for Caller" (WFC) mode as soon as the system is started. In this mode, Maximus initializes the modem and in- structs it to wait for incoming calls. When a ring is detected, the modem answers the phone. If a connection is successfully established, Maximus waits until the user presses twice, or until five seconds have elapsed, whichever occurs sooner. 2.2. Logging On After a connection is established, Maximus displays the sys- tem name and version, followed by any information that the SysOp has placed in the log-on display file, \max\misc\logo.mec. This screen must not include any graphics commands or high-bit characters, since Maximus has not yet determined the graphics capabilities of the caller. Maximus then prompts the user for a name. Unlike other BBS programs, Maximus allows more than two words in a username, so names such as "John Q. Public" are perfectly acceptable. However, Maximus rejects callers with one-word names unless the Single Word Names feature is enabled. If the user does not exist in the user file, Maximus displays the \max\misc\notfound.mec file. This file normally informs the user that no existing user record with the specified name could be found, and it normally indicates that a new account will be created if the user continues with the log-on proc- ess. Next, Maximus displays a prompt to ensure that the user's name was entered correctly. Given input of "John Doe", Maxi- mus will respond with: John Doe [Y,n]? 2. Maximus Overview 6 If the username was spelled incorrectly, the user can enter "n" and begin the log-on process again. 2.2.1. Log-on Process for Existing Users If the name of an existing user is entered, Maximus prompts the user to enter the password for that user account. The user has up to five tries to enter the correct password. If none of the five attempts are successful, Maximus displays the \max\misc\bad_pwd.mec file. By default, this file allows the user to leave a message to the SysOp before the system hangs up. Once Maximus validates the password entered by the user, it displays the \max\misc\welcome.mec file. This file can con- tain ANSI or RIPscrip graphics to be shown to the user. 2.2.2. Log-On Process for New Users If the user enters the correct password, Maximus validates the user and displays the \max\misc\welcome.mec file. If a non-existent username is entered, Maximus enters the "new user" state. In this state, Maximus first displays the \max\misc\applic.mec file, which normally gives the caller some information about the system. This file can also present an application form to be filled out by the user. Maximus will then prompt for the user's city and state/province, alias, phone number, and a number of other user settings. Lastly, Maximus will display \max\misc\newuser2.mec. This file typically describes the system in more detail. 2.3. Command Stacking Maximus allows the user to stack command responses by enter- ing multiple words at an input prompt. This feature is nor- mally used to expedite the log-on process, but command stack- ing can also be used for most other Maximus commands. Without command stacking, a typical log-on sequence looks like this: What is your name: John Doe John Doe [Y,n]? y Password: ...... 2. Maximus Overview 7 Instead of entering each of these responses separately, all of the responses can be placed on the same line, as shown be- low: What is your name: John Doe;y;password Maximus also supports command line editing at most system prompts. After the user has logged on, and as long as ANSI or AVATAR graphics are enabled, the user can use the cursor keys to edit any of the text on the command line. Editing can be performed using the , , , , , and keys. To use the command line editing feature from remote, the user's terminal program must support either "Doorway mode" or VT-100 keyboard codes. 2.4. Guest Accounts If the SysOp uses the user editor to create an account that has no password, Maximus treats it as a guest account. If a user logs on using a guest account, Maximus automatically skips the password prompt. In addition, Maximus prompts the guest user for a new set of configuration options at the be- ginning of every log-on, including editor preference, graph- ics support, and more. This feature allows the SysOp to specifically create a single account for new users, even if the Logon Level Preregistered feature is enabled. This feature is useful when the SysOp wants potential users to fill out an application form (using the guest account) before granting access to the system. 2.5. The Main Menu After displaying the log-on screens, Maximus also displays the text in the \max\misc\bulletin.mec file. This file typi- cally contains system bulletins or other messages of interest to all users. Following the system bulletins, the user is placed at the main menu. Although Maximus's menus are completely customiza- ble, this section describes the commands that are found on the main menu in the default configuration. Message Section This command takes the user to the message section. The message section is used to participate in public conference 2. Maximus Overview 8 areas and to enter messages to other users. Please see sec- tion 2.6 for more information. File Section This command takes the user to the file section. The file section contains libraries of files that can be downloaded (retrieved). The user can also upload (send) files, search for files of a specific name, and display a file list. Please see section 2.7 for more information. Change Setup This takes the user to the change setup section. This menu allows users to adjust settings in their user profiles. The user can change the screen width and length, select a de- fault file transfer protocol, change telephone numbers, and more. Please see section 2.8 for more information. Goodbye This option logs the user off and hangs up the phone. Even if the user does not log off using this command, Maximus will still update the user's user record. However, this command gives the user the opportunity to leave a comment to the SysOp. Comments to the SysOp are placed in the message area speci- fied by the Comment Area keyword in the system control file. The subject used for the log-off comment can be set in the comment_fr string in the Maximus language file. This string can include external program translation characters. Please see section 6 for more information. Statistics This command displays the user's statistics, including the time of day, the length of the current call, the user's to- tal time for the day, number of kilobytes uploaded and downloaded, and so on. Yell This command allows the user to request a conversation with the SysOp. By default, this command plays a simple tune on the system speaker. (This tune can be configured in the \max\tunes.bbs file.) The local speaker can also be toggled on and off by pressing "!" at the local console while a user is logged on. 2. Maximus Overview 9 OS/2 Maximus can also play yell tunes on a SoundBlaster or only! SoundBlaster-compatible device. Please see section 18.11 for more information. Userlist This command displays the list of all records in the user file. Users can exclude themselves from this list using the "InUserList" command on the Change Setup menu. In addition, the SysOp can modify the access control file to restrict the user list display to a certain set of privilege levels. Version This command displays the Maximus version number and copy- right information. SysOp Menu This command takes the user to the SysOp menu. Normally, only the system operator or a trusted user will have access to this command. Please see section 2.9 for more informa- tion. Chat Menu This command takes the user to the multinode chat menu. This menu allows the user to access all of Maximus's multi- node features, including paging, toggling chat availabil- ity, and private/public chatting. (This command is used ex- clusively to allow users to communicate among themselves. The Yell command is used to chat with the SysOp.) Who is On? This command displays a list of callers who are currently logged onto the system. The Who is On? display includes each user's name, status, and chat availability. At the SysOp's discretion, other options and submenus can be added to the main menu. Please see section 18.8 for more in- formation on adding menu options. 2.6. The Message Section Maximus supports four distinct message area types: local ar- eas, NetMail areas, EchoMail areas, and conference areas. Local areas are used for messages that are local to your BBS. These messages can be public or private, but local messages do not get transmitted to other bulletin boards. 2. Maximus Overview 10 NetMail areas are used for private, point-to-point communica- tion between users on two FidoNet-compatible systems. When entering a message in a NetMail area, Maximus prompts the user for additional addressing information, including the destination address of the message and (optionally) a number of message handling attributes. Maximus also maintains a "NetMail credit" account for each user that can be used when billing users for NetMail usage. Conference areas and EchoMail areas (also known as echoes) are used for public conferences that are distributed among many systems. A message entered in an EchoMail area is broad- cast to all of the systems which carry that conference. To a Maximus user, an EchoMail area appears identical to a local message area, except that messages entered in EchoMail areas have network control information added to the end of the mes- sage. In addition, after a user enters a message in an EchoMail area, Maximus adds the name of that area to the Log EchoMail file. This file can be used later by a scanning pro- gram, such as Squish, to export that message to the rest of the network. In addition to defining the message area type, a number of message area attributes can be assigned to each message area. A complete listing of these attributes can be found in sec- tion 18.6, but some of the more common attributes are given below: Pvt All messages entered in this area will be marked private. Private messages can only be read by the message sender and the addressee. (Users in a privilege level class that has the ShowPvt flag can also read private messages addressed to any user. Typically, these permissions are only granted to the SysOp.) Pub All messages entered in these areas are marked as public. Regardless of the addressee of the message, any user can read a public message. If both the Pvt and Pub attributes are specified, the user can enter either public or private messages. ReadOnly The SysOp can place messages in a read-only area, but nor- mal users are unable to post messages in areas of this type. (Users in a privilege level class that has the WriteRdOnly flag can also post messages in this area.) 2. Maximus Overview 11 Anon When a user enters a message in an area with the Anon at- tribute set, Maximus prompts the user to enter the From: field of the message. (In all other areas, Maximus auto- matically fills in the From: field with the user's real name.) However, Maximus can optionally embed the user's real name within the message such that the SysOp can read it if nec- essary. This option is enabled by default. See the Style NoNameKludge flag in section 18.6 for more information. Attach Message areas with this attribute allow users to attach files to messages created in the area. Please see the de- scription of the Enter Message command in section 2.6 for more information. Also see section 5.2 for information on local file attaches. The SysOp can also assign passwords to message and file ar- eas, enable message tracking, add support for high-bit char- acters, and more. Access to individual message areas can also be granted based on a user's privilege level or name. Please see section 18.6 for more information. 2.6.1. The Message Menu This section describes the commands that are found on the standard message menu: Area Change This command allows the user to select another message area. The user can select an area by name, but the "[" and "]" keys can be used to select the message areas which pre- cede or follow the current area, respectively. The "?" character displays a list of areas. For navigating within a hierarchical area structure, the "/" key moves to the top-level menu, and the ".." sequence ascends one level in the menu tree. Next This command displays the next message in the current area. After displaying a message with the Next command, pressing at the message area prompt automatically displays the next message. 2. Maximus Overview 12 Previous This command displays the prior message in the current area. After displaying a message with the Prior command, pressing at the message area prompt will automati- cally display the prior message. Enter a Message This command allows a user to enter (post) a message in the current message area. Maximus first prompts the user to fill out the message header, including the To field, the Subject field, and the message attributes. For users who have ANSI, AVATAR or RIPscrip graphics en- abled, Maximus displays a message header with fields that can be filled out by the user. The and keys can be used to move between fields, as can the and keys. If the message area definition permits both public and pri- vate messages, Maximus allows the user to select either type of message. For users who have graphics enabled, the private flag can be toggled by pressing when the cursor is on the attributes field (above the message date) The P key also has the same effect. In areas which support file attachments, a file can be at- tached to a message by pressing the A key while the cursor is on the attributes field. (Maximus will prompt the user to upload the file after the message has been created.) In Local areas, the user can obtain the system user list by pressing ? at the To prompt. Maximus normally generates this list automatically from the system user file, but if a \max\misc\userlist.mec file exists, Maximus will display it instead of the real user list. In NetMail areas, the attributes field can also be used to select other mail handling options. Entering a ? at the at- tribute prompt gives a complete list of keys. In addition, NetMail areas also allow the user to select the destination address for the message. After entering the message header information, Maximus will run the system editor and allow the user to enter the body of the message. 2. Maximus Overview 13 Change a Message This command allows the user to modify an existing message. Although the SysOp can modify any message on the system, a normal user can only modify messages which: * have not been read by the recipient, * have not been sent (in the case of NetMail or EchoMail), and * have the user's name in the From field. Both the message header and the message body can be modi- fied. When graphics are enabled, the user can also modify the message attributes. Reply to Message This command allows the user to enter a response to the currently-selected message. The Reply command is similar to the Enter command; however, Maximus will automatically fill out the fields in the message header when doing a Reply. In addition, Maximus will also adjust the message reply chain so that the new message is marked as a reply to the origi- nal message. Within the message editor, the user can also quote (copy) text from the original message into the newly-created re- ply. Read Non-Stop This command displays a number of messages all at once, with no pauses or prompts between messages. If the user last selected the Next command, Maximus displays all mes- sages from the current message to the last message in the area. Otherwise, if the user last selected the Prior com- mand, Maximus displays all messages from the current mes- sage to the first message in the area (in reverse order). Read Original This command examines the current message and finds the original message in the reply thread. (If the current mes- sage was a reply to another message, this command displays that other message.) Messages that are replies to other messages have a "*** This is a reply to #msg" line at the bottom of the message or a "- msg" field in the message header. 2. Maximus Overview 14 Read Reply This command displays the message which is a reply to the current message, if any. Messages which have replies have a "*** See also #msg" line at the bottom of the message or a "+ msg" field in the message header. Read Current This command redisplays the current message. Browse This command scans any or all of the message areas on the system and retrieves selected messages. Browse acts as a powerful database engine for the message bases. Users can select a set of messages and operations to perform, and then have Maximus automatically identify and display the messages that were requested. The first browse menu prompts the user to select a set of message areas. The user can select any of: * the current area, * all message areas, * all tagged message areas, * a wildcard specification (such as "comp.lang.*"), or * the current group (all areas which are on the same level in the message area hierarchy) The second browse menu prompts the user to select a type of message. The user can specify: * all messages, * new messages (those which are above the user's lastread pointer), * your messages (unread messages which are addressed to the user and which are above the user's lastread pointer), and * from a certain message number (such as from message 500 to the end of the area). Maximus also allows the user to perform a search based on keywords in the To, From and Subject fields, in addition to searching the message body. Complex searches can be defined by combining the logical or and and operators. The third and final browse menu prompts the user to specify an operation to perform on the selected messages. Messages can be: * listed (one to a line, with to/from/subject only), 2. Maximus Overview 15 * read (displayed in full, with the option to reply or kill each message), or * packed (compressed into a QWK packet for download and off-line mail reading). Tag This command allows users to select a subset of the message areas on the system. Each user can select his or her own set of personal message areas. This area selection is used to control the areas scanned by the Browse command and the off-line message reader. Edit User This command reads in the current message, checks the From field, invokes the system user editor, and automatically positions the user editor on that user's user record. This option is useful for validating users, since a user's user record can be displayed at the press of a key. (This com- mand is normally only available to SysOps.) To invoke the user editor without seeking to a specific user, instead use the User Edit command from the SysOp menu. Goodbye This option logs the user off and hangs up the phone. Even if the user does not log off using this command, Maximus will still update the user's user record. However, this command gives the user the opportunity to leave a comment to the SysOp. Comments to the SysOp are placed in the message area speci- fied by the Comment Area keyword in the system control file. The subject used for the log-off comment can be set in the comment_fr string in the Maximus language file. This string can include external program translation characters. Please see section 6 for more information. Main Menu This command returns the user to the main menu. Kill a Message This command allows the user to delete a message from the current area. A normal user can only delete messages which contain that user's name in either the To or the From field 2. Maximus Overview 16 of the message to be deleted. However, the SysOp can delete any message on the system. Upload a Message This command allows the user to directly upload a text file as a message. This command is identical to the Enter com- mand, except that Maximus prompts the user to start a file transfer protocol instead of invoking one of the system editors. Forward This command allows the user to copy a message in the cur- rent area and send it to someone else. Maximus prompts the user to enter the message number to be forwarded and the name of the addressee. The user can also forward the message directly into another area by typing the area number when prompted. The Forward command also supports two special modifiers: * Entering FK from the message area menu instructs Maximus to delete the original message after it has been for- warded. * Entering FB from the message area menu instructs Maximus to send a "bombing run." Maximus prompts the user to specify a local filename that contains a list of message addressees. (In order to use this command, the user's privilege level must be equal to the level required to create a message from a file, as defined by the Message Edit Ask FromFile keyword in the system control file.) The format of each line of the bombing run file is as follows: [-x] The and [-x] fields are only used for NetMail messages and should be omitted for local bombing runs. -x can be one of the switches shown below in Table 2.1: Table 2.1 Bombing Run Options Switch Description -h The message should be marked as "hold for pickup." -c The message should be marked as "crash." 2. Maximus Overview 17 -n The message should sent normally (default) In the username field, spaces in a user's name must be represented by underscores. For example: SysOp 1:225/337 Scott_Dudley 1:249/106 -c Bob_Davis 1:106/114 -h Vince_Perriello 1:141/191 -n Note! If you are performing a NetMail bombing run, it is cour- teous to send all messages directly to the destination (without routing your mail through other systems). Hurl This command moves messages from one area to another. The Hurl command asks the user for the destination area and the number of the message to be moved. Xport This command exports a message to a specific path and file- name on the local system. (The Xport command is normally only available to SysOps.) The exported message includes a copy of the message header. The message body is formatted for an 80-column screen. To print a message on the printer, specify an Xport file- name of "prn". In addition, other menu options can be placed on the message menu, including commands to call auxiliary menus, display text files, and run external programs. Please see section 18.8 for more information. 2.6.2. Message Editors Maximus has two internal message editors: MaxEd, the full screen editor, and BORED, the line-oriented editor. Maximus also supports a single, SysOp-defined external message edi- tor. 2.6.2.1. MaxEd MaxEd is the Maximus full screen editor. To use MaxEd, the user must have ANSI, AVATAR or RIPscrip graphics enabled, 2. Maximus Overview 18 have a screen width of 80 columns, and have a screen length of at least 23 rows. The full screen editor has a number of advantages over the line editor, with the most obvious being that it is much easier to use. MaxEd is more like a word processor than a conventional BBS line editor; the cursor keys can be used to page through a message and insert or de- lete text at various points in the message. For editing messages, MaxEd uses a mixture of WordStar and generic VT-100 keystrokes. A full list of the keys used by MaxEd can be obtained by pressing from within the editor. When composing a reply to another message, text from the original message can also be quoted (copied) into the reply. The R sequence (or on the local keyboard) toggles the quote window display. To scroll the quote window down by four lines, press either or . To scroll the quote window up by four lines, press either or . To copy text from the quote window into the message, press either C or . Maximus will copy the text and automatically scroll the quote window down by four lines. MaxEd also has its own menu that allows the user to modify the fields in the message header. This menu can be accessed by pressing either H or . The options available on the MaxEd menu include: Continue This command returns the user to the MaxEd's message- editing screen. To This command allows the user to change the addressee of the message. Subject This command allows the user to change the subject of the message. From This command allows the user to change the From field of the message. The privilege level of this command should be 2. Maximus Overview 19 set high enough so that only the SysOp can access this com- mand. Handling This command allows the user to modify the message's at- tributes. Attributes such as the Private flag can be changed, in addition to NetMail attributes (such as Crash, Hold and File Attach). This option is normally only avail- able to the SysOp. Read File This command allows the user to read in a file from the lo- cal hard drive and include it as part of the message. This option is normally only available to the SysOp. 2.6.2.2. BORED BORED is the Maximus line editor. Unlike MaxEd, BORED does not require ANSI or AVATAR graphics, so it can be used by any user. (However, most users who have graphics capabilities will likely prefer to use MaxEd.) BORED allows the user to enter a message one line at a time. If the user presses on a blank line, BORED displays the editor menu. The following editor commands are available: Save This command saves the message and returns to the message menu. Abort This command aborts (discards) the message and returns to the message menu. List This command lists the message. Each line in the message is indicated by number. Edit This command is used to replace text in a message. First, Maximus prompts the user to enter the line number which contains the text to be replaced. Next, the user enters the search text (the text which is to be replaced). Finally, the user enters the replacement text. 2. Maximus Overview 20 To insert text at the beginning of a line, simply press at the Text to replace: prompt. Insert This command inserts a blank line in the message. The user can specify a line number to indicate where the blank line is to be placed. Delete This command deletes a specified line in the message. Continue This command allows the user to continue writing by append- ing new lines to the end of the message. Quote For messages which are replies, this command allows the user to quote text from the original message. Maximus prompts the user to enter the starting and ending line num- bers (in the original message) for the text to be quoted. To This command allows the user to change the addressee of the message. Subject This command allows the user to change the subject of the message. From This command allows the user to change the From field of the message. The privilege level of this command should be set high enough so that only the SysOp can access this com- mand. Handling This command allows the user to modify the message's at- tributes. Attributes such as the Private flag can be changed, in addition to NetMail attributes (such as Crash, Hold and File Attach). This option is normally only avail- able to the SysOp. 2. Maximus Overview 21 Read File From Disk This command allows the user to read in a file from the lo- cal hard drive and include it as part of the message. This option is normally only available to the SysOp. 2.7. The File Menu This section describes the commands that are found on the standard file menu: Area Change This command allows the user to select another file area. The user can select an area by name, but the "[" and "]" keys can be used to select the areas which precede or fol- low the current area, respectively. The "?" character displays a list of file areas. For navi- gating within a hierarchical area structure, the "/" key can be used to go to the top-level menu, and the ".." se- quence can be used to ascend one level in the menu tree. Locate This command allows the user to search all file areas on the system for a specific file. Maximus first prompts the user to enter a text string. Next, it will go through all of the file areas on the sys- tem, and if it finds a match for that string (in either a filename or file description), it will display the name of the area and the corresponding file information. The L* command instructs Maximus to search all file areas for new files. This command will display a list of files that have been added to the system since the last L* com- mand was executed. File Titles This command displays a list of files in the current area. New files are identified by a flashing asterisk (*) next to the file date. If the user specifies an argument when invoking this com- mand, the File Titles command displays only those files which contain that string in the filename or description fields. (However, the File Titles command only searches the current file area, whereas the Locate command searches all file areas.) 2. Maximus Overview 22 In addition, when the More [Y,n,t,=]? prompt is displayed during a file list, the "t" option (if present) allows the user to tag files for download. This option is only dis- played if the user has an access level high enough to allow file downloading. View This command displays the contents of an ASCII file in the current area. Before displaying the file to the user, Maxi- mus first checks the file to ensure that it contains only ASCII text. Goodbye This option logs the user off and hangs up the phone. Even if the user does not log off using this command, Maximus will still update the user's user record. However, this command gives the user the opportunity to leave a comment to the SysOp. Comments to the SysOp are placed in the message area speci- fied by the Comment Area keyword in the system control file. The subject used for the log-off comment can be set in the comment_fr string in the Maximus language file. This string can include external program translation characters. Please see section 6 for more information. Main Menu This command returns the user to the main menu. Download This command allows the user to download one or more files from the system. Maximus first prompts the user to select a file transfer protocol. (However, if the user has selected a default file transfer protocol from the Change Setup menu, Maximus will automatically skip to the next step.) Maximus includes internal support for Xmodem, Xmodem-1k, Ymodem, Ymodem-G, SEAlink, and Zmodem. Other transfer pro- tocols can be added as external protocols. After selecting a protocol, users are prompted to enter the names of the files to be downloaded, one file to a line. Files that were previously tagged using the Tag command are automatically included in the list. 2. Maximus Overview 23 When processing filenames entered by the user, Maximus automatically expands wildcards, including the "*" and "?" characters. In addition, if the FB utility is used to maintain a system file database, the filenames entered by the user can reside in any file area. (Otherwise, the user must change to the correct file area before selecting the Download command.) In addition to entering filenames, the user can also: * press to start the download, * enter /q to abort the transfer without sending any files, * enter /e to enter edit mode. This mode allows the user to list and delete files in the download queue, or * enter /g to start the download and automatically hang up when the transfer is complete. Tag This command allows the user to queue one or more files for later download. The Tag command is also accessible through the t command when performing a File Titles or Locate com- mand. To download files which have been tagged using this com- mand, simply select the Download command and press at the File(s) to download: prompt. Upload This command allows the user to upload (send) files to the system. If no default file transfer protocol is defined, Maximus prompts the user for the protocol to be used for the upload. If the user selects Xmodem or Xmodem-1K, Maxi- mus also prompts the user for the name of the file to be uploaded. (With all of the other file transfer protocols, the filename is automatically transmitted by the sending terminal program.) Maximus will then start the upload. After the transfer is complete, Maximus will prompt the user to enter a descrip- tion for each file that is uploaded. Maximus can use the upload filename to automatically screen out certain types of uploads. The \max\badfiles.bbs file contains a list of files to be ignored. This list of files can include wildcards. A sample badfiles.bbs could look like this: MAKE$$$.TXT MAKECASH.* 2. Maximus Overview 24 *.RBS *.GBS *.BBS *.GIF *.JPG *.TIF Statistics This command displays the user's statistics, including the amount of time that the user has been online for the cur- rent call, the time online for the day, number of kilobytes uploaded, number of kilobytes downloaded, and so on. Contents This command displays the internal file catalog of a com- pressed file. The Contents command can display the direc- tory of any .zip, .arc, .pak, .arj or .lzh file Raw Directory This command displays a listing of all files in the current area, including files which are not listed in the files.bbs catalog for that area. This command is normally only avail- able to the SysOp. Override Path This command allows the user to override the download path for the current file area. For example, the download path can be overridden to c:\max to allow a privileged user to download files from the Maximus system directory. This com- mand is normally only available to the SysOp. Hurl This command moves a file from one area to another. Maximus prompts the user for the name of the destination area and the name of the file to be moved. This command is normally only available to the SysOp. Kill File This command deletes a file from the current file area. Maximus will prompt the user for the name of the file to be deleted. Maximus will ask the user to confirm the name of the file to be deleted; if the user answers "n" to this prompt, Maximus will give the user the option of leaving the physical file alone and removing the entry from the file listing. This command is normally only available to the SysOp. 2. Maximus Overview 25 2.8. The Change Setup Menu This menu allows the user to modify settings in the user pro- file. The following commands are available on the standard Change Setup menu: City This command modifies the user's "City" setting. Phone Number This command modifies the user's "Phone Number" setting. Alias This command is designed for use on systems that support aliases. This command allows a user to change his/her alias. Password This command changes the user's password. The user is first prompted to enter the old password. The user is given five chances to correctly enter the old password before Maximus hangs up. Next, the user is prompted to enter the new password. The user must enter the new password twice to prevent acciden- tal typing errors. Help Level This command selects the system help level. Maximus sup- ports the help levels shown below in Table 2.2: Table 2.2 System Help Levels Type Description NOVICE Full menus REGULAR Abbreviated menus EXPERT No menus Nulls This command selects the number of NUL characters which are transmitted after every line of text. Most users will not need to use this command. 2. Maximus Overview 26 Width This command changes the assumed screen width. This value is used by Maximus when displaying system menus and when drawing the full-screen editor display. However, for local users, Maximus will automatically detect the local screen size and adjust the "current width" value accordingly. The local screen size value overrides (but does not update) the value in the user file. Length This command changes the assumed screen length. Tabs This command toggles the translation of tab characters. Maximus normally sends tab characters directly to the user's terminal. However, if the user's terminal program does not support tab characters, this option can be dis- abled. More This command toggles the "More [Y,n,=]?" prompts on and off. Video Mode This command selects the user's video mode. Maximus sup- ports the following video modes: * TTY * ANSI * AVATAR RIPscrip graphics mode can be toggled by a separate menu option. Full-Screen Editor This command toggles the use of the MaxEd full-screen edi- tor. If MaxEd is turned off, BORED is used for message ed- iting. IBM Graphics This command toggles the use of IBM "extended ASCII" char- acters. DOS and OS/2 based computers support an "extended" 8-bit character set, including characters for box-drawing and block graphics. Most non-IBM systems do not support these extended ASCII characters, so Maximus can be config- 2. Maximus Overview 27 ured to map extended ASCII characters into normal ASCII characters. Hotkeys This command toggles the hotkeys setting. Turning on hot- keys instructs Maximus to process keystrokes as soon as they are received (without requiring an after most commands). Language This command selects an alternate system language. Maximus supports up to eight different language files, and the user can switch between installed language files at any time. Protocol This command selects a default file transfer protocol. When a default protocol is selected, the Download command imme- diately displays the File(s) to download: prompt instead of asking the user to select a protocol. Archiver This command selects a default archiving program. This al- lows the user to select a commonly-used archiver for com- pressing QWK mail packets. Show in Userlist This command toggle's the displaying of the user's name in the system user list. Users are displayed in the user list by default, but this command can be used to hide the dis- play of the user's name and last-call information. Full-Screen Reader This command toggles the use of the full-screen reader (FSR). When the FSR is enabled, Maximus will display a stylized blue box at the top of the screen when reading messages. This header includes information from the To, From and Subject fields, information on the message reply links, and net/node information. RIP This command toggles the use of RIPscrip graphics. When this command is selected, Maximus will test the remote user's terminal program to ensure that it supports RIPscrip. If RIPscrip graphics support is not detected, Maximus will not enable RIPscrip graphics. 2. Maximus Overview 28 Quit This command returns to the main menu. 2.9. The SysOp Menu This menu contains commands that are normally only accessible to the SysOp. User Editor This invokes the Maximus internal user editor. This command is normally only available to the SysOp. Please see Appendix E for more information. OS Shell This command invokes either a local or a remote shell to the operating system. Note that can always be used from the local console to shell to the operating system. OS/2 When running external programs that are not specifically only! designed to run as doors, OS/2 users should use the Max- Pipe program to invoke the command, rather than redirect- ing input with the "<" and ">" characters. DOS Under DOS, if you are using an alternate command processor only! (such as 4DOS or NDOS), the entry for this command (in the menus control file) must be changed to reflect the name of your command processor. 2.10. The Chat Menu Maximus supports an internal multinode chat facility. Users on different nodes can hold private discussions with one an- other, and users can even engage in large group discussions on a "virtual CB channels." CB Chat The CB Chat function allows two or more users to partici- pate in a real-time multinode chat. Messages can be sent back and forth to all users who are participating on a spe- cific CB channel. Messages are sent to other users one line at a time. Maximus supports up to 255 virtual CB channels. Page User The Page User command allows a user to initiate a private chat with another node. Selecting Page instructs Maximus to send a "chat request" message to the specified node number. 2. Maximus Overview 29 Maximus will then place the paging user in chat mode and wait for the other user to respond to the page. Answer Page The Answer Page command is used in conjunction with the Page User command. After a user receives a page request from another node, the paged user can select Answer Page to engage in a private chat with the first user. Toggle Status The Toggle Status command allows a user to toggle the chat availability flag. Users who are unavailable for chat can- not be paged using the Page User command. 2.11. The Off-Line Reader Menu The Off-Line Reader menu is the key to Maximus's internal QWK mail packer. Commands on this menu can be used to select a default protocol and archiving program, select a set of mes- sage areas, download messages from that set of areas, and up- load reply packets. Tag Area The Tag Area command (equivalent to the command of the same name on the message menu) allows the user to select a set of message areas to be processed by the Browse and Download commands. Download New Messages The Download command packs all new messages in the user's set of tagged areas. The messages are then compressed into an archive and sent to the user. Upload Replies The Upload Replies command allows the user to upload a .rep reply packet. Max automatically determines the program used to compress the .rep file, decompresses the reply packet, and places the uploaded messages into the appropriate ar- eas. Protocol Default The Protocol Default command allows the user to select a default file transfer protocol. 2. Maximus Overview 30 Archiver Default The Archiver Default command allows the user to select a default archiving program. 3. Installation This section of describes how to install a new copy of Maxi- mus 3.0. (To upgrade from Maximus 2.0, simply run the install program and follow the directions.) 3.1. Step 1: Unpacking the Distribution Files If you purchased a copy of Maximus, all of the required files are on the distribution disk and nothing more needs to be done. Skip to step 2 for information on running the install program. Otherwise, if you obtained Maximus electronically, the system consists of three separate archives, as shown below in Table 3.1: Table 3.1 Maximus Distribution Files File Description max300r.zip DOS (real-mode) executables. max300p.zip OS/2 (protected-mode) executables. max300c.zip Common executables and files for both DOS and OS/2. To install Maximus, you need max300c.zip, plus either or both of max300r.zip or max300p.zip, depending on the operating systems that you wish to use. The install program will examine the files that are avail- able, and if both the DOS and OS/2 versions of the executa- bles are present, it will allow you to select either or both versions for installation. Of course, you can also install Maximus for only one of the supported operating systems. The first step in the installation is to unarchive all of the required .zip files into a temporary subdirectory. (The in- stall program will move the files from the temporary direc- tory to a permanent directory of your choice, so this tempo- rary directory can be located anywhere on your system.) To decompress the .zip files, you need either the commercial "PKUNZIP" program from PKWare or the freeware "unzip" program from InfoZip. The following files are contained inside the .zip archives: 3. Installation 32 * an ASCII version of the system documentation, * the install program, * the program license agreement, and * a number of files with a .fiz extension. Most of the pro- grams in the distribution kit are packed using the proprie- tary FIZ compression algorithm, and the only way to extract these files is to run the install program. 3.2. Step 2: Running the Installation Program To execute the install program, run install.exe from the in- stall disk (or from the temporary directory, for the elec- tronic distribution version). After displaying some copyright information, the install pro- gram will prompt you for the type of install to perform. Se- lect the New Install button here, since these installation instructions only describe new installations. In the next dialog box, the install program will prompt you for a number of system paths. Aside from changing the drive letter or root name of the \max directory hierarchy, inexpe- rienced users should leave these paths alone. Next, the install program will prompt you for some basic in- formation about your system, including the BBS name, the name of the SysOp, and information about your communications hard- ware. In the dialog box, simply type text in the appropriate boxes, and use (or click with the mouse) to move between fields. To select a particular option from a radio button group, use the and keys to cursor over to the appropriate location and press to select that option. Press or click on the OK button when you have speci- fied the correct values. OS/2 Most of the executables in the OS/2 version of Maximus end only! with the letter "p." This "p" signifies that the executable runs in protected mode and is a native OS/2 application. Add- ing an extra "p" to the filename allows both Maximus-DOS and Maximus-OS/2 to be installed into the same directory. However, to keep this manual concise, only the base name of an executable is mentioned, without the trailing "p." When working through the installation, keep in mind that when the documentation refers to an executable filename, a "p" should be added for OS/2 users. For example, while the DOS version of the "ANS2BBS" utility is called ans2bbs.exe, the OS/2 version is called ans2bbsp.exe. 3. Installation 33 3.3. Step 3: Configuring your Modem This section describes how to configure your modem to work with Maximus and other related software packages. The modem is your BBS's gateway to the rest of the world, but it can also be one of the most difficult components to con- figure correctly. Due to the wide variety of modem manufac- turers and products, this manual cannot possibly cover all aspects of installing and configuring modems. However, this documentation describes a common set of modem commands that are supported by most popular modems. To run smoothly, Maximus requires a Hayes-compatible modem. Although it may be possible to use Maximus with a non Hayes- compatible modem, only Hayes-compatible modems are officially supported. When setting up your modem, the first step is to determine how your modem handles the Data Carrier Detect (DCD) signal. DCD is a signal sent by the modem to your computer to indi- cate when a connection has been established. When your modem is idle, DCD is normally in the low state. However, as soon as a user connects to your modem, DCD be- comes high. Maximus uses the DCD signal to determine when a user connects with the system, and it also uses DCD to deter- mine when a caller hangs up. Unfortunately, the default settings of many lower-speed mo- dems instruct the modem to always set the DCD signal high, regardless of whether or not the connection is active. To ensure that your modem is reporting the DCD signal prop- erly, you must check the configuration of your modem. Depend- ing on your modem type, this can be done in a number of ways: 1200 bps modems. If your modem is 1200 bps or slower, chances are that your modem's DCD handling is controlled by DIP switches. DIP switches are the small plastic toggles on the front, rear or bottom of your modem. (One or more panels may need to be removed to access these switches.) On most 1200 bps modems, DIP switch #6 controls the DCD sig- nal. For proper operation, this switch should be in the up position so that the modem reports the true DCD value. (However, some modems are different, so please consult your modem documentation before changing any DIP switches.) In addition, you may also need to change one of the other DIP switches so that your modem sends back verbal result codes (as opposed to numbers). The DIP switch to control these re- sult codes is manufacturer-dependent, so you will again need 3. Installation 34 to consult your modem's manual to determine which switch to check. 2400 bps, 9600 bps, 14.4 kbps, 19.2 kbps, or 28.8 kbps. If your modem is 2400 bps or faster, the configuration process can usually be performed using a standard terminal program (including Procomm Plus, Telix, Crosstalk, and others). After loading your terminal program and configuring it for the correct communications port, type in the command "AT" and press . If everything is well, your modem should re- turn an "OK" response. After you have established that your modem is working cor- rectly, enter the command "AT&C1&S1&D2&W" and press . (If this command does not work, try omitting either or both of the "&C1" or the "&S1" strings, since some modems do not support these settings.) This command configures your modem so that DCD always reflects the modem's actual state, and it also configures your modem's DTR handling so that Maximus can use the DTR signal to end a session and hang up on a user. External modems. If you have an external modem, one other po- tential problem is the modem cable. If your cable does not have the correct signals wired through, your modem may still behave as if DCD is set incorrectly, regardless of DIP switch settings. The best way to determine whether or not your modem cable is working correctly is simply to borrow a cable from another SysOp with a working BBS and try it on your system. If you determine that your cable is at fault, most computer stores or service centers can order or manufacture a modem cable. The wiring specifications for modem cables are: DB25 connectors (25 pins). This is the most common type of modem cable. As a minimum, pins 2 through 8 and pin 20 must be wired straight through. DB9 connectors (9 pins). All nine pins must be wired straight through. 3.4. Step 4: Installing Communications Drivers 3.4.1. OS/2 Communications Drivers OS/2 The following paragraphs are for OS/2 users only. DOS users only! can skip to section 3.4.2. 3. Installation 35 Unlike DOS, OS/2 does not require a FOSSIL driver. OS/2 in- cludes its own device driver to handle serial I/O. Unfortu- nately, the device driver included with OS/2 does not work correctly in all situations. (Under OS/2 2.x, the supplied COM.SYS driver sometimes uninstalls itself after certain com- munication errors occur.) Fortunately, a number of third-party device drivers are available: The 16-bit COM16550.SYS device driver can be used instead of the standard IBM driver. An evaluation version of COM16550 is bundled with Maximus, but COM16550 is a third-party product that is not sold or supported by Lanius. Please see the docu- mentation in the \max\com16550.zip file for more information. In addition, a third-party, 32-bit device driver called SIO.SYS has many more features than COM16550 and can operate at much higher speeds. SIO.SYS is not provided with Maximus, but it can be obtained from the Hobbes OS/2 archive at ftp.cdrom.com. SIO can also be found on most bulletin board systems that offer OS/2 support. Please note that COM16550 has a maximum speed of 19.2 kbps, whereas SIO.SYS has a maximum speed of 57.6 kbps. For this reason, if you are running a V.34 or V.FC modem, SIO.SYS is preferable to COM16550. In addition, Maximus runs with any serial device driver that supports the standard OS/2 "ASYNC IOCtl" interface. This means that Maximus-OS/2 can be used with intelligent serial cards such as the DigiBoard or the ARCTIC card. 3.4.2. DOS FOSSIL Drivers Under DOS, Maximus requires an external serial port driver called a FOSSIL. FOSSIL is an acronym which stands for "Fido/Opus/SEAdog Standard Interface Layer." The FOSSIL han- dles all of Maximus's low-level serial communication needs, including sending and receiving characters. Using a FOSSIL allows Maximus to be used on a wide range of serial port hardware without modifying the Maximus core. (For example, third-party vendors have developed FOSSIL drivers that support the DigiBoard intelligent serial card.) Maximus ships with a copy of Unique Computing Pty's BNU FOS- SIL driver. BNU supports most non-intelligent serial ports. If BNU is not suitable or will not run on your system, other FOSSIL drivers are available. Some of the most common FOSSILs are X00 and OpusComm. 3. Installation 36 There are two separate types of FOSSIL drivers. Some FOSSIL drivers, such as OpusComm and BNU, are loaded as Terminate and Stay Resident (TSR) programs in the c:\autoexec.bat file. Other drivers, including X00, are loaded in the c:\config.sys file. Although different FOSSIL drivers have different set-up instructions, it is fairly easy to install a FOSSIL for a ba- sic configuration. OpusComm installation. To install OpusComm on COM1, simply insert the following commands at the beginning of your AUTO- EXEC.BAT: opuscomm ocom_cfg L1=19200 (see note below!) Ensure that opuscomm.com and ocom_cfg.exe are on your current PATH, or else these commands will not work. The second "ocom_cfg" line locks port 1 at a speed of 19200 bps. This line is required for 9600+ bps modems. (Note that OpusComm does not support speeds faster than 19.2kbps.) This line is only required if you are using a 9600+ bps mo- dem. Users with 2400 bps or slower modems must not include the call to ocom_cfg. BNU installation. To install BNUcom on COM1, simply insert the following command at the beginning of your AUTOEXEC.BAT: bnu -l0=38400 Ensure that bnu.com is on your current PATH, or else this command will not work. The "-l0=38400" command instructs BNU to lock port 0 (COM1) at a speed of 38.4 kbps. This parameter is required for 9600+ bps modems. Users with 2400 bps modems must omit the "-l0=38400" parameter. Warni BNU uses 0-based COM port numbers. To lock the speed of COM1, ng! use "-l0=speed"; to lock the speed of COM2, use "-l1=speed"; and so on. X00 installation. To install the X00 driver on COM1, simply insert the following command at the beginning of your CON- FIG.SYS: DEVICE=X00.SYS B,0,19200 Ensure that X00.SYS is in your c:\ directory, or else this command will not work. 3. Installation 37 The "B,0,19200" parameter instructs X00 to lock COM1 at a speed of 19200 bps. This parameter is required for 9600+ bps modems. Users with 2400 bps modems must omit the "B,0,19200" parameter. Warni X00 uses 0-based COM port numbers. To lock the speed of COM1, ng! use "B,0,speed"; to lock the speed of COM2, use "B,1,speed"; and so on. 3.4.3. Checklist for high-speed modems When using a high speed modem (9600 bps or above, including any modems which support V.32, V.32bis, V.32ter, V.FC, or V.34), the modem normally communicates with the host BBS at a fixed speed, regardless of the speed of the user's modem. For this reason, if you are running a high-speed modem, you must instruct Maximus to talk to the modem at a fixed speed. To use a fixed port speed, you must: * ensure that the "&B1" parameter is included in your modem initialization string, * ensure that CTS flow control is enabled (using the "Mask Handshaking CTS" option in the system control files), and * use the -sspeed command line parameter when starting Maxi- mus. (This parameter is only required when running Maximus in a mode that handles remote callers. This parameter is not required when starting Maximus in local mode.) For example, to instruct Maximus to wait for a caller and use a locked port rate of 38.4 kbps: max -s38400 -w The "-s38400" parameter instructs Maximus to talk to the serial port at 38.4 kbps only. The modem itself will handle all rate negotiation with the remote system. 3.5. Step 5: Editing Configuration Files In order to run Maximus on your system, you need to make sev- eral changes to your system configuration files, including config.sys and autoexec.bat. For example, Maximus and related utilities always need to know how to find the main Maximus system directory. To accom- plish this, these utilities examine the system environment for the MAXIMUS environment variable. This variable must al- ways point to the master system configuration file. 3. Installation 38 OS/2 DOS users should skip the next few paragraphs. only! To set up the Maximus environment variable under OS/2, you must add the following line to the end of the config.sys file on your OS/2 boot drive: SET MAXIMUS=C:\MAX\MAX.PRM This example assumes that Maximus was installed in the c:\max directory. If you installed Maximus somewhere else, substi- tute the appropriate path for "c:\max". After making this change to config.sys, you must reboot the computer for the change to take effect. DOS OS/2 users should skip to the next section. only! To configure Maximus to run under DOS, you must add a number of lines to your c:\config.sys file. An ASCII editor, such as the standard DOS edit.com, can be used to edit this file. The first line to be added to config.sys is the "buffers=" statement. If there is no BUFFERS line in your config.sys file, simply add the following line to the end of the file: BUFFERS=30 However, if a BUFFERS line already exists, ensure that it specifies a value of at least 30. Next, the "files=" statement must be added. If there is no FILES line in your config.sys file, simply add the following line to the end of the file: FILES=40 However, if a FILES line already exists, ensure that it specifies a value of at least 40. Finally, if you plan to use Maximus in a multinode environ- ment, Maximus also requires the share.exe program. (Even in single-node environments, share.exe is still strongly recom- mended.) To install share.exe, simply add the following line to the end of c:\autoexec.bat: share Note for Novell users. Installing share.exe is not completely necessary. As long as you load int2f.com after running the Netware shell, you do not need to load share.exe. 3. Installation 39 Note for Windows for Workgroups and Windows 95 users. Windows comes with a SHARE-compatible VxD, and as long as you run Maximus exclusively within the Windows for Workgroups or Win- dows 95 environments, you do not need to install share.exe. Finally, to set up the system environment variable under DOS, you must add the following line to the end of the c:\autoexec.bat file: SET MAXIMUS=C:\MAX\MAX.PRM This example assumes that Maximus was installed in the c:\max directory. If you installed Maximus somewhere else, substi- tute the appropriate path for "c:\max". Once you have made all of these changes and saved the con- figuration files, you should press to reboot the computer. Unless you reboot now, changes made to con- fig.sys and autoexec.bat will not take effect. 3.6. Step 6: About Control Files This is the most complicated step in setting up a Maximus system. Four text-based configuration files control most of the operations of your system: max.ctl, msgarea.ctl, filearea.ctl and menus.ctl. max.ctl controls almost everything about your system, from the name of the log-on display file to the "time reward" given to users who upload files. msgarea.ctl controls all of the message areas that are acces- sible to users. filearea.ctl controls all of the file areas that are accessi- ble to users. menus.ctl controls all of the menus and options that can be selected by users. All of these text files are stored in an ASCII format, so the DOS edit.com or the OS/2 e.exe can be used to modify these files. These files contain a number of fairly complicated commands, but these control files give you control over even the most minute aspects of your BBS. However, the power to tailor your BBS to a very specific set of needs also makes it relatively easy to configure your system incorrectly. Consequently, new SysOps are advised to refrain from making too many modifica- tions to the control files until the basic BBS is up and run- ning. 3. Installation 40 The installation program will have already customized most of the system control files, so no specific modifications are required at this point. 3.7. Step 7: Compiling the Control Files Every time you modify max.ctl or any of the other control files, you must run SILT, the Maximus control file compiler. If you make changes to your control files and forget to run SILT, Maximus will not recognize the changes that you have made. Note! The system installation program will have already compiled your control file for the first time. However, it is a good idea to compile it again here, just so that you can learn how to run SILT.. Compiling your control files with SILT is easy; just enter the following from the command prompt: silt ctlname where ctlname is the name of your main system control file. In the default installation, the main control file is always called max, so most users only need to type "silt max". When SILT runs, it automatically compiles all of the control files, including menus.ctl, filearea.ctl, msgarea.ctl, and a number of other control files. These secondary control files cannot be compiled alone; you must always run SILT on the main control file, regardless of which secondary control file was changed. When SILT runs, it will scan through all of the control files and write a compiled version of the system information to max.prm, marea.dat, farea.dat, and a number of other system data files. If you made mistakes in the control files, such as misspell- ing a keyword or omitting a parameter, SILT will warn you about these mistakes. To correct these problems, use either the DOS edit.com or the OS/2 e.exe to load the control file, move to the problem line number, fix the error, and then re- compile using SILT. 3.8. Step 8: Starting Maximus Once you have compiled your control files, you are finally ready to start Maximus. Although your BBS is still fairly ge- neric, it is now usable. 3. Installation 41 To start up Maximus for the first time, enter the following sequence of commands. This example assumes that you have in- stalled Maximus in the c:\max directory: c: cd \max max -c The "-c" parameter tells Maximus to create a new user file, so you should only do this the first time you run Maximus. However, if you are converting from another BBS program, you should run the CVTUSR program before entering the above com- mand. (See section 8.3 for more information on the CVTUSR program.) Warni By default, Maximus encrypts all passwords in the Maximus ng! user file. While this adds an extra layer of security to your system, it means that you will be unable to convert your Maximus user file to the file format of any other BBS pro- gram. If you want to disable the password encryption, see the No Password Encryption feature in the system control file.) After entering "max -c", Maximus will display a copyright banner and print out a warning about the lack of an existing user file. Maximus will then display the prompt: "Your Name Here [Y,n]?", where "Your Name Here" is the name entered in the "SysOp" box in the installation program. Type the letter "Y" to continue your logon. After doing this, Maximus will display some text that de- scribes your BBS. This text is contained in the \max\misc\applic.mec file. (Files with an extension of .mec will be discussed in greater detail later in this document.) Maximus will also prompt you for a few pieces of information, including your city, phone number, and password. Maximus will also prompt you for ANSI screen control support, the MaxEd editor, IBM-PC characters, hotkeys, and RIPscrip graphics support. Answer "y" to the first four prompts, but answer "n" to the RIPscrip graphics question. After Maximus has finished configuring your account, it will display a welcome screen and a bulletin file. Finally, it will place you at the main system menu. All of the screens that you see are completely customizable. The steps required to customize these files are described later in this manual. Now that Maximus is working, you will probably want to look around for a while. Feel free to explore the different fea- tures of your new BBS. If you want to send some test NetMail messages, try going into the user editor (from the SysOp menu) and giving yourself some NetMail credit. 3. Installation 42 When you have finished looking around at your new BBS, type "g" from any menu to log off, and Maximus will exit back to the command prompt. 3.9. Step 9: Support for Remote Callers To handle non-local callers, Maximus must be run from a batch file. Unlike local log-ins, Maximus requires a batch file to recycle after remote callers. There are two mutually-exclusive methods of running Maximus: * Max can be run using the internal Waiting For Caller (WFC) subsystem. WFC takes care of answering the phone and talk- ing to the modem, so no external programs are required. * Maximus can also be run under a front end. A front end takes care of answering the phone and performing additional processing. Front ends are normally only required for Fi- doNet or UUCP support. If you are running a standalone sys- tem, you do not require a front end. In some cases, systems that run multiple nodes may wish to run a front end only on a subset of the BBS lines. In many cases, only one node needs to run a front end program, while the others can all use the internal WFC module. The command line is used to configure the system for WFC or front end op- eration, so no changes to the control files are required to support this. 3.9.1. Running the MODE command OS/2 If you are running Maximus under OS/2, special care must be only! taken to set up the communications port before calling Maxi- mus. In most cases, the OS/2 MODE command is used to config- ure the port. MODE is used to set the port speed, flow con- trol characteristics, and buffer settings. In most cases, the following command should be issued before trying to run Maximus with a remote caller. This command must be entered all on one line without spaces: MODE COMport:speed,n,8,1,,TO=OFF,XON=ON, IDSR=OFF,ODSR=OFF,OCTS=ON,DTR=ON,RTS=HS In the above command, port is the 1-based com port number of your Maximus system. speed is the maximum communications rate supported by your modem. This line should be included in the command file that starts Maximus. 3. Installation 43 For example, to configure com port 1 for 38.4 kbps, the fol- lowing command should be used: MODE COM1:38400,n,8,1,,TO=OFF,XON=ON,IDSR=OFF, ODSR=OFF,OCTS=ON,DTR=ON,RTS=HS If your modem has special flow control requirements, please see the documentation for the MODE command for more informa- tion. (On-line help is available by typing "help mode" from the OS/2 command prompt.) 3.9.2. Using WFC Mode When run in this mode, Maximus handles incoming callers on its own. The first step in enabling WFC mode is to use the "-w" command line parameter. To start Maximus in the most ba- sic WFC mode, the following command is used: max -w "-w" instructs Maximus to enter WFC mode. After this command is executed, Maximus will load up, display a few windows, initialize the modem, and then wait for an incoming call. Maximus will automatically detect the incoming caller's speed and switch speeds automatically. By default, Maximus is set up to run on any Hayes-compatible modem. If the WFC subsystem does not seem to be answering the phone correctly, read through the comments in the Equipment section of the system control file. Some of the modem command strings may need to be modified, but almost all modems can be made to work with Maximus. In addition to the standard "-w" switch, you can also use the "-b" (baud rate) and "-p" (COM port) switches to specify an alternate port number and maximum baud rate for the current node, overriding the defaults in the control file. For example, to start WFC on port 2 with a baud rate of 38400, specify the following command: max -w -p2 -b38400 To run WFC mode with a high-speed modem (9600+ bps), you must use a locked COM port. The "-s" command line parameter tells Maximus the speed to use for locking the port. For example, the following command is used to run Maximus with a high-speed modem on COM2 (locked at 38.4 kbps): max -w -p2 -s38400 3. Installation 44 No matter which options you use, the command line must always include a "-w" if you wish to handle remote callers. This command must be placed in the batch or command file that starts Maximus. (The batch/command file is described in more detail later in this section.) The WFC module can also handle timed events which cause Maxi- mus to wake up on specific days of the week or at a specific time of day. Please see section 5.1 for more information on WFC mode. 3.9.3. Using an External Front End In this mode, Maximus will not answer the telephone by it- self. You must obtain a third-party "front end" or "mailer" program to handle incoming calls. There are at least a dozen freeware/shareware FidoNet front ends for DOS, and two or three similar programs for OS/2. (At the time of this writ- ing, the two most common front ends were BinkleyTerm and FrontDoor.) Although setting up your front-end mailer is beyond the scope of this document, you will find several sample batch files for different front end mailers in Appendix G. Your mailer's documentation may give some specific instruc- tions for interfacing it with a Maximus system; if so, you should just follow those directions. If not, read on. When Maximus starts up with a caller already on-line, it ex- pects to be given a minimum of one parameter: "-bspeed", where speed is the speed of the caller. Generally, these parameters are passed from the mailer via the spawnbbs.bat or exebbs.bat files. OS/2 Under OS/2, Maximus also expects to be passed the COM port only! handle from the calling program. This means that the minimum requirements for starting Maximus are: maxp -bspeed -phandle where speed is the speed of the caller and handle is the OS/2 file handle for the communications port. Unlike under DOS, the -p parameter is a COM port handle (which is not the same value as the COM port number). This means that this value must be passed to Maximus by your front end mailer. 3. Installation 45 3.9.4. Maximus Errorlevels Although the preceding commands allow Maximus to handle one remote caller, either through the WFC subsystem or through a front end program, Maximus normally exits back to the command prompt after it processes a caller. After Maximus terminates, it needs to tell your system what to do next. For example, if a user entered a message in an EchoMail area, you may want to use an external utility (such as Squish) to export that message, or you may wish to run some sort of logging utility. To provide for these external programs, Maximus tells the op- erating system to set a numeric value called an errorlevel. As mentioned earlier, Maximus supports several different er- rorlevels for various types of events, including users enter- ing EchoMail messages, users entering NetMail messages, log- ging off before the user enters a name, and so on. In several places throughout the control files, you can in- struct Maximus to use a certain errorlevel when a given event occurs. Errorlevels are always numeric, and they always have a value from 1 to 255. In most cases, the errorlevels values do not need to be modified, but you can change them if you must. (However, Maximus reserves errorlevels 1 through 4 to indicate errors, so you should not use these values in the control file.) Once Maximus is set up to use errorlevels, you must also write a batch file to detect the errorlevel returned by Maxi- mus and take the appropriate action. The following statement is used to test an errorlevel in a .bat file (DOS) or in a .cmd file (OS/2): if errorlevel erl action erl is a number which corresponds to the errorlevel value for the event, as specified in the system control file. action is an action that is to be performed when the speci- fied errorlevel is detected. This action can consist of any normal batch file statement. However, if you wish to test for multiple errorlevels, be warned that both DOS and OS/2 examine errorlevels using a greater-than-or-equal-to comparison. This means that the fol- lowing statement: if errorlevel 10 echo Hi! 3. Installation 46 will be executed if Maximus sets an errorlevel value of 10 or greater. For this reason, if you have more than one errorlevel to process, the group of errorlevel statements must be listed in descending order. For example, to check for errorlevels 1, 3, 9, 10, 11 and 12, your batch file would look like this: max -w -p1 -b38400 if errorlevel 12 echo Do operation "A" here. if errorlevel 11 echo Do operation "B" here. if errorlevel 10 echo Do operation "C" here. if errorlevel 9 echo Do operation "D" here. if errorlevel 3 echo Do operation "E" here. if errorlevel 1 echo Do operation "F" here. Also, remember that all programs modify the errorlevel value when they are run. In the example given above, if you wanted to run a program called abcd.exe when errorlevel 12 was en- countered, the abcd.exe program would change the errorlevel to a new value after abcd terminated. Since the batch file is executed one line at a time, the following errorlevel checks (from 11 through 1) would be testing the errorlevel set by abcd.exe, not the errorlevel set by Maximus! To work around this limitation, you must use the goto state- ment for each errorlevel check. The goto statement allows your batch file to jump to a completely different location within the same batch file when a certain errorlevel is en- countered. An errorlevel-based goto statement looks like this: if errorlevel erl goto label As before, erl is the errorlevel value to be tested. The label value is a unique, alphanumeric, single-word name that indicates the destination of the jump. (Examples of valid label names are "GotCaller," "DidScanBld" and "Recycle.") In English, the above statement reads: If the errorlevel value is greater or equal to the value specified by erl, jump to the label in the batch/command file specified by label. To specify the destination of the jump, you must declare the label by placing the same name at another point in the same batch file. This lets the operating system know where it should jump to when it encounters the goto statement. 3. Installation 47 A label declaration looks like this: :label label is the same label name that was specified in the origi- nal goto statement. As soon as the command processor spots a statement of the form "goto label," it will jump to the loca- tion marked with ":label". For example, the following sample batch file: Line 1: :Top Line 2: echo Diamonds are forever Line 3: goto Top causes the line "Diamonds are forever" to be repeated over and over on the screen. When the operating system starts the batch file, it processes each line in sequence. After reading line 1, the OS recog- nizes that "Top" is simply a label definition, so it skips to the next line. After reading line 2, it processes the echo statement and displays "Diamonds are forever." Finally, after reading line 3, it realizes that it has to jump to the label marked "Top." Since the "Top" label is at the top of the file, it goes back to line 1 and repeats the entire process over and over again. However, the goto statement does have practical applications. The previous Maximus errorlevel example could be rewritten like this: max -w -p1 -b38400 if errorlevel 12 goto OpA if errorlevel 11 goto OpB if errorlevel 10 goto OpC if errorlevel 9 goto OpD if errorlevel 3 goto OpE if errorlevel 1 goto OpF :OpA echo Do operation "A" here. goto End :OpB echo Do operation "B" here. goto End :OpC echo Do operation "C" here. 3. Installation 48 goto End :OpD echo Do operation "D" here. goto End :OpE echo Do operation "E" here. goto End :OpF echo Do operation "F" here. goto End :End In this situation, the OS first compares the errorlevel re- turned by Maximus to those listed in the "if errorlevel" por- tion of the batch file. When it finds a match for the error- level, it jumps to the corresponding label. For example, if Maximus exited using errorlevel 10, the batch file interpreter would jump down to the "OpC" label and proc- ess the "echo Do operation `C' here" statement. (Most of the time, you would run an actual program after checking for an errorlevel, rather than simply echoing a string back to the console.) After processing the echo statement, the command processor reads and processes the next line of the batch file. The "goto End" statement ensures that the command processor skips over the following commands after the "OpD" label definition. (Recall that the command processor simply ignores label defi- nitions. Without the extra "goto End," the batch file would just "fall through" to the statements under the OpD and OpE la