PC Press 1997 July

home *** CD-ROM | disk | FTP | other *** search

/ PC Press 1997 July / Sezamfile97_1.iso / msdos / bbs / odors41.a02 / OPENDOOR.DOC < prev next >

Wrap

Text File | 1993-02-26 | 535KB | 12,634 lines

----------------------------- OpenDoors Door Programming Toolkit Version 4.10 Programmer's Manual ----------------------------- (C) Copyright 1991 - 1993 by Brian Pirie. All Rights Reserved. NOTE: Since this manual is likely something that you will want to refer to at the same time that you are working with OpenDoors, looking at the sample source code, or writing your own door and utility programs, it is highly recommended that you take a moment to print it out. Simply type COPY OPENDOOR.DOC PRN from your DOS prompt. TABLE OF CONTENTS TABLE OF CONTENTS .......................................2 CHAPTER 1 - INTRODUCTION TO OPENDOORS ...................4 WELCOME! ...........................................4 FEATURES OF THE OPENDOORS DOOR TOOLKIT .............4 CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING .........7 THE DEMO VERSION & BENEFITS OF REGISTERING .........7 FILLING OUT THE REGISTRATION FORM ..................11 SENDING YOUR ORDER FEE .............................13 ORDERING THE SOURCE CODE ...........................15 ORDER FORM .........................................17 USER FEEDBACK FORM .................................19 CHAPTER 3 - LEARNING THE BASICS OF OPENDOORS ............20 ABOUT THIS MANUAL ..................................20 COMPILING A PROGRAM WITH OPENDOORS .................21 BASICS OF DOOR PROGRAMMING WITH OPENDOORS ..........23 A SAMPLE DOOR PROGRAM: "EZVOTE" ....................26 CHAPTER 4 - THE OPENDOORS DOORDRIVER FUNCTIONS ..........31 AN OVERVIEW OF THE FUNCTIONS .......................31 OD_CARRIER() .......................................35 OD_COLOUR_CONFIG() .................................37 OD_CLEAR_KEYBUFFER() ...............................39 OD_CLR_LINE() ......................................41 OD_CLR_SCR() .......................................43 OD_DISP() ..........................................45 OD_DISP_STR() ......................................47 OD_DRAW_BOX() ......................................49 OD_EDIT_STR() ......................................52 OD_EMULATE() .......................................63 OD_EXIT() ..........................................65 OD_GET_ANSWER() ....................................67 OD_GET_KEY() .......................................68 OD_HOTKEY_MENU() ...................................72 OD_INIT() ..........................................74 OD_INIT_WITH_CONFIG() ..............................77 OD_INPUT_STR() .....................................84 OD_KERNAL() ........................................86 OD_LIST_FILES() ....................................88 OD_LOG_OPEN() ......................................90 OD_LOG_WRITE() .....................................92 OD_PAGE() ..........................................93 OD_PRINTF() ........................................94 OD_PUTCH() .........................................98 OD_REPEAT() ........................................100 OD_SEND_FILE() .....................................102 OD_SET_ATTRIB() ....................................106 OD_SET_COLOUR() ....................................109 OD_SET_CURSOR() ....................................112 OD_SET_STATUSLINE() ................................114 OD_SPAWN() .........................................116 OD_SPAWNVPE() ......................................118 OpenDoors Door Toolkit Manual - Version 4.10 Page 2 CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE .............120 INTRODUCTION TO THE CONTROL STRUCTURE ..............120 CONTROL STRUCTURE - DOOR INFO FILE STATS ...........122 CONTROL STRUCTURE - MODEM SETTINGS .................125 CONTROL STRUCTURE - BBS AND CALLER INFORMATION .....126 CONTROL STRUCTURE - DOOR SETTINGS ..................147 CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION ........150 CONTROL STRUCTURE - FUNCTION KEYS ..................161 CONTROL STRUCTURE - COLOUR CUSTOMIZATION ...........164 CONTROL STRUCTURE - TEXT CUSTOMIZATION .............165 CHAPTER 6 - DEBUGGING OPENDOORS DOORS & GETTING HELP ....169 ABOUT THIS CHAPTER .................................169 TROUBLESHOOTING PROBLEMS ...........................169 SOLUTIONS TO COMMON PROBLEMS .......................171 OPENDOORS SUPPORT ..................................173 THE OPENDOORS SUPPORT BBS ..........................173 THE OPENDOORS ECHOMAIL CONFERENCE ..................174 GETTING IN TOUCH WITH ME ...........................174 OPENDOORS DISTRIBUTION SITES .......................176 JOINING THE DISTRIBUTION NETWORK ...................179 APPENDIX A - CONTENTS OF ARCHIVE ........................181 APPENDIX B - OPENDOORS HISTORY ..........................182 APPENDIX C - FUTURE VERSIONS ............................191 APPENDIX D - SPECIAL THANKS .............................192 GLOSSARY ................................................193 INDEX ...................................................201 OpenDoors Door Toolkit Manual - Version 4.10 Page 3 -------------------------------------------------------------------------------- CHAPTER 1 - INTRODUCTION TO OPENDOORS -------------------------------------------------------------------------------- WELCOME! -------------------------------------------------------------------------------- Welcome to OpenDoors! The OpenDoors door programming toolkit is a powerful and easy to use door toolkit and BBS interface package for Turbo C(++) and Borland C++ programmers. OpenDoors provides a complete toolkit which allows you to EASILY and QUICKLY write spectacular, professional quality BBS doors that automatically support all of the popular BBS systems. With OpenDoors, you can write door programs just as you would write any other program - without having to worry about any of the internal details of door programming. OpenDoors takes care of everything for you: It handles all modem communications, ANSI/AVATAR graphics support and BBS interfacing via door information files (such as DOOR.SYS, DORINFO1.DEF, etc.). OpenDoors also looks after status lines and sysop function keys for DOS shells, chatting, hanging up, etc.. In addition, OpenDoors carries out all of the work involved in keeping track of carrier detection, user timeouts and much, much more. Plus, OpenDoors is can be completely customized, allowing you to take as little or as much control of your programs' behaviour as you wish - and posing no limit on the possibilities of what you can do with this package. FEATURES OF THE OPENDOORS DOOR TOOLKIT -------------------------------------------------------------------------------- OpenDoors is a complete "door driver" library that allows you to write doors that DIRECTLY support one of the largest variety of BBS systems, including RemoteAccess, QuickBBS, PC-Board, Maximus, Opus, WildCat, WWIV, Spitfire, SuperBBS, Telegard, RBBS-PC, TriTel, GAP and others. Interested in writing your own utility doors? Perhaps on-line games? Would you even like to get into the market of selling your doors for others to use? Or would you simply like make your own BBS unique by running "custom" doors? With OpenDoors, you can accomplish all of these things - and much easier than ever before. Unlike other such "door drivers", OpenDoors provides all of the following features: - OpenDoors handles all of the "dirty" work involved in writing door programs. Interested in writing doors for BBSes, either your own, or to distribute (even sell!) to other people? Since OpenDoors handles all of the door-related operations for you, you need do next to nothing different when writing door programs than you would when writing any other program. You simply call OpenDoors' simple functions to input, output and control door operation. In fact, many people have converted OpenDoors Door Toolkit Manual - Version 4.10 Page 4 non-door programs to door programs in only a matter of minutes using OpenDoors. One of the most common comments I receive about OpenDoors is how easy it is to use. - As you would expect, OpenDoors flawlessly monitors carrier detect functions, to automatically recover when a user drops carrier - without your having to do anything extra in your program. OpenDoors also monitors how much time the user has left in the door, and provides a fully-adjustable inactivity timeout monitor. - OpenDoors takes care of all the work involved in reading and writing BBS door information files, such as DORINFO1.DEF, EXITINFO.BBS, CHAIN.TXT, DOOR.SYS, etc. If the particular information is available to OpenDoors, it will provide you with just about everything you could ever want to know about the user on-line, the system your door is running under, and so on. - OpenDoors also does all the work involved in displaying and automatically updating the door's RemoteAccess-style status line, with information available to the sysop such as user name, location, baud rate, time left, function keys, ANSI and AVATAR settings, and so on. OpenDoors even keeps track of a user "wants-chat" indicator, just like the one in RemoteAccess, QuickBBS and other BBS systems. - OpenDoors automatically provides the sysop with all the standard function keys for adjusting user time, hanging up on or even locking out the user, and so on. OpenDoors also provides you with a chat mode, which is available to the sysop by pressing Alt-C. In addition, the door driver has full support for sysop shell to DOS, activated by the Alt-J key. - What's more, OpenDoors is designed to be very easy to use. Even the most novice `C' programmers are able to write professional-quality doors with OpenDoors. It takes care of just about every detail for you, yet still gives you the ability to completely control and customize every detail of your door's behaviour. There are even people who begin door programming with OpenDoors, having never programmed in C in the past. - OpenDoors has full support for locked baud-rates of up to 38,400 baud, using the FOSSIL driver for maximum compatibility with any system. To output text in your door, you simply call one print function. This function looks after all communication with the modem, and also echos the output to the local screen (referred to as twining the output). OpenDoors also automatically detects if the BBS is operating in local mode, and will function as expected. - Other OpenDoors functions include a built in sysop-page function that will ask the user why they wish to chat, and then proceed to page the sysop, just as any BBS package would. OpenDoors also provides screen clearing functions (which will OpenDoors Door Toolkit Manual - Version 4.10 Page 5 detect whether the user has screen clearing turned on), and various ANSI/AVATAR control functions (which again detect if the user has graphics mode turned on). - As if this weren't enough OpenDoors is also DesqView aware. When OpenDoors starts up, it will automatically check for the presence of DesqView, and if available, will perform all of it's screen output through DesqView. - OpenDoors has a number of special sub-systems that you may elect to include in your doors. Among these, are a log-file system that allows you to add log file support to your doors with only a single line of programming. - Another valuable OpenDoors sub-system is the configuration file system. Again using only a single line of code, you can add configuration file support to your doors. OpenDoors configuration files permit the sysop using the door to customize the door's performance to their own preferences. Among the settings available in the configuration file are system directories, screen colours, maximum time permitted within the door, sysop paging hours, memory swapping options. The sysop can also specify a custom door information file (drop file) format, to allow your doors to operate on literally ANY BBS system. - OpenDoors can also be fully customized in order that you may write door programs that use languages other than English. - Among the ANSI / AVATAR features found in OpenDoors is the ability to send ANSI / AVATAR files from disk. This allows you to easily design program screens, and incorporate them into your doors. - OpenDoors also comes with the source code for a user-voting door, EZVOTE, that you can modify, or simply extract bits and pieces for use in your own doors. Plus, this manual contains many examples of C source code, to help you in writing nearly any door program you might wish to build. A number of other example programs are also included with the package. - You may also elect to purchase the source code for OpenDoors, which will permit you to make modifications to any portion of OpenDoors, use any portions of the OpenDoors source code in other programs you write, or merely learn how communications- type programs are written. OpenDoors Door Toolkit Manual - Version 4.10 Page 6 -------------------------------------------------------------------------------- CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING -------------------------------------------------------------------------------- THE DEMO VERSION & BENEFITS OF REGISTERING -------------------------------------------------------------------------------- This archive contains the demo version of OpenDoors. This version has all the features of the registered version, but can only be used under limited circumstances: 1.) The demo (unregistered) version may only be used for a reasonable evaluation period, for evaluation purposes. 2.) Programs written in this version may not be distributed. Also, any program written in the demo version will display a message to the user indicating that it is not registered. This message is, of course, removed in the registered version. If you decided to purchase OpenDoors, you will become the owner of a powerful tool for creating BBS door and utility programs. Registered owners of OpenDoors are entitled to: 1.) Unlimited use of OpenDoors. You may write as many programs as you wish using OpenDoors, and do what you please with these programs. They may be freely distributed, or even sold. What's more, there are no additional royalty fees. Your one time purchase of OpenDoors entitles you to use it as you please. 2.) You also be entitled to free upgrades to newer versions of OpenDoors. In addition to the great many features and the quality that this version of OpenDoors has to offer, I am currently working on a great many additions and enhancements for the next version. (See the end of this document for an outline of features currently "in the works") Any programs you write in this version will also automatically take on these new features when you receive the new version. The best news of all is how cheap OpenDoors is! Other "door- drivers" sell for $50, $75, or even more! However, this version of OpenDoors will only cost you $28! (Also, you may be interested in knowing that the price will go up in future versions, so if you register now, you will save by getting ALL future upgrades for free.) Also, the source code for OpenDoors is now available to registered users for an additional $28! Ordering a copy of the source code will allow you to customize OpenDoors for your own use, making any changes or additions that you wish. It also gives OpenDoors Door Toolkit Manual - Version 4.10 Page 7 you the opportunity to see how OpenDoors works, and to use any portions of the OpenDoors code in any other programs you wish to write. If you think you might be interested in ordering the OpenDoors source code, please be sure to read the section entitled "Ordering The Source Code", located on page 15. OpenDoors Door Toolkit Manual - Version 4.10 Page 8 HOW TO ORDER -------------------------------------------------------------------------------- PLEASE Below are detailed instructions for registering OpenDoors. NOTE These instructions are not intended to seem confusing or complicated; they are simply meant to answer almost any question that you might have about registering. However, note that it is probably not necessary for you to worry about whether you are following these steps to the letter - I'm not that picky. So long as you send your registration form and fee by some means, there should not be any difficulty in processing your registration. If you do have any questions or uncertainties about your registration, please feel more than free to contact me. For information on how to contact me, please see page 173. To order OpenDoors, simply follow these three steps: 1.) Fill out the registration form. Information on filling out the form is located on page 11. 2.) Send the appropriate payment, $28 for the registration or $56 for both the registration and source code. If you wish more detailed instructions on sending the registration fee, see the section that begins page on 13. 3.) Send the above two items (along with a diskette and envelope if you are ordering the source code, and wish to receive it by mail) to me at: Brian Pirie Apt. 1416 - 2201 Riverside Dr. Ottawa, Ontario Canada K1H 8K9 If you think you might also be interested in the OpenDoors source code, be sure to read the section on the source code, which begins on page 15. Keep in mind that the registration form in this package is only used for registering the OpenDoors door toolkit. If you are also using the OpenDoors BBS interface package, you must register it by sending the separate registration form contained in that package. However, if you have both packages and wish to register both of them at the same time, you may send both registrations together, and must only make out a single cheque for the total of both registrations. Also, you may wish to send the OpenDoors feedback form (located on page 18), along with your registration. The feedback form gives you a chance to tell me what you think about OpenDoors, and OpenDoors Door Toolkit Manual - Version 4.10 Page 9 what changes you would like to see in future versions. In fact, the majority of suggestions made on suggestion forms in the past have already been implemented in more recent versions of OpenDoors. OpenDoors Door Toolkit Manual - Version 4.10 Page 10 FILLING OUT THE REGISTRATION FORM -------------------------------------------------------------------------------- If you have printed the OpenDoors manual, you can simply remove and mail the forms on pages 17 and 18. If you have not already printed a copy of the manual, and you have a printer, you can quickly print these forms by printing the ORDER.FRM file included in the OpenDoors distribution archive. (Type COPY ORDER.FRM PRN from your DOS prompt.) NO PRINTER? Alternatively, if you do not have a printer, simply send a hand- drawn version of the order form. If you have any special instructions for me, or anything that you would like to say when you register, feel free to write this down on the back of the registration form, or on a separate piece of paper. When filling out the OpenDoors registration form, be sure to indicate how you would prefer to receive your OpenDoors registration key and/or source code. You will have the choice of receiving your registration key and/or source code by one of three means: conventional mail, FidoNet CrashMail, or by a call to your BBS. Although I try to send all orders the same day that I receive your order form, if you have a FidoNet Email address, FidoNet CrashMail is still by far the quickest way to receive your order. Once you have decided which means you would prefer to receive your order by, please read the detailed instructions on your order method, below. Also, if you are ordering the source code, please be sure to read the section which begins on page 15. -------------------------------------------------------------------------------- RECEIVING In order to receive your OpenDoors registration key and/or ORDER source code by conventional mail, simply fill out the order BY MAIL form and mail it along with your payment as described below. I will cover the cost of postage. If you are ordering the source code (requiring the mailing of a diskette), or your address contains non-Arabic characters, also enclose a self-addressed envelope. If you are also ordering the source code, please be sure to enclose either a 5-1/4" 360K or 3-1/2" 720K/1.44M floppy disk. -------------------------------------------------------------------------------- RECEIVING In order to receive your OpenDoors registration key and/or BY CALL source code by a message and/or upload to your BBS, fill out TO BBS the order form and mail it along with your payment as described below. Be sure to include the phone number, baud rate, and my login and password for the BBS to which you would like me to call. As always, I will cover any long distance costs. If, for OpenDoors Door Toolkit Manual - Version 4.10 Page 11 some reason, I am unable to connect to your BBS (not because it is busy, but, for example, if your BBS is no longer online), I will send your order by conventional mail instead. -------------------------------------------------------------------------------- RECEIVING In order to receive your OpenDoors registration key and/or ORDER BY source code by FidoNet CrashMail, simply fill out the order FIDONET form and mail it along with your payment as described below. CRASHMAIL Be sure to include the FidoNet node address to which you wish to have your registration key and/or source code sent to (via CrashMail). Again I will cover any long distance costs. If, for some reason, I am unable to connect to your FidoNet system, I will send your order by conventional mail instead. OpenDoors Door Toolkit Manual - Version 4.10 Page 12 SENDING YOUR ORDER FEE -------------------------------------------------------------------------------- As mentioned before, the OpenDoors registration fee is only $28 in either Canadian or U.S. currency, or the equivalent in funds from any other country. You may also elect to receive the OpenDoors source code for an additional $28 (ie. $56 for both your OpenDoors registration, and the source code). I are able to accept your order fee in any of the following forms: -Cheque or Money Order in Canadian currency, drawn upon a Canadian bank. In this case, your order fee will be either $28CDN for just the registration, or $56CDN for both the registration and source code. -Cheque or Money Order in U.S. currency, drawn upon a U.S. bank. In this case, your order fee will be either $28US for just the registration, or $56US for both the registration and source code. -An International Money Order or International Bank Draft (available from your bank, post office or organization such as American Express), in Canadian currency. Depending on the particular case, your order fee MAY be sent to me by the postal service, and you will mail your order form by itself. You should have the money order drawn in either $28CDN for just the registration, or $56CDN for both the registration and source code. -A cheque drawn on any bank in the world, IN THAT COUNTRIES CURRENCY, equivalent to 28 Canadian or U.S. dollars. For instance, a cheque for the appropriate number of British Pounds, drawn on a British bank, is perfectly acceptable. However, I am unable to accept a cheque for $28 Canadian dollars, drawn on a British Bank. -Cash, $28 for the just registration, or $56 for both the registration and source code, in either Canadian or U.S. currency. Please note that it is not usually recommended that cash be sent in the mail, and that I cannot be responsible for any cash lost in the mail. Simply put, if you wish to order by cash, it is your responsibility to get the cash to me. However, if I do receive your order in the form of cash, it will be perfectly acceptable to me. I would like to mention that many people have already ordered OpenDoors by sending cash, and I have yet to run across any case of cash being lost in the mail. Nonetheless, if you wish to send cash, you may wish to consider doing so by registered mail, for your added security. If you are ordering OpenDoors from within Canada, you will most likely choose the first option (a Canadian cheque or money OpenDoors Door Toolkit Manual - Version 4.10 Page 13 order). If you are ordering OpenDoors from within the United States, you will most likely choose the second option (an American cheque or money order). If you are ordering from outside Canada and the U.S., it would be ideal if you could send your fee by an international money order. However, it should be noted that any of the above order methods will be acceptable from any location. Also, it is quite possible that I may be able to accept other means of sending your order fee. If you are unsure about sending your order fee, please feel free to get in touch with me by any of the means listed on page 173. OpenDoors Door Toolkit Manual - Version 4.10 Page 14 ORDERING THE SOURCE CODE ------------------------------------------------------------------------------ There are many benefits to also ordering the source code along with your OpenDoors registration. Ordering the source code will allow you to customize OpenDoors for your own use, use parts of the OpenDoors source code in other programs, and learn more about how OpenDoors works. If you have any ideas for changes that you would like to see in OpenDoors, either large or small, ordering the source code will allow you to makes these changes yourself, creating your own customized version of OpenDoors. You will be able to remove copyright notices, change the way certain OpenDoors functions work, or add new capabilities to OpenDoors in surprisingly little time. You will also be able to use any of the OpenDoors source code, be it the DesqView-aware code, EMS/disk swapping routines, configuration file system, communications routines, or anything else, in any other programs that you may wish to write. Also, ordering the OpenDoors source code will allow you to learn more about how OpenDoors works, and how to program communications software, door programs, BBS utilities, and so on. As mentioned before, registered users may order the OpenDoors source code for an additional $28, either at the same time you register OpenDoors, or separately. If you wish to order the OpenDoors source code, simply indicate on your order form that you wish to order both your OpenDoors registration, and your source code, and include the additional fee for ordering the source code. When you order the OpenDoors source code, you will receive the source code package. The source code package includes all of the source code, with the exception of the registration key decoding algorithm. This small piece of code is instead included in the form of .OBJect files, one for each memory model. The source code package also includes a short "Source Code Manual", with a description of how the OpenDoors source code is organized, instructions on how to recompile the source code, and more. In addition, the source code package includes a full set of batch files for automatically re-compiling the OpenDoors libraries. In order to re-compile the OpenDoors source code, we would recommend that you have Turbo C++ 1.00 or later, or any version of Borland C++. If you are using Turbo C 2.00 or earlier, you will have to make a few minor alterations to the source code in order to re-compile it with your compiler. Also, as with your OpenDoors registration, when you order the OpenDoors source code, you are entitled to receive all future versions of the source code. OpenDoors Door Toolkit Manual - Version 4.10 Page 15 IMPORTANT If you wish to order the source code there are a few important things which you should note. First of all, if you choose to receive your source code by mail (as opposed to upload to your BBS, or FidoNet CrashMail), be sure to enclose a Double-Density 5-1/4" diskette with mailing envelope, or either Double-Density or High-Density 3-1/2" diskette. Also, due to the costs of over- seas long distance, an extra $15 is required in order to send the OpenDoors source code by BBS upload or FidoNet CrashMail to any sites outside of North America. There is no extra cost for sending the source code by BBS upload or FidoNet CrashMail within North America. Nor is there any extra cost for having it sent by conventional mail in or outside North America. OpenDoors Door Toolkit Manual - Version 4.10 Page 16 --------------------------------------------------------------------------- OPENDOORS DOOR PROGRAMMING TOOLKIT 4.10 - ORDER FORM --------------------------------------------------------------------------- YOUR NAME : _______________________________ (AS SHOULD APPEAR IN REGISTRATION) POSTAL ADDRESS : ______________________________________________________ ______________________________________________________ VOICE PHONE NUMBER : ______________________ NETWORK ADDRESSES : ____________________________________ (IF APPLICABLE) BBS PHONE NUMBER : ______________________ (IF APPLICABLE) BEST TIME TO CALL : __________________ BRIAN'S PASSWORD : __________ (ONLY IF YOU WISH TO RECEIVE YOUR ORDER BY A MESSAGE ON YOUR BBS) ___ I WISH TO RECEIVE MY ORDER BY: | | - FIDONET "CRASHMAIL" |___| ___ | | - CALL TO MY BBS |___| ___ | | - CONVENTIONAL MAIL |___| ___ I WOULD LIKE TO ORDER: | | - JUST MY REGISTRATION KEY, FOR $28 |___| ___ | | - JUST THE SOURCE CODE (ONLY IF ALREADY |___| REGISTERED), FOR $28 ___ | | - BOTH REGISTRATION KEY AND SOURCE CODE, |___| FOR $56 I HAVE ALSO SENT THE APPROPRIATE ORDER FEE, PAYABLE TO BRIAN PIRIE. ____________________________ (SIGNATURE) MAIL TO: BRIAN PIRIE APT. 1416 - 2201 RIVERSIDE DR. OTTAWA, ONTARIO CANADA K1H 8K9 +-- OFFICE USE ONLY ------------------------------------------------------+ | | | Rcvd : _______ Date : _________ S.N. : _________ Key : _____________ | +-------------------------------------------------------------------------+ OpenDoors Door Toolkit Manual - Version 4.10 Page 17 --------------------------------------------------------------------------- OPENDOORS DOOR PROGRAMMING TOOLKIT 4.10 - USER FEEDBACK FORM --------------------------------------------------------------------------- YOUR NAME : _______________________________ POSTAL ADDRESS : ______________________________________________________ ______________________________________________________ VOICE PHONE NUMBER : ______________________ NETWORK ADDRESSES : ____________________________________ (IF APPLICABLE) WHERE DID YOU RECEIVE YOUR COPY OF OPENDOORS? ____________________________________________________________ WHICH COMPILER AND VERSION ARE YOU USING? (EG. BORLAND C++ 3.00) ____________________________________________________________ WHAT DO YOU LIKE MOST ABOUT OPENDOORS? ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ WHAT CHANGES OR ADDITIONS WOULD YOU LIKE TO SEE IN FUTURE VERSIONS? ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ DO YOU HAVE ANY ADDITIONAL COMMENTS? ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ ------------------------------------------------------------------------------ OpenDoors Door Toolkit Manual - Version 4.10 Page 18 ------------------------------------------------------------------------------ CHAPTER 3 - LEARNING THE BASICS OF OPENDOORS ------------------------------------------------------------------------------ ABOUT THIS MANUAL ------------------------------------------------------------------------------ The OpenDoors programmer's manual is intended to serve as a complete tutorial, guide and reference to writing programs with OpenDoors. Chapter 1 of this manual, beginning on page 4, serves as an introduction and overview of the features of OpenDoors. Chapter 2, beginning on page 7, then contains all of the information related to this demo version of OpenDoors, and how to register your copy. This chapter then serves as a tutorial on OpenDoors and door programming in general. Chapter 4 then deals with the functions which OpenDoors provides for door programming. Chapter 5 deals with the "OpenDoors control structure", which gives you access to a wide array of information, and allows you to customize OpenDoor's appearance and behaviour. Chapter 6 (which begins on page 168) is perhaps the most important single part of this manual. This chapter gives detailed instructions on troubleshooting programs written with OpenDoors, lists solutions to common difficulties, and has information about the many sources for OpenDoors support. If at any time you are having difficulty with OpenDoors, be sure to refer to this chapter for complete step-by-step instruction on tracing the source of your problem, and for solutions to common difficulties with OpenDoors. This chapter also directs you to some of the many means of OpenDoors support, including information on the OpenDoors EchoMail conference, the OpenDoors support BBS, and how to get in touch with me. You will also find many useful tools in this manual, which will no doubt come in useful while working with OpenDoors. Beginning on page 2 is a basic table of contents, showing you have the manual is organized, and helping you to locate general topics. At the end of the manual, beginning on page 200, is an index to help you locate more information on specific topics. The manual also includes a glossary, on page 192, which will help you in understanding new terms that you may come across while reading the manual. At the end of the manual, you will also find several useful section, such as a brief history of OpenDoors, information on how to contact us, and information about new OpenDoors features currently in the works. It is suggested that if you wish to get the most out of OpenDoors, that you carefully read the sections of the manual that describe the use of the features you are using, and at least skim other portions of the manual to find out what additional features are available. Also, you will likely want to print this manual, to make reading and reference while programming easier. OpenDoors Door Toolkit Manual - Version 4.10 Page 19 To print this manual, simply type the following line from your DOS prompt: COPY OPENDOOR.DOC PRN: COMPILING A PROGRAM WITH OPENDOORS -------------------------------------------------------------------------------- The process of compiling a program written with OpenDoors is very similar to that of compiling any other program. However, there are two additional steps which you must be sure to remember: 1.) To include the OPENDOOR.H header file. 2.) To link your program with the appropriate OpenDoors library file. All programs written with OpenDoors, must "include" the OPENDOOR.H header file. This is easily accomplished by placing the line #include "OPENDOOR.H" at the beginning of your program's .C file. You must also "link" the OpenDoors library file with your program. The recommended way of doing this is by including the appropriate library in your project file. If you are unfamiliar with the process of using project files, please refer to your Turbo C(++)/Borland C++ manuals. Simply put, if you are using Turbo C, you should create a text file with a .PRJ file, and list in this text file the name of your program's .C file, along with the name of the appropriate library file. You should then select this .PRJ project file from within Turbo C, prior to compiling your program. If you are using Turbo C++ or Borland C++, you can create a project file by selecting the "Open" command from the "Project" menu. Simply type in the name of a new .PRJ project file to create, and then "Add" the name of your program's .C file, along with the name of the appropriate OpenDoors library. Again, whenever you wish to compile your program simply load the project file for that program first. There are a number of different library files included with OpenDoors, one for each memory model. The following chart lists the library file names, along with their corresponding memory model. It is important that you use the library file which corresponds to the memory model you are using. If you are unfamiliar with the concept of memory models, you should refer to your C programming manuals. Simply put, within Turbo C(++)/Borland C++, you must select the memory model you wish to use when compiling your program. In order for your program to compile correctly, you must also include the library file which corresponds to the memory model you have selected. OpenDoors Door Toolkit Manual - Version 4.10 Page 20 +------------------------------------------------+ | Library | Memory | | Filename | Model | +-------------+----------------------------------| | ODOORS.LIB | The Small memory model library | | | | | ODOORM.LIB | The Medium memory model library | | | | | ODOORC.LIB | The Compact memory model library | | | | | ODOORL.LIB | The Large memory model library | | | | | ODOORH.LIB | The Huge memory model library | +------------------------------------------------+ For more information on including third-party libraries in your programs, please also see your Turbo C(++) / Borland C++ manuals. OpenDoors Door Toolkit Manual - Version 4.10 Page 21 BASICS OF DOOR PROGRAMMING WITH OPENDOORS -------------------------------------------------------------------------------- This section provides a complete tutorial to the basics of door programming with OpenDoors. It is important that you read this section, as while OpenDoors allows you to write door programs in almost the same manner as you would any "normal" program, there are a few things which you must keep in mind, in order that your door functions correctly. We would also encourage you to look at the sample door included with OpenDoors, EZVote. This program, which is described beginning on page 25, will give you a much better idea of what an OpenDoors door will look like, and provides you with a starting point for writing your own doors. Perhaps the best means of introduction to door programming with OpenDoors is by doing it yourself. As such, it would probably be a good idea for you to try typing in, compiling and running the simple introduction program below. For instructions on compiling programs written with OpenDoors, see page 20. #include "opendoors.h" main() { od_printf("Welcome to my first Door!\n\r"); od_printf("Press a key to return to BBS!\n\r"); od_get_key(TRUE); od_exit(10,FALSE); } Keep in mind that even this simple program will automatically have all of the door capabilities we have already mentioned. Notice the inclusion of the OPENDOOR.H file. All doors written with OpenDoors must include the OPENDOOR.H header file in order to compile correctly. The first two lines in the main function simply call the OpenDoors printf function (which sends the output to both the modem and the local screen). Notice that the strings displayed by the od_printf() function end with a "\n\r" sequence, instead of the normal "\n". The next line is the OpenDoors single-key input function. The TRUE value causes the system to wait for a key to be pressed (again, either from remote or local keyboard). The last line of the main function then ends the door, returning an errorlevel of 10. The FALSE indicates that you do not wish to have OpenDoors terminate the call (hang up on the user). If you placed a TRUE in its place, then a remote user would be logged off when the door exits. We would strongly encourage you to try compiling and running this program on your own BBS setup. For information on compiling programs with OpenDoors, see the section beginning on page 20. Congratulations, you have written your first door! Feel free to make any changes to this program, and see what effects your changes have. OpenDoors Door Toolkit Manual - Version 4.10 Page 22 In case you are not completely familiar with the operation of door programs, we will now provide an introduction to the internals of a door's operation. Keep in mind that OpenDoors automatically carries out most of these tasks for you. When any door program starts up, one of the first things it must do is to read the door information file(s) passed to it by the BBS . When a user is on-line, and wishes to run a door, they will most likely select a command from a menu. At this point, the BBS system (such as RemoteAccess, Maximus, or whatever), will create a file of information about the system, who is on-line, and so on. Various BBS packages produce various styles of door information files. OpenDoors recognizes a wide variety of door information files, and future versions will recognize others. As a result, your doors will be able to run on a great many different BBS systems. The door itself will actually be loaded in one of two manners. Either the BBS will perform a "shell" and run the door while the BBS system resides in memory (sometimes called a type 7 exit), or it will exit to a batch file, which will trap an errorlevel and load the appropriate door. (sometimes called a type 15 exit). In either case, when the door gains control, it will first read the door information file(s), and then begin to communicate with the modem. OpenDoors, as with almost all other BBS software, performs all of its modem communication with the "FOSSIL driver". The FOSSIL driver is loaded either as a .SYS device driver from Config.Sys at boot-up, or from an .EXE file as a TSR program, and provides the BBS software with a standard interface layer for communicating with just about any type of modem. Hence, whenever your door is not running in local mode, it will require a FOSSIL driver, such as X00 or BNU to be loaded. Fortunately, OpenDoors takes care of all the work involved in detecting and reading the door information file, and then initializing and communicating with the FOSSIL driver for you. In order to carry out these tasks, along with setting up the status line, and so on, OpenDoors provides a function called od_init();. If you do not explicitly call this function, the first call to any other OpenDoors DOOR DRIVER function (such as the first time your door program outputs anything) will automatically cause the od_init function to be called. As a result, upon the first call to an OpenDoors DOOR DRIVER function (but not BBS interface module functions), all of the initialization tasks for the door will automatically be carried out. However, there may be times when you will want your program to have access information about the user who is on-line, or carry out other actions which require od_init() to have been executed - prior to the point where you call any other OpenDoors functions. In this case, you will have to call od_init() yourself before you do any of these things. OpenDoors provides you with a C structure, by the name of od_control, which allows you to access all the available information about the user who is on-line, the system your door is running on, and also allows you to adjust various OpenDoors parameters. Depending on what BBS system your door is running under, the actual information available from the od_control OpenDoors Door Toolkit Manual - Version 4.10 Page 23 structure will vary. For more information on the od_control structure, see the section on the control structure, beginning on page 119. Once the door has initialized itself, it will then begin communications with the user who is online. OpenDoors takes care of all communications, through its various input and display functions. When the door has finished, it will then write any information that has changed back to the door information file (if applicable), finish communicating with the modem, and return to the BBS. In OpenDoors, this is accomplished with the od_exit() function. This function will terminate the door's activity, OPTIONALLY hang up on the user (allowing you to provide either return to BBS or logoff options for exiting), and then exit with the specified errorlevel. You *MUST* exit your door by calling the od_exit() function. One other important OpenDoors function that you should be aware of is the od_kernal() function. od_kernal() is the central OpenDoors control function, and is responsible for much of OpenDoors' updating of the status line, monitoring the carrier detect and user timeout status, responding to sysop function keys, and so on. The od_kernal() function is called automatically by OpenDoors, within the other OpenDoors door driver functions. As a result, since most door programs will call some OpenDoors function on a regular basis, you will most often have no need to call the od_kernal() function yourself. However, if your door is going to perform some action, such as updating data files, during which it will not call any OpenDoors door driver function for more than a few seconds, you should then call the od_kernal() function yourself. For more information on the od_kernal() function, see page 85. For more information on the functions available from OpenDoors, or the control structure, see the corresponding sections in this manual. We would also suggest that you have a look at the sample door included with OpenDoors, EZVote. OpenDoors Door Toolkit Manual - Version 4.10 Page 24 A SAMPLE DOOR PROGRAM: "EZVOTE" ------------------------------------------------------------------------------- One of the best ways to see how OpenDoors works, and the potential that it has, is to look at the source code for the included sample door, EZVote. While this is by no means a complex door, it should certainly give you a clear impression of how OpenDoors doors are built, and will likely give you many ideas for your own doors. You can run the door as included in the archive by typing EZVOTE (the archive also contains a sample DORINFO1.DEF file, which will allow you to test any doors in local mode.) If you wish to manually create your own DORINFO1.DEF file, you can do so very easily. The DORINFO1.DEF door information file is a simple text file which lists a different piece of information on each line, in the following format: +----------------------------------------------------------+ | LINE NUMBER | DESCRIPTION | EXAMPLE | +-------------+------------------------+-------------------| | 1 | Name of the BBS | MY OWN BBS | | 2 | Sysop's first name | BRIAN | | 3 | Sysop's last name | PIRIE | | 4 | Com Port modem is on | COM0 | | 5 | Baud rate, etc. | 0 BAUD,N,8,1 | | 6 | Unused | 0 | | 7 | User's first name | JOHN | | 8 | User's last name | PUBLIC | | 9 | Caller's location | OTTAWA, ON | | 10 | ANSI mode (0=off, 1=on)| 1 | | 11 | User's security level | 32000 | | 12 | User's time left | 60 | +----------------------------------------------------------+ Feel free to make any changes you wish to the door, and recompile it! One of the best and most enjoyable ways to learn OpenDoors is by experimenting. If you are a registered owner of OpenDoors, you may even distribute your own versions of this door. Also, you may find that EZVote serves as a good framework for building your own doors. The EZVote door behaves similarly to most other door programs, and will have a fair bit in common with any other door you write in OpenDoors. What you see in the output window is identical to what a remote user will be seeing. If the user has ANSI or AVATAR mode turned on, you will see the same colours as they do, and if they have screen clearing turned on, your screen will be cleared when their's is. The status line at the bottom of the screen will list the name of the user currently on-line (if you are using the sample DORINFO1.DEF file, the user's name will be "The Sysop"), the user's location, and the user's baud rate (0 if the door is operating in local mode). You will also be told how much time the OpenDoors Door Toolkit Manual - Version 4.10 Page 25 user has left, and there will be indicators as to whether the user has ANSI and/or AVATAR modes on, etc. If the user wishes to Chat with the sysop (ie, they have paged the sysop, but haven't receive a response yet), a [Want-Chat] indicator will be flashing on the status line. Try Paging the sysop, using OpenDoors built in sysop page feature. The following function keys will also be available to the sysop in any OpenDoors door: [UP]/[DOWN] - Use the arrow keys to increase or decrease the amount of time which the user has left in the door. [Alt]-[C] - Allows the sysop to break into chat with the user at any time. [Alt]-[C] again, or [ESC] will end chat mode. (Notice that the Want-Chat indicator will also be turned off, if it was flashing. If your door is running under Apex, RemoteAccess or QuickBBS, paging from within the door will even cause the Want-Chat indicator to stay lit when the user returns to the BBS) [Alt]-[J] - Allows the sysop to shell to DOS, if enough memory is available. Simply type EXIT to return to the door again. [Alt]-[H] - Hang up on the user. When the sysop does this, OpenDoors will optionally call a function you have indicated in the OpenDoors control structure, to allow you to close files, etc. OpenDoors will then exit with the appropriate errorlevel: 0 - A critical error has occurred 1 - Carrier lost, user off-line 2 - Sysop terminated call, user off-line 3 - User time used up, user STILL ON-LINE 4 - Keyboard inactivity timeout, user off-line 5-255 - Defined by your door These errorlevel will allow sysops using your door to optionally log the user back on-line, place the BBS in "wait for call" mode, or whatever they wish, depending on how the door exited [Alt]-[L] - This key locks the user out of the BBS. It first hangs up on the user, and then sets their security level to 0, to prevent them from ever logging on again. This feature may require use of the EXITINFO.BBS file, depending on what system the door is running under. [Alt]-[K] - The "User Keyboard-Off" key allows the sysop to temporarily prevent the user from typing anything on their keyboard. This has no effect on the local keyboard, but causes OpenDoors to ignore any keystrokes from remote. OpenDoors Door Toolkit Manual - Version 4.10 Page 26 [Alt]-[N] - The "Sysop Next" key, this function reserves the system for use by the sysop after the user logs off, if the door is running under an Apex or RA 1.00 or later system. [Alt]-[D] - "Drop to BBS" key. This function allows the sysop to exit the door and return the user to the BBS, without hanging up. [F1]..[F10] - The Function keys [F1] thru [F10] allows the sysop access to various types of information on the status line, or to turn the status line off. These keys are as follows: [F1] - Display basic door and user information [F2] - Display phone numbers and important dates [F3] - Display security flags and up/download info [F4] - Display system information and current time [F5] - Display message info and user's settings [F6] - Display chat reason and sysop's comment [F9] - Display help information for sysop [F10] - Turn off the status line Now, let us take a closer look at the actual source code for the EZVote door. If you have not already printed out a copy of this manual, and possibly the EZVOTE.C file as well, it would probably be a good idea to do so now. Notice that near the top of the program, along with all the standard header files, the OPENDOOR.H file is included. This file must be included in all programs written under OpenDoors. If you are placing the OPENDOOR.H file in the same directory as the door you are compiling, simply include the line: #include "opendoor.h" in your program. If you are placing the OPENDOOR.H in your include directory, along with the rest of your header files, use the line: #include <opendoor.h> You may notice the file structure just before the main function in the EZVote door. EZVote stores its data file of questions, results, and who has voted on what in a single fixed length file called EZVOTE.BBS. This file is simply a memory image of the file structure. The elements in this structure includes the total number of questions, the total number of users that the door knows about, the questions they have and have not voted on, the actual questions and answers themselves, and so on. The execution of the EZVote door begins with the allocation of memory for its file structure. OpenDoors Door Toolkit Manual - Version 4.10 Page 27 Next, the EZVote program calls the od_init_with_config() function. This function instructs OpenDoors to begin execution, by reading a configuration file if available, setting up some of its internal storage, reading the door information file (eg. DORINF1.DEF, DOOR.SYS), and begins communicating with the modem (if it is not running in local mode). The od_init_with_config() function is only required if you wish your door to use a configuration file. In this case, od_init_with_config() must be the first OpenDoors function you call. If you do not call the od_init_with_config(), the OpenDoors initialization process will ocurr whenever your program calls its first OpenDoors function. For more information on configuration files in OpenDoors, please see page . The EZVote door also include the optional OpenDoors log file system. To add log file capabilities to a door, the line od_log_open() is simply placed after the od_init_with_config() function. OpenDoors will now automatically include the logfile system, and make the most common logfile entries, such as the time the user enters and exits the door, sysop pages, shell to DOS, and so on. The next line in the main() function of the EZVote door looks as follows: od_control.od_before_exit=save_file; This line simply tells OpenDoors to call the save_file() function (to save the EZVOTE.BBS data file) before it exits. If you do not wish OpenDoors to call any function before exiting, simply leave this variable set to its default of NULL. Keep in mind that OpenDoors automatically shuts down the door and returns control to the BBS, if it detects that the user's time has expired, if the user has hung up, and so on. As a result, it is possible that OpenDoors could cause your program to exit at any time an OpenDoors door driver is called. Hence, the use of this od_control. od_before_exit variable will allow you to finish any uncompleted activities, such as closing data files, before control is returned to the BBS. After EZVote has performed these door related startup procedures, it opens/creates its EZVOTE.BBS data file. If the EZVOTE.BBS file exists in the current directory, it is opened and read. If the file does not exist, then EZVote creates a new one. Next, EZVote searches through the data file for the name of the user who is currently on-line. This allows EZVote to keep track of all the users who have used it, with its own statistics about them. EZVote also compares the name of the user currently on-line to the name of the system's sysop. If they match, the EZVote will also enable it's sysop-only functions, such as deleting questions from the door. Once EZVote has done all of this housekeeping, it begins to communicate with the user. All of the functions performed by the EZVote door center around the main menu, which is displayed by the main_menu() function. The EZVote door is written in such a OpenDoors Door Toolkit Manual - Version 4.10 Page 28 way that the main menu may be either the built-in menu, or one contained in an external, sysop definable, ASCII/ANSI/AVATAR file. Hence, the main_menu() function begins by attempting to display a EZVOTE.ASC/ANS/AVT file, by use of the od_send_file() function. If such a file is found, the od_send_file() function will display the appropriate file corresponding to the current graphics mode, and return a value of TRUE. (For more information on TRUE/FALSE Boolean values, see the entry on "BOOLEAN VALUES", in the glossary.) The EZVote main_menu() function then tests the value returned by the od_send_file() function. If the od_send_file() function was unable to find the appropriate file, OpenDoors proceeds to display its built-in main menu. Before the main menu is displayed, you will notice that the screen is cleared (the od_clr_scr() function only clears the screen if the user has screen clearing mode turned on), as well as the keyboard input buffer. The keyboard buffer is cleared by the od_clear_keybuffer() function, in order to prevent unwanted behaviour, if the user has been pressing keys on their keyboard while the door was loading, etc. While all the internal OpenDoors functions check for ANSI/AVATAR mode, EZVote also checks the status of the od_control.user_ansi variable. This allows it to only display extended characters (such as the line and box drawing characters) to users who have ANSI/AVATAR capabilities. Menu display is accomplished using the od_disp_str() function. Also note that when using the OpenDoors display functions you must end a line with the "\n\r" sequence, instead of the single "\n" that you would use with the C printf() function. In door program, both the "\n" (line feed) and "\r" (carriage return) characters must be sent to the modem, in order that the text is displayed correctly on the remote user's screen. The remainder of the EZVote door should be more or less self- explanatory. To learn more about OpenDoors and door programming, you should now continue to look through the following chapter, which describes the functions that you can use when creating doors with OpenDoors. You will probably also be interested in looking at, compiling, testing and altering the other example programs included in the OpenDoors package. There are also a number of example programs throughout this manual, that will help to demonstrate how you can accomplish various things using OpenDoors. OpenDoors Door Toolkit Manual - Version 4.10 Page 29 -------------------------------------------------------------------------------- CHAPTER 4 - THE OPENDOORS DOORDRIVER FUNCTIONS -------------------------------------------------------------------------------- AN OVERVIEW OF THE FUNCTIONS ------------------------------------------------------------------------------- All of the activities of an OpenDoors door program are coordinated through one of two facilities - the door driver functions, and the OpenDoors door control structure. Any door program written with the OpenDoors door driver will have to make use of the OpenDoors door driver functions for all of its door-related input and output. The OpenDoors door driver functions also provide many capabilities to your door programs, such as displaying ASCII/ANSI/AVATAR files, controlling the door's operation, and so on. You should also note that much of the information about the user who is online, information about the system your door is running under, and variables to customize OpenDoors' behavior, are accessed not through the door driver functions, but the OpenDoors control structure. The control structure is described in the section beginning on page 119. Below, the door driver function available to door programs written with OpenDoors are listed, grouped according to general categories of functionality. On the following pages, the OpenDoors functions and their use is described in detail, listed in alphabetical order. -------------------------------------------------------------------------------- OUTPUT DISPLAY FUNCTIONS FUNCTIONS ----------------- od_disp_str() Displays a normal, NULL-terminated string. (page 46) od_disp() Sends the specified number of characters to the modem, with or without local echo. (page 44) od_printf() Performs formatted output, as the printf() function does. Also allows imbedded codes to change display colour. (page 93) od_putch() Displays a single character. (page 97) od_emulate() Displays a character, interpreting imbedded ANSI/AVATAR codes. (page 62) OpenDoors Door Toolkit Manual - Version 4.10 Page 30 od_repeat() Displays the same character any number of times, using AVATAR optimization, if possible. (page 99) od_draw_box() Draws a window on the screen in ANSI/AVATAR graphics mode. (page 48) COLOUR FUNCTIONS ---------------- od_set_colour() Sets current colour to specified foreground and background settings. (page 108) od_set_attrib() Sets current colour to specified IBM-PC display attribute. (page 105) SCREEN FUNCTIONS ---------------- od_clr_scr() Clears the screen, if user has screen clearing enabled. (page 42) od_clr_line() Clears the remainder of current line. (page 40) od_set_cursor() Sets the position of the cursor, if ANSI/AVATAR mode is enabled. (page 111) FILE DISPLAY FUNCTIONS ---------------------- od_send_file() Displays an ASCII/ANSI/AVATAR file (for instance, an .ANS file created by a program such as "TheDraw" (page 101) od_hotkey_menu() Displays an ASCII/ANSI/AVATAR menu file, with hotkeys active. (page 71) od_list_files() Lists the files available for download in an area, using a FILES.BBS file. (page 87) -------------------------------------------------------------------------------- INPUT od_get_answer() Inputs a single key from the keyboard, FUNCTIONS allowing only particular responses. (page 66) od_get_key() Inputs a single key from the keyboard, optionally waitin if a key is not available. (page 67) od_input_str() Inputs a string of specified length, from the keyboard. (page 83) od_edit_str() Formatted string editing function, requiring ANSI/AVATAR graphics. (page 51) OpenDoors Door Toolkit Manual - Version 4.10 Page 31 od_clear_keybuffer() Removes any waiting keys from the keyboard input queue. (page 38) -------------------------------------------------------------------------------- DOOR od_init() Begins door operation by setting up FUNCTIONS the OpenDoors control structure, setting up the local screen, initializing the FOSSIL driver (if applicable), and reading the door information file. (page 73) od_exit() Ends door operations, closing the FOSSIL driver, re-writing the door information file, and optionally returning control to the BBS. (page 64) od_kernal() The central OpenDoors control function, which should be executed every few seconds. (page 85) od_set_statusline() Temporarily alters the setting of the current OpenDoors status line. (page 113) od_page() Allows the user to page the sysop for chat. (page 92) od_spawn() OpenDoors quick-spawn function. Executes an external program (eg. file compressor, external protocol, etc.) on a separate screen, restoring the OpenDoors screen afterwards. (page 115) od_spawnvpe() OpenDoors full-featured spawn function. Executes an external program on a seperate screen, searching the path for tthe program, allowing you to specify an environment to pass to the child process, and returning the errorlevel returned by the chiold process. (page 117) od_carrier() Allows detection of carrier signal in programs that have disabled OpenDoors internal checking. (page 34) -------------------------------------------------------------------------------- CONFIG od_init_with_config() Begins doors operations, parsing FILE information from a configuration file. FUNCTIONS (page 76) od_colour_config() Transfers a colour configuration line to a colour attribute value. (page 36) OpenDoors Door Toolkit Manual - Version 4.10 Page 32 -------------------------------------------------------------------------------- LOGFILE od_log_open() Opens a log file and begins logging FUNCTIONS activities. (page 89) od_log_write() Creates a log file entry. (page 91) OpenDoors Door Toolkit Manual - Version 4.10 Page 33 OD_CARRIER() -------------------------------------------------------------------------------- PURPOSE To determine the status of the carrier detect signal, in programs where OpenDoors' internal carrier detection has been disabled. FORMAT int od_carrier(void); RETURNS TRUE if a carrier is present, or FALSE if no carrier is present, or in local mode. DESCRIPTION Usually, you will not have any use for the od_carrier() function, as OpenDoors automatically monitor's the carrier detect signal, and will correctly recover if the carrier detect signal is lost while the door is operating in remote mode. However, in some programs, you may wish to disable OpenDoors' internal carrier detection routines, using the od_control.od_disable variable. Two such cases in which you might want to do this, are a call-back verification door, which disconnects the user and attempts to call them back, or in a terminal program, which is in fact not a door at all (and as such you would not want to have OpenDoors exit when the carrier detect signal is lost). In cases like these, you will then be able to use the od_carrier() function in order to determine the state of the carrier detect signal. This function will return a Boolean value (for more information on Boolean values, see the Glossary which begins on page 192), of either TRUE or FALSE. If a carrier detect signal is present when the function is called, it will return TRUE, and if no carrier detect signal is detected, it will return FALSE. Since there is no remote connection, and thus no carrier when OpenDoors is operating in local mode, this function will always return a value of FALSE in local mode. EXAMPLE As an example of the use of this function, let us consider a call back verification door, which hangs up on the user, and then calls the user back at their entered phone number, in order to verify the correctness of that number. This program would probably contain a function that is responsible for disconnecting the user, waiting for the connection to be broken, and then phoning the user. At some point in this function, likely just prior to the point where the function hangs up on the user, you would disable OpenDoors' internal carrier detection, using the line: od_control.od_disable |= DIS_CARRIERDETECT; OpenDoors Door Toolkit Manual - Version 4.10 Page 34 You would then want to have a piece of code which would simply wait up to a given amount of time for the carrier signal to drop. If this occurs, you would continue to place the call, and if it does not occur, you would probably try your hangup procedure one or two more times. In this example, the function will simply return with a value of FALSE if the carrier signal does not drop, and will call the place_call() function if it does drop, returning the Boolean value returned by the place_call() function. Our piece of example code would be as follows: char hangup(void) { register long timer; ... /* Perform hangup */ /* Wait up to 30secs (546 ticks) */ timer=(*(long far *)0x46cL)+546L; while(timer>=*(long far *)) { /* If carrier has been lost, dial the modem */ if(!od_carrier()) return(place_call()); } return(FALSE); } OpenDoors Door Toolkit Manual - Version 4.10 Page 35 OD_COLOUR_CONFIG() -------------------------------------------------------------------------------- PURPOSE Parses a colour configuration line from the configuration file, generating a colour attribute value. FORMAT unsigned char od_colour_config(char *config_line); RETURNS Colour attribute value DESCRIPTION This function will be of use if you are using the configuration file system of OpenDoors, and wish to allow the sysop to specify text colours to be used in your door. While OpenDoors automatically recognizes colour configuration settings for things such as sysop chat mode and FILES.BBS listings, you may wish to add additional colour configuration options. In this case, you could call the od_colour_config() function from your custom line function. For more information on the custom line function, see the description of the od_init_with_config() function. To use this function, simply pass the configuration file line you wish to have parsed to the function in it's single parameter. The function will then return a colour attribute value in the same format that is used but the od_set_attrib() function. Colours are specified using a string of the format: {Flashing} {Bright} [foregoround] on [background] Where "Flashing" is an optional keyword indicating that the text should be flashing. "Bright" is an optional keyword indicating that the foreground colour should be bright. Foreground is the name of a foreground colour, and background is the name of a background colour. Case (upper or lower) is not significant. The colour keywords are language configurable, using the global array od_config_colours. The default definition of this array is listed below. Note that all keywords must all be uppercase. The first eight elements in this array are the names of the eight basic colours, in order from 0 to 7. The next two options are alternative names for the colours 6 and 7. This is provided because these two colours look significantly different in low and high intensity, and will often be called by different names. The last to elements in this array are the "Bright" and "Flashing" keywords. char od_config_colours[12][33]={ "BLACK", "BLUE", "GREEN", "CYAN", "RED", "MAGENTA", "YELLOW", OpenDoors Door Toolkit Manual - Version 4.10 Page 36 "WHITE", "BROWN", "GREY", "BRIGHT", "FLASHING"}; SEE ALSO od_init_with_config() EXAMPLE See the example accompanying the od_init_with_config() function documentation. OpenDoors Door Toolkit Manual - Version 4.10 Page 37 OD_CLEAR_KEYBUFFER() -------------------------------------------------------------------------------- PURPOSE Function to clear the input keyboard buffer FORMAT void od_clear_keybuffer(void); RETURNS N/A DESCRIPTION OpenDoors maintains its own keyboard input buffer, in order to permit the user to "type ahead" - to send input to the door prior to the time when it is ready to process those key presses. For example, the user could begin to type a command while a menu is still being displayed, and when your door reaches the point of inputting the menu command, the characters already typed by the user will already be waiting for the OpenDoors input functions. Note that the keyboard input buffer will include both the keys hit by the user on-line, and the non-function keys (ie, Alt-C will not appear in the OpenDoors keyboard buffer), hit by the sysop. This allows both the user on-line and the sysop to control the door at any time. If the sysop wishes to temporarily prevent the user from having any control over the door, the sysop may use the Alt-K (user-keyboard off) key. The key strokes placed in the OpenDoors type-ahead buffer will be retrieved by the od_get_key() and od_input_str() functions. The keyboard buffer can contain a maximum of 64 user keystrokes in this version of OpenDoors, after which any additional keystrokes will simply be discarded by OpenDoors. There are times, however, when you will want to erase any keys that have been hit by the user, to prevent them from typing ahead. For example, if your door has been busy doing some processing for a few moments, they user may have been pressing keys on their keyboard - perhaps in the hope that doing so will speed things up. These keys will be waiting in the type-ahead buffer, and if one of the keys the user entered was a valid response to the next prompt in your door, the user may find that they have accidentally made a choice they did not wish to. A well designed door will simply erase the contents of the type-ahead buffer after any long period of internal processing, etc. Keep in mind that too much use of the od_clear_keybuffer() function can be just as undesirable as not using it all, as there are times when the presence of the keyboard buffer can prove to be very useful for the user of a door. To erase the contents of the type-ahead buffer, you simply call the od_clear_keybuffer() function. This function takes no parameters, and does not return any value. OpenDoors Door Toolkit Manual - Version 4.10 Page 38 SEE ALSO od_get_key(), od_input_str(), od_edit_str() EXAMPLE For one example of the use of the od_clear_keybuffer() function, see the example door program EZVote, which is described beginning on page 25. Below is another example of using this function. In this case, we present a simple function, wait_for_return(), which simply pauses for the user to press their [Enter]/[Return] key. The function begins by displaying a prompt asking for the [Enter] or [Return] key to be pressed. The function then clears the keyboard input buffer, and waits until the user presses the carriage return key, using the od_get_key() function. Note also that this function will only continue if the user has pressed the correct key. This is a good idea in all door programs, as it allows your door to distinguish between a character pressed by the user, and a "line noise" character. void wait_for_return(void) { /* Display prompt */ od_disp_str("Please Press [Enter] to continue...\n\r"); od_clear_keybuffer(); /* Clear keyboard buffer */ while(od_get_key(TRUE)!=13); /* Wait for Enter key */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 39 OD_CLR_LINE() -------------------------------------------------------------------------------- PURPOSE Clears the rest of the current display line FORMAT void od_clr_line(void); RETURNS N/A DESCRIPTION This function clears the line that the cursor is on, from the cursor position to the end of the line. After the rest of the line is cleared, the cursor is automatically returned to the position it was at prior to issuing the command. Hence, if the display line the cursor was located on looked as follows, with the underscore (_) character representing the cursor position: This is a_line of text! With the cursor between the words "a" and "line", after the od_clr_line command is issued, the line would appear as follows: This is a_ With the cursor directly following the word "a". Note that this function places a space character at the cursor location, and every location up to the end of the line. When the door is running in plain ASCII mode, this command will simply clear the rest of the line by manually sending a series of space and backspace characters. When ANSI or AVATAR modes are active, the corresponding ANSI/AVATAR control sequence will be sent in order to accomplish the line clear. Since the graphics mode sequences are much shorter than the sequence that would be required to clear the line manually, the use of this function will cause your door's graphics to display much more quickly when ANSI or AVATAR modes are active. Also note that in ANSI or AVATAR graphics modes, the line will be cleared with the currently selected colour attribute. Thus, if you wanted to place a blue background on a particular line, you would use the od_set_colour() (or od_set_attrib()) function, then use the od_set_cursor() function to locate the cursor at the beginning of the desired line, followed by the od_clr_line() function. Just such a procedure is demonstrated in the example, below. SEE ALSO od_clr_scr(), od_set_cursor() OpenDoors Door Toolkit Manual - Version 4.10 Page 40 EXAMPLE Below, is an example of a function that clears an entire line with a specified colour. Since this function performs operations that require ANSI or AVATAR graphics mode, it should only be used in a case where these modes are known to be available. For example, this function would be useful in a full-screen editor or viewer, or when performing ANSI animations. The function accepts three parameters: the line to be cleared (where 1 is the first line, 2 the second, and so on), the foreground colour of this line, and the background colour of this line. This function differs from the od_clr_line() function itself in several important manners. First of all, this function clears the entire line, whereas the od_clr_line() function can be used to clear only the remaining characters of the line, after any particular location. Also, as mentioned before, this function selects a colour to clear the line to, and moves the cursor to the line which is to be cleared - neither of which is done by the od_clr_line() function. void clear_line(char line_number,char foreground,char background) { od_set_cursor(line_number,1); /* move to correct line */ od_set_colour(foreground,background); /* set colour */ od_clr_line(); /* clear entire line */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 41 OD_CLR_SCR() ------------------------------------------------------------------------------- PURPOSE The OpenDoors clear screen function FORMAT void od_clr_scr(void); RETURNS N/A DESCRIPTION The od_clr_scr() function can be used to clear the door screen. (ie, the user's screen and local screen with the exception of the status line are cleared.) Also, if your door is running under a system, such as RemoteAccess, Apex or QuickBBS, which produce an EXITINFO.BBS file, this function will detect the user's screen clearing setting, and only clear the screen if screen clearing is turned on. If an EXITINFO.BBS file is not available, this function will always clear the screen (as OpenDoors will not be able to determine whether or not the user has screen clearing enabled). If your door will be running under BBS systems that do not pass the user's screen clearing setting to the door, you may wish to determine yourself whether or not the user's system supports screen clearing codes, during the first time the user uses the door. You will then be able to store this setting in a data file. The example below demonstrates how to detect whether or not the user's system supports screen clearing. You should note that the ability for the user's terminal to support screen clearing codes is independent of the user's ANSI / AVATAR graphics mode settings. The od_clr_scr() function accomplishes screen clearing by sending an ASCII 12 character to the remote terminal, and thus ANSI or AVATAR graphics are not necessarily required in order to clear the screen. For more information on the user's screen clearing setting, please refer to the user_attrib variable in the OpenDoors Control Structure chapter of this manual. If you wish to force a screen clear, regardless of the user's screen clearing setting, simply use the function call: od_emulate(12); SEE ALSO od_clr_line() EXAMPLE Below is an example of a function which determines whether or not the user's system supports screen clearing. This function will return a value of TRUE if screen clearing is supported, and will return a value of FALSE if screen clearing is not supported: OpenDoors Door Toolkit Manual - Version 4.10 Page 42 int user_supports_screen_clearing(void) { char answer; /* display instructions to user */ od_disp_str("In order for this door to function\n\r"); od_disp_str("correctly, we must know whether or not\n\r"); od_disp_str("your system supports screen clearing.\n\r"); od_disp_str("In a moment, we will attempt to clear\n\r"); od_disp_str("your screen in order to test your system's\n\r"); od_disp_str("capabilities.\n\r\n\r"); od_disp_str("Please press [Enter]/[Return] when you are\n\r"); od_disp_str("Ready to perform this test.\n\r"); while(od_get_key(TRUE)!=13); /* wait for [Return] key */ od_clr_scr(); /* attempt to clear screen */ /* ask user if their screen cleared */ od_disp_str("Did your screen just clear? (Y/N)\n\r"); for(;;) /* loop until user chooses [Y]es or [N]o */ { answer=od_get_key(TRUE); /* Get user's answer */ if(answer=='y' || answer=='Y') return(TRUE); if(answer=='n' || answer=='N') return(FALSE); } } OpenDoors Door Toolkit Manual - Version 4.10 Page 43 OD_DISP() ------------------------------------------------------------------------------- PURPOSE Sends a buffer of text with optional local echo FORMAT void od_disp(char *buffer, int size, char local_echo); RETURNS N/A DESCRIPTION This function allows you to send a buffer of text of any specified length, with the option of enabling or disabling local echo. You will probably have little use for this function - instead you will most likely display strings using either the od_disp_str() or od_printf() functions, depending on whether or not you wish to use printf()'s formatting options. For a breakdown of the uses of the various OpenDoors display functions, see the description of the od_disp_str() function, on page 46. There are two cases when this function will come in useful: 1.) If you wish to display a buffer of characters of known length, which may contain null (ASCII 0) characters. Since this character is used by the C language to indicate the end of a string, the other two string display functions (od_disp_str() and od_printf()) will not send this character to the remote system. 2.) If you wish to send text to the remote system without having it displayed on the local screen, or if you wish to send strings to the modem when it is in command mode, without having these characters displayed on the local screen. The od_disp() function is called with three parameters. The first parameter, *buffer, is a pointer to a buffer of characters you wish to have displayed. The second parameter, size, is simply the number of characters in the buffer to be displayed. If the third parameter, local_echo, is set to TRUE, then all characters sent to the modem will also be displayed on the local screen. If the third parameter is set to FALSE, then the buffer will be sent to the modem without being echoed to the sysop's screen. SEE ALSO od_disp_str(), od_printf(), od_putch(), od_repeat(), od_emulate() EXAMPLES The following are a few examples of the use of the od_disp() function: OpenDoors Door Toolkit Manual - Version 4.10 Page 44 In order to display a single character, contained in the variable "character", without echo to the local screen: od_disp(&character,1,FALSE); In order to send a command to the modem (only if you know that the modem is in command mode), with the command contained in the null-terminated string "string": od_disp(string,strlen(string),FALSE); In order to send exactly 5 characters from the buffer "buffer", WITH echo to the local screen: od_disp(buffer,5,TRUE); OpenDoors Door Toolkit Manual - Version 4.10 Page 45 OD_DISP_STR() -------------------------------------------------------------------------------- PURPOSE Displays a string to the screen (remote and local) FORMAT void od_disp_str(char *string); RETURNS N/A DESCRIPTION The two functions most often used for displaying strings within a door are the od_disp_str() and od_printf() functions. The od_printf() function allows for formatted output, whereas the od_disp_str function simply displays the actual contents of the string passed to it. If you wish to display a single character, use the od_putch() function. If you wish to send a string or buffer to the modem without local echo, use the od_disp() function. If you wish to send a sequence of the same character to the modem, the od_repeat() function will use graphics control codes, if available to display the sequence much faster than simply sending the same character in repetition. Also, if you wish to send ANSI or AVATAR graphics control codes, and have them emulated on the local screen, use the od_emulate() function. The od_disp_str() function displays the contents of the null- terminated string pointed to by *string. Display is sent to both the local screen and modem (presuming the door is not running in local mode). All modem output is accomplished through the Fossil driver. Also, if the variable directvideo is set to 1, then the screen display is accomplished by direct writes, either to video memory, or to the DesqView screen buffer, if DesqView is running. If directvideo is set to 0, then BIOS function calls are used for video output. While using direct video writes results in much greater screen updates speeds, it will also cause difficulties for people running in multitaskers, such as DesqView. Ideally, you could design your door to either accept a command-line parameter or a setting in it's configuration file to allow the sysop using your door to select either direct or BIOS writes. An important thing to keep in mind when using the od_disp_str() function, is that you should use "/n/r" instead of simply "/n" for a new line. This is due to the fact that terminal programs usually require a carriage-return line-feed sequence (/n/r), instead of just a line-feed (/n). For example, instead of using: od_disp_str("Hello world!\n"); You should use: OpenDoors Door Toolkit Manual - Version 4.10 Page 46 od_disp_str("Hello world!\n\r"); To change the cursor colour or location of output with the od_disp_str() function, refer to the od_set_cursor() and the od_set_attrib() functions. SEE ALSO od_disp(), od_printf(), od_putch(), od_repeat(), od_emulate() EXAMPLES Below are a few examples of various uses of the od_disp_str() function: Displaying three string constants on separate lines: od_disp_str("This is an example\n\r"); od_disp_str("of the OpenDoors\n\r"); od_disp_str("od_disp_str() function\n\r"); Displaying three string constants on the same line: od_disp_str("Another "); od_disp_str("od_disp_str() "); od_disp_str("example\n\r"); Displaying a string variable: char string[80]; strcpy(string,"This is a string!\n\r"); od_disp_str(string); OpenDoors Door Toolkit Manual - Version 4.10 Page 47 OD_DRAW_BOX() -------------------------------------------------------------------------------- PURPOSE Draws a window on the screen in ANSI or AVATAR graphics modes. FORMAT int od_draw_box(char left, char top, char right, char bottom); RETURNS TRUE on success, FALSE on failure DESCRIPTION This function is for use in ANSI or AVATAR graphics modes. This function will draw a window in the current display attribute, at the specified location on the screen. The boarder of the window is made up of the characters specified in the od_control. od_box_chars[] array. If AVATAR graphics mode is available, this function uses AVATAR control codes to display the window in less than 1/10 the length of time required to display the window in ANSI mode. The first two parameters of this function, "left" and "top", specify the coordinates of the top, left-hand corner of the window to be draw. The third and fourth parameters, "right" and "bottom", specify the coordinates of the bottom, left-hand corner of the window. Like the values passed to the od_set_cursor() function, these coordinates are relative to the upper left-hand corner of the screen, with the position (1,1) being this corner. As mentioned above, this function will display the window in the current text colour. Thus, before calling this function, you should use either the od_set_colour() or the od_set_attrib() function to specify the colour in which you would like to have the window displayed. Normally, the boarder of the window will be displayed using the IBM extended ASCII characters which produce a single line boarder. However, you may wish to have the boarder displayed using different characters. In this case, the characters used to display the boarder can be specified by the od_control. od_box_chars variable, described in the OpenDoors control structure section of this manual. SEE ALSO od_set_colour(), od_set_attrib(), od_clr_scr(), od_edit_str(), od_set_cursor() EXAMPLE As an example of the use of the od_draw_box() function in conjunction with the od_edit_str() function, we show a portion of a program which displays a window, and allows the user to input the name of a file they would like to upload, a description of the file, and whether they want it to be a private upload. The OpenDoors Door Toolkit Manual - Version 4.10 Page 48 user is able to move among fields using the tab key, and select a "continue" button when they are finished. The function returns TRUE if the user selects continue, and FALSE if the user presses [ESCape]. // Main "dialog box" function int get_information(char *filename, char *description, char *private) { char current_field=1; // Currently selected field int choice; // User's choice od_set_colour(L_WHITE,D_BLUE); // Display window od_draw_box(10,5,70,13); od_set_cursor(5,25); // Display window title od_set_colour(L_GREEN,D_BLUE); od_disp_str(" ENTER FILENAME INFORMATION "); od_set_colour(L_CYAN,D_BLUE); // Display fields and titles od_set_cursor(6,15); od_disp_str("FILENAME : "); od_repeat(176,13); od_set_cursor(7,12); od_disp_str("DESCRIPTION : "); od_repeat(176,43); od_set_cursor(8,16); od_disp_str("PRIVATE : "); od_repeat(176,2); draw_button(); filename[0]='\0'; // Blank out contents of input variables description[0]='\0'; private[0]='\0'; for(;;) // Main dialog box loop { if(current_field==4) // If field is the button { od_set_colour(L_GREEN,D_BLUE); // Highlight button draw_button(); do // Loop until user presses [TAB], [ENTER], or [ESC] { choice=od_get_key(TRUE); } while(choice!=9 && choice!=13 && choice!=27); od_set_colour(L_CYAN,D_BLUE); // Un-highlight button draw_button(); if(choice==13) return(TRUE); // If [ENTER] was pressed if(choice==27) return(FALSE); // If [ESC] was pressed current_field=1; // Otherwise, [TAB] was pressed } switch(current_field) // According to selected field OpenDoors Door Toolkit Manual - Version 4.10 Page 49 { // Input from the appropriate line case 1: choice=od_edit_str(filename,"FFFFFFFFFFFF",6,26, 0x1b,0x1a,176, EDIT_FLAG_EDIT_STRING| EDIT_FLAG_ALLOW_CANCEL| EDIT_FLAG_FIELD_MODE| EDIT_FLAG_KEEP_BLANK); break; case 2: choice=od_edit_str(description,"*******************", 7,26,0x1b,0x1a,176, EDIT_FLAG_EDIT_STRING| EDIT_FLAG_ALLOW_CANCEL| EDIT_FLAG_FIELD_MODE| EDIT_FLAG_KEEP_BLANK); break; case 3: choice=od_edit_str(private,"Y",8,26, 0x1b,0x1a,176, EDIT_FLAG_EDIT_STRING| EDIT_FLAG_ALLOW_CANCEL| EDIT_FLAG_FIELD_MODE); } // If user pressed [ESCape] if(choice==EDIT_RETURN_CANCEL) return(FALSE); // If user choice to go to previous field if(choice==EDIT_RETURN_PREVIOUS) { if(current_field==1) // If at first field { current_field=4; // Go to last field } else // If not at first field { --current_field; // Go to previous field } } else // If user chose next field { ++current_field; // Go to next field } } } void draw_button(void) // Function to display the button { od_draw_box(12,10,23,12); // Draw box for button od_set_cursor(11,14); od_disp_str("Continue"); // Display text in button } OpenDoors Door Toolkit Manual - Version 4.10 Page 50 OD_EDIT_STR() -------------------------------------------------------------------------------- PURPOSE Allows you to perform formatted input with full line editing features, etc., in ANSI / AVATAR graphics mode. FORMAT unsigned int od_edit_str(char *input_string, char *format_string, int row, int col, unsigned char normal_colour, unsigned char highlight_colour, char character, unsigned int flags); RETURNS This function will return one of the following values. Note that some of these values will only be applicable in certain cases. For example, EDIT_RETURN_CANCEL will never be returned if you have not enabled the cancel feature of this function. EDIT_RETURN_ERROR Indicates that an error has occurred, and the edit function was unable to run. This will occur if there is an error in one of the parameters, or if ANSI / AVATAR graphics is not available EDIT_RETURN_CANCEL Indicates that the user pressed the cancel key [ESC], and that the string was left unaltered. EDIT_RETURN_ACCEPT Indicates that the user pressed the accept key [Enter], or that the auto- enter feature was activated. EDIT_RETURN_PREVIOUS Indicates that the user wishes to move to the previous field, by pressing [UP ARROW], [SHIFT]-[TAB], etc. EDIT_RETURN_NEXT Indicates that the user wishes to move to the next field, by pressing [DOWN ARROW], [TAB], etc. DESCRIPTION To perform string input within OpenDoors, one of two functions can be used, od_input_str() and od_edit_str(). The first function, od_input_str(), allows simple line input and editing, and can be used in ASCII, ANSI and AVATAR modes. The second function, od_edit_str(), allows many formatted input options, advanced line editing, and other features, but requires the use of ANSI or AVATAR graphics modes. The od_edit_str() function provides a great deal of features and functionality, and as such, may appear to be one of the most complicated functions within the OpenDoors door driver. The simple fact that the function accepts eight parameters may make OpenDoors Door Toolkit Manual - Version 4.10 Page 51 the od_edit_str() function seem daunting. However, you need not concern yourself with all of the features available from the od_edit_str() function in order to make use of it. Reading through this section should give you some idea of what is possible with the od_edit_str() function, and the following examples should help to demonstrate the use of this function. The first thing to remember about the od_edit_str() function is that it requires ANSI / AVATAR graphics, as the graphics control codes are needed for the advanced editing capabilities provided by the od_edit_str() function. Thus, you will only want to use the od_edit_str() in one of two cases; either in a door which requires ANSI / AVATAR graphics to operate, or in the case that you program tests for the availability of ANSI / AVATAR graphics, and only calls od_edit_str() if graphics is available. If ANSI / AVATAR graphics is not available, your program should use the od_input_str() function instead. As mentioned above, the od_edit_str() function allows for advanced line editing, such as inputting and deleting text from the middle of the string (whereas the od_input_str() function only allows editing from the end of the string, such as backspacing to erase a mistake). The edit functions available from the od_edit_str() are listed below. Note that some of these functions may or may not be available, depending upon the capabilities of the user's terminal program. While there is no single standard used for the transmission of special edit keys such as the arrow keys, the od_edit_str() function makes as much effort as possible to make all of the edit features available to most terminal programs. Many of the edit functions can be accesses using either [CONTROL]-key combinations or special keys such as the arrow keys, delete key, and so on. OpenDoors will recognize most of these special control keys when sent as either an ANSI control sequence (which is sent by most terminal programs), or as a DoorWay style scan code / ASCII code sequence (which is also available from many terminal programs, but is not usually required). The od_edit_str() edit functions are as follows. Note that all edit functions are always available from the local keyboard. HOME - Moves the cursor to the beginning of the line being edited. Press the [HOME] key, either in DoorWay mode or from the local keyboard. END - Moves the cursor to the end of the line being edited. Press the [END] key, either in DoorWay mode or from the local keyboard. DELETE CHARACTER - Deletes the character under the cursor. Press [DELete] on the local keyboard, in DoorWay mode, and under many terminal programs without DoorWay mode. Alternatively, press [CONTROL]-[G]. BACKSPACE - Deletes the character left of the cursor. Press [BACKSPACE] or [CONTROL]-[H]. OpenDoors Door Toolkit Manual - Version 4.10 Page 52 TOGGLE INSERT MODE - Switches the od_edit_str() function between insert mode and overwrite mode. Press [INSert], either in DoorWay mode, or from the local keyboard. Alternatively, press [CONTROL]-[V]. CURSOR LEFT - Moves the cursor left one character. Press [LEFT ARROW] on the local keyboard, in DoorWay mode, and under many terminal programs without DoorWay mode. Alternatively, press [CONTROL]-[S]. CURSOR RIGHT - Moves the cursor right one character. Press [RIGHT ARROW] on the local keyboard, in DoorWay mode, and under many terminal programs without DoorWay mode. Alternatively, press [CONTROL]-[D]. ERASE ENTIRE LINE - Press [CONTROL]-[Y]. ACCEPT INPUT - Press the [ENTER] / [RETURN] line to accept the input. Alternatively, press [CONTROL]-[Z]. Note that this key will only work when the current input is "valid" (ie, it conforms to the format string, which is described below) CANCEL INPUT - Only available if specifically enabled on the od_edit_str() command line. Press [ESCape]. NEXT FIELD - If enabled, allows the user to move to the next field in a dialog box / form. Press [DOWN ARROW] in DoorWay mode and under many terminal programs without DoorWay mode. Alternatively, press [TAB]. Note that the [DOWN ARROW] key is NOT usually available from the local keyboard, as it is usually used to adjust the user's remaining time. PREVIOUS FIELD - If enabled, allows the user to move to the previous field in a dialog box / form. Press [UP ARROW] in DoorWay mode and under many terminal programs without DoorWay mode. Alternatively, press [SHIFT]- [TAB] on the local keyboard or in DoorWay mode. Again, note that the [UP ARROW] key is NOT usually available from the local keyboard, as it is usually used to adjust the user's remaining time. Let us now look at the parameters which the od_edit_str() function accepts. The first parameter, input_string, is a pointer to the string where the user's input should be stored. It is important that this string be long enough to accommodate the longest input your format string will permit, including the '\0' C string terminator (ie, the string should be one character greater than the length of the format string, not including the format string's ' and " characters). The second parameter, format_string, is a pointer to a string which specifies the format and maximum length of the input the od_edit_str() function should accept. Using the format string, OpenDoors Door Toolkit Manual - Version 4.10 Page 53 not only do you specify the length of the input field, but you can also force the user's input into certain formats. For example, if you wished to input a North American style phone number, you could use a format string of "###-###-####". Then regardless of whether the user typed any dash character or not, their input would be converted, as they type, to the format of the phone number 613-526-4466. You could also specify a format string such of "MMMMMMMMMMMMMMMMMMMMMMMMMMMMMM", which would permit the user to enter a name of up to 30 characters. The od_edit_str() function would then automatically capitalize the name, so that the first character of each word is capitalized, and the remain characters of the word is in lower case. Even if the user were to move the cursor to the middle of the string they had entered, and add or delete a space (and thus either make one work two or two words one), od_edit_str() would re-format the string to reflect the change. The valid characters for the format sting, along with their meanings, are listed below. Note that the format string is NOT case sensitive (except for literal strings delimited by the '' or "" characters), and space characters can be added at any point to increase legibility. (Note that this string format is a modified version of a format suggested in the OPENDOORS EchoMail conference, and it is understood that a similar format is used by at least one other C programming library. In using a similar format, it is not my intention to copy someone else's idea, but simply to build upon a format that it seems is familiar to some C programmers already.) # Indicates that numeric characters from '0' to '9' are valid for this position % Indicates that numeric characters from '0' to '9', and the space character (' ') are valid for this position. 9 Indicates that numeric characters from '0' to '9', along with '.', '-' and '+' are valid for this position. This format style is intended for floating-point numeric input. ? Indicates that any character is valid for this position. * Indicates that any printable character, from ASCII 32 to ASCII 127, is valid for this position. A Indicates that alphabetical characters 'A' to 'Z', 'a' to 'z' and space (' ') are valid for this position. C Indicates that city name characters are valid for this position. As with the 'M' format character, words are automatically capitalized so that the first letter is in upper case, and all subsequent letters are in lower case. In addition to permitting alphabetical characters and the space (' ') character, the ',' and '.' characters are also accepted in this position. D Indicates that date characters '0' to '9', '-' and '/' are valid for this position. OpenDoors Door Toolkit Manual - Version 4.10 Page 54 F Indicates that MS-DOS filename characters are valid for this position. H Indicates that hexidecimal character '0' to '9', 'A' to 'F' and 'a' to 'f' are valid for this position. L Indicates that only lower case alphabetical characters 'a' to 'z', and the space (' ') character is valid for this position. However, if the user attempts to enter an upper case alphabetical character in this position, it will automatically be converted to the lower case equivalent. M Indicates that name characters are valid for this position. These characters are the alphabetical characters 'A' to 'Z', 'a' to 'z', and the space character (' '). A character's case is converted such that the first character of a word is in upper case, and all other letters are in lower case. T Indicates that telephone number character '0' to '9', '(', ')', '-' and ' ' are valid for this position. U Indicates that only upper case alphabetical characters 'A' to 'Z', and the space (' ') character is valid for this position. However, if the user attempts to enter a lower case alphabetical character in this position, it will automatically be converted to the upper case equivalent. W Indicates that MS-DOS filename characters are permitted in this position, including the '*' and '?' wildcard characters. X Indicates that alphanumeric characters 'A' to 'Z', 'a' to 'z', '0' to '9' and ' ' are valid for this position. Y Indicates that yes/no characters 'Y', 'N', 'y', 'n' are valid for this position. The characters are automatically converted to upper case. '/" Single or double quotes can be used to specify sequences of characters that should appear at the same location in the input string (referred to elsewhere as "literal strings"). When the user is entering the string, these characters are automatically supplied, and the user is not required to type them. Literal strings must begin and end with the same quote character. Remember that the double quote (") character must be imbedded in C strings by preceding the quote character with a \ (backslash) character. The third and fourth parameters, row and col specify the location on the screen where the first (left most) character of the input field should be located. These parameters are identical to the row and col parameters passed to the od_set_cursor() function. In other words, row specifies the line number on the screen, where 1 is the first line, and col specifies the column across the screen, where 1 is the first column. OpenDoors Door Toolkit Manual - Version 4.10 Page 55 The fifth and sixth parameters, normal_colour and highlight_colour, allow you to specify the colour of the input field. The fifth parameter, normal_colour, specifies the colour of the input field when input is not taking place and the sixth parameter, highlight_colour, specifies the colour of the field while input is taking place. Thus, if you had several input fields on the screen at one time, you would be able to make is easier for the user to identify the currently active field by having the field currently accepting input highlighted in a colour distinct from the other fields. When the od_edit_str() function begins, it will change the current colour of the field from the normal colour to the highlighted colour. Then, when the od_edit_str() function exits, it will change the current colour of the field back to its normal colour. If you do not wish to have the field highlighted, you can set both of these parameters to the same value, and disable field re-drawing by using the eighth parameter, flags. The seventh parameter accepted by the od_edit_str() function, character, will serve one of two purposes. Normally, this parameter will specify a background character to display in the unfilled portion at the end of the input field. This can be set to a character, such as the ASCII 177 grey block character, to produce a visual background to the field. Doing this will show the user visually how long the field is, and how many character they will be permitted to type into the field. Normally, this field will be displayed during input, and removed when the od_edit_str() function exits. However, you may cause the background to remain in place using the eighth parameter, flags. If you do not wish to have this "background" visual field effect, simply set the character parameter to a space (ASCII 32). In password input mode, this parameter will instead specify the character to display in place of characters typed by the user. In this case, the background display character defaults to the space (ASCII 32) character. The eighth, and last, parameter accepted by the od_edit_str() function is the flags parameter. This parameter is a bit-mapped flags variable which allows you to control special features of the od_edit_str() function. More than one of these settings may be specified by listing a chain of the values, separated by the bitwise-or (|) operator. If you do not wish to turn on any of these modes, simply pass the EDIT_FLAG_NORMAL value as the flags parameter. EDIT_FLAG_NORMAL - Default setting, use this value of none of the other flags below are active. EDIT_FLAG_NO_REDRAW - When set, prevents the od_edit_str() function from re-drawing the input string and field when it starts up and exits. If you set this flag, the normal_colour and highlight colour should contain the same value. If background character (the character parameter) is not a space (ASCII 32) character, you must draw the field background prior to calling OpenDoors Door Toolkit Manual - Version 4.10 Page 56 od_edit_str(). Also, if you are calling od_edit_str() with the EDIT_FLAG_EDIT_STRING flag set, you must display the existing string in the field prior to calling od_edit_str(). EDIT_FLAG_FIELD_MODE - Setting this flag specifies that od_edit_str() should operate in field input mode. In field input mode, the user may finish entering their input by pressing the previous field or next field button (arrow keys, tab keys, etc.), as described above. If the user chooses to finish and accept their input by pressing one of these keys, the od_edit_str() return value will reflect which choice they made. This will allow you to make it possible for the user to move between a number of input fields in a form / dialog box, as demonstrated in the example accompanying the od_draw_box() function. EDIT_FLAG_EDIT_STRING - Setting this flag specifies that od_edit_str() should edit a pre-existing string, instead of starting with a blank string. In this case, the input_string parameter MUST point to an initialized string. This string may either contain some text, or be empty, but od_edit_str() will expect to find a string terminator ('\0') character, and will begin editing the contents of the string prior to that character. If you do not set the EDIT_FLAG_EDIT_STRING flag, the previous contents of the input_string parameter is not significant, as od_edit_str() will automatically start with a blank string. EDIT_FLAG_STRICT_INPUT - Setting this flag causes the od_edit_str() function to operate in "strict" input mode, which may be desirable if your input format contains more than one type of input. Normally, if you were inputting such a string, the user would be able to move to the middle of the string, and insert any text. Doing so would cause the rest of the input line to shift right. However, in cases where your format string specifies different types of character to be permitted in different positions, this can cause the input to be changed so that it no longer conforms to the format string. In this case, the user's input will no longer be valid, and the user will not be able to exit the function by pressing [ENTER] (although [ESCAPE] will still be available, if you activated it) until they change their input. However, when strict input mode is turned on, od_edit_str() will restrict the ways in which the user is permitted to edit the string, to prevent just such a case from occurring. EDIT_FLAG_PASSWORD_MODE - Setting this flag causes the od_edit_str() function to operate in "password" mode. In password mode, the characters typed by the user will be hidden, displayed instead as the blank character specified in the "character" parameter. OpenDoors Door Toolkit Manual - Version 4.10 Page 57 EDIT_FLAG_ALLOW_CANCEL - When this flag is set, the user will be able to cancel their current input and abort the editing process by pressing their [ESCAPE] key. When they do so, any changes they have made to the input field will be cancelled, and replaced by the original contents of the string. The od_edit_str() function will then exit, indicating that the user has cancelled their input. EDIT_FLAG_FILL_STRING - When set, this flag will force the user to enter a string that fills the entire length of the format string. Normally, the user will be able to enter a string of any length up to the maximum length specified by the format string. However in some cases, such as when inputting a date, you will want to have the input field filled. (Otherwise, the user would be able to enter only the first part of the date.) EDIT_FLAG_AUTO_ENTER - When set, this flag will cause the od_edit_str() function to automatically simulate pressing of the [ENTER] key when the string is filled. This can be used to cause the od_edit_str() function to finish inputting as soon as a valid string is entered, instead of having to wait for the user to press [ENTER] / [RETURN]. EDIT_FLAG_AUTO_DELETE - When set, along with the EDIT_FLAG_EDIT_STRING flag, this flag will activate the auto-delete feature of the od_edit_str() function. When auto-delete is active, if the first key pressed by the user is not an edit control key, the existing text will automatically be deleted, and a totally new string accepted from the user. This could be useful when you are allowing the user to go back to edit a previous input. If the user wishes to only change part of the old string, they can move the cursor to the location where they wish to make the change, and perform their editing. However, if the user wishes to completely replace the old string with a new one, they can simply begin to type, and the old string will automatically be deleted, and the new string accepted. EDIT_FLAG_KEEP_BLANK - Normally, OpenDoors will only display the input field background (as passed in the "character" parameter) while the user is editing the string, and will remove it when the od_edit_str() function exits. However, you may wish to continue having this field displayed after input has taken place, and the od_edit_str() function has exited. In this case, setting this flag will cause the background characters to remain visible after input has finished. EDIT_FLAG_PERMALITERAL - When the format string contains literal characters (such as forcing a ':' character to be added to a time input by using the format string OpenDoors Door Toolkit Manual - Version 4.10 Page 58 "##':'##':'##"), the od_edit_str() function can operate in one of two modes. In the default mode, the literal characters will only be displayed when they have been automatically added to the string. For instance, if you were inputting the current time using the above format string, this mode would result in the input field initially being blank. When the user types the first digit of the time, that number would appear. When the user types the second digit of the time, that number will appear, and then the colon character will automatically be added by OpenDoors. However, you can also set the od_edit_str() function to operate in "PermaLiteral" mode, by setting this flag. When the EDIT_FLAG_PERMALITERAL flag is set, the input field will initially contain the literal characters (ie, the colons in our example), with the cursor still located at the leftmost position in the input field. In this mode, the literal character become a permanent part of the input field, and can not be moved or deleted by the user - instead the cursor simply skips over the literal character's position. EDIT_FLAG_LEAVE_BLANK - This flag applies to the special case where the first character or characters of the format string are literals. By default, the od_edit_str() function will always return a string containing at least these first literal characters. However, you can alter this behavious by setting this flag. When set, if no non-literal characters have been entered in the string, od_edit_str() will return an empty string. SEE ALSO od_input_str(), od_get_char(), od_clear_keybuffer() EXAMPLE Below are several examples of typical uses of the od_edit_str() function. For the sake of simplicity, all of these examples perform their input beginning at the top, left hand corner of the screen, and store the user's input in the string variable named "string". For an example of the user of the od_edit_str() function in a dialog-box / form entry application, see the example accompanying the od_draw_box() function. To input a name with a maximum of 25 characters, having the first letter of each word automatically capitalized: od_edit_str(string, "MMMMMMMMMMMMMMMMMMMMMMMMM", 1, 1, 0x03, 0x21, 176, EDIT_FLAG_NORMAL); To input a North American style phone number, requiring that all digits be filled, and running in "strict input" mode: od_edit_str(string, "###'-'###'-'####", 1, 1, 0x03, 0x21, 176, EDIT_FLAG_FILL_STRING| OpenDoors Door Toolkit Manual - Version 4.10 Page 59 EDIT_FLAG_STRICT_INPUT); To allow the user to edit a previously entered 20 character string, with auto-delete mode on. Any characters will be permitted in the string. Remember that when the EDIT_FLAG_EDIT_STRING flag is set, the string must be initialized prior to calling the od_edit_str() function. od_edit_str(string, "????????????????????", 1, 1, 0x03, 0x21, 176, EDIT_FLAG_EDIT_STRING| EDIT_FLAG_AUTO_DELETE); To input a password of up to 16 characters from the user. Here, the password will only be permitted to contain upper case characters, and the od_edit_str() password mode is used, with a small block displayed in place of any characters typed: od_edit_str(string, "UUUUUUUUUUUUUUUU", 1, 1, 0x03, 0x21, 254, EDIT_FLAG_PASSWORD_MODE); To input a two-digit number from the user, requiring that both digits be filled, and automatically accepting the input after the two digits have been entered (not requiring the user to press [ENTER]): od_edit_str(string, "##", 1, 1, 0x03, 0x21, 176, EDIT_FLAG_FILL_STRING| EDIT_FLAG_AUTO_ENTER); To input a filename to download, as a field in a dialog box. Here, the filename will be permitted to contain valid filename characters, and the od_input_str() function will operate in field mode, with the cancel [ESCape] key enabled. Also, string edit mode will be enabled, allowing the user to edit a previously entered line, and the EDIT_FLAG_KEEP_BLANK flag will be set, causing the field background to remain displayed after the user exits. This time, however, auto-delete mode will not be used. Note that this combination of parameters expects that the field and it's contents will have already been displayed, prior to calling the od_edit_str() function. od_edit_str(string, "WWWWWWWWWWWW", 1, 1, 0x03, 0x21, 176, EDIT_FLAG_EDIT_STRING| EDIT_FLAG_FIELD_MODE| EDIT_FLAG_ALLOW_CANCEL| EDIT_FLAG_KEEP_BLANK); OpenDoors Door Toolkit Manual - Version 4.10 Page 60 To input a string without the field background and line redrawing before and after input takes place: od_edit_str(string, "******************************", 1, 1, 0x07, 0x07, ' ', EDIT_FLAG_NO_REDRAW); To input a date, using permaliteral mode. Here, the month is entered by a three digit short form ("JAN", "FEB", etc.), and the literal characters such as the '-' and the "19" are a permanent part of the input field: od_edit_str(string,"UUU'-'##'-19'##", 1, 1, 0x03, 0x21, 176, EDIT_FLAG_PERMALITERAL| EDIT_FLAG_FILL_STRING); OpenDoors Door Toolkit Manual - Version 4.10 Page 61 OD_EMULATE() -------------------------------------------------------------------------------- PURPOSE Displays a character with ANSI/AVATAR emulation FORMAT void od_emulate(register char in_char); RETURNS N/A DESCRIPTION od_emulate() is a low-level function which allows you to display your own ANSI / AVATAR graphics sequences and QBBS/RA style control characters. This function passes the characters you wish to display to the OpenDoors terminal emulator, which is fully documented in the description of the od_send_file() function, on page 101. As a result, this function can be used to send these control sequences to the user's terminal, and also have them displayed on the local screen as they will appear to the user. The characters passed to the od_emulate() function will both be sent directly to the modem, and sent to the local screen, after being translated by the terminal emulator. Thus, if you were to send the characters ESCape,[,2,;,4,H to the emulator using this function, the cursor would be positioned at location 2 by 4 (on both the local and remote screens). Note that this function only accepts a single character at a time. The example below demonstrates a function to send an entire string of characters using the od_emulate() function. Note that if you wish to display an entire file containing ANSI/AVATAR graphics sequences (perhaps as your door's menu or title screen), use the od_send_file() function. SEE ALSO od_send_file(), od_disp(), od_disp_str() od_printf(), od_putch(), od_repeat(). For a breakdown of the uses of the various OpenDoors display functions, see the od_disp_str() function, on page 46. EXAMPLE Below is an example of a function which will allow you do display strings of ANSI or AVATAR sequences, using the od_emulate() function: void emulate_string(char *pointer) { /* loop through string, sending each character */ while(*pointer) od_emulate(*pointer++); } OpenDoors Door Toolkit Manual - Version 4.10 Page 62 Using this function you could have an ANSI sequence sent to the user's terminal program, and displayed on the local screen as it would appear on the user's screen. For example, to display the ANSI sequence of ESCape followed by "[2;4H", which just happens to move the cursor to location 2 by 4, you could: emulate_string("\x1b[2;4H"); (Note that \x1b represents the ESCape character, ASCII 27 or 1B in hexidecimal.) OpenDoors Door Toolkit Manual - Version 4.10 Page 63 OD_EXIT() -------------------------------------------------------------------------------- PURPOSE The OpenDoors program termination function FORMAT void od_exit(int errorlevel,char term_call); RETURNS N/A DESCRIPTION When writing a door program, you MUST USE THIS FUNCTION when you want your Door to exit. This function will deinitialize the fossil driver, re-write changed information to the EXITINFO.BBS file, call your end-of-program function (if any), and then exit with the errorlevel specified in the first parameter. Also, if the second parameter, "term_call", is set to TRUE, od_exit() will also log the user off (for options such as logging off within the door - as shown in the example below). This is accomplished by lowering the DTR line to the modem, causing the modem to hangup. When control is returned to the BBS, it will then detect that the user is no longer online, and will carry out its own logoff processing. If you wish for your program to always perform any activities prior to exiting, such as updating or closing data files, you should set a function to be executed from within the od_exit() function. This is accomplished by using the od_control. od_before_exit variable, as described in the section on the OpenDoors control structure in chapter 5. Use of this variable will allow your program to always carry out these activates, even if OpenDoors decides to call the od_exit() function itself, such as when a user hangs up on the door. Note that in special cases, you may use the od_control.od_disable variable to prevent the od_exit() function from re-writing the door information file. Also, you may use the od_control.od_noexit variable to shutdown door operations without actually exiting your program. Both of these variables are described in chapter 5. This function should not be used in utility program that only use the BBS interface module of OpenDoors, nor with any program that has not previously called the od_init(), or some other OpenDoors DOOR DRIVER function. SEE ALSO od_init() OpenDoors Door Toolkit Manual - Version 4.10 Page 64 EXAMPLE The example below demonstrates a function which a door could execute when the user chooses to exit the door. This function will ask the user whether they wish to exit the door and return to the BBS, simply logoff of the BBS, or continue using the door. The example function will then call od_exit() if the user wishes to exit the door, or return control to the function which called it, if the user does not wish to exit: void goodbye(void) { char pressed; /* Display choices to user */ od_disp_str("You have chosen to exit this door.\n\r"); od_disp_str("Do you wish to:\n\r"); od_disp_str(" [R]eturn to the BBS\n\r"); od_disp_str(" [L]ogoff of the BBS\n\r"); od_disp_str(" [C]ontinue using the door\n\r"); for(;;) /* loop until user makes valid choice */ { pressed=od_get_key(TRUE); /* Get key from user */ /* If user selects R, exit without hanging up */ if(pressed=='R' || pressed=='r') od_exit(40,FALSE); /* If user selects L, hangup and then exit */ if(pressed=='L' || pressed=='l') od_exit(41,TRUE); /* If user selects C, return and allow door to continue */ if(pressed=='C' || pressed=='c') return; } } OpenDoors Door Toolkit Manual - Version 4.10 Page 65 OD_GET_ANSWER() -------------------------------------------------------------------------------- PURPOSE Function to allow the user to respond to a prompt using only certain keys. FORMAT char od_get_answer(char *string); RETURNS User's response to prompt DESCRIPTION This function can be used to get a response from the user, when only particular responses should be accepted. The parameter to the od_get_answer() function is simply a string listing the valid responses. The function will wait until the user selects one of the valid responses, and then return that response. The function is case insensitive, and will return the character in the same case that was supplied to it in the string. SEE ALSO od_get_key(), od_hotkey_menu() EXAMPLES od_get_answer("YN"); - If the user presses 'y', will return 'Y'. od_get_answer("yn"); - If the user presses 'y', will return 'y'. od_get_answer("ABC 123\nZ"); - Valid responses will be: [A], [B], [C], [SPACE], [1], [2], [3], [ENTER], [Z] OpenDoors Door Toolkit Manual - Version 4.10 Page 66 OD_GET_KEY() -------------------------------------------------------------------------------- PURPOSE Function to input a key from the user FORMAT int od_get_key(int wait); RETURNS The next key waiting from the keyboard, or 0 if none. DESCRIPTION This function retrieves the next key waiting in the OpenDoors keyboard buffer (see the description of the od_clear_keybuffer() function, on page 38, for more information on the OpenDoors keyboard buffer). The od_get_key() function allows your door to retrieve both those keystrokes pressed by the user, and the keystrokes pressed on the sysop keyboard (other than the sysop function keys), in the sequence they were pressed. Since input is accepted from both sources, it is possible for the sysop, as well as the remote user, to make selections and control the door. Door input with OpenDoors can be accomplished with this function, with the od_input_str() function or with the od_edit_str() function. The od_input_str() and od_edit_str() functions is used to input an entire sequence of characters from the user (a string), and requires the user to press the [Enter] key when they are finished typing their input. On the other hand, the od_get_key() function is used to input a single keystroke (one character) from the user, and allows the user to make choices without having to press the enter key. The od_get_key() function accepts a single parameter, which determines whether or not it should wait for the user to press a key, if they have not already done so. If you pass a FALSE value to od_get_key(), then the function will not wait for a key to be pressed at the keyboard, but instead return a 0 if there are no keys waiting in the buffer. If you pass a TRUE value to od_get_key(), then this function will instead wait for a key to be pressed. Also, while waiting for the user to press a key, the od_get_key() function will give up the processor to other waiting programs, if you door is running under DesqView. If you are waiting for the user to make a choice from a menu or list of options, you will most likely pass a TRUE to the od_get_key() function, indicating that you wish for it to wait until a key is pressed. However, if you wish to continue other processing if no key is yet available from the keyboard, you should pass a FALSE to the od_get_key() function. For example, if you are displaying a screen of text, and wish to allow the user to pause or abort the display, you would simply call the od_get_key() function every few moments, passing it a value of FALSE. You would then be able to check if any control keys have been pressed, and if not, continue displaying text. OpenDoors Door Toolkit Manual - Version 4.10 Page 67 The od_get_key() function returns the ASCII value representing the keystroke that was made. If you are waiting for the user to make a particular choice, perhaps from a menu, you will most likely store the value returned by od_get_key() in a variable of type char. For example: char key; ... key=od_get_key(TRUE); You would then be able to determine which key the user pressed by testing the value of key, either by comparing it's numerical ASCII value, or by comparing it to a character constant. If you are testing for a non-character key, such as [ESCape], [Tab] or [Return], you may wish to use the ASCII value of that key. For example, if you wished to take some action in the case that the user presses the [Enter]/[Return] key, who's ASCII value is 13, you could do: key=od_get_key(TRUE); /* Get keypress from user */ if(key==13) /* If key was [Enter]/[Return] */ { ... /* Whatever you want to do */ } A complete reference of all the ASCII values is listed below. To determine whether input originated from the local or remote keyboards, see the OpenDoors control structure variable od_last_input. If you wish, instead, to respond to the user pressing a character key (perhaps as a choice from a menu), you can do so by using character constants, such as 'c', '6', or 'F'. Also, when testing for an alphabetical character, you will probably want to check for the user pressing either the upper or lower-case version of the letter. For example, if you wished to have the user press the [Y] key to continue, you could test for either an upper or lower- case Y as follows: key=od_get_key(TRUE); /* Get keypress from user */ if(key=='y" || key=='Y") /* If key was [y]/[Y] */ { ... /* Whatever you want to do */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 68 The chart below lists the decimal value and corresponding keystroke(s) of each of the ASCII values from 0 to 127. ASCII KEYSTROKE | ASCII KEYSTROKE ----- ------------------------------ | ----- ---------------------- 0 [Control]-[@] | 15 [Control]-[O] 1 [Control]-[A] | 16 [Control]-[P] 2 [Control]-[B] | 17 [Control]-[Q] 3 [Control]-[C] | 18 [Control]-[R] 4 [Control]-[D] | 19 [Control]-[S] 5 [Control]-[E] | 20 [Control]-[T] 6 [Control]-[F] | 21 [Control]-[U] 7 [Control]-[G] | 22 [Control]-[V] 8 [Control]-[H]/[Backspace] | 23 [Control]-[W] 9 [Control]-[I]/[Tab] | 24 [Control]-[X] 10 [Control]-[J] | 25 [Control]-[Y] 11 [Control]-[K] | 26 [Control]-[Z] 12 [Control]-[L] | 27 [ESCape] 13 [Control]-[M]/[Enter]/[Return] | 32 [SpaceBar] 14 [Control]-[N] | ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE ----- --------- | ----- --------- | ----- --------- | ----- --------- 33 '!' | 57 '9' | 80 'P' | 104 'h' 34 '"' | 58 ':' | 81 'Q' | 105 'i' 35 '#' | 59 ';' | 82 'R' | 106 'j' 36 '$' | 60 '<' | 83 'S' | 107 'k' 37 '%' | 61 '=' | 84 'T' | 108 'l' 38 '&' | 62 '>' | 85 'U' | 109 'm' 39 '\'' (') | 63 '?' | 86 'V' | 110 'n' 40 '(' | 64 '@' | 87 'W' | 111 'o' 41 ')' | 65 'A' | 88 'X' | 112 'p' 42 '*' | 66 'B' | 89 'Y' | 113 'q' 43 '+' | 67 'C' | 90 'Z' | 114 'r' 44 ',' | 68 'D' | 91 '[' | 115 's' 45 '-' | 69 'E' | 92 '\\' (\) | 116 't' 46 '.' | 70 'F' | 93 ']' | 117 'u' 47 '/' | 71 'G' | 94 '^' | 118 'v' 48 '0' | 72 'H' | 95 '_' | 119 'w' 49 '1' | 73 'I' | 96 '`' | 120 'x' 50 '2' | 74 'J' | 98 'b' | 121 'y' 51 '3' | 75 'K' | 99 'c' | 122 'z' 52 '4' | 76 'L' | 100 'd' | 123 '{' 53 '5' | 77 'M' | 101 'e' | 124 '|' 54 '6' | 78 'N' | 102 'f' | 125 '}' 55 '7' | 79 'O' | 103 'g' | 126 '~' 56 '8' | | | 127 [DELete] OpenDoors Door Toolkit Manual - Version 4.10 Page 69 SEE ALSO od_input_str(), od_edit_str(), od_clear_keybuffer() EXAMPLE For examples of the use of the od_get_key() function, see the examples in the description portion, above, and the examples for the od_exit() and od_clear_keybuffer() functions. For further examples of this function, see the example door EZVote, described in the section beginning on page 25. OpenDoors Door Toolkit Manual - Version 4.10 Page 70 OD_HOTKEY_MENU() -------------------------------------------------------------------------------- PURPOSE Function to display a menu file with hotkeys FORMAT char od_hotkey_menu(char *filename, char *hotkeys, char wait); RETURNS Key pressed in response to menu, or '\0' if none. DESCRIPTION This function can be used to display a menu from an ASCII, ANSI or AVATAR file, allowing the user to select an option at any time while the menu is being displayed. The od_hotkey_menu() function is quite similar to the od_send_file() function, and you should probably familiarize yourself with that function if you are going to use od_hotkey_menu(). Like od_send_file(), od_hotkey_menu() will display the file specified by filename, using the appropriate terminal emulation. If no extention is provided for the filename, OpenDoors will automatically search for matching files ending in .ASC, .ANS and .AVT extentions. OpenDoors will the select the appropriate file to display, based on the available files and available terminal emulation. The second parameter, hotkeys, is a string specifying the valid responses to the menu, in the same format as the string passed to the od_get_answer() function. If any of the characters listed in this string are pressed, either uppercase or lowercase versions, OpenDoors will immediately stop displaying the menu, and return with the value of the key pressed. The case (upper or lower) returned will always be identical to the case used in the hotkeys string. You can include the [ENTER] key as a valid hot key by including the \n character in the hotkey string. The third parameter passed to od_hotkey_menu(), wait, specifies whether OpenDoors should wait after displaying the menu for the user to make a valid selection from the menu (TRUE), or if it should exit immediately (FALSE). Normally, you will want to use the TRUE value when calling this function. This will allow you to use a single function call that will display the menu and always return the user's selection. If you wish to gain control as soon as OpenDoors has displayed the menu and sent it to the FOSSIL driver, you may specify FALSE for this parameter. In this case, if the user does not press any of the valid hot keys while the menu is being sent, the function will return the character '\0'. SEE ALSO od_send_file(), od_get_answer() OpenDoors Door Toolkit Manual - Version 4.10 Page 71 EXAMPLE As an example of the use of the od_hotkey_menu() function, consider the following code fragment: for(;;) /* Main pogram loop */ { /* Display menu and get user's choice */ char choice=od_hotkey_menu("MAINMENU","123Q",TRUE"); switch(choice) /* Perform the appropriate action */ { case '1': od_printf("You selected one.\n\r"); break; case '2': od_printf("You selected two.\n\r"); break; case '3': od_printf("You selected three.\n\r"); break; case 'Q': od_exit(FALSE,10); } } This is an example of the main menu loop of a simple door that uses the od_hotkey_menu() function. The program will continue executing the for(;;) loop until the user chooses to exit the door. On each iteration of the loop, the od_hotkey_menu() function is called, to display the door's menu from the file MAINMENU.A??. The appropriate .ASC/.ANS/.AVT file will be chosen and displayed as the menu. The possible choices that may be made from the menu are specified by the string "123Q". Thus, whenever the user presses one of the keys [1], [2], [3] or [Q], the od_hotkey_menu() function will return immediately with the value of the key pressed. If the menu is still being displayed at the time when the key was pressed, menu display will cease at that moment. The program then executes a case statement, to respond to the user's key appropriately. If the user presses [1], [2] or [3] this door will output a simple message to the screen. If the user presses the [Q] key, the door will pass control back to the BBS. OpenDoors Door Toolkit Manual - Version 4.10 Page 72 OD_INIT() -------------------------------------------------------------------------------- PURPOSE To initialize OpenDoors activities FORMAT void od_init(void); RETURNS N/A DESCRIPTION This function initializes any door running under OpenDoors. This function must be called manually if you wish to access data about the user, etc., before you call any other OpenDoors functions. However, if you do not explicitly call the od_init() function, it will be called automatically on the first call to any other OpenDoors door driver function. The od_init() function reads information from the door information file, initializes communications with the modem, displays the status line, and sets up OpenDoors' internal data structures. For more information on what data is and is not available before od_init() has been called, please refer to the chapter on the OpenDoors control structure, which begins on page 119. The od_init() function will read the door information file which is located in the directory specified by the variable od_control.info_path. If this variable has not been set prior to calling the od_init() function, OpenDoors will expect to find the door information file in the current directory. Thus, if you wish your door to be able to be run in a directory other than the BBS system directory, it would be a good idea to allow the sysop using your door to specify the location of the door information file. For an example of setting the od_control.info_path variable, please see the example program located on page 122. Note that the od_init() function should not be called in any utility-only program (ie, programs which only use the BBS interface module of OpenDoors), or when you wish for your door program to run in "maintenance mode", as described and demonstrated in the example below. Also note that you can prevent the od_init() function from carrying out some of it's normal activities, such as attempting to read a door information file, by the use of the od_control.od_disable variable, as described in the section on the OpenDoors control structure, which begins on page 119. SEE ALSO od_exit() OpenDoors Door Toolkit Manual - Version 4.10 Page 73 EXAMPLE At times, you may wish to write a door program which will require a maintenance utility to be run on a regular basis. For example, a game door may have to have its system files updated on a daily basis, by having a utility program run in a system event each day at midnight. One way of accomplishing this would be to have your door package include two .EXE files, one being the actual door program, and the other being a utility program. However, another option would be to have both the door and maintenance functions to be accessible from a single .EXE file, in order to simplify use of the door for the sysop. In this case, you would want to test the command line to determine whether your program should run in door mode or maintenance mode. You would then only execute the od_init() function, along with the rest of your door code, if you program were running in "door mode". The program below demonstrates one method of doing just this. In this case, the program would include two functions, door(), which would carry out all of the door-related activities, and maint(), which would carry out all of the maintenance-related activities. In this simple example, if the command line includes a "-M" or "/M", the program will run in maintenance mode, otherwise it will run in door mode. Also, if it is running in door mode, the program will take the first command-line parameter, if any, as a path to the location of the door information file. #include "opendoor.h" void door(void); void maint(void); int main(int argc, char *argv[]) { int counter; /* Check any command line parameters for /M or -M */ for(counter=1;counter<argc;++counter) { if((argv[counter])[1]=='m' || (argv[counter])[1]=='M') { maint(); /* Then carry out maintenance */ exit(20); /* And exit */ } } /* If there was no -M or /M, then run in door mode */ /* If there are any command-line parameters, take the first */ /* as the path to the door information file */ if(argc>1) strncpy(od_control.info_path,argv[1],59); od_init(); /* call the od_init() function */ door(); /* Run the door portion of the program */ od_exit(30,FALSE); /* Shutdown the door */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 74 void maint(void) { ... /* Carry out maintenance activities here */ } void door(void) { ... /* Carry out door activities here */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 75 OD_INIT_WITH_CONFIG() -------------------------------------------------------------------------------- PURPOSE To initialize OpenDoors activities, parsing a configuration file. FORMAT void od_init_with_config(char *filename, (*custom_line_function) (char *keyword,char *options) ); RETURNS N/A DESCRIPTION This function can be used instead of the od_init() function, to begin OpenDoor's operations. This function performs all of the initialization activities that the od_init() function does, and also reads any information in the door's configuration file. The configuration file system automatically provides support for a considerable number of sysop configurable options, such as system directories, BBS information, display colours, custom door information file formats, maximum time within the door, and so on. To familiarize yourself more with the OpenDoors configuration file format, it is suggested that you examine the example configuration file, EZVOTE.CFG. Feel free to distribute the EZVOTE.CFG or a modified version of the file with your own doors. The od_init_with_config() function accepts two parameters. The first parameter specifies the name of the configuration file that OpenDoors should look for. If no configuration file is found, the od_init_with_config() will continue initialization normally, using the default settings. This means that the configuration file is always optional, and that OpenDoors is designed to continue normally if the sysop elects not to use a configuration file. OpenDoors will first search for the configuration file in the directory specified on the od_init_with_config() command line. If the configuration file is not found there, OpenDoors will search in the current dirrectory. If the configuration file is still not found, it will then look for the file in the directory where the door's .EXE file is located. The format for the configuration file is as follows. Blank lines and any text following the semi-colon (;) character are ignored. Configuration options are specified using a keyword, possibly followed by one or more options. The keywords are not case sensitve, but some of the options are. The order of options in the configuration file is not significant. The built-in configuration options are as follow: BBSDir - BBS System directory. Indicates where the door information file (drop file) can be found. OpenDoors Door Toolkit Manual - Version 4.10 Page 76 DoorDir - The door's working directory. This is where the door's system files are located. OpenDoors will automaticaly perform a chdir into this directory at initialization, and will return to the original directory on exit. LogFileName - Specifies the filename (path optional) where the door should record log information. DisableLogging - Prevents door from writing to a log file. Node - BBS node number that the door is running on. Only used if OpenDoors is unable to determine the node number by some other means. ???dayPagingHours - Specifies sysop paging hours. Sysop paging will be permitted beginning at the start time, up until, but not including, the end time. Times should be in the 24-hour format. To disable paging on a particular day, set the paging start and end times to the same time. ???day can be one of Sunday, Monday, Tuesday, Wednesday, Thursday, Friday or Saturday. PagDuration - Duration of sysop page. Value indicates the number of beeps that compose the sysop page alarm. MaximumDoorTime - Maximum length of time a user is permitted to access the door. If the user's total remaining time on the BBS is less than this value, the user will only be permitted to access the door for this shorter length of time. This option is disabled by commenting out the line. InactivityTimeout - Specifies the maximum number of seconds that may elapse without the user pressing a key, before the user will automatically be disconnected. A value of 0 disables inactivity timeouts. SysopName - Name of the sysop. OpenDoors can usually determine the sysop's name from the door information (drop) file. How3ever, some BBS packages do not supply this information. In such cases, if the sysop's name is required by the door, it may be supplied here. SystemName - Like the sysop's name, this option can usually be determined from the door information file. If it is not available, the sysop my supply the information here. ChatUserColour - Specifies the colour of text typed by the user in sysop chat mode. The format of the colour name is included in the description of the od_colour_config() function. ChatSysopColour - Specifies the colour of test typed by the sysop in chat mode. FileListTitleColour - Files.BBS listing colours. OpenDoors Door Toolkit Manual - Version 4.10 Page 77 FileListNameColour FileListSizeColour FileListDescriptionColour FileListOfflineColour SwappingDir - Directory where disk swapping will be done. SwappingNoEMS - Disables swapping to EMS memory. SwappingDisable - Disables swapping entirely. LockedBPS - BPS rate at which door should communicate with the modem. Valid rates are 300, 600, 1200, 2400, 4800, 9600, 19200 and 38400. A value of 0 forces the door to always operate in local mode. This option is not normally needed, as the information is usually available from the door information file. FossilPort - Specifies the FOSSIL driver prot number tha tthe modem is connected to. FOSSIL port 0 usually corresponds to COM!, port 1 to COM2, and so on. This option is not normally needed, as the information is usually available from the door information file. CustomFileName - Specifies the filename used by the custom door information file format. Described in more detail below. CustomFileLine - Specifies the contents of a particular line in the custom door information file format. Two of the most powerful options of the configuration file are those that allow the sysop to specify a custom door information file format. To permit OpenDoors doors to operate on BBS systems that produce a door information file format not directly supported by OpenDoors, the sysop may define a custom door information file format. A custom door information file format is defined using the "CustomFileName" option, followed by one or more lines beginning with the "CustomFileLine" option. The "CustomFileName" option specifies the filename used to distinguish this file format from other file formats. This filename should not include a path. To specify the path where the door information file is located, use the BBSDir setting, near the beginning of this file. If the filename of the custom format is the same as that of one of the built-in formats, the custom format will override the built-in format. The actual format of the custom file is specified using a number of lines that begin with the keyword "CustomFileLine". Each of these lines will correspond to a single line in the door information file, with the option following the "CustomFileLine" keyword specifying the information that can be found on that line. This can be one of the following keywords: OpenDoors Door Toolkit Manual - Version 4.10 Page 78 Ignore - Causes the next line in the door information file to be ignored. Use on lines for which none of the options below apply. COMPORT - COM? port the modem is connected to (0 indicates local mode) FOSSILPORT - Fossil port number the modem is connected to MODEMBPS - BPS rate at which to communicate with modem (0 or non-numerical value indicates local mode) LOCALMODE - 1, T or Y if door is operating in local mode USERNAME - Full name of the user USERFIRSTNAME - First name(s) of the user USERLASTNAME - Last name of the user ALIAS - The user's psuedonym / handle HOURSLEFT - Hours user has left online MINUTESLEFT - Minutes user has left online, or time left online in format hh:mm SECONDSLEFT - Seconds user has left online, or time left online in format hh:mm:ss or format mm:ss (If more than one of the above time options are used, the user time left is taken to be the total of all of these values.) ANSI - 1, T, Y or G for ANSI graphics mode AVATAR - 1, T or Y for AVATAR graphics mode PAGEPAUSING - 1, T or Y if user wishes a pause at end of screen SCREENLENGTH - Number of lines on user's screen SCREENCLEARING - 1, T or Y if screen clearing mode is on SECURITY - The user's security level / access level CITY - City the user is calling from NAME - Node number user is connected to SYSOPNAME - Full name of the sysop SYSOPFIRSTNAME - The sysop's first name(s) SYSOPLASTNAME - The sysop's last name SYSTEMNAME - Name of the BBS OpenDoors Door Toolkit Manual - Version 4.10 Page 79 You can also extend OpenDoor's configuration file format to add your own option, by supplying od_init_with_config with a custom line function. A pointer to the custom line function is provided as the second parameter to the od_init_with_config() function. If you do not wish to add any custom lines to the configuration file, simply pass the value NULL to the function. For an example of implementing a custom line function, the example code at the end of this section on configuration files. The custom line function should accept two pointers to strings and return "void". If a custom line function has been specified, whenever the configuration file system encounters an unknown configuration option, it will call your custom line function. The first parameter that the configuration system passes to your function is a pointer to the string containing the keyword found, in upper case. The second parameter will be the text of the configuration file line. For instance, if the following line were encountered in the configuration file: RegisteredTo John Smith ; Sysop's name The parameters passed to your function would be: char *keyword = "REGISTEREDTO" char *options = "John Smith" Your custom line function should be written in such a way that if OpenDoors passes a configuration option to your function that your function does not recognize, that option should simply be ignored. All of the keywords used within the OpenDoors configuration file are language customizable. These prompts are specified in two global variables, od_config_text and od_config_lines. The default definitions for these arrays are as follows: char *od_config_text[12]={"Node", "BBSDir", "DoorDir", "LogFileName", "DisableLogging", "SundayPagingHours", "MondayPagingHours", "TuesdayPagingHours", "WednesdayPagingHours", "ThursdayPagingHours", "FridayPagingHours", "SaturdayPagingHours", "MaximumDoorTime", "SysopName", "SystemName", "SwappingDisable", "SwappingDir", "SwappingNoEMS", "LockedBPS", OpenDoors Door Toolkit Manual - Version 4.10 Page 80 "FossilPort", "CustomFileName", "CustomFileLine", "InactivityTimeout", "PageDuration"}; char *od_config_lines[24]={"Ignore", "ComPort", "FossilPort", "ModemBPS", "LocalMode", "UserName", "UserFirstName", "UserLastName", "Alias", "HoursLeft", "MinutesLeft", "SecondsLeft", "ANSI", "AVATAR", "PagePausing", "ScreenLength", "ScreenClearing", "Security", "City", "Node", "SysopName", "SysopFirstName", "SysopLastName", "SystemName"}; SEE ALSO od_init(), od_colour_config() EXAMPLE Below is an example of using a custom line function to add additional options to the default settings in the configuration file. #include "opendoor.h" /* Include opendooor.h */ /* Prototype for custom line funciton */ void custom_line_function(char *keyword, char *options); unsigned long key=0L; /* Variables for our own config opation */ unsigned char default_colour=0x07; char display_winners=FALSE; main() /* Program's execution begins here */ { /* Begin door operations, reading config file */ od_init_with_config("DOOR.CFG",custom_line_function); /* Main program's operations go here */ od_exit(FALSE,10); /* Exit door */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 81 /* Code for custom line function */ void custom_line_function(char *keyword, char *options) { /* If option is registration key */ if(strcmp(keyword,"REGISTRATIONKEY")==0) { key=atol(options); /* Store key in variable */ } /* If option is text colour */ else if(strcmp(keyword,"DEFAULTCOLOUR")==0) { /* Get colour value using od_colour_config() */ default_colour=od_colour_config(options); } /* Example of option enabled by just the keyword */ else if(strcmp(keyword,"DISPLAYWINNERS")==0) { /* If keyword is present, turn on option */ display_winners=TRUE; } } OpenDoors Door Toolkit Manual - Version 4.10 Page 82 OD_INPUT_STR() -------------------------------------------------------------------------------- PURPOSE Inputs a string from the user FORMAT void od_input_str(char *string,int max_len,char minchar, char maxchar); RETURNS N/A DESCRIPTION To perform string input within OpenDoors, one of two functions can be used, od_input_str() and od_edit_str(). The first function, od_input_str(), allows simple line input and editing, and can be used in ASCII, ANSI and AVATAR modes. The second function, od_edit_str(), allows many formatted input options, advanced line editing, and other features, but requires the use of ANSI or AVATAR graphics modes. The od_input_str() function allows you to input a string from the user. The string will be permitted to have up to the number of characters specified by the max_len parameter, and all characters must be between the values of the min_char and max_char parameters. This function will wait until the user presses the [Enter] key to finish inputting the string. The first parameter passed to this function should be a pointer to the string where the user's input should be stored. So, if you wanted to store a string of up to 30 characters inputted by the user, you might define this string as follows: char input_string[31]; Notice here than the string must be long enough to hold the thirty characters which can be entered by the user, along with the additional "null" character which is used to indicate the end of a string in C. Hence, the length of the string should always be at least one greater than the total number of characters the user is permitted to enter, passed in the max_len parameter. The second parameter passed to the od_input_str() function should be an integer value indicating the maximum number of characters which can be input by the user. For example, if this parameter had a value of 10, the user would be able to enter a string containing any number of characters up to and including 10 characters. If this parameter had a value of 1, the user would only be able to enter a single character. However, the user would be able to backspace, change the character, and press [Enter] when they were satisfied with their entry. Note that even if you only ask the od_input_str() function to input a single character, OpenDoors Door Toolkit Manual - Version 4.10 Page 83 it will still expect a STRING to be passed to it, and will return a string with either zero or one character, followed by a null (string terminator) character. The third and fourth parameters passed to this function allow you to control what characters the user will be permitted to enter as part of the string. For example, you could set the minimum character to the '0' character and the maximum character to the '9' character, permitting the user to only enter numeric characters. On the other hand, you could permit the user to enter all ASCII characters in the range from 32 to 127. The od_input_str() function will permit characters in the range beginning with the character passed as minchar, up to and including the character passed as maxchar. SEE ALSO od_edit_str(), od_get_key(), od_clear_keybuffer() EXAMPLE Below are a number of examples of the use of the od_input_str() function in various applications: - To input a two character number (only digits from 0-9): od_input_str(string,2,'0','9'); - To input a 35 character name (characters from Space to ASCII 127): od_input_str(string,35,32,127); OpenDoors Door Toolkit Manual - Version 4.10 Page 84 OD_KERNAL() -------------------------------------------------------------------------------- PURPOSE The OpenDoors Central Control function FORMAT void od_kernal(void); RETURNS N/A DESCRIPTION The od_kernal() function is responsible for many vital OpenDoors tasks, such as monitoring the carrier detect signal, monitoring the amount of time that the user has remaining, updating the status line, responding to sysop hotkeys, and reading characters which are received from the modem. The od_kernal() function is automatically called on a frequent basis by the other OpenDoors door driver functions, so most often you will not need to be concerned with this function. However, in order that OpenDoors can carry out the activities mentioned above with a quick response, it is important that od_kernal(), or some other OpenDoors door driver function be called at least once every second. Thus, if your program will be carrying out some processing, in which it will not be calling any OpenDoors door driver functions for more than a second or so, you should call the od_kernal() function yourself. The example below demonstrates one method of doing just this. Note that if for some reason or other, it is not possible for your program to call the od_kernal() function, or any other OpenDoors door driver functions for a period of several seconds, this will not cause your door to crash or fail in any way. The only problem will be that OpenDoors will not be able to respond to any action, such as the sysop pressing a function key, or the user dropping carrier, until such time as you next call od_kernal(), or some OpenDoors door driver function. Hence, use of the od_kernal() function will improve the quality and response time of your program, but calling it or some OpenDoors door driver function on a regular basis is not absolutely vital. EXAMPLE As mentioned above, if it is possible that several seconds may pass between your program calling any OpenDoors door driver functions, it would be a good idea for you to call the od_kernal() function on a regular basis. Below is an example of a door_sleep() function, which will pause for the specified amount of time, while continually calling the od_kernal() function. This function will thus allow a door program to pause for a given length of time, perhaps after having displayed its title screen, or in order to add special effects to an ANSI animation. In this case, the program will be able to respond to events such as the OpenDoors Door Toolkit Manual - Version 4.10 Page 85 sysop pressing function keys, or the user dropping carrier, while it is pausing. void door_sleep(int seconds) { /* Calculate the timer tick to wait until */ long until=(*(long far *)0x46cL)+(18L*(long)seconds); /* Loop until the specified number of seconds have expired */ while(until>*(long far *)0x46cL) { od_kernal(); /* Repeatedly call od_kernal() */ } } OpenDoors Door Toolkit Manual - Version 4.10 Page 86 OD_LIST_FILES() -------------------------------------------------------------------------------- PURPOSE Lists files in a particular file area (using FILES.BBS) FORMAT int od_list_files(char *directory); RETURNS TRUE if successful, FALSE if unsuccessful DESCRIPTION This function allows you to display a list of files available for download from a particular file area, as any BBS system would. The file names and descriptions are taken from the FILES.BBS located in the directory pointed to by *directory. Thus, to list the files available for download in C:\APEX\FILES\UPLOADS, simply: od_list_files("C:\\APEX\\FILES\\UPLOADS"); OpenDoors uses a third-generation FILES.BBS format, that is compatible with other FILES.BBS formats, but adds some additional features. Each line in the FILES.BBS file lists a filename, along with it's description. Thus, a typical FILES.BBS file might look as follows: PKZ110.EXE PKZip file compressor, version 1.10 ODOORS40.LZH The newest version of OpenDoors! EZVOTE40.ZIP EZVote user voting door. BID12.ZIP BBS info. door for new BBS users When displayed, OpenDoors will list the size of each file found in the FILES.BBS file beside it's name, if the file is found. If the file does not exist, then a "[OFFLINE]" string is displayed in the file size column. Title lines may also be added to the FILES.BBS, by indenting them one or more columns. Thus, you could have something like: NEWEST UPLOADS ~~~~~~~~~~~~~~ PKZ110.EXE PKZip file compressor, version 1.10 ODOORS40.LZH The newest version of OpenDoors! EZVOTE40.ZIP EZVote user voting door. BID12.ZIP BBS info. door for new BBS users In addition to this standard FILES.BBS format, OpenDoors will also permit wildcards to be used in FILES.BBS filenames (ie FNEWS???.*), or full directory paths to allow files from several different directories to be included in the same files area. OpenDoors Door Toolkit Manual - Version 4.10 Page 87 You may alter the colours used to display the various portions of the files list using the od_control variables: od_control.od_list_title_col od_control.od_list_name_col od_control.od_list_size_col od_control.od_list_comment_col od_control.od_list_offline_col which are documented in the OpenDoors control structure section on this manual, which begins on page 119. SEE ALSO od_read_files(), od_write_files(), od_send_file() OpenDoors Door Toolkit Manual - Version 4.10 Page 88 OD_LOG_OPEN() -------------------------------------------------------------------------------- PURPOSE Opens a log file and begins logging activities, if logging has not been disabled. FORMAT int od_log_open(void); RETURNS TRUE on success or if logging is disabled FALSE if unsuccessful DESCRIPTION This function will cause OpenDoors to open the log file and begin logging activities, unless logging has been disabled with the od_logfile_disable variable. The log file name will be taken from the od_logfile_name variable, which is usually set by the configuration file. If no logfile name has been set, od_log_open() will use the logfile named DOOR.LOG. Upon opening the log file, OpenDoors will write an entry indicating the time at which the use entered the door. OpenDoors uses the "FrontDoor format" logfile standard. This was chosen as it is a clearly documented format that is quickly becoming the standard for bulletin board software log files. A segment from a log file produced by OpenDoors is listed below. ---------- Thu 25 Feb 93, EZVote 4.10 > 19:42:23 Brian Pirie entering door > 19:50:55 User paging system operator > 19:51:02 Entering sysop chat mode > 20:05:41 Terminating sysop chat mode > 20:18:32 User time expired, exiting door Note that the name of your door to be output to the logfile is taken from the od_program_name variable. If this variable is not set, OpenDoors will simply output "OpenDoors x.xx" as the program name. If a configuration file is to be used, the od_log_open() function should be called after calling the od_init_with_config() function. Thus, the approprate order in which to perform the various startup operations of your door are: - Set OpenDoors registration variables - Set the door's name - Set default logfile name - Call od_init_with_config(), if applicable - Call od_log_open() After od_log_open() has been called, OpenDoors will automatically produce logfile entries for the following events: OpenDoors Door Toolkit Manual - Version 4.10 Page 89 - User paging sysop - Beginnig of sysop chat - Ending of sysop chat - Sysop entering DOS shell - Sysop returning frmo DOS shell - User inactivity timeout - User time expired - Sysop dropping user back to BBS - Sysop hanging up on user - User hagning up on BBS - Sysop locking out user - Your door calling the od_exit() function These built in log file entries can be customized by altering the value of the global array od_log_messages. The default definition for this array is as follows: char *od_log_messages[12]={"Carrier lost, exiting door", "System operator terminating call, exiting door", "User time expired, exiting door", "User keyboard inactivity, exiting door", "System operator returning user to BBS, exiting door", "Exiting door", "Invoking operating system shell", "Returning from operating system shell", "User paging system operator", "Entering sysop chat mode", "Terminating sysop chat mode", "%s entering door"}; There is no od_log_close() function, as the logfile is automatically closed when your doors exits through the od_exit() function. SEE ALSO od_log_write(), od_init_with_config() OpenDoors Door Toolkit Manual - Version 4.10 Page 90 OD_LOG_WRITE() -------------------------------------------------------------------------------- PURPOSE Function to write an entry to the log file FORMAT int od_log_write(char *message); RETURNS TRUE on success, or FALSE on failuer DESCRIPTION This function can be used to write entries to the log file. If the logfile has not already been opened when you call this function for the first time, OpenDoors will automatically open the log file at that time. To create an entry in the log file, simply call the od_log_write() function, passing to it the string of the text you wish to write. You should not include any control characters in this string, simply the text that should appear on the line. OpenDoors will automatically format the log file, adding the time information and other control characters. It is recommended that the length of the string passed to od_log_write() not exceed 67 characters, in order that logfile lines will all be less than 80 characters in length. Log file entries do not usually contain periods or other punctuation at the end of the line. Also, log file entries are usually written in the present tense. The first character of the entry is usually upper-case, with all other entries in lower case. Also, since excessive numbers or lengths of log file entries can quickly use a lot of disk space, it is best to think carefully about what events should be recorded in the log file. It is also a good idea to minimize the number of words used in the entry, without being too cryptic. As an example, "User entering options menu" should be used instead of "user entered the options menu." SEE ALSO od_log_open() EXAMPLE Calling the od_log_write() function is as simple as follows: od_log_write("Awarding user with 5 minutes more time"); OpenDoors Door Toolkit Manual - Version 4.10 Page 91 OD_PAGE() -------------------------------------------------------------------------------- PURPOSE Function to allow user to page the sysop FORMAT void od_page(void); RETURNS N/A DESCRIPTION This function can be called to allow the user to page the sysop. This function will ask the user why they wish to chat with the sysop, and then page the sysop. The sysop will then be free to break into chat at any time. Sysop paging will also be aborted by the user, simply by pressing [Enter] when asked for a reason for chat. When the user pages the sysop, the [Wants-Chat] indicator will begin to flash on the main status line, and the status line will switch to show the user's reason for wanting to chat. Also, the user's total number of pages will be incremented. Depending upon the setting of the od_control.od_okaytopage variable, this function will also optionally check sysop paging hours, and only allow the user to page the sysop during valid paging hours. For information on the variables containing the user's total number of pages, the user's want-chat status, valid sysop paging hours, and the od_control.od_okaytopage variable, see the section on the OpenDoors control structure, which begins on page 119. EXAMPLE For an example of the use of the od_page() function, see the EZVote example door, which is described beginning on page 25. OpenDoors Door Toolkit Manual - Version 4.10 Page 92 OD_PRINTF() -------------------------------------------------------------------------------- PURPOSE Performs formatted output (remote & local) FORMAT void od_printf(char *format,...); RETURNS N/A DESCRIPTION This is one of two OpenDoors function which allows you to display a string of characters, the other being the od_disp_str() function. For a complete comparison of the various OpenDoors display function, see the description of the od_disp_str() function, on page 46. Like the od_disp_str() function, the od_printf() function will display its output both on the local screen, and on the remote user's screen (if the door is not operating in local mode). However, the od_printf() function also allows for formatted output, just as the printf() function does. In addition to providing all of the features of the normal C printf() function, the od_printf() function allows you to include codes to change the colour of the display of text. This unique feature allows you to display multi-coloured text, without having to use chains of alternating od_disp_str() and od_set_colour() calls. As with the printf() function, the od_printf() function accepts one or more parameters, the first parameter being the format string to be displayed, and the additional parameters being data to be displayed within the string. The OpenDoors od_printf() function recognizes all of the control characters and options recognized by the normal printf() function. For example, to display the amount of time that a user has left online, the following line would be a valid use of the od_printf() function: od_printf("Time Left: %d\n\r",od_control.user_timelimit); Note that a full discussion of the printf() function is beyond the scope of this manual. For more information on using printf(), please see your Turbo C(++) / Borland C++ manuals. In addition to the normal control sequences, such as "%s", "%d", or "%12.12s", the od_printf() function also allows you to include special colour-setting codes within the format string. These colour code sequences BEGIN and END with a delimiter character, which is used to indicate that the sequence is a colour setting. Consider, for example, the following line of code, which displays text in various colours: od_printf("`blue`Blue `green`Green `red`Red \n\r"); OpenDoors Door Toolkit Manual - Version 4.10 Page 93 In this case (assuming of course that a colour monitor is being used) the word "Blue" will be displayed in the colour blue, the word "Green" will be displayed in the colour green, and the word "Red" will be displayed in the colour red. In this case, the sequence `blue` sets the display colour to dark blue on black. Here, the the back-quote (`) is the delimiter character which indicates the beginning and end of the colour sequence. Be sure not to confuse the back-quote character (`) with the normal forward quote ('). THIS IS THE MOST COMMON DIFFICULTY EXPERIENCED WITH THE OD_PRINTF() FUNCTION. The text between the back-quote characters indicates the colour that should be set. This text can include the name of the foreground colour, the name of the background colour, the "bright" keyword and the "flashing" keyword. The first colour mentioned is taken to be the foreground colour, and the second the background colour. Case is not sensitive, additional words can be included for legibility. Thus: `bright white cyan` is equivalent to: `Bright white on a cyan background`. The "bright" keyword indicates that the foreground colour should be displayed in high intensity, and the "flashing" keyword indicates that the text should be flashing. If no background is specified, the background colour defaults to black. If no foreground or background colours are specified, the colour defaults to white on black. The od_printf() function will automatically detect whether the user has ANSI or AVATAR graphics, and will send the appropriate colour codes to change the colour of displayed text. If the user does not have either ANSI or AVATAR graphics modes turned on, then the od_printf() function will not send any colour codes. Thus, a door program using colour codes would work just as well when ANSI or AVATAR graphics are not available, except that all text will appear in the same colour. You may prefer to set colours by using the od_set_colour() or od_set_attrib() functions, instead of using these cryptic colour codes imbedded in od_printf() functions. In some cases, however, it will be much more advantageous to place the colour codes within your od_printf() strings. As a case in point, consider the single od_printf() statement in the example, above. To accomplish the same result using the od_disp_str() and od_set_colour() functions, you would have to use the following SIX function calls: od_set_colour(D_BLUE,D_BLACK); od_disp_str("Blue "); od_set_colour(D_GREEN,D_BLACK); od_disp_str("Green "); od_set_colour(D_RED,D_BLACK); od_disp_str("Red \n\r"); OpenDoors Door Toolkit Manual - Version 4.10 Page 94 While this method MAY be easier understand, it certainly requires many more line of code to accomplish. However, either method will work, and the choice is up to you as to which method you prefer. Keep in mind, however, that if the colour to be set is stored in a variable, instead of always being the same colour, you must use either the od_set_colour() or od_set_attrib() function to set the display colour. While the back-quote (`) character is normally used to delimit a colour sequence in the od_printf() function, you may wish to be able to print a back-quote character using the od_printf() function. In this case, you may configure OpenDoors to use a different character to represent colour code sequences. To do this, simply use the od_control.od_colour_delimiter variable, which is described in the OpenDoors control structure section, beginning on page 119. For example, if you wished to use the tilde (~) character instead of the back-quote character to change colours, simply place the following line within your program, at some point after having called od_init() or some OpenDoors door driver function: od_control.od_colour_delimiter='~'; Also, you may disable the colour code interpretation within the od_printf() function altogether, by setting the od_control.od_colour_delimiter variable to 0. Note that the od_printf() function interprets the colour codes AFTER parsing the other control sequences, such as "%d" or "%s". Thus, if you used the command: od_printf("%s",string); Any colour codes contained in the string "string" would also be interpreted. If you did not wish to have any colour code characters which might be contained in the string "string" treated as such, you could again disable od_printf()'s colour code interpretation, by setting the od_control.od_colour_char variable to 0. SEE ALSO od_disp_str(), od_disp(), od_putch(), od_repeat(), od_emulate() EXAMPLE Below is a simple example of a user statistics door program, which displays various pieces of information to the user, by using the od_printf() function. Notice the use of colour code sequences in order to display the titles in a different colour from the information fields. Note that since the information available to this door will depend on the BBS system under which it is running, not all of the information displayed by this door will be available under all BBS systems. For a description of what information is available under what BBS systems, see the OpenDoors control structure portion of this manual, which begins on page 119. OpenDoors Door Toolkit Manual - Version 4.10 Page 95 #include "opendoor.h" int main(int argc,char *argv[]) { od_init(); /* Begin OpenDoors program */ od_printf("`bright white` YOUR STATISTICS\n\r"); /* Display title */ od_printf("---------------\n\r\n\r"); /* Display statistics */ od_printf("`red`NAME : `blue`%s\n\r",od_control.user_logintime); od_printf("`red`LOCATION : `blue`%s\n\r",od_control.user_location); od_printf("`red`PHONE NUMBER : `blue`%s\n\r",od_control.user_homephone); od_printf("`red`LAST CALL : `blue`%s\n\r",od_control.user_lastdate); od_printf("`red`NUMBER OF CALLS : `blue`%u\n\r",od_control.user_numcalls); od_printf("`red`NUMBER OF PAGES : `blue`%u\n\r",od_control.user_numpages); od_printf("`red`REMAINING TIME : `blue`%d\n\r",od_control.user_timelimit); od_printf("`red`# OF DOWNLOADS : `blue`%u\n\r",od_control.user_downloads); od_printf("`red`# OF UPLOADS : `blue`%u\n\r",od_control.user_uploads); od_printf("`red`KBYTES DL TODAY : `blue`%u\n\r",od_control.user_todayk); /* Ask user to press [Enter] */ od_printf("`bright green on green`Press [Enter] to return to BBS...\n\r"); while(od_get_key(TRUE)!=13); /* Wait for user to press [Enter] */ od_exit(20,FALSE); /* Return to BBS */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 96 OD_PUTCH() -------------------------------------------------------------------------------- PURPOSE Function to display a single character. FORMAT void od_putch(int character); RETURNS N/A DESCRIPTION This function performs a similar function to the other OpenDoors display functions. For information on the uses of the various OpenDoors display functions, see the description of the od_disp_str() function, on page 46. This function is most similar to the od_disp() and od_disp_str() functions, except that it only displays a single character at a time. This function will display the character passed to it at the cursor position in the output window, and then advance the cursor to the next display position. If OpenDoors is not operating in local mode, the character will also be sent to the modem, and thus displayed on the user's screen in the same manner that it is displayed on the local screen. If either ANSI or AVATAR graphics mode is activated the character will be displayed in the current colour. SEE ALSO od_disp_str(), od_disp(), od_printf(), od_repeat(), od_emulate() EXAMPLE Below is an example of the use of the od_putch() function. This example is a function which you could use in place of the od_get_key() function. This function inputs a single character from the keyboard, just as the od_get_key() function does. However, if the character entered is a printable character, the function will also echo the character to the local screen, using the od_putch() function. This is helpful for a user to know what key they have pressed within your door. char get_key_with_echo(int wait) { char pressed=od_get_key(wait); /* Get key from user */ if(pressed>=32 && pressed<=126) /* If key is printable */ { od_putch(pressed); /* Display the character */ } return(pressed); /* Return key pressed by user */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 97 For a further example of the user of the od_putch() function, see the example accompanying the od_repeat() function, which is described on page 99. OpenDoors Door Toolkit Manual - Version 4.10 Page 98 OD_REPEAT() -------------------------------------------------------------------------------- PURPOSE Repeatedly display the specified character any number of times, using special graphics codes for greater speed, if possible. FORMAT void od_repeat(char value,unsigned char times); RETURNS N/A DESCRIPTION This display function will repeatedly display the character "value", "times" times. For a complete breakdown of the various OpenDoors display functions, see the description of the od_disp_str() function, located on page 46. The advantage of using this function to display a series of identical characters is that this function will use special graphics-mode control sequences to display the repeated character very efficiently, if the required graphics mode is available. For example, in AVATAR mode, this function can display an entire line of one character, by sending a control sequence to the modem that is only three characters long. If graphics mode is not turned on, then the od_disp_str() function will simply send the specified character the appropriate number of times. As with the other display functions, the output of this function is sent to both the local and remote screens. SEE ALSO od_putch(), od_disp_str(), od_disp(), od_printf(), od_emulate() EXAMPLE The example function below demonstrates the use of the od_repeat() function in drawing a window (a square box) on the screen. This function is essentially a simplified version of the od_draw_box() function, which is described on page 48. Unlike this function, the od_draw_box() function allows the customization of the characters used to draw the box's boarder, and if possible uses additional AVATAR graphics codes to display the window even faster than this function does. Thus, the function below is really provided for demonstration purposes only. This function accepts four parameters, which indicate the location of the upper left and lower right corners of the window to be displayed. The function then displays the window with the current colour attribute settings. Since this function uses the od_repeat() function, if AVATAR graphics are available, it can display the entire window in a fraction of a second, even if it is displaying a window the size of the entire screen at slow baud OpenDoors Door Toolkit Manual - Version 4.10 Page 99 rates. Note that this window displaying function requires that the user has either ANSI or AVATAR graphics mode activated. void draw_window(char left, char top, char right, char bottom) { char line_counter; /* Number of current line being drawn */ char between_size=(right-left)-1; /* X size of window */ od_set_cursor(top,left); /* move to top corner */ od_putch(218); /* display corner character */ od_repeat(196,between_size); /* display top line */ od_putch(191); /* display corner character */ /* loop through middle lines of window */ for(line_counter=top+1;line_counter<bottom;++line_counter) { od_set_cursor(line_counter,left); /* move to line start */ od_putch(179); /* display left line char */ od_repeat(' ',between_size); /* display blank area */ od_putch(179); /* display right line char */ } od_set_cursor(bottom,left); /* move to bottom corner */ od_putch(192); /* display corner character */ od_repeat(196,between_size); /* display bottom line */ od_putch(217); /* display corner character */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 100 OD_SEND_FILE() -------------------------------------------------------------------------------- PURPOSE Sends an ASCII/ANSI/AVATAR file from the disk, using terminal emulation. Also interprets RA/QBBS style information control codes. FORMAT int od_send_file(char *filename); RETURNS TRUE if the file was successfully sent FALSE if OpenDoors was unable to send the file DESCRIPTION: This powerful function will display any ASCII, ANSI or AVATAR text file. The od_send_file() function can be used to display existing BBS text files, such as GOODBYE.A?? before your door hangs up on the user. You can also make use of the od_send_file() function to build many of your door screens as external files. This will allow you to easily create these screens in an ANSI editor program, such as "TheDraw". It will could also optionally allow sysops to customize your door for use on their own BBS. The od_send_file() function is called with the full path and filename of the file you wish to have displayed. Thus, if you wished to send the ANSI file MAINMENU.SCR, you would simply call: od_send_file("MAINMENU.SCR"); In many cases, instead of having just one file that you want displayed in particular, you will have several different files, and will want a different one displayed according to the user's graphics mode. For example, you might have the three files, MAINMENU.ASC, MAINMENU.ANS and MAINMENU.AVT; the .ASC file containing no graphics control codes, the .ANS file containing ANSI graphics control codes, and the .AVT file containing AVATAR graphics control codes. In this case, you can have the od_send_file() function automatically select the appropriate file according to the user's current display mode, by omitting the extension altogether. Thus, a call to: od_send_file("MAINMENU"); would cause OpenDoors to automatically send the appropriate file, according to the user's graphics mode settings. When the od_send_file() function is used in this "automatic mode" (where you do not specify a filename extension), it will look for one of the three filename extensions listed on the following page. OpenDoors Door Toolkit Manual - Version 4.10 Page 101 +----------------------------------------------------------+ | Extension| File type | +----------+-----------------------------------------------| | .ASC | Does not require any graphics mode to display | | .ANS | Requires ANSI graphics mode to display | | .AVT | Requires AVATAR graphics mode to display | +----------------------------------------------------------+ Thus, if the user has AVATAR graphics enabled, od_send_file() will first search for the .AVT file. If no file exists with the specified filename and a .AVT extension, od_send_file() will then search for a .ANS, and if not found .ASC. If the user has only ANSI graphics enabled, od_send_file() will attempt first to display the .ANS file, and if not found will search for .ASC. In the case that the user is using plain-ASCII mode, this function will attempt only to display the .ASC file. The od_send_file() will send any ANSI or AVATAR codes in the file directly to the remote terminal, and interpret them to display on the sysop's local screen (regardless of the actual filename extension). This interpretation is accomplished by OpenDoor's built in terminal emulator. The terminal emulator fully supports all ANSI and AVATAR level 0 and level 0+ control codes. The terminal emulator will also translate Apex/Remote Access/QuickBBS style control codes. The control codes supported by OpenDoors are listed in the chart on the following pages. When these control codes are inserted into the file, OpenDoors will replace them with various pieces of user or system information. OpenDoors Door Toolkit Manual - Version 4.10 Page 102 +-----------------------------------------------------+ | CONTROL | ASCII | | | CODE | VALUE | DESCRIPTION | +---------+-------+-----------------------------------| | ^FA | 06,65 | Displays the user's full name | | ^FB | 06,66 | Location the user is calling from | | ^FC | 06,67 | Displays the user's password | | ^FD | 06,68 | Business/data phone number | | ^FE | 06,69 | Home/voice phone number | | ^FF | 06,70 | Date of the user's last call | | ^FG | 06,71 | Time of day of the last call | | ^FH | 06,72 | The user's `A' flags settings | | ^FI | 06,73 | The user's `B' flags settings | | ^FJ | 06,74 | The user's `C' flags settings | | ^FK | 06,75 | The user's `D' flags settings | | ^FL | 06,76 | User's remaining netmail credit | | ^FM | 06,77 | Number of messages posted by user | | ^FN | 06,78 | Last read message number by user | | ^FO | 06,79 | Displays security level of user | | ^FP | 06,80 | Number of times user has called | | ^FQ | 06,81 | Total # of uploads by user | | ^FR | 06,82 | Total KBytes uploaded by user | | ^FS | 06,83 | Total # of downloads by user | | ^FT | 06,84 | Total Kbytes downloaded by user | | ^FU | 06,85 | # of minute user has used today | | ^FV | 06,86 | User's screen length setting | | ^FW | 06,87 | User's first name only | | ^FX | 06,88 | User's ANSI setting | | ^FY | 06,89 | User's "continue?" prompt setting | | ^FZ | 06,90 | Does user have screen clearing on | | ^F0 | 06,48 | User's Full-screen editor setting | | ^F1 | 06,49 | User's Quiet mode setting | | ^F2 | 06,50 | User's hot-keys setting | | ^F3 | 06,51 | Displays the user's alias | | ^F4 | 06,52 | The date of the User's first call | | ^F5 | 06,53 | The user's date of birth | | ^F6 | 06,54 | User's subscription expiry date | | ^F7 | 06,55 | Number of days until expiry | | ^F8 | 06,56 | User's AVATAR setting | | ^F9 | 06,57 | The user's upload:download ratio | | ^F: | 06,58 | User's Upload K:download K ratio | +-----------------------------------------------------+ OpenDoors Door Toolkit Manual - Version 4.10 Page 103 +-----------------------------------------------------+ | CONTROL | ASCII | | | CODE | VALUE | DESCRIPTION | +---------+-------+-----------------------------------| | ^F; | 06,59 | Full-screen message reader | | ^KA | 11,65 | Total # of calls BBS has received | | ^KB | 11,66 | Name of the last caller to BBS | | ^KC | 11,67 | Total # of active messages on BBS | | ^KD | 11,68 | Displays # of the first message | | ^KE | 11,69 | Displays # of the last message | | ^KF | 11,70 | # of times user has paged sysop | | ^KG | 11,71 | Full name of the current weekday | | ^KH | 11,72 | Displays total number of users | | ^KI | 11,73 | Displays the current time | | ^KJ | 11,74 | Displays the current date | | ^KK | 11,75 | Minutes the user has been online | | ^KL | 11,76 | Seconds the user has been online | | ^KM | 11,77 | Minutes the user has used today | | ^KN | 11,78 | Seconds the user has used today | | ^KO | 11,79 | Minutes remaining for user today | | ^KP | 11,80 | Seconds remaining for user today | | ^KQ | 11,81 | The user's daily time limit | | ^KR | 11,82 | Displays the current baud rate | | ^KS | 11,83 | The current weekday in short-form | | ^KT | 11,84 | The user's daily download limit | | ^KU | 11,85 | # of minutes until the next event | | ^KV | 11,86 | Time of the next system event | | ^KW | 11,87 | # of node user is currently on | | ^KX | 11,88 | Disconnects the user | +-----------------------------------------------------+ SEE ALSO od_emulate(), od_list_files(), od_hotkey_menu() EXAMPLE For an example of the use of the od_send_file() function in displaying a custom door menu, see the EZVote example door, which is described beginning on page 25. OpenDoors Door Toolkit Manual - Version 4.10 Page 104 OD_SET_ATTRIB() -------------------------------------------------------------------------------- PURPOSE Function to change the text colour in ANSI or AVATAR mode, using a single IBM-PC colour attribute value. FORMAT void od_set_attrib(int colour); RETURNS N/A DESCRIPTION od_set_attrib() is one of two functions which change the colour of the currently displayed text. This function allows you to set the text colour using a single IBM-PC style colour attribute. On the other hand, the od_set_colour() function allows you to set the display colour by specifying a foreground and background text colour. Generally speaking, which of these two functions you use will be only a matter of personal preference. You will, however, most likely find it more convenient to use the od_set_colour() function for changing display colour. However the od_set_attrib() offers the advantage of allowing you to manipulate the colour to be displayed as a single value, instead of two separate values. This could be convenient, for example, when displaying text in a user configured colour. Using a single byte to represent the colour will likely be easier than using two. An alternative method of setting the colour of displayed text is to include the colour codes within a string displayed by the od_printf() function. The benefits of doing this, along with instructions on how to do this, are described in the section on the od_printf() function, which begins on page 93. This function will only have an effect if the user has ANSI or AVATAR mode turned on. As a result, you can use this function within your door program, and have your text automatically displayed in multiple colours if graphics mode is available, and displayed without colours if graphics mode is not available. Note that the colour to be set is passed to this function as an IBM-style screen attribute. Hence, you can set the colour of text to be displayed by a single hexidecimal value, encoded as follows: +------------- Background colour | 0x7f | +------------ Foreground colour Where the left digit (most significant nibble) of the hexidecimal number represents the background colour, and the right digit OpenDoors Door Toolkit Manual - Version 4.10 Page 105 (least significant nibble) represents the foreground colour. Each of the possible colours, along with their corresponding hexidecimal values, are listed in the charts, below. +-----------------------+ +--------------------------+ | Foreground colours | | Background | Flashing | +-----------------------| +---------------+----------| | 0 | Black | | 0 | Black | Off | | 1 | Blue | | 1 | Blue | Off | | 2 | Green | | 2 | Green | Off | | 3 | Cyan | | 3 | Cyan | Off | | 4 | Red | | 4 | Red | Off | | 5 | Magenta | | 5 | Magenta | Off | | 6 | Brown | | 6 | Brown | Off | | 7 | White (grey) | | 7 | White | Off | | 8 | Bright Black | | 8 | Black | On | | 9 | Bright Blue | | 9 | Blue | On | | a | Bright Green | | a | Green | On | | b | Bright Cyan | | b | Cyan | On | | c | Bright Red | | c | Red | On | | d | Bright Magenta | | d | Magenta | On | | e | Yellow | | e | Brown | On | | f | White (bright) | | f | White | On | +-----------------------+ +--------------------------+ Hence, od_set_attrib(0x0e) would set the display colour to yellow on a black background, and od_set_attrib(0x70) would set the display colour to black on a while background. SEE ALSO od_set_colour(), od_emulate(), od_clr_scr(), od_clr_line(), od_set_cursor() EXAMPLE At times, you may wish to allow the user to select the colour of text they wish to have displayed, perhaps to configure your door for the ideal colours to be displayed on their system. To demonstrate the use of the od_set_attrib() function, we show another function, which shows the user all 256 possible colours that can be displayed, and allows the user to choose which colour they prefer. The function will then return the colour attribute value of the user's chosen colour, which can later be passed to od_set_attrib() to set the displayed text colour to the colour which was chosen by the user. unsigned char choose_colour(void) { register unsigned char counter; /* for displaying colours */ char string[4]; /* string input by user */ od_set_attrib(0x07); /* display title */ od_disp_str("Available colours:\n\r\n\r"); for(counter=0;counter<=255;) /* loop through all colours */ { od_set_attrib(counter); /* set appropriate colour */ OpenDoors Door Toolkit Manual - Version 4.10 Page 106 od_printf("%03.3u",counter); /* display colour's number */ if(((++counter)%16)==0) /* after every 16 colours ... */ { od_set_attrib(0x07); /* ... reset display colour ... */ od_disp_str("\n\r"); /* ... and start a new line */ } } od_set_attrib(0x07); /* Allow user to choose colour */ od_disp_str("Which colour do you prefer : "); od_input_str(string,3,'0','9'); return(atoi(string)); /* Return chosen colour */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 107 OD_SET_COLOUR() -------------------------------------------------------------------------------- PURPOSE Function to change the text colour in ANSI or AVATAR mode, using foreground and background colour values. FORMAT void od_set_colour(int foreground, int background); RETURNS N/A DESCRIPTION od_set_colour() is one of two functions which change the colour of the currently displayed text. This function allows you to set the text colour using separate foreground an background text colours, whereas od_set_attrib() allows you to set the text colour using a single IBM-PC style colour attribute. Generally speaking, which of these two functions you use is only a matter of personal preference. An alternative method of setting the colour of displayed text is to include the colour codes within a string displayed by the od_printf() function. The benefits of doing this, along with instructions on how to do this, are described in the section on the od_printf() function, which begins on page 93. This function will only have an effect if the user has ANSI or AVATAR mode turned on. As a result, you can use this function within your door program, and have your text automatically displayed in multiple colours if graphics mode is available, and displayed without colours if graphics mode is not available. The od_set_colour() function accepts two parameters, the first parameter being the foreground colour to be used in displaying text, and the second parameter being the background colour to be used in displaying text. For example, od_set_colour(L_WHITE,D_BLACK); would set the current colour to Light White on Dark Black. The foreground and background text colours can be any one of the colour values listed on the following page. OpenDoors Door Toolkit Manual - Version 4.10 Page 108 +-------------------+-----------+ | Foreground Colour | Value | +-------------------+-----------+ | Dark Black | D_BLACK | | Dark Blue | D_BLUE | | Dark Green | D_GREEN | | Dark Cyan | D_CYAN | | Dark Red | D_RED | | Dark Magenta | D_MAGENTA | | Dark Brown | D_BROWN | | Grey (Dark White) | D_GREY | | Light Black (Grey)| L_BLACK | | Light Blue | L_BLUE | | Light Green | L_GREEN | | Light Cyan | L_CYAN | | Light Red | L_RED | | Light Magenta | L_MAGENTA | | Yellow | L_YELLOW | | White | L_WHITE | +-------------------+-----------+ +-------------------+-----------+ | Background Colour | Value | +-------------------+-----------+ | Black | D_BLACK | | Blue | D_BLUE | | Green | D_GREEN | | Cyan | D_CYAN | | Red | D_RED | | Magenta | D_MAGENTA | | Brown | D_BROWN | | Grey | D_GREY | | Blinking Black | B_BLACK | | Blinking Blue | B_BLUE | | Blinking Green | B_GREEN | | Blinking Cyan | B_CYAN | | Blinking Red | B_RED | | Blinking Magenta | B_MAGENTA | | Blinking Brown | B_BROWN | | Blinking Grey | B_WHITE | +-------------------+-----------+ SEE ALSO od_set_attrib(), od_emulate(), od_clr_scr(), od_clr_line(), od_set_cursor() EXAMPLE As an example of using the od_set_colour() function to set the colour of displayed text, we show a pair of two functions. These functions will allow a program to set the foreground OR background colour of text, without setting the other. In contrast, the od_set_colour() function sets both the foreground and background colour at the same time. These function presume that they are the only functions used within the door to set the OpenDoors Door Toolkit Manual - Version 4.10 Page 109 colour of displayed text, and that the original text colour prior to calling either of these functions is dark white on black. These function must also have access to the two global variables "current_foreground" and "current_background", as defined below. void set_foreground(char foreground); void set_background(char background); unsigned char current_foreground=D_BLACK; unsigned char current_background=D_GREY; void set_foreground(char foreground) { /* set new text colour */ od_set_colour(foreground,current_background); current_foreground=foreground; /* save new foreground */ } void set_background(char background) { /* set new text colour */ od_set_colour(current_foreground,background); current_background=background; /* save new background */ } Using these functions, you would then be able to set just the foreground text colour by a function call like: set_foreground(L_YELLOW); Or set just the background text colour by a function call like: set_background(D_GREY); OpenDoors Door Toolkit Manual - Version 4.10 Page 110 OD_SET_CURSOR() -------------------------------------------------------------------------------- PURPOSE Function to locate the cursor in ANSI or AVATAR mode FORMAT void od_set_cursor(int row, int col); RETURNS N/A DESCRIPTION This function will only have an effect if the user has ANSI or AVATAR graphics mode turned on. In graphics mode, this function can be used to position the cursor anywhere on the screen (cursor is moved both locally and on the remote terminal). The first parameter "row", can normally have a value between 1 to 23, and indicates the row, or y position on the screen, where the cursor should be located. The second parameter, "col", can have a value between 1 and 80, and indicates the column (x-position) on the screen, where the cursor should be located. SEE ALSO od_emulate(), od_clr_scr(), od_clr_line(), od_set_colour(), od_set_attrib() EXAMPLE Below is a simple sample door that demonstrates the use of the od_set_cursor() function. Note that this door detects whether or not graphics mode is available, and if it is not, will carry out the same task without the use of the od_set_cursor() function. #include "opendoor.h" int main(int argc,char *argv[]) { od_init(); /* Initialize door operations */ od_clr_scr(); /* Clear the screen */ if(od_control.user_ansi || od_control.user_avatar) { /* If graphics mode is available */ od_set_cursor(1,1); /* Display demo */ od_disp_str("Top, Left Corner"); od_set_cursor(1,70); od_disp_str("Top, Right Corner"); od_set_cursor(15,1); od_disp_str("Fifteenth line\n\r"); } else /* If graphics mode is not available */ OpenDoors Door Toolkit Manual - Version 4.10 Page 111 { /* Display demo */ od_disp_str("Top, Left Corner Top, Right Corner\n\r"); /* Skip 13 lines */ od_disp_str("\n\n\n\n\n\n\n\n\n\n\n\n\n"); od_disp_str("Fifteenth line\n\r"); } od_get_key(TRUE); /* Wait for user to press key */ od_exit(FALSE,20); /* Exit door */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 112 OD_SET_STATUSLINE() -------------------------------------------------------------------------------- PURPOSE To set the currently displayed status line. FORMAT void od_set_statusline(char setting); RETURNS N/A DESCRIPTION If you have the OpenDoors status line enabled within your door program (as is the default), the sysop will be able to control the setting of the status line using the F1 - F10 keys on the keyboard. These function keys are as follows: [F1] - Display basic door and user information [F2] - Display phone numbers and important dates [F3] - Display security flags and up/download info [F4] - Display system information and current time [F5] - Display message info and user's settings [F6] - Display chat reason and sysop's comment [F9] - Display help information for sysop [F10] - Turn off the status line Using the od_set_statusline() function, you can manually set which of these status line settings is currently selected. The od_set_statusline() accepts a single parameter, which should be one of the values listed below, which indicates which status line you would like to have selected: +---------------+---------------+-------------------------------+ | | Corresponding | | | Value | Function Key | Meaning | +---------------+---------------+-------------------------------+ | STATUS_NORMAL | [F1] | Basic door and user info | | STATUS_NONE | [F10] | Turn off status line | | STATUS_HELP | [F9] | Displays help for the sysop | | STATUS_USER1 | [F2] | Phone Numbers and dates | | STATUS_USER2 | [F3] | Security flags & up/downloads | | STATUS_USER3 | [F5] | Message info & user settings | | STATUS_USER4 | [F6] | Chat reason and sysop comment | | STATUS_SYSTEM | [F4] | System info & current time | +---------------+---------------+-------------------------------+ (Note that these keys may be customized using variables in the OpenDoors control structure.) Keep in mind that the od_set_statusline() function only temporarily changes the current status line setting, and that the sysop will still be able to change the status line to any of the other settings using the function keys. For instance, if you OpenDoors Door Toolkit Manual - Version 4.10 Page 113 wished to allow the sysop to normally see all 25 lines of text displayed by your door, but at the same time to still allow the sysop to turn on the status line at any time, you could place the line od_set_statusline(STATUS_NONE); at the beginning of your program. Similarly, when the user pages the sysop, OpenDoors itself calls od_set_statusline(STATUS_USER4); in order to display the status line which shows the user's reason for chat, while still allowing the sysop to switch back to any of the other status lines. If you wish to permanently turn off the OpenDoor's status line, without allowing the sysop to be able to turn it back on using the sysop function keys, simply set the "od_control.od_status_on" variable to FALSE. This variable is described in the OpenDoors control structure section of this manual, which begins on page 119. OpenDoors Door Toolkit Manual - Version 4.10 Page 114 OD_SPAWN() -------------------------------------------------------------------------------- PURPOSE To facilitate easy execution of child tasks from doors. FORMAT int od_spawn(char *command_line); RETURNS TRUE on success, FALSE on failure DESCRIPTION This function allows you to easily run other programs from within your door programs, such as external file transfer utilities, compression utilities, and so on. This function will attempt to swap OpenDoors and your entire door to expanded memory or disk. OpenDoors swapping can be controlled by the OpenDoors control structure variables, od_swapping_disable, od_swapping_ems and od_swap_path. The od_spawn...() functions first attempt to swap OpenDoors to EMS memory. If enough EMS 3.2 or later memory is available, it will be used. If not, OpenDoors will swap to a disk file in the directory specified by the od_control.od_swap_path variable. Unlike the other Turbo C(++) / Borland C++ library functions such as system() or spawnf(), this function will automatically store the door screen prior to executing the sub-program, and will restore the screen upon return. This function will also store the current drive and directory settings prior to executing the program, and restore them after the program has returned. Normally, the user's time will continue to be decreased during the execution of the od_spawn() function. However, you can freeze the user's time during the spawn process by using the OpenDoors control structure variable od_spawn_freeze_time. SEE ALSO od_spawnvpe() EXAMPLE Below are a few examples of various uses of the od_spawn() function: To run the command processor from within your door program, to allow the sysop access to the DOS shell, simply use the following line of code: od_spawn(getenv("COMSPEC")); OpenDoors Door Toolkit Manual - Version 4.10 Page 115 The following function is an example of using the od_spawn() function to call DSZ, allowing the user to download a file. You pass the name of the file that you wish to send to the user. This function will then ask the user what transfer protocol they would like to use, generate the appropriate DSZ command line, and then transmit the file to the user. Note that in order to use a door which implements this function, the external file transfer program "DSZ" must be available in the current search path. As an alternative, you may want to allow the sysop to specify the location of the DSZ file from within a configuration program. If you wish to receive a file (allow the user to upload), instead of sending one, simply change the "s" in the command line to a "r". char download(char *filename) { char commandline[80]; /* string containing DSZ command line */ char protocol; /* character representing chosen protocol */ /* display protocol menu */ od_printf("Select File Transfer Protocol:\n\r"); od_printf(" [X] XModem\n\r"); od_printf(" [Y] YModem\n\r"); od_printf(" [Z] ZModem\n\r"); od_printf("or press [A] to abort transfer\n\r"); do /* loop until valid protocol has been chosen */ { protocol=od_get_key(); /* get key */ /* abort if [A] key is pressed */ if(protocol=='a' || protocol=='A') return(FALSE); } while(protocol!='x' && protocol!='y' && protocol!='z' && protocol!='X' && protocol!='Y' && protocol!='Z'); od_printf("Begin receiving file now or press [CTRL]-[X] to abort\n\r"); /* generate DSZ command line */ sprintf(commandline,"dsz port %d s%c %s", od_control.port+1, protocol, filename); return(od_spawn(commandline)); /* spawn to DSZ */ } OpenDoors Door Toolkit Manual - Version 4.10 Page 116 OD_SPAWNVPE() -------------------------------------------------------------------------------- PURPOSE To facilitate easy execution of child tasks from doors. Allows specification of childs environment, returns errorlevel returned by child task, and seaches path for the executable file. FORMAT int od_spawnvpe(int modeflag, char *path, char *argv[], char *envp[]); RETURNS -1 on failure errorlevel returned by child process on success DESCRIPTION This function behaves very similarly to the od_spawn() function. Thus, to save space in the manual, I will not recapitulate what is already said in the description of the od_spawn() function. Instead, this description concentrates on the additional features available through the od_spawnvpe() function. If you are not already familiar with the od_spawn() function, take a moment now to review the description of that function. The od_spawn() function (the OpenDoors "quick-spawn" function) is designed to be quick and easy to use, but does not have all of the features available in the od_spawnvpe() function. In addition to the features of the od_spawn() function, the od_spawnvpe() function also provides the following features: - od_spawnvpe() will search the "path" for the file to be executed. - od_spawnvpe() allows you to pass an altered environment to the child process. - od_spawnvpe() returns the errorlevel returned by the child process. The parameters passed to the od_spawnvpe() function are identical to those passed to the C spawnvpe() function. The first paramter should usually the be P_WAIT flag. The second parameter is the name of the child program to execute. If a full path to the child program is not specified, and the child program does not exist in the current directory, OpenDoors will search the directories listed by the PATH environment variable. Also, if the .EXE or .COM extention is not provide, OpenDoors will look forst for a .COM file, and if not found, for a .EXE file. The third parameter is an array of arguments to pass to the child process, or NULL if no arguments are to be passed. The fourth parameter is the environment to be passed to the child process, or NULL if the a copy of the current environment should be used. SEE ALSO od_spawn() OpenDoors Door Toolkit Manual - Version 4.10 Page 117 EXAMPLE For an example of the use of the od_spawn...() functions, see the example accompanying the od_spawn() function. As a specific exampe of the od_spawnvpe function, consider the following code which executes the "TEST.EXE" program. od_spawnvpe(P_WAIT,"TEST.EXE",NULL,NULL); OpenDoors Door Toolkit Manual - Version 4.10 Page 118 -------------------------------------------------------------------------------- CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE -------------------------------------------------------------------------------- INTRODUCTION TO THE CONTROL STRUCTURE -------------------------------------------------------------------------------- The OpenDoors "Control Structure" is used by the OpenDoors door driver in order to provide you with a wide range of information about the system on which you door is running, and the user who is currently using the door, along with providing you a means by which to customize much of OpenDoor's behaviour. Using the OpenDoors control structure, you can access or alter information about the user who is online, information about the system on which your door is running, and information about OpenDoors itself. You can also use the control structure to customize all of the text displayed by OpenDoors, the function keys to which it responds, and many other aspects of OpenDoor's behaviour. The OpenDoors control structure is quite simply a normal C "struct", named od_control, and is defined in the OPENDOOR.H file. This "struct" contains many different variables, which provide you access to the information provided by the control structure. Hence, to access the contents of a control structure variable, for example the variable "system_name" which contains the name of the BBS the door is running under, you would use: od_control.system_name The following section of this chapter contains a complete reference to all of the variables which make up the OpenDoors control structure. This reference includes the name, type and complete description of the use of each variable. The reference is divided into the following categories of variables, with the reference to the variables in each section beginning on the listed page. Door Information File Statistics .................121 Modem Settings ...................................124 BBS and Caller Information .......................125 Door Settings ....................................146 OpenDoors Behaviour Customization ................149 Function Keys Customization ......................160 Colour Customization .............................163 Text Customization ...............................164 Within each section, variables are listed alphabetically, according to their names. If you would like more information on C "struct"s, please refer to your Turbo C(++)/Borland C++ manuals. OpenDoors Door Toolkit Manual - Version 4.10 Page 119 Also, in order to make use of some of the variables in the OpenDoors control structure, it is important to understand the concepts of boolean (TRUE/FALSE), and bit-mapped flag variables. If you are not familiar with these two terms, they are described in detail in the glossary, located towards the end of this manual. OpenDoors Door Toolkit Manual - Version 4.10 Page 120 CONTROL STRUCTURE - DOOR INFO FILE STATS -------------------------------------------------------------------------------- The following OpenDoors control structure variables provide your program with information concerning the door information file from which OpenDoors obtained the BBS and caller information that is found elsewhere in the control structure. The following control structure items are listed in this section: info_path Contains the path to the door information file od_info_type Type of door information file that was found od_node Node number the door is running under user_timeofcreation The time at which the door information file was created -------------------------------------------------------------------------------- info_path char od_control.info_path[60]; This variable stores the location of the door information file (such as DORINFO?.DEF, EXITINFO.BBS, CHAIN.TXT, DOOR.SYS, CALLINFO.BBS, SFDOORS.DAT, etc.), from which OpenDoors will read and write information about the BBS and the caller online. Note, however, that this variable only contains the path to this file, and not the name of the file itself. For example, if your door knew that the door information file resided in C:\BBS, this variable might contain "C:\\BBS\\". Remember that when programming in C, that you must place two backslash characters in a literal string in order to have a single backslash placed in the actual string, as shown in the example string above. The info_path variable is not case sensitive, and may or may not include the trailing backslash in the directory name. OpenDoors only uses this variable when it first starts up, during the od_init() function, and when it shuts down, during the od_exit() function. Thus, if you wish to alter the setting of the info_path variable, you must do so before calling od_init(), or any other OpenDoors functions. Also, you will not normally want to change the value of this variable after having called od_init() or any OpenDoors functions, as doing so would cause OpenDoors to re-write the caller information to another door information file in a different directory. This would most likely prevent the BBS system which your door is running under from being able to re-read the changes to the door information file. OpenDoors Door Toolkit Manual - Version 4.10 Page 121 It is usually a good idea to design any door in such a way as to allow the user of the door to specify the location of the door information file. This will allow the sysop to place your door in it's own directory, and will facilitate the use of your door on multi-line BBS systems. If your door has a configuration file, you may wish to include a setting in the configuration file to indicate the location of the door information file. However, an even better design choice would be to allow the location of the door information file to optionally be passed to the door on the command line, as the example door, EZVote does. The following trivial door illustrates a method of reading and setting the location of the door information file from the door's command line: #include "opendoor.h" main(int argc, char *argv[]) { if(argc>1) strncpy(od_control.info_path,argv[1],59); od_disp_str("This is a sample OpenDoors door.\n\r"); od_disp_str("Press any key to continue...\n\r"); od_get_key(TRUE); od_exit(20); } -------------------------------------------------------------------------------- od_info_type char od_control.od_info_type; This variable indicates the type of information file from which OpenDoors has obtained the BBS and caller information that is found elsewhere in the OpenDoors control structure. This variable will have one of the following values, indicating that the door information file was of the corresponding type: +----------------+----------------------------+ | od_info_type | Door Information File Type | | Value | | +----------------+----------------------------+ | DORINFO1 | DORINFO?.DEF | | EXITINFO | EXITINFO.BBS (Normal) | | RA1EXITINFO | EXITINFO.BBS (Extended) | | QBBS275EXITINFO| EXITINFO.BBS (QuickBBS) | | CHAINTXT | CHAIN.TXT | | SFDOORSDAT | SFDOORS.DAT | | CALLINFO | CALLINFO.BBS | | DOORSYS_GAP | DOOR.SYS (GAP/PC-Board) | | DOORSYS_DRWY | DOOR.SYS (Doorway style) | | DOORSYS_WILDCAT| DOOR.SYS (WildCat standard)| | | | | CUSTOM | Custom door information | | | file, defined in config | | | file. | +----------------+----------------------------+ OpenDoors Door Toolkit Manual - Version 4.10 Page 122 The value of this variable is only valid AFTER od_init() or some OpenDoors door driver function has been called. Note that this variable should be treated as a read-only variable, and should not normally be altered by your program. Altering this variable may cause OpenDoors to re-write a different type of door information file upon exiting, than was read upon startup. -------------------------------------------------------------------------------- od_node char od_control.od_node; This variable indicates the node number that the door is running under. If this information is supplied by the BBS in the door information file, the node number will be automatically by OpenDoors. Specifically, the node number can be determined automatically from systems that produce an SFDOORS.DAT, PC- Board/GAP style DOOR.SYS or Wildcat style DOOR.SYS door information file. If this information is not supplied in the door information file, but is provided by the sysop in the door's configuration file, OpenDoors will use the value found there. Alternatively, you can set this variable manually. On systems that produce a DORINFO?.DEF file, OpenDoors will use this variable to determine which DORINFO?.DEF file to search for. For instance, if od_control.od_node is set to 3, OpenDoors will first search for a DORINFO3.DEF file. If this file is not found, OpenDoors will then default to the DORINFO1.DEF filename. -------------------------------------------------------------------------------- user char od_control.user_timeofcreation[6]; _timeof creation This variable contains the time of day at which the door information file was created. This variable is available only when the door is running under a system that produces an EXITINFO.BBS file. To determine what type of door information file your door is running under, see the od_control.od_info_type variable, below. OpenDoors Door Toolkit Manual - Version 4.10 Page 123 CONTROL STRUCTURE - MODEM SETTINGS -------------------------------------------------------------------------------- The following OpenDoors control structure items store the communications settings that OpenDoors uses to communicate with the modem. These values are normally set upon the first call to an OpenDoors door driver function, during the od_init() procedure. However, if you are reading the door information file yourself, or using the OpenDoors door driver to write some sort of non-door program, where you have disabled the reading of the door information file, you will have to set these values yourself before you use any of the OpenDoors door driver functions. -------------------------------------------------------------------------------- port char od_control.port; This variable contains the FOSSIL port number of the modem. Note that most often, FOSSIL port 0 corresponds to COM1:, FOSSIL port 1 corresponds to COM2:, and so on. This value will normally be set by the od_init() function, when the door information file is read, and should not be changed after modem initialization has been carried out by the od_init() function. In other words, od_control.port should generally be treated as a read-only variable. This variable will most often be useful in passing the port number to an external program, such as DSZ. -------------------------------------------------------------------------------- baud unsigned int od_control.baud; This variable contains the actual BPS rate at which the modem is operating. Note that if a high speed modem is in use, that the comm port may actually be locked at a higher baud rate. OpenDoors Door Toolkit Manual - Version 4.10 Page 124 CONTROL STRUCTURE - BBS AND CALLER INFORMATION -------------------------------------------------------------------------------- As we have already described, there are two types of variables in the OpenDoors control structure. Some of the variables are simply used to allow you to customize OpenDoor's various features, such as altering colours, prompts, timeouts, etc. Other variables in the OpenDoors control structure serve to provide you with information about the user who is online and the BBS system your door is running under. This section deals with those variables that provide you with information about the BBS and the user. The information in these variables is read from the door information file, a small file created by the BBS specifically for the purpose of communicating with door programs. Depending on what BBS system your door is running under, the type of door information file will vary. Since different door information files do not all provide the same pieces of information, some variables in this section will only be available when your door is running under particular BBS systems. Other variables will be available with many or all BBS systems. In the description of each variable in this section, we indicate under which door information files the particular variable will be . So, if you wish to access a variable that is only under certain door information files, your program should test whether or not the required information is available under the particular door information file that was found. In order to determine which door information file your door is running under, you should use the od_control.od_info_type variable. This variable is described in the section which begins on page 121. If you test the value of the od_control.od_info_type variable, and find that the required information is not available, you may wish to simply use some sort of default value for the variable, or alternatively, not allow your door to run under certain BBS systems. Another possibility, if the required information is not available, is imply to obtain this information from the user yourself. For example, if you wished to know the length of the user's screen, when this information is not available from the door information file, you could simply prompt the user for their screen length the first time they use your door. This information could then be stored in your door's data files for future reference. As an example of testing what door information file your door is running under, consider the case where you wanted to display the user's birthday. The example below will display the user's birthday if it is known, and otherwise, print the string "unknown". if(od_control.od_info_type==RA1EXITINFO) { od_disp_str(od_control.user_birthday); } else OpenDoors Door Toolkit Manual - Version 4.10 Page 125 { od_disp_str("Unknown"); } The chart below lists the door information file formats that OpenDoors recognizes, along with example BBS systems that produce these files and a reference letter for each type. Thus, an OpenDoors door can run DIRECTLY under ANY BBS SYSTEM that produces one of these files formats, and under ANY OTHER BBS system when used in conjunction with a door information file conversion utility. +--------------------------+----------------------------------------+ | FILE FORMAT | EXAMPLE BBS SYSTEMS | +--------------------------+----------------------------------------+ | CHAIN.TXT | WWIV | +--------------------------+----------------------------------------+ | DORINFO1.DEF | RBBS-PC | +--------------------------+----------------------------------------+ | DORINFO1.DEF | QuickBBS | | & | Remote Access (versions 0.01-0.04) | | EXITINFO.BBS (Std. Ver.) | | +--------------------------+----------------------------------------+ | DOOR.SYS (DoorWay Style) | Remote Access | +--------------------------+----------------------------------------+ | DOOR.SYS (PCB/GAP Style) | PC-Board | | | GAP | +--------------------------+----------------------------------------+ | DOOR.SYS (WildCat Style) | Wildcat 3.00 and above | | | Telegard | +--------------------------+----------------------------------------+ | SFDOORS.DAT | Spitfire | | | TriTel | +--------------------------+----------------------------------------+ | CALLINFO.BBS | WildCat 2.xx | +--------------------------+----------------------------------------+ | DORINFO1.DEF | Remote Access (versions 1.00 and later)| | & | | | EXITINFO.BBS (Ext. Ver.) | | +--------------------------+----------------------------------------+ OpenDoors Door Toolkit Manual - Version 4.10 Page 126 The following chart lists all of the OpenDoors control structure variables in this section, along with a brief description of their use. The variables are then described in detail, below. +-----------------------+-----------------------------------------------+ | VARIABLE NAME | VARIABLE CONTENTS | +-----------------------+-----------------------------------------------+ | EMSI INFORMATION | Information on current IEMSI session | | event_status | The status of the next system event | | event_starttime | The start time of the next system event | | event_errorlevel | The errorlevel of the next system event | | event_days | The days of the week to execute the event | | event_force | Whether the next system event is forced | | event_last_run | When the next system event was last run | | sysop_name | The name of the BBS's sysop | | system_calls | Total number of calls BBS has received | | system_last_caller | The name of the last caller to the BBS | | system_name | The name of the BBS | | TIMELOG VARIABLES | The times at which the BBS has been most busy | | user_ansi | Whether the user has ANSI graphics mode on | | user_attribute | User attribute bit-mapped flags | | user_attrib2 | Second set of user attribute bit-mapped flags | | user_avatar | Whether the user has AVATAR graphics mode on | | user_birthday | The date the user was born | | user_callsign | The user's amateur radio call sign | | user_combinedrecord | The user's combined message areas settings | | user_comment | Sysop's comment about the user | | user_credit | Amount of NetMail credit the user has | | user_dataphone | The user's data phone number | | user_date_format | Format user wishes to have dates displayed in | | user_deducted_time | Total time that has been subtracted from user | | user_downk | Total Kilobytes downloaded by the user | | user_downlimit | User's daily download limit | | user_downloads | Total number of files downloaded by the user | | user_echomailentered | Whether or not the user has entered EchoMail | | user_error_free | Whether or not connection is error-free | | user_file_area | The user's current file area | | user_firstcall | Date of the user's first call to the BBS | | user_flags | User's sysop-defined flag settings | | user_forward_to | Name to forward user's mail to | | user_group | User's group number | | user_handle | User's alias | | user_homephone | User's home telephone number | | user_language | User's language setting | | user_last_pwdchange | Total calls since last password change | | user_lastdate | Date of the user's last call | | user_lastread | Highest message number read by user | | user_lasttime | Time of the user's last call | | user_location | Name of the city where the user lives | | user_logindate | Date on which the current call began | | user_loginsec | User's security at the beginning of this call | +-----------------------+-----------------------------------------------+ OpenDoors Door Toolkit Manual - Version 4.10 Page 127 +-----------------------+-----------------------------------------------+ | VARIABLE NAME | VARIABLE CONTENTS | +-----------------------+-----------------------------------------------+ | user_logintime | Time at which the current call began | | user_logonpassword | User's password at the beginning of this call | | user_menustack | Contents of the user's current menu stack | | user_menustackpointer | Pointer to the top of the menu stack | | user_messages | Total number of messages written by the user | | user_msg_area | The user's current message area | | user_name | The user's name | | user_net_credit | The user's remaining netmail credit | | user_netmailentered | Whether or not the user has entered NetMail | | user_num | The user's record number in the user file | | user_numcalls | Number of calls the user has made to the BBS | | user_numpages | Number of times the user has paged the sysop | | user_password | The user's current password | | user_pending | The value of unsent NetMail written by user | | user_reasonforchat | The reason the user wishes to chat with sysop | | user_screen_length | The length of the user's screen | | user_screenwidth | The width of the user's screen | | user_security | The user's security access level | | user_sex | The user's gender | | user_subdate | The date the user's subscription expires | | user_timelimit | The user's daily time limit | | user_todayk | Kilobytes downloaded by the user today | | user_upk | Total Kilobytes uploaded by the user | | user_uploads | Total number of files uplaoded by the user | | user_wantchat | Whether or not the user wishes to chat | | user_xi_record | The user's record in the USERSXI.BBS file | +-----------------------+-----------------------------------------------+ -------------------------------------------------------------------------------- EMSI char od_control.ra_emsi_session; INFORMATION char od_control.ra_emsi_crtdef[41]; char od_control.ra_emsi_protocols[41]; char od_control.ra_emsi_capabilities[41]; char od_control.ra_emsi_requests[41]; char od_control.ra_emsi_software[41]; char od_control.ra_hold_attr1; char od_control.ra_hold_attr2; char od_control.ra_hold_len; These variables provide your door with information pertaining to an interactive EMSI session that has been established. Note that these variables are only available under systems that produce an RA 1.00 and later style extended EXITINFO.BBS door information file. OpenDoors Door Toolkit Manual - Version 4.10 Page 128 If an IEMSI session has been established, the boolean variable od_control.ra_emsi_session will be TRUE, and if no session has not been established, this variable will be FALSE. A full discussion of the IEMSI protocol is beyond the scope of this manual. Specifications for the IEMSI protocol are available from the OpenDoors support BBS. -------------------------------------------------------------------------------- event_days unsigned char od_control.event_days; This variable is a bit-mapped flag of the days of the week on which the next system event is run. The bit-map bits are as follows: +-----+------+-----------+ | BIT | MASK | MEANING | +-----+------+-----------+ | 0 | 0x01 | Sunday | | 1 | 0x02 | Monday | | 2 | 0x04 | Tuesday | | 3 | 0x08 | Wednesday | | 4 | 0x10 | Thursday | | 5 | 0x20 | Friday | | 6 | 0x40 | Saturday | | 7 | 0x80 | All Days | +-----+------+-----------+ For more information on bit-mapped flags, see the glossary item entitled "BIT-MAPPED FLAGS". This variable is only available under systems that produce an EXITINFO.BBS door information file. -------------------------------------------------------------------------------- event_ unsigned char od_control.event_errorlevel; errorlevel This variable contains the ErrorLevel associated with the next system event. This variable is only available under systems that produce an EXITINFO.BBS door information file. -------------------------------------------------------------------------------- event char od_control.event_force; _force This variable indicates whether the next system event should be forced to run at a particular time. If this variable contains a value of TRUE, then the user should be forced off-line in order to accommodate the event, and if this variable is false, then the event can wait until after the user logs off normally. This OpenDoors Door Toolkit Manual - Version 4.10 Page 129 variable is only available under systems that produce an EXITINFO.BBS file. -------------------------------------------------------------------------------- event char od_control.event_last_run[9]; _last_run This variable contains a string representing the date on which the next system event was last run, and is in the same format as the user_lastdate variable. This variable is only available under systems that produce an EXITINFO.BBS file. -------------------------------------------------------------------------------- event char od_control.event_starttime[6]; _starttime This variable contains a string representing the time at which the next system event is scheduled to start, in the same format as the user_lasttime variable. This variable is only available under systems that produce an EXITINFO.BBS or Wildcat style DOOR.SYS door information file. -------------------------------------------------------------------------------- event unsigned char od_control.event_status; _status This variable represents the status of the next system event, and will be equal to the value ES_ENABLED if and only if the other event information contained in the control structure is valid. This variable is only available under systems that produce an EXITINFO.BBS file. -------------------------------------------------------------------------------- sysop_name char od_control.sysop_name[40]; The od_control.sysop_name variable contains the name of the sysop of the BBS under which your door is running. This variable is available under any BBS system that produces a DORINFO?.DEF (including RA & QBBS which process both DORINFO1.DEF and EXITINFO.BBS files), or Wildcat style DOOR.SYS file. -------------------------------------------------------------------------------- system_calls long od_control.system_calls; OpenDoors Door Toolkit Manual - Version 4.10 Page 130 This variable contains the total number of calls that have been placed to the BBS, and is available under any BBS which produces an EXITINFO.BBS file. -------------------------------------------------------------------------------- system_last char od_control.system_last_caller[36]; _caller This string contains the name of the previous caller to the BBS, on any line, and is available under EXITINFO.BBS. -------------------------------------------------------------------------------- system_name char od_control.system_name[40]; The od_control.system_name variable contains the name of the BBS under which your door is running. This variable is available under any BBS system that produces a DORINFO?.DEF (including RA & QBBS which process both DORINFO1.DEF and EXITINFO.BBS files). -------------------------------------------------------------------------------- TIMELOG char od_control.timelog_start_date[9]; VARIABLES This string contains the date of the beginning of the time period for which the time log is recorded. This variable is available under any system that produces an EXITINFO.BBS file. int od_control.timelog_busyperhour[24]; This variable is an array of 24 elements, with each element indicating the total number of times the BBS was in use during each of the 24 hours of the day. Element 0 corresponds to the time period of 0:00-1:00, element 1 corresponds to the time period of 1:00-2:00, and so on. In order to determine the frequency of system use during any hour as a percentage, simply calculate the total of all 24 entries in the array, and divide any given entry by the total, in order to come up with an average. This variable is available under any system that produces an EXITINFO.BBS file. int od_control.timelog_busyperday[7]; This variable is an array of 7 elements, with each element indicating the total number of times the BBS was in use during each of the 7 days of the week. Here, elements 0 corresponds to Sunday, element 1 to Monday, and so on. In order to calculate the frequency of system use during any day of the week, use the same method as for calculating the frequency of calls during each hour, as described above. This is only available under systems that produces an EXITINFO.BBS file. Note that at least some, if OpenDoors Door Toolkit Manual - Version 4.10 Page 131 not all, versions of RemoteAccess do not maintain this variable correctly, and thus even with the presence of an EXITINFO.BBS file, this array may contain all zero entries. -------------------------------------------------------------------------------- user_ansi char od_control.user_ansi; This variable contains a boolean value, indicating whether or not the user has ANSI mode turned on. If ANSI graphics mode is enabled, this variable will contain a value of TRUE, and if ANSI graphics mode is disabled, this variable will contain a value of FALSE. Many of the OpenDoors door driver functions test the setting of this variable in order to determine whether or not they should send ANSI-graphics control characters. Also, if this variable contains a TRUE value, OpenDoors will display an "[ANSI]" indicator on the status line. You may change the value of this variable at any time after the first call to od_init() or any other OpenDoors door driver functions. Depending upon what BBS system your door is running under, changes to this variable may or may not result in changes to the user's ANSI setting upon return to the BBS. This variable is available under all door information file formats. -------------------------------------------------------------------------------- user_ unsigned char od_control.user_attribute; attribute This variable is a bitmap of eight flags, each of which represent individual pieces of information pertaining to the user that is currently online. These flags are as follows: +-----+------+-----------------------+ | BIT | MASK | DESCRIPTION | +-----+------+-----------------------+ | 0 | 0x01 | Is the user deleted | | 1 | 0x02 | Is screen clearing on | | 2 | 0x04 | Is "more" prompt on | | 3 | 0x08 | Is ANSI mode on | | 4 | 0x10 | User no-kill setting | | 5 | 0x20 | Transfer-priority | | 6 | 0x40 | Full screen editor | | 7 | 0x80 | Quiet mode | +-----+------+-----------------------+ For more information on using and setting bit-mapped flags, please see the entry entitled "BITMAPED FLAGS" in the glossary of this manual. Note that this variable is only available under systems that produce and EXITINFO.BBS format door information file. OpenDoors Door Toolkit Manual - Version 4.10 Page 132 -------------------------------------------------------------------------------- user_ unsigned char od_control.user_attrib2; attrib2 See the user_attrib variable for more information. This variable is like the user_attrib variable, except that it contains different information. The bit-mapped flags for the od_control.user_attrib2 variable are as follows: +-----+------+-----------------------+ | BIT | MASK | DESCRIPTION | +-----+------+-----------------------+ | 0 | 0x01 | User hot-keys setting | | 1 | 0x02 | Is AVATAR graphics on | | 2 | 0x04 | Full screen reader | | 3 | 0x08 | Hidden from userlist | +-----+------+-----------------------+ Note that this variable is only available under systems that produce an EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_avatar char od_control.user_avatar; This variable is a boolean value indicating whether or not AVATAR graphics mode is on. If AVATAR graphics is available, then many of the OpenDoors door driver functions will make use of AVATAR graphics codes for greater display speed. If AVATAR graphics mode is on, a [AVT] indicator will appear on the status line. If your door is running under a system which produces an RA 1.00+ style extended EXITINFO.BBS door information file, the user_avatar variable is set automatically. If the extended EXITINFO.BBS file is not available, this value will default to FALSE. In this case, you may wish to ask the user whether or not they wish to use AVATAR graphics, and thus set this variable yourself. -------------------------------------------------------------------------------- user char od_control.user_birthday[9]; _birthday This variable is a string, in the same format as the od_control.user_lastcall variable, which stores the date of the user's birthday, if it is available. This variable is only available under systems that produce an RA 1.00 and later style extended EXITINFO.BBS or Wildcat style DOOR.SYS file. -------------------------------------------------------------------------------- user char od_control.user_callsign[12]; _callsign OpenDoors Door Toolkit Manual - Version 4.10 Page 133 This variable is a string which contains the user's amateur radio call sign, if any. This variable is only available under systems that produce a CHAIN.TXT file. -------------------------------------------------------------------------------- user_combined unsigned char od_control.user_combinedrecord[25]; record This variable is an array of bit-mapped flags, with each flag corresponding to an individual message area. In this case, the first bit of od_control.ra_combinedrecord[0] corresponds to the first message area, the second bit to the second message area, and so on. If any given bit-flag is turned on, then the user has corresponding message area enabled for combined access, and if the bit is turned off, the user does not have the area enabled for combined access. A detailed description of the combined message access is beyond the scope of this manual. This variable is only available under systems that produce an RA 1.00 or later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_comment char od_control.user_comment[81]; This variable is a string which contains the sysop's comment about the user that is currently online. This comment may be displayed on the OpenDoors status line, if this variable is available. This variable is available under systems that produce an RA 1.00 and later style extended EXITINFO.BBS or Wildcat style DOOR.SYS file. -------------------------------------------------------------------------------- user_credit unsigned int od_control.user_credit; This variable contains the total amount of NetMail credit that the caller has left. Changes to this variable will be by the BBS when your door exits and control is returned to the BBS. This variable is only available under systems that produce an EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_ char od_control.user_dataphone[13]; dataphone This string contains the user's data or business phone number, if available. This value is only available under system that produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS and WildCat DOOR.SYS format door information files. OpenDoors Door Toolkit Manual - Version 4.10 Page 134 -------------------------------------------------------------------------------- user int od_control.user_deducted_time; _deducted _time This variable contains a signed integer value, which indicates the total amount of time that has been decuted from the user during this call. This variable is only available under systems that produce an RA 1.00 and later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_downk unsigned int od_control.user_downk; This variable contains the total kilobytes of files that the current user has downloaded from the BBS, and is available under systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or SFDOORS.DAT format door information files. -------------------------------------------------------------------------------- user unsigned int od_control.user_downlimit; _downlimit This variable contains the total number of kilobytes that the caller is permitted to download during this call. If your door allows files do be downloaded, you will probably want to compare the value of this variable to the size of any file to be transferred and the total kilobytes already downloaded, as stored in the od_control.user_todayk variable. This variable is only available under systems that produce an EXITINFO.BBS file. -------------------------------------------------------------------------------- user unsigned int od_control.user_downloads; _downloads This variable contains the total number of files that the current user has downloaded from the BBS, and is available under systems that produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat style DOOR.SYS or SFDOORS.DAT format door information files. -------------------------------------------------------------------------------- user_echo char od_control.user_echomailentered; mailentered This variable is a boolean value, indicating whether or not the user has entered new EchoMail during this call. If this variable has a value of TRUE, then EchoMail has been entered, and if it has a value of FALSE, then EchoMail has not been entered. This variable will contain a valid value only after od_init() or some OpenDoors door driver function has been called. Any changes made to this variable will be reflected within the BBS software when control is returned to the BBS. This variable is accessible only OpenDoors Door Toolkit Manual - Version 4.10 Page 135 under systems which produce an EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_error char od_control.user_error_free; _free This variable contains a boolean value indicating whether or not the user is connected to the BBS via an error free connection (eg. a V.42/MNP or similar modem protocol). This variable is only available under systems that produce an SFDOORS.DAT, Wildcat style DOOR.SYS or RA 1.00 or later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_first char od_control.user_firstcall[9]; call This variable is a string which contains the date of the user's first call, in the same format as the od_control. user_lastcall variable. This variable is only available under systems which produce an RA 1.00 and later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_ unsigned char od_control.user_flags[4]; flags The od_control.user_flags variable is an array of four sysop defined bit-mapped flags, which represent some sort of information about the user. od_control.user_flags[0] stores flags A1 - A8 in bits 0 through 7, respectively. Likewise, od_control.user_flags[1] stores flags B1 - B8, and so on. This variable is only available under systems that produce EXITINFO.BBS format door information files. -------------------------------------------------------------------------------- user_handle char od_control.user_handle[36]; This variable contains the user's alias or handle name, if any. If the user does not have and alias or handle, this variable will be blank. This variable is only available under systems that produce a CHAIN.TXT, RA 1.00 and later extended EXITINFO.BBS or Wildcat style DOOR.SYS door information file. -------------------------------------------------------------------------------- user_ char od_control.user_homephone[13]; homephone OpenDoors Door Toolkit Manual - Version 4.10 Page 136 This string contains the user's home or data phone number, if available. This value is only available under system that produce one of the following door information files: EXITINFO.BBS, PC- Board/GAP style DOOR.SYS, WildCat style DOOR.SYS or SFDOORS.DAT. -------------------------------------------------------------------------------- user unsigned char od_control.user_last_pwdchange; _last _pwdchange This variable contains the number of calls that the user has made since they last changed their password. This variable is only available under EXITINFO.BBS files. -------------------------------------------------------------------------------- user char od_control.user_lastdate[9]; _lastdate This variable is a string containing the date of the user's last call to the BBS, and should always be of the format: "MM-DD-YY" Where MM is two digits representing the number of the month of the user's call, with 1 being January, 2 being February, and so on. DD should be two digits representing the day of the month of the user's last call, beginning with 1, and MM should be the last two digits of the year of the user's last call. This variable is only available under systems that produce one of the following door information files: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP style DOOR.SYS or WildCat style DOOR.SYS files. -------------------------------------------------------------------------------- user_ unsigned int od_control.user_lastread; lastread This variable contains the number of the highest message number that the user has read, and is only available under EXITINFO.BBS format door information files. -------------------------------------------------------------------------------- user char od_control.user_lasttime[6]; _lasttime This variable contains a string representing the time of the user's last call to the BBS, and should always be of the format: "HH:MM" Where HH is two digits representing the 24-hour format hour of the user's last call, and MM is two digits representing the OpenDoors Door Toolkit Manual - Version 4.10 Page 137 minute of the user's last call. Thus, the following strings would be valid entries for this string: "00:01" (12:01 am) "03:47" (3:47 am) "18:20" (6:20 pm) This variable is only available under systems that produce an EXITINFO.BBS or Wildcat style DOOR.SYS format door information file. -------------------------------------------------------------------------------- user char od_control.user_location[26]; _location This string contains the name of the location from which the current user is calling from. This will usually be the name of the city, region (province, state, etc.) and sometimes country where the user lives. The contents of this variable are displayed on the OpenDoors status line. The value of this variable is valid after od_init() or any other OpenDoors door driver function has been called. Also, you may change the value of this variable if you wish. However, not that these changes may not immediately be reflected in the status line, and may or may not cause the setting to be changed after the user returns to the BBS. This variable is available under systems that produce one of the following door information files: DORINFO?.DEF, EXITINFO.BBS, PC- Board/GAP style DOOR.SYS, WildCat style DOOR.SYS SFDOORS.DAT and CALLINFO.BBS, but is not available under CHAIN.TXT or DoorWay style DOOR.SYS files. -------------------------------------------------------------------------------- user char od_control.caller_logindate[9]; _logindate This variable contains a string representing the date on which the current call to the BBS began. This variable is in the same format as the od_control.user_lastdate variable, described below. This variable is only available under systems which produce an EXITINFO.BBS file. -------------------------------------------------------------------------------- user long od_control.user_loginsec; _loginsec This variable contains the user's security at login, and can be used to detect changes by the sysop or other programs during the course of the call, by comparing it's value with the od_control.user_security variable. This variable is only available under systems which produce an EXITINFO.BBS file. OpenDoors Door Toolkit Manual - Version 4.10 Page 138 -------------------------------------------------------------------------------- user char od_control.user_logintime[6]; _logintime This variable contains a string representing the time of day at which the current call to the BBS began. This variable is in the same format as the od_control.user_lasttime variable, which is also described below. This variable is available under systems which produce an EXITINFO.BBS, a Wildcat style DOOR.SYS, or an SFDOORS.DAT file. -------------------------------------------------------------------------------- user char od_control.user_logonpassword[16]; _logon password This variable is a string which contains the user's password at the time at which the current call to the BBS began. This variable can be used to detect changes by the sysop or other programs to the user's password, which have taken place during the course of the call. In order to detect such changes, simply compare the contents of this string with the contents of the od_control.user_password variable. This variable is only available under systems which produce an EXITINFO.BBS format door information file. -------------------------------------------------------------------------------- user char od_control.user_menustack[50][9]; _menustack This variable is an array of 50 strings, containing the stack of BBS menus that have been executed, and is used to record the current position of the user within the BBS's menu system. Each string contains just the base portion of the filename of the menu, without the extension. The od_control.ra_menustackpointer variable points to the top of the menu stack. However, a complete discussion of the menu stack is beyond the scope of this manual. This variable is only available under systems that produce an RA 1.00 and later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user unsigned char od_control.user_menustackpointer; _menustack pointer This variable points to the top of the current menu stack. For more information on the menu stack, please refer to the od_control.ra_menustack variable, above. This variable is only available under systems that produce an RA 1.00 and later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user unsigned int od_control.user_messages; _messages OpenDoors Door Toolkit Manual - Version 4.10 Page 139 This variable contains a value representing the total number of messages that have been written by the user, and is available under EXITINFO.BBS or Wildcat style DOOR.SYS format door information files. -------------------------------------------------------------------------------- user_name char od_control.user_name[36]; This string contains the name of the user that is currently on- line, and is used by OpenDoors to display the current user name on the status line, and will most likely be used by your door for differentiating among different users. In most cases, you should probably not change the value of this variable, as a user's name does not usually change, and doing so could results in problems when returning to some BBS systems. For an example of using this variable, see the EZVote example program. This variable is available under all BBS systems. -------------------------------------------------------------------------------- user_net_ unsigned int od_control.user_net_credit; credit This variable contains the amount of NetMail credit that the current user has to his or her name. This variable is only available under systems that produce an EXITINFO.BBS file. Note that if you wish to change the value of the user's remaining NetMail credit, you should use the od_control. user_credit variable, instead of this variable. -------------------------------------------------------------------------------- user_net char od_control.user_netmailentered; mailentered This variable is a boolean value, indicating whether or not the user has entered new NetMail or GroupMail during this call. If this variable has a value of TRUE, then NetMail/GroupMail has been entered, and if it has a value of FALSE, then NetMail/GroupMail has not been entered. This variable will contain a valid value only after od_init() or some OpenDoors door driver function has been called. Any changes made to this variable will be reflected within the BBS software when control is returned to the BBS. This variable is accessible only under systems which produce an EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_num unsigned int od_control.user_num; This variable contains the number of the user's record in the user database file, where 0 is the first record. This can be OpenDoors Door Toolkit Manual - Version 4.10 Page 140 useful for changing user settings that are not re-read by the BBS, such as the user's phone number or security level which might be altered by a call back verification door. However, the value of this variable itself should not be altered. This variable is available under systems which produce any of the following door information file formats: CHAIN.TXT, PC-Board/GAP style DOOR.SYS, Wildcat style DOOR.SYS SFDOORS.DAT and EXITINFO.BBS. -------------------------------------------------------------------------------- user_ unsigned int od_control.user_numcalls; numcalls This variable contains the total number of calls that the current user has placed to the BBS, and is available under systems that produce EXITINFO.BBS or PC-Board/GAP and Wildcat style DOOR.SYS door information files. -------------------------------------------------------------------------------- user unsigned int od_control.user_numpages; _numpages The value of this variable contains the total number of times that the user has paged the sysop, and can be used to limit the number of times that the user is permitted to page the sysop. OpenDoors increments this variable every time that the user pages the sysop, via the od_page() function. This variable is used with all types of door information files. However, this variable will only reflect the value within the BBS if an EXITINFO.BBS file is produced. Otherwise, the variable will only contain the number of times that the user has paged within the door, but not the total number of times the user has paged. Under EXITINFO.BBS systems, changes to the value of this variable will be reflected within the BBS upon return by the DOOR. -------------------------------------------------------------------------------- user char od_control.user_password[16]; _password This variable contains the user's password for accessing the BBS. OpenDoors does not use this value itself. This variable will contain a valid value only after od_init() or some OpenDoors door driver function has been called. You may change the value of this variable. Note, however, that changes in this variable may or may not cause the setting to be changed when control returns to the BBS - this will depend upon the particular BBS system your door is running under. This variable is only available under systems that produce one of the following door information files: EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS, SFDOORS.DAT, and CALLINFO.BBS. OpenDoors Door Toolkit Manual - Version 4.10 Page 141 -------------------------------------------------------------------------------- user_pending unsigned int od_control.user_pending; This variable represents the total value of NetMail that has been written by the current user, but not yet exported from the message base. This variable is only available under systems that produce an EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user_reason char od_control.user_reasonforchat[78]; forchat This variable is a string, containing the reason for which the user wishes to chat with the sysop, as they entered at the time of paging the sysop. This variable will contain an empty string if the user has not paged the sysop, or if the reason the user wishes to chat is unknown. See also the od_control.user_wantchat variable. This variable is available under all BBS systems, regardless of what style of door information file they produce. However, this variable will not be passed between the door and BBS, and thus the user's reason for chat within the door will not necessarily correspond to their reason for chat outside the door. -------------------------------------------------------------------------------- user unsigned int od_control.user_screen_length; _screen _length This value of this variable represents the total number of lines that can be displayed on the user's screen at once, and is usually either 24 or 25. You may wish to make use of this variable to allow your door to pause the display of long pieces of text after every screen length, in order to allow the user to read this information before it passes off of their screen. In this case, you would simply maintain a counter of the total number of lines displayed, and when this value reaches one less than the length of the user screen, display a prompt asking the user to whether or not they wish to continue. This variable is set to the user's setting within the BBS under systems that produce any of the following door information file formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS and CALLINFO.BBS files. This variable is used by the OpenDoors door driver function, od_list_files(). If this variable contains a valid value, OpenDoors will pause the listing of files after every screen, and give the user the option of continuing, aborting, or disabling the "Continue?" prompt for the rest of the file listing. Thus, if you are using the od_list_files() under a system that does not produce one of the door information files listed above, you may wish to obtain the user's screen length from the user themselves. If the screen length is not available from the particular type of door information file that is found, and you do not set this OpenDoors Door Toolkit Manual - Version 4.10 Page 142 value yourself, this variable will default to 23. If you are going to set the value of this variable yourself, you should do so after having called od_init() or some OpenDoors door driver function. -------------------------------------------------------------------------------- user_ unsigned char od_control.user_screenwidth; screenwidth This variable contains a value representing the width of the user's screen, and will most often be equal to 80. This variable is only available under systems that produce a CHAIN.TXT or RA 1.00 and later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user unsigned int od_control.user_security; _security This variable contains a numerical value representing the user's security access level on the BBS. You may wish to use this value to determine wether or not the current user of your door should have access to certain sysop-only functions. In this case, you may wish to have a configuration file used by your door, in which the sysop may define the minimum security level for sysop access. You would then be able to compare this configuration setting to the security level stored in this variable, in order to determine whether or not sysop function should be available. An alternative method, used by the EZVote sample door, of determining whether or not the current user is the sysop is to compare the user's name with the value of the od_control.sysop_name variable. This method has the advantage of not requiring a configuration program, but the disadvantage that the door will not function correctly under all BBS systems, as the od_control.sysop_name variable is not available under all BBS systems. The od_control.user_security variable is available under BBS systems that produce any of the following door information file formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS, SFDOORS.DAT or CALLINFO.BBS. -------------------------------------------------------------------------------- user_sex char od_control.user_sex; This variable contains a single character representing the gender of the user that is currently online. This variable will contain an upper-case 'F' if the user is female, and an upper-case 'M' if the user is male. This variable is only available under systems that produce a CHAIN.TXT file. -------------------------------------------------------------------------------- OpenDoors Door Toolkit Manual - Version 4.10 Page 143 user_subdate char od_control.user_subdate[9]; This variable is a string, in the same format as the od_control.user_lastdate variable, which stores the date of expiry of the user's subscription to the BBS. This variable is only available under systems which produce a PC-Board/GAP and Wildcat style DOOR.SYS or RA 1.00 and later style extended EXITINFO.BBS door information file. -------------------------------------------------------------------------------- user int od_control.user_timelimit; _timelimit This variable contains the amount of time, in minutes, that the user has left in the door. Note that this value may or may not be equal to the total amount of time that the user has left on the BBS, depending upon whether the BBS or a third-party door manager program only allows a limited amount of time in this door. This variable contains a valid value after od_init() or some OpenDoors door driver function has been called. OpenDoors uses this variable to keep track of how much time the user has left in the door, and will automatically warn the user when nearly all of his or her time has been used up. OpenDoors will also force the user out of the door when their time in the door has expired. OpenDoors automatically subtracts one minute from this variable every minute that OpenDoors is active, unless chat mode has been activated (in which case the user's time will freeze), and also adjusts the value of this variable when the sysop uses the time adjustment function keys. Hence, you will not normally have any need to alter the value of this variable yourself. However, there may be some cases in which you wish to subtract a penalty or add a bonus to the user's time, such as in a "timebank" door or a door game that permits the user to "gamble time". Depending on which BBS system your door is running under, the value of this variable may or may not effect the user's time left upon return to the BBS. The BBS system will either reset the user's time to the value re-written to the door information file (this variable), or will always subtract the amount of time spent in the door from the user's remaining time. Other BBS systems, such as Apex, give the sysop an option of which means should be used. This variable is available under all door information file formats. -------------------------------------------------------------------------------- user unsigned int od_control.user_todayk; _todayk This variable contains the total kilobytes of files that the current user has downloaded from the BBS during the current day, and is available under systems that produce EXITINFO.BBS, PC- OpenDoors Door Toolkit Manual - Version 4.10 Page 144 Board/GAP and Wildcat style DOOR.SYS, or SFDOORS.DAT format door information files. -------------------------------------------------------------------------------- user_upk unsigned int od_control.user_upk; This variable contains the total kilobytes of files that the current user has uploaded to the BBS, and is available under systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or SFDOORS.DAT files. -------------------------------------------------------------------------------- user_uploads unsigned int od_control.user_uploads; This variable contains the total number of files that the current user has uploaded to the BBS, and is available under systems that produce EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS, or SFDOORS.DAT format door information files. -------------------------------------------------------------------------------- user char od_control.user_wantchat; _wantchat This variable is a boolean value which indicates whether or not the user wishes to chat with the sysop (ie, the user has paged the sysop, but has yet to receive a chat with the sysop). This variable is used under all door information file formats. However, changes to this variable are only reflected on the BBS when the door is running under a system that produces an EXITINFO.BBS door information file. This variable is automatically turned on (ie., set to TRUE), when the user begins to page the sysop for chat, within the od_page() function, and is automatically turned off (ie., set to FALSE), when the sysop breaks in for chat via the chat function key. Also, setting this variable to TRUE will turn on the flashing want-chat indicator on the OpenDoors status line. -------------------------------------------------------------------------------- user unsigned int od_control.user_xi_record; _xi_record This variable contains the number of the user's record in the USERXI.BBS file, if any. This variable is only available under system that produce a Remote Access 1.00 and later style extended door information file. OpenDoors Door Toolkit Manual - Version 4.10 Page 145 CONTROL STRUCTURE - DOOR SETTINGS -------------------------------------------------------------------------------- This section deals with those variables in the OpenDoors control structure which reflect the current door settings. These variables are as follows: od_okaytopage Controls whether the user is currently permitted to page the sysop. od_pageendmin End of valid paging hours. od_pagestartmin Start of valid paging hours. od_user_keyboard_on Controls whether OpenDoors will currently accept input from the remote user's keyboard. sysop_next Indicates whether or not the sysop has reserved use of the system after the current calls. -------------------------------------------------------------------------------- od char od_control.od_okaytopage; _okaytopage This variable allows you to control whether or not the user is currently permitted to page the sysop via the od_page() function. This variable contains one of three values. A value equal to TRUE indicates that paging is currently permitted. A value equal to FALSE indicates that paging is not current permitted. A value of MAYBE indicates that the od_page() function should check the values of the od_pagestartmin and od_pageendmin variables in order to determine whether or not paging should be permitted. If you wish to always permit sysop paging, you can simply leave this variable set at its default value of TRUE. On the other hand, you may wish to allow the sysop to configure paging hours - either within your own configuration program, or within the BBS's configuration. In this case, you can either turn paging on and off manually by changing the value of this variable, or by setting this variable to MAYBE, and using the od_pagestartmin and od_pageendmin variables. These two variables are described below. For more information on the od_page() function itself, see page 92. -------------------------------------------------------------------------------- od unsigned int od_control.od_pageendmin; _pageendmin OpenDoors Door Toolkit Manual - Version 4.10 Page 146 This variable can be used to set the beginning of valid sysop paging hours within the od_page() function. If the od_control.od_okaytopage variable (which is described above) is set to MAYBE, then OpenDoors will check the value of this variable prior to paging the sysop via the od_page() function. This variable should contain the time at which the valid sysop paging hours end, represented as the a number of minutes since midnight. For more information on the od_page() function itself, see page 92. -------------------------------------------------------------------------------- od unsigned int od_control.od_pagestartmin; _pagestartmin This variable can be used to set the beginning of valid sysop paging hours within the od_page() function. If the od_control.od_okaytopage variable (which is described above) is set to MAYBE, then OpenDoors will check the value of this variable prior to paging the sysop via the od_page() function. This variable should contain the time at which the valid sysop paging hours begin, represented as the a number of minutes since midnight. For more information on the od_page() function itself, see page 92. -------------------------------------------------------------------------------- od_user char od_control.od_user_keyboard_on; _keyboard_on This variable is a boolean value, indicating whether OpenDoors will currently accept input from a remote user. OpenDoors provides a function key (usually [ALT]-[K], unless you have changed the default), which will allow the sysop to temporarily prevent the user from having any control over the door. When the sysop activates this feature, a flashing [Keyboard-Off] indicator will appear on the status line, and this variable will be set to FALSE. When the sysop presses the [ALT]-[K] combination a second time, to toggle the user's keyboard back on, the flashing indicator will disappear, and this variable will be set back to TRUE. -------------------------------------------------------------------------------- sysop_next char od_control.sysop_next; This variable is a boolean value, indicating whether or not the "sysop next" feature has been activated. The "sysop next" feature, which reserves the system for the sysop after the call has ended, can be toggled on and off within OpenDoors by use of a function key (Alt-N by default). Also, when the "sysop next" feature has been activated, an indicator will appear on the OpenDoors status line. This variable is only available under systems that produce an SFDOORS.DAT or RA 1.00 and later style extended EXITINFO.BBS door information file. For more information OpenDoors Door Toolkit Manual - Version 4.10 Page 147 on testing the type of door information file available, please see page 125. OpenDoors Door Toolkit Manual - Version 4.10 Page 148 CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION -------------------------------------------------------------------------------- The OpenDoors control structure provides many variables which allow you to customize OpenDoor's behaviour and appearance. These customization variables fit into one of the following categories: General Behaviour Customization Variables Sysop Function Keys Customization Variables Colour Customization Variables Language-Specific Prompts Customization Variables This section deals with those variables that fit into the first category, "General Behaviour Customization Variables". The other categories are dealt with in the following sections of this chapter. Below is a brief overview of the variables grouped into this section of the OpenDoors control structure. Following the overview is a detailed description of each of these variables. od_box_chars Array of characters used by the od_draw_box() function od_before_exit Function to call prior to exiting od_cafter_chat Function to call after sysop chat od_cafter_shell Function to call after DOS shell od_cbefore_chat Function to call prior to sysop chat od_cbefore_shell Function to call prior to DOS shell od_clear_on_exit Controls whether the screen is cleared upon door exit od_colour_delimiter Indicates what character should delimit imbedded colour codes for the od_printf() function. od_disable Disable OpenDoors activities such as reading door information file and monitoring carrier detect / remaining time od_inactivity Controls user inactivity timeout od_last_input Indicates whether the last input came from the remote user (==0) or the local sysop (==1). OpenDoors Door Toolkit Manual - Version 4.10 Page 149 od_list_pause Controls whether or not the user may pause display within the od_list_files() and od_send_file() functions by using the [P] key. od_list_stop Controls whether or not the user may terminate display within the od_list_files() and od_send_file() functions using [S], [CTRL]-[K], etc. od_logfile_disable Prevents the logfile from being opened when od_log_open() is called. od_logfile_name Contains the filename and possibly path of the logfile. od_maxtime Indicates the maximum length of time any user is permitted to use the door. od_maxtime_deduction Indicates the amount of time that has temporarily been taken away from the user's remaining time, as a result of the maximum door time settting. od_nocopyright Prevents OpenDoors from displaying it's name and version number when a door program begins execution. od_noexit Prevents OpenDoors from exiting when the od_exit() function is called od_page_len Controls length of the sysop page beep. od_page_pausing Enables or disables page pausing in od_send_file(), od_hotkey_menu() and od_list_files() functions. od_page_startmin Indicates the time of day at which sysop paging is first enabled. od_page_endmin Indicates the time of day at which sysop paging is disabled. od_spawn_freeze_time Indicates whether the user's time remaining continues to be decreased during the execution of the od_spawn...() functions (FALSE), or if the timer should be "frozen" (TRUE). od_swapping_disable Disables swapping during DOS shell and od_spawn...() functions od_swapping_noems Prevents swapping form being done to EMS expanded memory. OpenDoors Door Toolkit Manual - Version 4.10 Page 150 od_swapping_path Location where disk swap file should be created. od_status_on Controls whether the status line sub- system is active -------------------------------------------------------------------------------- od_box char od_control.od_box_chars[6]; _chars This variable allows you to specify which character the od_draw_box() function uses in drawing the boarder of a window. The elements of this array are as follows: od_control.od_box_chars[0] - Upper left corner of box od_control.od_box_chars[1] - Horizontal line od_control.od_box_chars[2] - Upper right corner of box od_control.od_box_chars[3] - Vertical line od_control.od_box_chars[4] - Lower left corner of box od_control.od_box_chars[5] - Lower right corner of box -------------------------------------------------------------------------------- od_before void (*od_control.od_before_exit)(); _exit This variable contains a pointer to a function which OpenDoors should call prior to exiting, or NULL if you do not wish to have any function called at exit time. For an example of the use of this variable, see the description of the EZVote demo door, which begins on page 25. -------------------------------------------------------------------------------- od_cafter void (*od_control.od_cafter_chat)(); _chat The function pointed to by this variable will be called after sysop chat mode has ended. This may be useful for allowing you to save the user's screen contents prior to chat, and restoring the afterwards. If this variable contains its default value of NULL, no function will be called. To alter the string of text which is displayed after sysop chat, see the od_control.od_after_chat variable, which is described in the section on the prompts customization portion of the control structure. -------------------------------------------------------------------------------- od_cafter void (*od_control.od_cafter_shell)(); _shell The function pointed to by this variable will be called after the sysop has returned from a DOS shell. If this variable contains its default value of NULL, no function will be called. To alter OpenDoors Door Toolkit Manual - Version 4.10 Page 151 the string of text which is displayed after a DOS shell, see the od_control.od_after_shell variable, which is described in the section on the prompts customization portion of the control structure. -------------------------------------------------------------------------------- od_cbefore void (*od_control.od_cbefore_chat)(); _chat The function pointed to by this variable will be called prior to entering sysop chat mode. This may be useful for allowing you to save the user's screen contents prior to chat, and restoring the afterwards. If this variable contains its default value of NULL, no function will be called. To alter the string of text which is displayed prior to sysop chat, see the od_control.od_before_chat variable, which is described in the section on the prompts customization portion of the control structure. -------------------------------------------------------------------------------- od_cbefore void (*od_control.od_cbefore_shell)(); _shell The function pointed to by this variable will be called prior to executing a sysop DOS shell. If this variable contains its default value of NULL, no function will be called. To alter the string of text which is displayed before a DOS shell, see the od_control.od_before_shell variable, which is described in the section on the prompts customization portion of the control structure. -------------------------------------------------------------------------------- od_clear char od_control.od_clear_on_exit; _on_exit This variable contains a boolean value, which indicates whether or not you wish OpenDoors to clear the screen prior to exiting. This variable defaults to a value of TRUE, which causes the screen to be cleared when a door program exits. However, you may wish to set this variable to a value of FALSE, which will cause the contents of the screen to remain unchanged when the door exits. While setting this variable to FALSE will probably result in a messy display if the door is to return control to a batch file, if the door returns directly to the BBS, it will result in a smoother transition from the door back to the BBS (as the sysop is not left with a blank screen). If your door has a configuration file or configuration program, you may wish to have an option which will allow the individual sysop to determine whether or not the screen should be cleared when the door exits. -------------------------------------------------------------------------------- od_colour char od_control.od_colour_delimiter; OpenDoors Door Toolkit Manual - Version 4.10 Page 152 _delimiter This variable sets the character that is used to delimit colour codes in the od_printf() function, and defaults to the back-quote (`) character. If you wish to be able to display the back-quote (`) character using the od_printf() function, and thus wish to use a different character to delimit colour codes in the od_printf() function, simply set this variable to the alternative character you wish to use. If you wish to disable the imbedded colour codes feature of the od_printf() function, simply set this variable to a value of zero. For more information on od_printf() imbedded colour codes, see the description of the od_printf() function, which begins on page 93. -------------------------------------------------------------------------------- od_disable char od_control.od_disable; This variable is a bit-mapped flag which can be used to disable certain OpenDoors features which are normally active, in order to allow for maximum customization of OpenDoors. Each bit of this variable represents a different feature that can be disabled. To DISABLE a feature, you set the bit that corresponds to the particular feature. To ENABLE the feature, the bit is reset. Each bit is represented by a keyword, as follows: DIS_INFOFILE - Setting the DIS_INFOFILE bit of the od_control.od_disable variable allows you to prevent OpenDoors from reading or re-writing a door information file. If you wish to disable OpenDoors' reading of the door information file, you must do so prior to calling od_init() or any other OpenDoors door-driver functions. At the same time, you must also manually set any required variables that are normally set by the information obtained from the door information file, such as the comm port number, baud rate, user name, and so on. You may wish to disable reading of the door information file in a number of cases. For example, you may wish to manually read another format of door information file not supported by OpenDoors, or to obtain the necessary door information from your program's command line. Also, if you are using OpenDoors to write a non-door communications program, such as a terminal program, you want to prevent OpenDoors from attempting to read a door information file on startup. DIS_CARRIERDETECT - Setting this bit allows you to prevent OpenDoors from exiting when it the carrier detect signal from the modem disappears. This bit may be set or rest at any time. If you use this bit to disable OpenDoors' carrier detection, you will probably want to monitor the state of the carrier detect signal yourself, using the od_carrier() function, which is described on page 34. DIS_TIMEOUT - This flag allows you to prevent OpenDoors from exiting when the user runs out of time. As with the DIS_CARRIERDETECT flag, you may set or reset this bit at any OpenDoors Door Toolkit Manual - Version 4.10 Page 153 time. You will most often want to use this setting when writing a non-door program, which you would not want to have exit after a particular amount of time has elapsed. Be sure that you do not confuse this flag with the user's inactivity timeout. To disable the inactivity timeout, set the do_control.od_inactivity variable to 0. DIS_LOCAL_OVERRIDE - This variable affects OpenDoors' behaviour when a locked BPS rate is specified in the configuration file, and another BPS rate is specified in the door information file. By default, OpenDoors will initialize the modem at the BPS rate specified in the congiruation file, unless the BPS rate specified in the door information file is 0. In this case, the 0 BPS rate is used to indicate that the door is operating in local mode, and will override the BPS rate specified in the configuration file. Setting this flag disables the local mode override, causing the modem to always be initialized at the locked BPS rate, even when the door information file specifies that local mode should be used. Note that in order to disable the OpenDoors status line, the od_control.od_status_on variable is used, instead of the od_disable variable. You may also disable the user's inactivity timeout by setting the od_control.od_inactivity variable to 0. The od_control.od_status_on variable is described later in this section. Also note that you do not need to set this variable in any program that only uses the BBS interface module of OpenDoors, as the od_init() function is only called in programs which use the door driver module. -------------------------------------------------------------------------------- od unsigned int od_control.od_inactivity; _inactivity The OpenDoors door driver has a built in user-inactivity timeout facility, which will automatically disconnect a user who appears .to be sleeping at the keyboard. If the user has not pressed any keys on their keyboard for to great a length of time, they will be warned that they are about to be disconnected due to inactivity. If they still do not respond after another few seconds, OpenDoors will automatically disconnect the user and return control to the BBS software. The od_control.od_inactivity variable allows you to set the maximum length of time, in seconds, after which the user will be disconnected for inactivity. This variable defaults to a value of 200 seconds. You may disable OpenDoors' inactivity timeout altogether, by setting the od_control.od_inactivity variable to a value of 0. -------------------------------------------------------------------------------- od_last char od_control.od_last_input; _input OpenDoors Door Toolkit Manual - Version 4.10 Page 154 Indicates whether the last key retrieved using the od_get_key() function originated from the remote user, or the local sysop. If the input originated from the remote, this variable is set to 0. If the input originated from the local keyboard, this variables is set to 1. -------------------------------------------------------------------------------- od_list char od_control.od_list_pause; _pause This variable contains a boolean value, which allows you to control whether or not the user may pause displaying within the od_list_files() and od_send_file() function. When this variable is set to its default value of TRUE, the user will be able to pause the display by pressing the [P] key, and resume display by pressing any other key. However, the pause feature may be disabled by setting this variable to FALSE. -------------------------------------------------------------------------------- od_list char od_control.od_list_stop; _stop This variable contains a boolean value, which allows you to control whether or not the user may abort displaying within the od_list_files() and od_send_file() function. When this variable is set to its default value of TRUE, the user will be able to pause the display by pressing the [S], [CTRL]-[K] or [CTRL]-[C] keys. However, the stop feature may be disabled by setting this variable to FALSE. -------------------------------------------------------------------------------- od_logfile char od_control.od_logfile_disable; _disable This variable defaults to the value of FALSE, unless the "LogfileDisable" option is specified in the configuration file, in which case the variable will be set to TRUE. If this variable is set to TRUE, OpenDoors will not write to a logfile, even if the od_log_open() function is called. -------------------------------------------------------------------------------- od_logfile char od_control.od_logfile_name[80]; _name This variable specifies the filename, and optionally the full path of the logfile where OpenDoors should perform logging. This variable only has an effect when set prior to calling od_log_open() or od_log_write(). If the log file name is specified in the configuration file, that name will be stored in this variable. If you do not set this variable, and the log file name is not specified in the configuration file, the default name OpenDoors Door Toolkit Manual - Version 4.10 Page 155 "DOOR.LOG" will be used. If you wish to set this variable, you should do so prior to calling the od_init_with_config() function. -------------------------------------------------------------------------------- od_ unsigned int od_control.od_maxtime; maxtime This variable specifies the maximum length of time that any user is permitted to use the door, and is normally set from a configuration file option. If upon entering the door, the user's time remaining online is greater than the od_maxtime setting, their time remaining is temporarily decreased to the maximum value. Then upon exit of the door, the number of subtracted minutes is added back onto the user's remaining time. If the user's remaining time is less than this value, then the setting has no effect. A value of 0 disables the maximum time setting altogether. -------------------------------------------------------------------------------- od_maxtime int od_control.od_maxtime_deduction; _deduction This variable store the amount of time that should be added to the user's time upon exit of the door, as a result of the maximum time deduction, described above. If the maximum time feature is not used, this variable will be given a value of 0. -------------------------------------------------------------------------------- od_ char od_control.od_nocopyright; nocopyright This variable is a boolean value that allows you to prevent OpenDoors from displaying its name, version number and the copyright notice when an OpenDoors door program begins execution. When this variable is set to TRUE, and OpenDoors is running in registered mode, the OpenDoors name display will be disabled. If you decide that you must use this variable to remove the version and name display, I would appreciate it if you were to place a notice elsewhere indicating that your door is written with OpenDoors. -------------------------------------------------------------------------------- od_noexit char od_control.od_noexit; This variable contains a boolean value, which allows you to prevent OpenDoors from exiting when shutting down. This may be useful when you want to have your program to do more processing after you have called the od_exit() function, or if you do not wish to have your program exit automatically when the user drops carrier. Normally, this variable will default to a value of FALSE, indicating that OpenDoors will exit normally when the OpenDoors Door Toolkit Manual - Version 4.10 Page 156 od_exit() function is called. However, you may optionally set this variable to TRUE after od_init() or some OpenDoors door driver function has been called. In this case, when the od_exit() function is called, either by your program manually, or automatically by OpenDoors in response to the user dropping carrier, etc., OpenDoors will not exit. However, the normal operations of closing the FOSSIL driver and re-writing the door information file will be carried out. If you set the od_noexit variable to TRUE, it will be up to your program to detect the closing of the door driver by the od_exit() function. The best way of doing this is to provide a function which is to be called at the beginning of the od_exit() function, by setting the od_control.od_before_exit pointer, described above. -------------------------------------------------------------------------------- od_page char od_control.od_page_len; _len This variable allows you to control the length, in seconds, of the sysop page beep produced when the user pages the sysop via the od_page() function. -------------------------------------------------------------------------------- od_page char od_control.od_page_pausing; _pausing This variable contains a Boolean value that indicates whether or not page pausing is enabled in the od_send_file(), od_hotkey_menu() and od_list_files() functions. The default value of TRUE indicates that page pausing is enabled. A value of FALSE indicates that page pausing is disabled. -------------------------------------------------------------------------------- od_page int od_control.od_pagestartmin; startmin int od_control.od_pageendmin; od_page These variables indicate the start and end times for sysop endmin paging, expressed as the number of minutes past midnight. Sysop paging will be available through the od_page() function from the start time, up to but not including the end time. -------------------------------------------------------------------------------- od_spawn char od_control.od_spawn_freeze_time; _freeze_time This variable is a boolean value which indicates whether or not the user's time remaining is frozen during the execution of one of the od_spawn...() functions. If this variable is set to TRUE, the user's time remaining will not decrease during the time that the od_spawn...() function is executing. However, if this OpenDoors Door Toolkit Manual - Version 4.10 Page 157 variable is set to FALSE, the user's time remaining will continue to be subtracted during the execution of the od_spawn...() function. The default value of this variable is FALSE. -------------------------------------------------------------------------------- od_swapping char od_control.od_swapping_disable; _disable This variable is a boolean value which specifies whether or not OpenDoors will attempt to swap itself and your entire door upon DOS shell or a call to one of the od_spawn...() functions. This variable defaults to FALSE. If set to TRUE, OpenDoors will not attempt to perform swapping activities. -------------------------------------------------------------------------------- od_swapping char od_control.od_swapping_noems; _noems This variable is a boolean value which can be used to prevent OpenDoors from swapping to EMS memory. This variable defaults to the value FALSE. If set to TRUE, OpenDoors will not attempt to use EMS memory for swapping, and will only swap to disk. -------------------------------------------------------------------------------- od_swapping char od_control.od_swapping_path; _path This variable specifies the drive and directory where OpenDoors should create its disk swapping file, if applicable. More than one path can be specified, by seperating the paths with a semi- colon (;) character. -------------------------------------------------------------------------------- od_status char od_control.od_status_on; _on This variable is a boolean value which allows your program to completely disable the OpenDoors status line. The variable defaults to a value of TRUE, which causes the OpenDoors status line to be controllable by function keys, displayed and updated as it would normally be. However, if this variable is set to FALSE, then OpenDoors will not update the status line, nor will it allow the status line to be re-displayed as a result of one of the status line ([F1] through [F10]) keys being pressed. When you change the value of this variable from FALSE to TRUE, OpenDoors will automatically redisplay the status line. Note, however, that the status line isn't automatically removed when the value of this variable is changed from TRUE to FALSE. In order to erase the status line after resetting the value of this variable, you should reset the output window to the full screen, by calling the function window(1,1,25,80). Then manually erase the old status OpenDoors Door Toolkit Manual - Version 4.10 Page 158 line either by clearing the bottom two lines of the screen, or by clearing the entire screen. It is important that you do not confuse the use of this variable with the od_set_statusline() function, which is described on page 113. When the status line is enabled, the sysop can change which status line, if any, is being displayed, using the function keys [F1] through [F10]. The od_set_statusline() function allows your program to make the same changes to the status line setting which the sysop can make by pressing one of the function keys. The status line can be removed from the screen, allowing a full 25 lines of text to be displayed, by pressing the [F10] key, or by making the appropriate call to the od_set_statusline() function. Note, however, than when this is done, the status line is still enabled, and can be turned on by pressing any of the other function keys. On the other hand, if the status line is turned off using this variable (od_control.od_status_on), the status line sub-system will be disabled, and pressing function keys will not "bring it back". So, if you were writing a program where a status line would be undesirable - such as a non-door communications program, you would use the od_control.od_status_on variable. On the other hand, if you only wanted to temporarily remove the status line - say in order that all 25 lines of a door program's output could be viewed - while still allowing the status line to be turned on with the sysop function keys, you would use the od_set_statusline() function. For more information on the od_set_statusline() function, see page 113. OpenDoors Door Toolkit Manual - Version 4.10 Page 159 CONTROL STRUCTURE - FUNCTION KEYS -------------------------------------------------------------------------------- Within OpenDoors, as with most BBS software and doors, the sysop has access to a number of function keys, which permits the sysop to carry out various functions such as entering chat mode, hanging up on the user, shelling to DOS, and so on. (For more information on these function key, see page 26.) The variables in this section allow you to customize which keys carry out the standard sysop functions, allowing you to customize your door's interface to mimic any BBS package. By default, OpenDoors emulates the function keys used by the Remote Access BBS package, but you may choose, for example, to have your door use the key combinations used by PC-Board. In addition, OpenDoors provides an interface which allows you to add your own function keys which will be accepted by the door. This could allow you to add additional features, such as giving the sysop access to a status screen which displays information about your door. Many of the variables in this section are unsigned ints, which represent a sysop key combination such as [ALT]-[H], [F8], or [CTRL]-[P]. These values are in the same format as is returned by the Turbo C(++) / Borland C++ bioskey() function. The high-order byte represents the scan code of the key, and the low-order byte represents the ASCII value, if any, of the key combination. Note that a complete tutorial on these key codes is beyond the scope of this manual. For more information on these key codes, you should see the documentation on the bioskey() function, which accompanies your compiler. If you wish to determine the key code which corresponds to a particular keystroke, there is a simple program, listed below, which you can compile and use. This program will simply display the key code for any key pressed, until you press the [ESCape] key. So, in order to determine the code for [SHIFT]-[F8], you would simply run this program, press the [SHIFT]-[F8] key combination on your keyboard, and record the value displayed on your screen. #include <bios.h> int main(int argc, char *agv[]) { register unsigned int keystroke=0; while((keystroke&0xff)!=27) { keystroke=bioskey(0); if(keystroke!=0) { printf("You pressed %u\n",keystroke); } } OpenDoors Door Toolkit Manual - Version 4.10 Page 160 } -------------------------------------------------------------------------------- BUILT IN These variable allow you to customize the sysop function keys FUNCTION which control functions such as hanging up on the user, shelling KEYS to DOS, and so on. All of these variable will be assigned default values, which correspond to the same function keys used by the RemoteAccess BBS package. However, you may change the values of these variables in order to customize the key combinations which carry out these functions in your own door program. Remember that if you wish to change the value of any of these variables, you must do so after having called od_init() or some OpenDoors door driver function. Each of these variables contain a scan-code / ASCII-code combination representing a keystroke, as is described above. These variables are as follows: +---------------------+-----------------------------------------+ | VARIABLE | CORRESPONDING FUNCTION | +---------------------+-----------------------------------------+ | od_control. | Enter sysop chat mode | | key_chat | (Normally [ALT]-[C] | | | | | od_control. | Invoke sysop DOS shell | | key_dosshell | (Normally [ALT]-[J] | | | | | od_control. | Return to the BBS without hanging up | | key_drop2bbs | (Normally [ALT]-[D]) | | | | | od_control. | Hangup on the user | | key_hangup | (Normally [ALT]-[H]) | | | | | od_control. | Turn off the user's keyboard | | key_keyboardoff | (Normally [ALT]-[K]) | | | | | od_control. | Decreases the user's remaining time | | key_lesstime | (Normally [DOWN-ARROW]) | | | | | od_control. | Lock the user out of the BBS system | | key_lockout | (Normally [ALT]-[L]) | | | | | od_control. | Increases the user's remaining time | | key_moretime | (Normally [UP-ARROW]) | | | | | od_control. | Array of eight function keys to set the | | key_status[8] | current status line. | | | (Normally [F1], [F2], [F3], [F4], [F5], | | | [F6], [F9], [F10]) | | | | | od_control. | "Sysop next" toggle key | | key_sysopnext | (Normally [ALT]-[N]) | +---------------------+-----------------------------------------+ -------------------------------------------------------------------------------- OpenDoors Door Toolkit Manual - Version 4.10 Page 161 CUSTOM In addition to the sysop function keys built into OpenDoors, you FUNCTION may wish to add your own function keys to your door. For example, KEYS you might wish to have the [ALT]-[Z] combination display a window of information about your door, or you may wish to add your own user editor to your door, accessible through the [ALT]-[E] combination. The three variables: unsigned char od_control.od_num_keys; unsigned int od_control.od_hot_key[16]; unsigned int od_control.od_last_hot; provide your program with an interface to add your own sysop function keys (not accessible by the remote user) to the door you have written. OpenDoors allows you to define up to sixteen custom sysop function keys. The key codes (as described at the beginning of this section) are stored in the od_control.od_hot_key[] array, and the od_control.od_num_keys variable records the number of keys which have been defined. The od_control.od_num_keys variable defaults to a value of 0. So, in order to add your own function keys, simply place the key codes for these keys in the first n elements of the od_control.od_hot_key[] array, and set the od_control.od_num_keys variable to the number of keys you have defined. OpenDoors will then watch the keyboard for any of your predefined sysop function keys being pressed. If one of these keys is pressed, OpenDoors will place the key code of the pressed key in the od_control.od_last_hot variable. Your program will then be able to respond to one of your custom function keys being pressed by checking the value of the od_control.od_last_hot variable. At any time this variable contains a non-zero value. If this is the case, you will then be able to determine which of your function keys has been pressed by checking the key code contained in this variable. After taking the appropriate action for the key pressed, you should be sure to reset the value of the od_control.od_last_hot variable back to zero, which will indicate to OpenDoors that your program has received and responded to the function key which was pressed. OpenDoors Door Toolkit Manual - Version 4.10 Page 162 CONTROL STRUCTURE - COLOUR CUSTOMIZATION -------------------------------------------------------------------------------- The OpenDoors control structure variables listed in this section allow you to customize the colour of text displayed by several of the OpenDoors functions. Each of the variables in this section are unsigned chars, which contain the IBM-PC colour attribute of the colour to be displayed. For more information on these colour attributes, see the description of the od_set_attrib() function on page 105. These colour variables are listed below, along with a description of where each colour is used: +---------------------+-----------------------------------------+ | VARIABLE | WHERE COLOUR IS USED | +---------------------+-----------------------------------------+ | od_control. | Text typed by the sysop in chat mode | | od_chat_colour1 | | | | | | od_control. | Text typed by the user in chat mode | | od_chat_colour2 | | | | | | od_control. | File description fields in FILES.BBS | | od_list_comment_col | listings | | | | | od_control. | Filename fields in FILES.BBS listings | | od_list_name_col | | | | | | od_control. | "Missing" string in FILES.BBS listings | | od_list_offline_col | | | | | | od_control. | File size fields in FILES.BBS listings | | od_list_size_col | | | | | | od_control. | Title fields in FILES.BBS listings | | od_list_title_col | | +---------------------+-----------------------------------------+ OpenDoors Door Toolkit Manual - Version 4.10 Page 163 CONTROL STRUCTURE - TEXT CUSTOMIZATION -------------------------------------------------------------------------------- In addition to the other aspects of OpenDoors which may be customized by use of the OpenDoors control structure, all of the text displayed by OpenDoors may also be customized. This may be done either to create doors with OpenDoors that use languages other than English, or to simply give your doors a "personal touch". The variables described in this section allow you to define what text you want to have displayed by OpenDoors at any time. All of these variables are pointers to strings, and are set to default values in the od_init() function. Thus, if you wish to change the string pointed to by any of these variables, you must do so after od_init() or some OpenDoors doordriver function has been called. To set any of these variables, you can simply set them to point to a string-constant in your program. For example, to set the text displayed by OpenDoors prior to a DOS shell, you could: od_control.od_before_shell=(char *)"\n\rJust a moment...\n\r"; The chart below lists each of the text customization variables (without the "od_control." prefix, for the sake of brevity), along with their default strings. Note that some of these strings MUST always be the same length as their default string. You may not display longer text within these strings, and if you wish to display shorter text, you must pad the remaining space in the string with spaces, in order to preserve its length. Those string which must be of fixed length also have their length listed in the chart below. Any strings which have an asterisk (*) in their length column may be any length. Also keep in mind that any string with "printf-style" formatting sequences, such as "%s", must retain the same sequences in the same order. In addition, four of these pointers - od_after_chat, od_after_shell, od_before_chat and od_before_shell - can be set to a value of NULL. In this case, OpenDoors will not display any string where this variable's string is normally displayed. +-----------------------+-----+----------------------------------------------+ | VARIABLE NAME | LEN | DEFAULT VALUE | +-----------------------+-----+----------------------------------------------+ | od_after_chat | * | "\n\rChat mode ended...\n\r\n\r" | | | | | | od_after_shell | * | "\n\r...Thanks for waiting\n\r\n\r" | | | | | | od_before_chat | * | "\n\rSysop breaking in for chat...\n\r\n\r" | | | | | OpenDoors Door Toolkit Manual - Version 4.10 Page 164 | od_before_shell | * | "\n\rPlease wait a moment...\n\r" | | | | | | od_chat_reason | * | " Why would you " | | | | "like to chat?\n\r" | | | | | | od_continue | * | "Continue? [Y/n/=]" | | | | | | od_continue_no | char| 'N' | | | | | | od_continue_nonstop | char| '=' | | | | | | od_continue_yes | char| 'Y' | | | | | | od_day[0] | 3 | "Sun" | | | | | | od_day[1] | 3 | "Mon" | | | | | | od_day[2] | 3 | "Tue" | | | | | | od_day[3] | 3 | "Wed" | | | | | | od_day[4] | 3 | "Thu" | | | | | | od_day[5] | 3 | "Fri" | | | | | | od_day[6] | 3 | "Sat" | | | | | | od_help_text | 80 | " Alt: [C]hat [H]angup [L]ockout [J]Dos " | | | | "[K]eyboard-Off [D]rop to BBS " | | | | | | od_help_text2 | 79 | " OpenDoors 4.10 - (C)Copyright 1992, " | | | | "Brian Pirie - Registered Version " | | | | | | od_inactivity_timeout | * | "User sleeping at keyboard, inactivity " | | | | "timeout...\n\r\n\r" | | | | | | od_inactivity_warning | * | "Warning, only %d minute(s) remaining " | | | | "today...\n\r\n\r" | | | | | | od_month[0] | 3 | "Jan" | | | | | | od_month[1] | 3 | "Feb" | | | | | | od_month[2] | 3 | "Mar" | | | | | | od_month[3] | 3 | "Apr" | | | | | | od_month[4] | 3 | "May" | | | | | | od_month[5] | 3 | "Jun" | | | | | | od_month[6] | 3 | "Jul" | | | | | | od_month[7] | 3 | "Aug" | | | | | | od_month[8] | 3 | "Sep" | OpenDoors Door Toolkit Manual - Version 4.10 Page 165 | | | | | od_month[9] | 3 | "Oct" | | | | | | od_month[10] | 3 | "Nov" | | | | | | od_month[11] | 3 | "Dec" | | | | | | od_no_keyboard | 10 | "[Keyboard]" | | | | | | od_no_sysop | * | "\n\rI'm afraid the sysop is not available " | | | | "at this time.\n\r" | | | | | | od_no_response | * | " No response.\n\r\n\r" | | | | | | od_no_time | * | "Sorry, you have used up your time for " | | | | "today...\n\r\n\r" | | | | | | od_offline | 10 | "[OFFLINE] " | | | | | | od_paging | * | "\n\rPaging Sysop for Chat" | | | | | | od_press_key | * | "Press [Enter] to continue..." | | | | | | od_status_line[0] | 80 | " " | | | | " [Node: " | | | | | | od_status_line[1] | * | "%s of %s at %u BPS" | | | | | | od_status_line[2] | 79 | "Security: Time: " | | | | " [F9]=Help " | | | | | | od_status_line[3] | 80 | "Voice#: Last Call : " | | | | " First Call : " | | | | | | od_status_line[4] | 79 | "Data #: Times Called : " | | | | " Age : Birthdate : " | | | | | | od_status_line[5] | 80 | "Uploads : Downloads" | | | | " : " | | | | | | od_status_line[6] | 79 | "Flags:(A):-------- (B):-------- (C):--" | | | | "------ (D):-------- " | | | | | | od_status_line[7] | * | "%uk, %u files" | | | | | | od_status_line[8] | 80 | "Last Caller: T" | | | | "otal System Calls : [Time: ] " | | | | | | od_status_line[9] | 79 | "[Printer: OFF] [Local Screen: ON] " | | | | " Next Event : " | | | | | | od_status_line[10] | <=20| "[none, errorlevel 0]" | | | | | | od_status_line[11]] | <=20| "[%5.5s, errorlevel %u]" | | | | | | od_status_line[12] | 80 | "Msgs posted : Highread : " | OpenDoors Door Toolkit Manual - Version 4.10 Page 166 | | | " " | | | | | | od_status_line[13] | 79 | "Netmail Credit : Handle : " | | | | " " | | | | | | od_status_line[14] | * | " Reason for chat : %-60.60s" | | | | | | od_sysop_next | 5 | "[SN] " | | | | | | od_time_left | 10 | "%d mins " | | | | | | od_time_warning | * | "Warning, only %d minute(s) remaining tod" | | | | "ay...\n\r\n\r" | | | | | | od_want_chat | 11 | "[Want-Chat]" | +-----------------------+-----+----------------------------------------------+ OpenDoors Door Toolkit Manual - Version 4.10 Page 167 -------------------------------------------------------------------------------- CHAPTER 6 - DEBUGGING OPENDOORS PROGRAMS AND GETTING HELP -------------------------------------------------------------------------------- ABOUT THIS CHAPTER -------------------------------------------------------------------------------- This chapter is perhaps the most important section of this entire manual. Here, we provide detailed instructions to help you in tracing the source of problems in programs written with OpenDoors. Included in this chapter is a step-by-step OpenDoors troubleshooting guide and a chart listing common problems and their solutions. Also included in this chapter is information on the many means available to you for getting more help with OpenDoors, including the OpenDoors support BBS, the OpenDoors EchoMail conference, and how to get in touch with me. It is strongly encouraged that you take the time to read through this chapter. TROUBLESHOOTING PROBLEMS -------------------------------------------------------------------------------- If you are experiencing difficulty with a program that you are writing using OpenDoors, it is suggested that you follow the steps listed below in order to quickly solve your problem. Also, be sure to check to "solutions to common problems" section of this manual. There are many common difficulties which people have with OpenDoors, that can easily be fixed using the instructions in the "common solutions" section. Also, if you are having difficulty solving a problem yourself, do not hesitate to get in touch with me, as I am always happy to help with any problems. In addition, you may find the other means of OpenDoors support (described latter in this chapter), invaluable in solving difficulties with OpenDoors. Keep in mind that most programs you write will have some "bugs" to begin with, and you should expect to spend at least 50% of any programming project tracing down and solving errors and bugs. While it would be nice if every program written worked correctly the first time, it is a fact of life that debugging is and always has been an important part of the software life-cycle. In fact, what most often separates the good programs from the bad is the amount of time their programmer's spend debugging and improving them. Unfortunately, it is difficult, if not impossible, to come up with a "magic formula" for debugging software. Debugging software is really more of an art than a science. However, there are some basic guidelines, which if followed, can greatly ease the task of software debugging. OpenDoors Door Toolkit Manual - Version 4.10 Page 168 As with all problem solving, the secret to software debugging lies in obtaining as much information about the problem as possible. While it is sometimes possible to solve a bug by making intuitive changes in your program, or in re-writing a piece of code to solve the problem by a different means, debugging most often requires more of a "planned attack". This planned attack generally involves little more than learning as much about what is going wrong as possible. The first step in solving a bug usually lies in locating the source of the problem. Once you have located the problem, solving it is often a relatively simple procedure. In locating the source of your bug, the use of a software debugger, such as the one built into the Turbo C(++) / Borland C++ integrated development environment, can be invaluable. When debugging programs written with OpenDoors, you should also follow the steps listed below, in order to obtain more information related to the problem you are trying to solve: 1.) Re-read the section(s) of this manual, your Turbo C(++) / Borland C++ manuals and your program's source code, which apply to the problem you are experiencing. 2.) Check the solutions to common problems section below. The most common problems with OpenDoors can be solved using this simple chart. 3.) Check the value in the od_errno variable, which will often provide vital clues as to the source of the problem. Use of the od_errno variable is described in the section below. 4.) If you are still stuck, please feel more than free to get in touch with me! (see the end of this chapter for information on reaching me) I am always more than happy to help with any OpenDoors or general programming problems! OpenDoors Door Toolkit Manual - Version 4.10 Page 169 SOLUTIONS TO COMMON PROBLEMS -------------------------------------------------------------------------------- Below, several common difficulties with OpenDoors are listed, along with suggested solutions to these problems. If you are experiencing any difficulty with a program that you have written with OpenDoors, we would suggest that you read this section thoroughly. Here, the common problem is listed in the left margin, and the solutions listed on the right portion of the page. -------------------------------------------------------------------------------- PROGRAM 1.) Check that the compiler is able to locate the OpenDoors WON'T header file, "OPENDOOR.H". This can be accomplished either by COMPILE placing this header file in the same directory as your other header files (such as STDIO.H, etc.), or by placing the header file in the current directory. 2.) Be sure that you are linking your program with the correct library for the memory model you are using. (See the section on compiling with OpenDoors). Also be sure that both the source code file for your program (such as EZVOTE.C) and the library file are listed in your project file, and that the project file is loaded. For more information on compilling programs written with OpenDoors, see page 20. 3.) If you have tried the above solutions, and your program still won't compile, then the problem is most likely an error in your source code file. If you are unable to resolve your problem, feel free to get in touch with me. -------------------------------------------------------------------------------- SCREEN Sometimes, when compiling an OpenDoors door with some versions of SCROLLED Borland C++, the local screen will not be scrolled correctly. In INCORRECTLY this case, although everything works correctly on the remote screen, the bottom line will not be correctly cleared when the screen is scrolled. This results in scrolled lines appearing to be partially repeated on the screen. This problem can be remedied by including the following line at the beginning of the main() module of your door program: directvideo=0; -------------------------------------------------------------------------------- SCREEN If you are using the od_clr_scr() function to clear the screen, WILL NOT but are not getting any results, this is likely because the user CLEAR online has screen clearing turned off. If you wish to force screen clearing regardless of the user's screen clearing settings OpenDoors Door Toolkit Manual - Version 4.10 Page 170 (this is probably not a good idea), use the function call od_emulate(12); -------------------------------------------------------------------------------- ALT-J KEY If you press the Alt-J function key, but do not get any results, DOES NOT your problem is likely as a result of lack of memory. If enough WORK memory is not available to load the command processor (usually COMMAND.COM) when the Alt-J function key is pressed, OpenDoors will automatically return to the door. -------------------------------------------------------------------------------- FIXUP This problem was probably caused by a mismatch between your OVERFLOW memory model selection in your compiler, and the memory model ERROR library you are using. See the section on compiling programs with OpenDoors for more information on the correct library you should be using for your memory model selection. -------------------------------------------------------------------------------- DIFFICULTY The OpenDoors built-in terminal emulation routines, od_emulate() COMPILING and od_send_file() require Turbo C++ or Borland C++ in order to WITH OLD be compiled into your programs. You may, however, "trick" the old VERSIONS OF versions of Turbo C into compiling your door, by creating a TURBO C global variable, _wscroll. Simply place the line: int _wscroll; at the beginning of your source code file. You will now be able to compile your program and use these function under old versions of Turbo C, however a few of the AVATAR-specific control codes will not always function correctly. OpenDoors Door Toolkit Manual - Version 4.10 Page 171 OPENDOORS SUPPORT -------------------------------------------------------------------------------- The powerful and easy to use door toolkit and BBS interface package, along with this comprehensive manual are only two parts of what make up OpenDoors. The third element of OpenDoors is the extensive OpenDoors support mechanisms. The OpenDoors EchoMail conference and support BBS each give you a chance to share ideas and source code with other OpenDoors programmers. You can also receive help learning OpenDoors or solving difficulties from the OpenDoors echo and BBS. In addition to these sources, I am also more than happy to answer any of your questions, or hear any suggestions for future versions of OpenDoors. The remainder of this chapter provides more information on the various sources of OpenDoors support. Also keep your eyes open for the "OpenDoors Tech Journal", which will soon be available. Included in this newsletter will be information on OpenDoors and future versions, questions and answers about OpenDoors and BBS door / utility programming in general, sample source code, and much more. THE OPENDOORS SUPPORT BBS -------------------------------------------------------------------------------- One of the many means of receiving OpenDoors support is via the OpenDoors BBS. Below is an outline of some of what is available from the OpenDoors BBS: - The newest version of this package and the OpenDoors BBS interface package is always available for download. - Also available for download is example source code and other files which you may find helpful when writing programs with OpenDoors. - The newest list of OpenDoors distribution sites is available from the BBS. - Access to the OpenDoors support conference where OpenDoors programmers can share ideas, source code, and receive help with difficulties or with learning OpenDoors. - Get in touch with me with any questions, comments, suggestions or bug reports. - Other files by yours truly, which may be of use in you programming, such as a registration key system, and so on. OpenDoors Door Toolkit Manual - Version 4.10 Page 172 All users receive full access upon their first call to the OpenDoors BBS. The North American phone number for the support BBS is: +1 613 526 4466 Note that if you are calling from outside of North America, you may have to add the appropriate long distance routing codes to the phone number. If you are having difficulty getting through to the BBS (ie, you get a BUSY signal), it may be best to try again in ten to twelve hours time. Since the BBS system is sometimes used for beta test purposes, it may be unavailable for several hours at a time. The OpenDoors support BBS also has a FidoNet address, 1:243/8. If you are interested in a list of files available from the support BBS, simply file-request "FILES". To receive the newest version of OpenDoors, you can file-request "ODOORS". THE OPENDOORS ECHOMAIL CONFERENCE -------------------------------------------------------------------------------- Also available to OpenDoors users who are a member of FidoNet or other EMail networks is the OpenDoors EchoMail support conference (tag-name "OPENDOORS"). The OpenDoors support conference is devoted to OpenDoors and BBS door and utility programming in general. As with the OpenDoors support BBS, this conference gives people programming with OpenDoors a chance to share ideas and source code. It also is a forum for receiving help either learning OpenDoors, or with a specific difficulty. Bug reports, suggestions and information on future versions of OpenDoors is also available in the OpenDoors conference. For more information on the OPENDOORS echo, please feel more than free to get in touch with me. GETTING IN TOUCH WITH ME -------------------------------------------------------------------------------- If you have any questions about OpenDoors, would like help with any programs that your are writing, or have any suggestions for future versions of OpenDoors, please feel free to get in touch with me. You can get in touch with me by any of the following means: - By calling the OpenDoors support BBS. Information on the support BBS is provided earlier on in this chapter. - By electronic mail. My FidoNet NetMail address is: 1:243/8 ***SEE NOTE BELOW*** And my Internet address is: OpenDoors Door Toolkit Manual - Version 4.10 Page 173 brian@bpecomm.ocunix.on.ca While I would like to be able to reply to all NetMail messages by CrashMail, I am afraid I simply can not afford to do this. So, if you choose to send NetMail, please indicate whether you would like me to reply by routed NetMail (this may not work, if routed NetMail is not available in your area), or to place the message on hold for you to poll and pick up. - By writing a message to me in the OpenDoors support EchoMail conference. For more information on the OPENDOORS echo, see the previous section of this chapter. - By conventional mail. My postal address is: Brian Pirie Apt. 1416 - 2201 Riverside Dr. Ottawa, Ontario Canada K1H 8K9 I try to respond to all correspondences as soon as possible (ie, within twenty-four hours). However, it is possible that it may take slightly longer to reply to your message, if you are asking a question that requires time for me to get an answer, or if I happen to be away for a few days. If you are having some sort of difficulty with OpenDoors, the more detailed information you supply (such as source code to the program that is causing the problem, how to duplicate the problem, and so on), the more quickly I will be able to determine the source of your problem. Also, before you write about a problem with OpenDoors, you may wish to be sure that you have read and followed the instructions in the section on troubleshooting, found on page 168. While I do not mind taking the time to answer any questions related to OpenDoors, you may be able to save yourself the time of writing and waiting for a response - simply by following the instructions in the troubleshooting section. More often than not, the answer to questions I receive is already in this manual. If you have suggestions for enhancements or additions for future versions of OpenDoors, and are sending your suggestions by conventional mail, it would be easiest for me if you sent your suggestions on the suggestion form, located on page 18. If you have a BBS system, for which you would like to see support added, and either have the technical information on that BBSes structures, or know where I could get this information, please let me know. OpenDoors Door Toolkit Manual - Version 4.10 Page 174 OPENDOORS DISTRIBUTION SITES -------------------------------------------------------------------------------- Below is a list of sites from which the newest version of OpenDoors is available, as of February 25th, 1993, sorted by country. If you would like to join the list of official OpenDoors distribution systems, please see the end of this chapter. Please also keep in mind that I cannot gurantee the accuracy of the information in the list below. If you are having any difficulty contacting any of the distribution sites, please let me know. The only site that I can gurantee OpenDoors to be available from is the OpenDoors support BBS. For more information on the OpenDoors support BBS, please see page 172. In addition to the sites listed below, the newest verion of OpenDoors will likely be available from any system that carries "Programmer's Distribution Network" files. Also, if you send a self-addressed envelope, along with either a 3-1/2" or 5-1/4" (360K) diskette, and $2.00 to cover postage, I would be happy to mail the newest version of OpenDoors to you. My address is included in the list, below. Also, the newest version of this file is always available for download or file request from the OpenDoors support BBS, with the filename OD_SITES.ZIP. -------------------------------------------------------------------------------- AUSTRALIA Sydney, Australia - Rosalyn Anderson Data Number : +61 2 552 3255 Modem : 9600, v.32/PEP Fidonet : 3:712/618 Intlnet : 58:2100/146 Comments : 24 hours - log on as "opendoors user" password "doors" Sydney, Australia - Mark Laurence Data Number : +61 2 938 5707 Modem : 14400, v.32bis/v.42bis Fidonet : 3:714/910 Comments : 24 hours, file request for nodelisted sysops -------------------------------------------------------------------------------- CANADA Lancaster Park, Alberta, Canada - Thomas King Data Number : +1 403 973 6311 Modem : 16800, v.32bis/HST/v.42bis Fidonet : 1:342/49 IMEX : 89:701/513 Worldnet : 62:3200/50 Comments : Freq by Magic name ODOORS 23hrs/day Guest Name "Visiting Sysop" PW is "PhoneBill" Saint John, New Brunswick, Canada - George Hannah OpenDoors Door Toolkit Manual - Version 4.10 Page 175 Data Number : +1 506 652 7292 Modem : 14400, v.32bis/v.42bis Fidonet : 1:255/7 Comments : Freq ODOORS, except during ZMH Login as OPENDOORS password GUEST Ottawa, Ontario, Canada - Brian Pirie Data Number : +1 613 526 4466 Modem : 9600, v.32/v.42bis Fidonet : 1:243/8 *** SEE PAGE 173 *** Internet : brian@bpecomm.ocunix.on.ca Postal addr : Brian Pirie 1416 - 2201 Riverside Drive Ottawa, Ontario Canada K1H 8K9 Comments : Freq and BBS available 24 hours / day to everyone Mascouche, Quebec, Canada - Robert La Ferte Data Number : +1 514 968 1709 Modem : 14400, v.32bis/v.42bis Fidonet : 1:167/235 Comments : BBS opened 24 hours a day, 7 days/week, file request OPENDOORS for the latest version -------------------------------------------------------------------------------- ITALY Trieste, Italy - Pietro Budicin Data Number : +39 40 3783111 Modem : 14400, v.32bis/HST/v.42bis Fidonet : 2:333/603 Comments : Freq ODOORS and BBS 24hrs/day -------------------------------------------------------------------------------- UNITED Cambridge, United Kingdom - Marcel Cook KINGDOM Data Number : +44 223 301487 Modem : 14400, v.32bis Fidonet : 2:440/34 Comments : 24 hours for callers and file requests Ipswich, Suffolk, United Kingdon - Mark Clark Data Number : +44 473 692882 Modem : 14400, v.32bis/v.42bis Fidonet : 2:440/107 Comments : 24 Hours/Freqs Instant Registration Mildenhall, Suffolk, United Kingdom - Dale Elrod Data Number : +44 638 718623 Modem : 16800, v.32bis/HST/v.42bis Fidonet : 2:440/37 Comments : 23 hours a day, magic name of OPENDOORS to get latest version online. OpenDoors Door Toolkit Manual - Version 4.10 Page 176 -------------------------------------------------------------------------------- UNITED San Jose, California, USA - Darryl Perry STATES Data Number : +1 408 265 4660 Modem : 9600, v.32/v.42bis Fidonet : 1:143/324 Comments : Freq the full filename only. San Ramon, California, USA - Brent Johnson Data Number : +1 510 830 4616 Modem : 14400, v.32bis/HST Fidonet : 1:161/610 Comments : 23 hours, FREQ almost anytime if listed in nodelist. Columbus, Georgia, USA - Scott Burkett Data Number : +1 706 596 8126 Modem : 9600, v.32 Fidonet : 1:3613/12 Comments : 24 Hour Operation and FREQ's Baltimore, Maryland, USA - Mike Gurski Data Number : +1 410 256 1979 Modem : 14400, v.32bis/v.42bis Fidonet : 1:261/1062 Echonet : 50:5410/1062 Comments : 24 hour FREQs, unlisted systems welcome Muskogee, Oklahoma, USA - Vince Jacobs Data Number : +1 918 687 1612 Modem : 14400, v.32bis/v.42bis Fidonet : 1:3813/309 DoorNet : 75:7918/200 Comments : 24 Hours, FREQ hours anytime but ZMH, Guest Log In as The Inspector, password Gadget OpenDoors Door Toolkit Manual - Version 4.10 Page 177 JOINING THE DISTRIBUTION NETWORK -------------------------------------------------------------------------------- Essentially, the OpenDoors Distribution Network is a list of "official" OpenDoors distribution sites that will be distributed with future versions of OpenDoors, and anyone is welcome to participate. The idea behind the "OpenDoors distribution network" is simply to make it easier for you, the OpenDoors programmer, to obtain OpenDoors updates. While the newest version of OpenDoors is always available from the OpenDoors Support BBS, and often from any system carrying the "Programmer's Distribution Network", most OpenDoors programmers would find it useful to know of a system closer to them where the newest version of OpenDoors is always available. Although I would like to be able to send the newest version of OpenDoors to any support site, the cost of doing so unfortunately makes this impossible. However, it is likely that you would pick up the newest version of OpenDoors when it is available anyhow, so this shouldn't really make any difference. So, if you are interested in becoming an official OpenDoors distribution site, simply fill in the form below, and send it to me, either electronically or by conventional mail at one of the addresses listed on page 173. OpenDoors Door Toolkit Manual - Version 4.10 Page 178 OPENDOORS OFFICIAL DISTRIBUTION SITE APPLICATION FORM ----------------------------------------------------- YOUR NAME : ________________________________________ (eg. Brian Pirie) LOCATION : ________________________________________ (eg. Ottawa, Ontario, Canada) DATA NUMBER(S) : ________________________________________ (eg. (613) 526-4466) NETWORK ADDRESSES: ________________________________________ (eg. 1:243/8 in FidoNet) MODEM TYPE: ________________________________________ (eg. 9600, V32bis, v42bis, HST) OTHER INFORMATION: ________________________________________ ________________________________________ (eg. Hours of BBS operation, file request hours, guest login and password, etc.) I CAN BE INFORMED OF NEW RELEASES BY: ____ | | - ***ROUTED*** FIDONET NETMAIL |____| ____ | | - OPENDOORS SUPPORT CONFERENCE |____| ____ | | - OTHER: ________________________________ |____| OpenDoors Door Toolkit Manual - Version 4.10 Page 179 -------------------------------------------------------------------------------- APPENDIX A - CONTENTS OF ARCHIVE -------------------------------------------------------------------------------- OpenDoors is usually distributed in the form of a single, compressed archive file. Thus, you should have received this version of OpenDoors in a file who's name began with ODOORS41. The files listed below should be included in your OpenDoors package. If any of these files are missing, you will probably want to look for the most recent version of OpenDoors from another source. Also, as of OpenDoors 4.00, each file contains the same date and time. The time listed in a file's directory entry represents the version number it belongs to, and it's date is the date of that version's release. Hence, a file with a time of 4:10 is part of OpenDoors 4.10. This is intended to help in distinguishing between a file that is part of the current version of OpenDoors, and one that is part of an older version. DOOR TESTING DROP FILE DORINFO1.DEF Sample door info file for testing doors MISCELLANEOUS EXAMPLE DOORS EX_HELLO.C Demonstrates how simple a door can be EX_MUSIC.C Example of ANSI music in OpenDoors EZVOTE TUTORIAL DOOR EZVOTE.C Source code to the sample door program EZVOTE.EXE Sample door program, EZVote EZVOTE.CFG Sample OpenDoors configuration file THE LIBRARY FILES ODOORS.LIB Small memory model library ODOORC.LIB Compact memory model library ODOORM.LIB Medium memory model library ODOORL.LIB Large memory model library ODOORH.LIB Huge memory model library THE HEADER FILE OPENDOOR.H OpenDoors #include .Header file OPENDOORS DOCUMENATION ORDER.FRM Easy-to-print order form OPENDOOR.DOC OpenDoors programmer's manual; this file OpenDoors Door Toolkit Manual - Version 4.10 Page 180 -------------------------------------------------------------------------------- APPENDIX B - OPENDOORS HISTORY -------------------------------------------------------------------------------- This section of the manual is a brief history of the additions and enhancements that OpenDoors has gone through in the process of getting to where it is today. OpenDoors is constantly being improved and upgraded, and almost all of the changes are made in response to requests by current users of OpenDoors. In fact, almost every reasonable request to date has been implemented in the current version of OpenDoors. (If you are a registered user of OpenDoors, do you notice where some of your own suggestions have been implemented?) If you are upgrading from a previous version of OpenDoors, this history list will also help you to identify what new features are available in this version. VERSION 1.00 Initial beta test version of the OpenDoors doordriver. Proved to be very bug-free. VERSION 1.10 Many features have been improved upon and added since version 1.00. VERSION 1.20 Made several changes: - Support for the new RemoteAccess 1.00 enhanced exitinfo.bbs file, with many extra pieces of information. - Added a Alt-K function key to allow the sysop to temporarily disable the user's keyboard - Added full support for turning on and off status line. Status line has been changed slightly in format, and [F9] help function key added. - Improved sysop chat mode (added multi-colour and wordwrap) - Fixed up shell-to-DOS to automatically shell to the command processor specified in COMSPEC instead of always using COMMAND.COM. OpenDoors now also returns to system to the drive and directory it was in before DOS shell was issued. - Added support for the new RemoteAccess "sysop next" key. VERSION 1.30 A few quick changes to perfect all the features of this version before beginning major development work on OpenDoors 2.00. Fixed two problems: - The status line can no longer be turned back on by the sysop using F1 - F9 keys when a door program has disable the status line itself. OpenDoors Door Toolkit Manual - Version 4.10 Page 181 - A rather major problem was fixed for use of OpenDoors in conjunction with RA 1.00. We accidentally forgot to save some of the data that is unused in previous versions, but is now used in the new version. This bug caused some unexpected problems, including damage to the USERSXI.BBS file. VERSION 1.40 Another maintenance release. This version should now function perfectly when used in conjunction with older versions of Turbo C. Other changes in this version include: - Better error recovery in the case that the door information file has been damaged. - OpenDoors was made more customizable, including allowing the programmer to alter the various OpenDoors messages, and provisions for user defined function keys for the sysop. (ie, it is now possible for the programmer to make Alt-Y another hotkey for the sysop) VERSION 2.00 Another release, adding a number of new features, such as: - Added support for AVATAR graphics. OpenDoors will automatically detect the presence of AVATAR graphics mode when running under Remote Access, and will allow your door to toggle it when running under other BBS systems. - Improved ANSI routines. Added some new functions, and changed existing functions to send more efficient ANSI codes in some circumstances. - The "Sysop Next" key should now work correctly with RA 1.00 and later. VERSION 2.10 Changes in this version include: - Implementation of a registration key-code to allow registered users to more easily upgrade to new versions. - Added an od_printf() function for ease of formatted output from within OpenDoors. VERSION 2.20 More improvements, including: - Fixing of some minor bugs, such as incorrect handling of the path to DORINFO1.DEF/EXITINFO.BBS files. - Added support for more customization, such as hooks for functions that will be called before and after Shell to DOS and sysop chat. - OpenDoors is now DesqView aware. OpenDoors will automatically detect the presence of DesqView, and uses the DesqView `virtual screen buffer' for screen display if present. OpenDoors Door Toolkit Manual - Version 4.10 Page 182 - A QuickBBS 2.75 compatibility problem has also been fixed. VERSION 2.30 Fixed a small bug in the registration system. VERSION 3.00 A major upgrade, released as a beta-test version, including the following additions/changes: - Eliminated many bugs. - Added support for door information files from: WWIV, PC- Board, Spitfire, WildCat, GAP, TriTel and others. - Added .ASC/.ANS/.AVT file display support with automatic interpretation of QBBS/SuperBBS/RA control characters. - Added ALT-D key to drop the user back to the BBS without hanging up. - Added direct access to RA style configuration, file area, message area, external protocols, event configuration, caller history, users online, menu files, user base and other system files. - Added complete set of message base manipulation routines, with full support for the RA 1.01 message base locking scheme. - The user manual has also been re-written in order to make it easier to work with. VERSION 3.10 The following bug fixes and changes have been made since the release of the beta version, 3.00: - Time fields in messages are now correctly formatted - Corrected a bug in the od_set_attrib function where the intensity setting would not correctly be transmitted to the remote when using ANSI graphics. - Fixed a bug in the re-writing of the DORINFO1.DEF which cause sysop and user's last names to be corrupted. - Registered users may now disable the display of copyright and registration information when the door starts up. VERSION 3.20 A few more changes and bug fixes were made since version 3.10, including: - Fixed the FILES.BBS lister to correctly support FILES.BBS files located in directories other than the default dir, and added page pausing to the FILES.BBS lister. VERSION 3.30 The following changes and bug fixes were made since version 3.20: OpenDoors Door Toolkit Manual - Version 4.10 Page 183 - OpenDoors no longer re-writes the DORINFO1.DEF upon exiting. No BBS's are known to actually make use of the information changed in DORINFO1.DEF, and re-writing this file was causing more troubles than it was worth. - The od_msg_read_hdr() function's NEXT_MESSAGE command now works correctly. - Added an od_errno variable to assist in debugging of programs written with the BBS file engine portion of OpenDoors. VERSION 3.40 A minor upgrade version, with the following changes: - Fixed a compatibility problem with some locked baud rates. Now, if OpenDoors receives a baud rate the door information file that is not supported in the FOSSIL definitions, it will continue without setting the baud rate. (Whereas before, OpenDoors would report an error and exit.) - Made some changes to the manual, and included a utility to remove the extended-ASCII characters from the manual to ease printing on some printers. VERSION 4.00 This version is a major overhaul of the entire OpenDoors package, including a great many enhancements and additions. As of version 4.00, OpenDoors is available as two separate packages - the door programming toolkit (this package), and the BBS interface package (which is available separately) Among the major changes to version 4.00 of the OpenDoors door programming toolkit are: - A complete re-organization of the manual, including the re-writing of a large portion of the manual. In order to ease printing on some printers, the manual has been re- formatted in order that it no longer contains extended ASCII characters. More thorough documentation on the OpenDoors functions and structures was written, along with the addition of many more examples. Also added to the manual are an index, glossary and other features intended to make the reference manual an even more powerful and flexible tool. - Full support for the changes to RemoteAccess 1.10/1.11 has been added for version 4.00. These include the addition of some new fields stored in the EXITINFO.BBS door information file, and proper adjusting of the user's time remaining online. Version 4.00 also now has full support for the new QuickBBS-specific EXITINFO.BBS file. - All of the text displayed by OpenDoors is now fully customizable using od_control structure variables. This permits both greater door customization, and adds the ability to write 100% non-English doors and programs. OpenDoors Door Toolkit Manual - Version 4.10 Page 184 - The OpenDoors status lines have been changed. OpenDoors now provides additional user information through multiple RemoteAccess-style status lines, accessible through the F2, F3, etc. keys. Also, the status line may now be turned off by using the F10 key, allowing the sysop to view all 25-lines of the information displayed by a door program. A new function od_set_statusline(), permits program selection of the current status line setting. - OpenDoors now allows colour codes to be embedded in od_printf() functions, to eliminate the need for long chains of alternating od_disp_str(), od_set_colour() / od_set_attrib() function calls. - A new formatted input function, od_edit_str() has been added for use in door programs running in ANSI or AVATAR graphics mode. The od_edit_str() function features advanced line editing capabilities which are normally found only in non-door programs, such as inserting or deleting text from the middle of a string, moving the cursor with the arrow keys, and so on. The od_edit_str() function also provides input formatting, allowing you to force the user's input into any format you wish, from phone number formats to date formats to username formats. The od_edit_str() also provides special modes for implementing features such as password input, field input (where the user may move from one field to another using arrow/tab keys), input field highlighting, editing existing strings, auto-delete, and much more. The old od_input_str() function still provides a subset of these features which do not require ANSI or AVATAR graphics. - New functions have been added to the door driver module of OpenDoors. Among these, are an od_putch() function for displaying one character at a time, and an od_spawn() function, for easily executing other programs from within OpenDoors. The od_spawn() function automatically saves the contents of the current door screen, system drive and directory, and provides a separate screen on which the spawned-to program can execute. The od_draw_box() function allows you to easily display windows in door programs, using ANSI or AVATAR graphics codes. Also added is are od_carrier(), od_set_statusline() and od_edit_str() functions, mentioned elsewhere. - More changes have been made in order to permit greater customization and flexibility of OpenDoors. An od_carrier() function has been added to detect the state of the carrier detect signal in programs that disable OpenDoor's internal carrier detection. Also, it is now possible to shut down OpenDoors without exiting via the od_exit() function. - OpenDoors now yeilds the processor to other executing tasks in multitasking environments (ie. DesqView), when the door is inactive or waiting for input. OpenDoors Door Toolkit Manual - Version 4.10 Page 185 - The door driver function od_clr_scr() now only checks the user's screen clearing setting if that information is available from the door information file. If the information is not available, the od_clr_scr() function will always clear the screen. - Many other small changes were also made for version 4.00. Among these, you now have access to the user's reason for chat and you can switch the pause and stop keys on and off during listing of available files or displaying a text file. Also, previous versions of OpenDoors would read the user's information from the first door information file found. Instead, version 4.00 now reads the most recently created door information file. A bug in the od_clr_line() function has also been fixed. VERSION 4.10 A great deal of work has been done between version 4.00 and 4.10 of OpenDoors. This work falls into three major categories: bug fixes, improved performance, and new features. In fact, enough changes and improvements have been made that this version really ought to be numbered 5.00. Below is a summary of the changes that have occurred since version 4.00: - Much of the door information file interfacing code has been revamped, in order that OpenDoors now works correctly with the newest versions of the BBS packages it supports. OpenDoors now differentiates between three different DOOR.SYS formats - the DoorWay format, the PC-Board / GAP format, and the Wildcat format. Also, the SFDOORS.DAT code has been fixed to correctly work with the newest version of Spitfire. - OpenDoors will now attempt to swap itself and your entire door program to expanded memory or disk when the sysop shells to DOS, or when you call one of the od_spawn...() functions. Memory swapping may be configured in a number of ways, or even disabled. The OpenDoors swapping code adds only 2K to the door's .EXE file size. - OpenDoors now includes a new od_spawnvpe() function. In addition to the features of the "quick-spawn" od_spawn() function, od_spawnvpe() also returns the errorlevel the called program returned, allows you to alter the environment passed to the child process, and uses the same parameter format as the C spawnvpe() function. (see page 117) - The od_page() function now checks the sysop paging hours, set in the OpenDoors control structure. If the user attempts to page the sysop outside of the defined paging hours, he or she will be notified that the sysop is not available. - OpenDoors now includes a configuration file sub-system that you may choose to include in your OpenDoors programs. OpenDoors Door Toolkit Manual - Version 4.10 Page 186 This sub-system automatically parses the configuration file you specify, responding to any of the built-in configuration commands, and passing configuration options specific to your program back to you. With only a single line of code on your part, this sub-system will allow people running your program to configure many options such as sysop paging hours, system directories, maximum time within the door, etc. It also allows the sysop to provide information that may not be supplied by their particular BBS software, such as modem settings, the system's name and so on. In addition to all these built in commands, you can add your own configuration options, such as display colours, registration key numbers and other information needed by your program - without the need to write your own configuration file parsing routines. (See page 76) - OpenDoors now supports custom, sysop-defined door information file (drop file) formats. By defining a custom door information file format in the cofiguration file, OpenDoors door programs can now be made to run directly under BBS packages that use proprietary file formats that are not directly supported by OpenDoors. (see page 78) - In order to make doors written with OpenDoors even more foolproof for the sysop to setup, an intelligent door information file (drop file) locator has been added. OpenDoors will automatically search for a door information file in the directory specified by the configuration file, the directory specified by your door's source code, the current directory, and the directory pointed to by the environment variables used by any of a number of BBS packages. - OpenDoors now includes a log file sub-system that you may choose to include in your programs. The log file system handles all access and formatting of the logfile, allowing the programmer to make log file entries by simple function calls such as od_write_log("User downloading file");. Also, since the log file system is closely integrated with the rest of OpenDoors, choosing to include the logfile system in a program causes OpenDoors to automatically output the most common logfile entries for events such as the user paging sysop, the user hanging up, sysop chatting with the user, user inactivity timeouts, and so on. (see page 89) - OpenDoors 4.00 would not always correctly turn on and off high intensity or flashing colour attributes in ANSI mode. The ANSI colour handling code has been reworked for version 4.10, to eliminate these problems. - An od_get_answer() function has been added, which can be used to easily permit only certain keys to be pressed in response to a prompt. For instance, to get a Yes/No response from the user, use od_get_answer("YN"); (see page 66) OpenDoors Door Toolkit Manual - Version 4.10 Page 187 - A popular addition to OpenDoors 4.00 was the ability to change the current display colour within od_printf() format strings, using imbedded control characters. However, the programmer was forced to use a rather cryptic two-byte control sequence, where the second character of the sequence contained an 8-bit colour attribute value. It is now possible to change the display colour within od_printf() by specifying the names of the desired foreground and background colours, delimited by a set of BACK-QUOTE (`) characters. For example: od_printf("`Red` THIS TEXT IS RED `Blue` THIS TEXT IS BLUE"); od_printf("`Flashing bright green on dark green` AND THIS IS GREEN"); (see page 93) - Version 4.10 would not correctly "freeze" the user's time during DOS shell and sysop page operations, when the door was operating under RemoteAccess 1.11. This has been fixed. - A new variable, od_spawn_freeze_time, has been added to the OpenDoors control structure. When set to FALSE, the user's time remaining continues to be deducted during the execution of any of the od_spawn... functions. When set to TRUE, the user's time remaining is frozen during the execution of an od_spawn... function. - The current directory is now correctly restored to its original setting after the sysop returns from a DOS shell, and after calls to the od_spawn... functions. - A number of people were experiencing difficulty using the od_edit_str() function in version 4.00. A number of improvements to this function's logic have been made in an attempt to make od_edit_str() more foolproof to use. Also, a new flag setting, EDIT_FLAG_LEAVE_BLANK has been added. However, there were a few reports of problems which we were not able to reproduce. If you are still having difficulty with this function, please carefully re-read the section of the manual pertaining to it's use. In particular, be sure that your difficulty is not resulting from the flag settings you are using. If you still suspect a bug in this function, please include with your bug report the source code that is causing the problem. - Page pausing within the od_send_file() and od_list_files() (FILES.BBS listing routine) functions can now be disabled and re-enabled by the programmer. - The "Continue? [Y/n/=]" end of screen prompt and response keys are now fully customizable. - The od_list_files() FILES.BBS listing function now works correctly in all memory models. The function has also been OpenDoors Door Toolkit Manual - Version 4.10 Page 188 fixed to correctly handle cases where the trailing backslash is not supplied in the path parameter. - The actual BBS line (node) number is now displayed on the default status line, provided that this information is supplied by the BBS software. - It is now possible to detect whether keystrokes originated from the remote or local keyboard. This is a feature that is useful in some special applications, such as split- screen sysop chat programs. - Version 4.00 would not always correctly display the status lines, if there was information missing from the EXITINFO.BBS file. This has been fixed. In addition, the "next event" information is now correctly displayed on the status lines. Also, if the user's birthday is available, their age will also be calculated and displayed on the status line. - If you temporarily disable inactivity timeouts, OpenDoors will no longer automatically trigger and inactivity timeout as soon as you re-enable this feature. - A new function, od_hotkey_menu(), has been added to facilitate displaying a menu with "hot keys". Like the od_send_file() function, od_hotkey_menu() will display an ASCII, ANSI or AVATAR file. However, od_hotkey_menu() also allows you to pass a string listing possible hot keys. If the user presses any of these keys while the menu is being displayed, menu display will immediately cease, and the function will return the key pressed by the user. (See page 71) - The od_send_file() (the ASCII/ANSI/AVATAR file display routine) no longer sends the EOF character if it happens to exist at the end of a file. - In addition to the EZVote OpenDoors tutorial door, an number of other example doors are now included in the OpenDoors package. - A few errors have been corrected in the documentation, and additional information has been added about the new features in this version. OpenDoors Door Toolkit Manual - Version 4.10 Page 189 -------------------------------------------------------------------------------- APPENDIX C - FUTURE VERSIONS -------------------------------------------------------------------------------- While I cannot make any promises about what features and changes will be seen in future versions of OpenDoors, I would like to take a moment to tell you a bit about some of the features you can expect to see in future versions of OpenDoors As you are probably already aware, OpenDoors is a constantly evolving package. To help meet the needs of programmers working with OpenDoors, nearly every idea and change that is made to the package results from the suggestions and comments I receive from the people using OpenDoors. For this reason, I will most likely continue to produce new versions of OpenDoors for as long as there is a demand and ideas for upgrades. There certainly is no shortage of either of this right now. Some of the features that are currently in the works for up and coming version of OpenDoors include: - The OpenDoors "Multiple Personality System", which will allow sysops using OpenDoors doors to select from one of many status line and function key personalities. This will allow OpenDoors doors to mimic the behaviour of the BBS package the sysop is most familiar with. - A built-in automatic ANSI/high-ASCII to plain-ASCII conversion system. - More advanced ANSI/AVATAR terminal routines, such as screen save and restore, window scrolling, and more. - Direct interfacing with more BBS systems, including Maximus direct interfacing. - AVATAR compression. - Built in ANSI music support, including optional local sound. - Improvements to exisiting OpenDoors features, such as more configuration file options, multiple log file formats, and many smaller changes. OpenDoors Door Toolkit Manual - Version 4.10 Page 190 -------------------------------------------------------------------------------- APPENDIX D - SPECIAL THANKS -------------------------------------------------------------------------------- There are a great many people who I would like to thank, for their suggestions, ideas and assistance in making OpenDoors what it is today. In a way, I feel somewhat relucant to list people names, as I will no doubt forget someone important. Among those I would like to thank are: - Everyone who has taken the time to register OpenDoors - The folks in the OpenDoors EchoMail conference will all of your suggestions and bug reports. - Those people in the OpenDoors distribution network, who help to make OpenDoors available to others. - In particular I would like to thank the following people for their devotion of time, in the form of suggestions, bug reports, sending information, etc.: Ron Bergeron Scott Burkett Mike Hartmann Winfried Hirsch Robert La Ferte Ron Le Blanc Bill Pavich OpenDoors Door Toolkit Manual - Version 4.10 Page 191 -------------------------------------------------------------------------------- GLOSSARY -------------------------------------------------------------------------------- ANSI "ANSI", often referred to as "ANSI Graphics", is a display protocol which allows (in this case), BBS software to perform certain display functions such as changing the colour of displayed text, or moving the location of the cursor on the screen. The majority, though not all, BBS users use terminal software with ANSI graphics capabilities. Any users that do not have graphics display capabilities, will be using ASCII mode, instead. Compare ASCII and AVATAR. ASCII ASCII (pronounced "ass-key") is an acronym for "American Standard Code for Information Interchange", and is a definition of a set of 128 letters, number and symbols, which can be displayed by computer systems. Also, when used within the domain of BBS software, ASCII mode is often used to refer to the lack of any graphics display capabilities, such as ANSI or AVATAR. When ASCII mode is used, characters can only be displayed in standard Teletype fashion, one after another. Also, colour and cursor positioning functions are not available in ASCII mode. Compare ANSI and AVATAR. AVATAR AVATAR is an acronym for "Advanced Video Attribute Terminal Assembler and Recreator". AVATAR is a graphics display protocol, similar to ANSI. Like ANSI-graphics, AVATAR graphics allow functions such as cursor positioning, and colour changing. However, AVATAR also offers many capabilities not available from ANSI, and performs the same functions as ANSI much more quickly. AVATAR graphics is less common than both ANSI or ASCII, but is becoming more popular as time goes by. Compare ASCII and ANSI. BAUD For our purposes, the term "baud" or "baud rate" refers to the speed at which data is being sent from one computer to another over a modem. Sometimes referred to as "BPS". BIT-MAPPED As with Boolean values, described below, bit mapped flags FLAGS are used to indicate whether or not various conditions exist. (For example, whether or not a certain setting is enabled, or whether or not a particular event has occurred.) However, unlike Boolean variables, a single bit-mapped flag represents more than one of these TRUE/FALSE values. In fact, each bit (BInary Digit), which makes of the variable can be used to represent a separate TRUE/FALSE state. (ie, each bit maps to a particular piece of information, and hence the term "Bit Map"). For an example of using bit-mapped flags, let us take a case of a single "unsigned char" which contains three independent TRUE/FALSE values. We will call this variable user_info, and it will indicate whether or not a user has ANSI graphics, whether or not the user has screen clearing turned on, and wether or not the OpenDoors Door Toolkit Manual - Version 4.10 Page 192 user has end-of-page "more" prompts enabled. Internally, the bits of the user_info variable will be as follows: Bit: 7 6 5 4 3 2 1 0 | | | | | +--- ANSI Graphics | +----- Screen Clearing +------- More prompts In this case, we will have three constants which we define in order to simplify access to these bit-mapped flags, as follows: #define ANSI_GRAPHICS 0x01 #define SCREEN_CLEARING 0x02 #define MORE_PROMPTS 0x04 Note that normally within OpenDoors, these constants will be defined for you, and you will have no need to know what their values are, nor in which bit which piece of information is stored. Using bit-mapped flags, you are able to set or clear any of the individual flags, and check whether any of the flags are set, using these simple methods: (Not that a set flag is the equivalent of a Boolean value of "True", and a cleared flag is the equivalent of a Boolean value of "False".) Set Flag: variable |= FLAG_CONSTANT; Clear Flag: variable &=~ FLAG_CONSTANT; Test Flag: variable & FLAG_CONSTANT Where "variable" is the name of the bit-mapped flag variable, and "FLAG_CONSTANT" is the pre-defined constant for the individual setting. To return to our example, you could turn on the user's ANSI graphics setting by using the line: user_info |= ANSI_GRAPHICS; and to turn off screen clearing you would: user_info &=~ ANSI_GRAPHICS; To perform an action (such as waiting for the user to press [Return]/[Enter]) only if "More" prompts are enabled, you would: if(user_info & MORE_PROMPTS) { ... /* Whatever you want */ } BOOLEAN Many of the variables used within OpenDoors contain a VALUES "Boolean Value". A Boolean value is a two-state variable, who's states are referred to as "True" and "False'. If the variable contains a value of "True", it indicates that a certain condition OpenDoors Door Toolkit Manual - Version 4.10 Page 193 is so, and if it contains a value of "False", it indicates that the condition is not so. For example, a Boolean variable "wait" might be used to indicate whether or not OpenDoors should wait for the user to press a key, or continue without waiting. In this case, a value of "True" would indicate that OpenDoors should wait, and a value of "False" would indicate that it should not wait. Note that in the C programming language, there is no actual Boolean variable type - usually a char or an int are used to store Boolean values. The constants TRUE and FALSE, as defined in the OPENDOOR.H file, are used to represent the two states of a Boolean value. Thus, to set a boolean variable "wait" to the value of "True", you would use this line: wait=TRUE; and to set the variable "wait" to "False", you would: wait=FALSE; However, you SHOULD NOT test whether a Boolean variable is "True" or "False" by using the C compare (==) operator, as the value "True" will not always be the same numerical value. (Actually, the TRUE constant represents just one of many possible numerical values for "True"). Instead, to perform an action of the "wait" boolean variable is "True", you would: if(wait) { ... /* Whatever you want */ } and to perform an action if the "wait" boolean variable is "False', you would: if(!wait) { ... /* Whatever you want */ } For interest sake, Boolean values are named after the 19th century English mathematician, who studied formal logic, and created Boolean algebra - an algebra which deals with TRUE and FALSE values. BPS BPS is an acronym for "Bits Per Second". For our purposes here, the terms BPS and BAUD refer to the same thing. CARRIER The term "Carrier" or "Carrier Detect" refers to a signal which DETECT most modems send to the computer, which indicates whether or not the modem is currently connected to (communicating with) another OpenDoors Door Toolkit Manual - Version 4.10 Page 194 modem. The door driver module of OpenDoors, as with most other BBS software, uses the status of this carrier detect signal in order to know whether the user is still connected to the BBS computer. Thus, if the user hangs up, or if something goes wrong and the connection is lost, OpenDoors is able to detect this state, and exit to the BBS. The BBS will then also detect that the carrier signal has been "lost", and will reset itself, and then again be ready to accept calls. CHAT MODE The term "chat mode" refers to a means by which the sysop can communicate with a user of the BBS / door. During sysop chat, anything typed by the sysop will appear on the user's screen, and likewise, anything typed by the user will appear on the sysop's screen. Sysop chatting is available on both single and multi-line systems. Sysop chatting is initiated by the sysop, either at any time a user is online, or specifically in response to a sysop page. DOOR A "door" is a program that runs as part of a BBS system, but which is separate from the central BBS software (RemoteAccess, Maximus, QuickBBS, PC-Board, etc.) itself. A door provides additional features not built into the BBS software, such as on- line games, on-line shopping services, voting booths, match making systems, access to special files or messages, and much much more. Since the user also communicates with the door online, as they do with the BBS, it may not necessarily be obvious to the user that the door is even a separate entity from the central BBS software itself. DOOR DRIVER OpenDoors is broken into two individual, though closely related package, the door driver module and the BBS interface module. The door driver module is a complete toolkit used to quickly and easily write BBS door programs. DOOR Also referred to as a "drop file", "exit file", or "chain INFORMATION file". The door information file is a file passed from the FILE central BBS software to a door program, providing it with information about the user who is online, the BBS the door is running under, and the current modem connection. The door information file may also be used to pass changed information back to the BBS, such as the amount of time that the user has used in the door. OpenDoors takes care of all of the work involved in reading and writing the door information file for you, as described in the "Basics of Door Programming" section, in chapter 4. Examples of door information files supported by OpenDoors include: DOOR.SYS, EXITINFO.BBS, DORINFO?.DAT, SFDOORS.DAT, CALLINFO.BBS and CHAIN.TXT. ECHO See "Local Echo". OpenDoors Door Toolkit Manual - Version 4.10 Page 195 FOSSIL DRIVER The FOSSIL driver, or simply FOSSIL, is a particular computer program which OpenDoors uses in order to facilitate its communication with a modem. The FOSSIL driver is either an MS-DOS device driver or TSR program that is loaded prior to starting up the BBS or your DOOR, usually from the AUTOEXEC.BAT or CONFIG.SYS files. The two most commonly used FOSSIL drivers are X00 and BNU. (FOSSIL is an acronym for "Fido/Opus/SEAdog Standard Interface Layer", although it has now become the standard for nearly all BBS software.) LOCAL MODE The term "local mode" refers to a mode in which a BBS system or door program may operate. In local mode, the BBS/door behave as they would if a user were connected via modem to the BBS, except that all display and input is done simply on the BBS software, but not through the modem. Local mode allows the sysop or another person with direct access to the BBS computer to use the BBS/door software, either for their own user, or for testing that the software is running correctly. When programming door software, local mode can be very useful in testing and debugging the door, without requiring the door to be connected to a remote system. All doors written with OpenDoors automatically support local mode operation. Compare "Remote". LOCAL ECHO The term "Local Echo" refers to a door displaying the same characters which are sent to the modem on the local screen ("Output Window"). This allows the sysop to view the same information that is sent to the user's system, in the same manner that it will appear on the user's screen. LOCKED (eg. "Locked Baud Rate", "Locked BPS Rate", "Locked Commport Speed", etc.) Usually, the communication port to which a modem is connected is set to transfer data at the same BPS rate as the rate at which the modem is communicating. However, many high speed modems allow very high speed data transfer by using built- in data compression methods. In this case, the actual rate of data transfer can easily exceed the true BPS rate of the connection. As a result, the BPS rate of the port is kept a single speed, faster than any of the true modem connections, in order to increase modem speed performance. This is referred to as locking the commport BPS rate. OpenDoors has full support for the use of locked BPS rates. LOG FILE A log file is a normal text file in which BBS software records all major activities that have taken place. As such, the log file permits the sysop, to review what activities have taken place on the BBS during the time which they have been away from the computer. A log file can be helpful in identifying system errors or crashes that have occurred, in alerting the sysop in the case that any users have been causing problems on the BBS, or in simply letting the sysop know who has called recently, and what when they did when they called. OpenDoors Door Toolkit Manual - Version 4.10 Page 196 MODEM A device connected to a computer which permits it to communicate with other computers, usually over standard telephone lines. ONLINE In the case of BBS software and BBS door programs, the term online refers to the state of a user using the BBS. Usually, the user will be connected to the BBS from a remote location, using a modem. However, it is also possible that the user will be using the actual BBS computer, with the software operating in "local mode". OUTPUT WINDOW The local screen of the BBS on which BBS software is running is usually divided into two sections. At the bottom of the screen, there is often a one or two line status line, which displays information to the sysop about the BBS and the user who is currently online. The rest of the screen is usually an "output window", in which the information which is being displayed to the user, is also displayed on the local screen. In some cases, there will be no status line, in which case the entire screen will be the output window. Usually, the upper 23 lines of the screen in an OpenDoors door will be the output window, with the bottom two lines being the status line. However, it is possible to disable the OpenDoors status line, in which case the entire screen will be the output window. See also "Status Line" PAGE See "SYSOP PAGE" PARAMETER In the C programming language, many tasks are accomplished by calling functions. When a function is called, one or more pieces of information may be passed to a function, in the form of parameters. For example, a function used to set the foreground and background colour of displayed text might accept two parameters, one for each of the two colour settings. In this example, a function such as od_set_colour(), would be called as follows: od_set_colour(D_GREEN,D_RED); In this case, D_GREEN, the foreground colour, is the first parameter, and D_RED, the background colour, is the second parameter. In C, parameters are enclosed in parentheses, ( and ), which are located after the name of the function to be called. Each parameter is then separated by a comma character. If a function does not accept any parameters, the parentheses will have nothing between them. (ie. od_clr_scr() ). REGISTRATION This is a demonstration version of OpenDoors, which may only be used under limited circumstances, for a limited period of time. If you wish to continue using OpenDoors after this "evaluation OpenDoors Door Toolkit Manual - Version 4.10 Page 197 period", you must "register" it. For more information on registering OpenDoors, please see chapter 2 of this manual. REMOTE When used in reference to BBS software or door programs, the term remote is used to refer to a user or computer that is communicating with the BBS, for a distant location, by use of a modem. Compare "Local Mode" STATUS LINE Usually, the bottom two lines of the screen, as displayed by an OpenDoors door, is devoted to a status line (although this status line may be turned off). This status line will display information about the user who is online, along with information about the current state of the BBS system, and a reference to the sysop function keys. See also "Local Window". SYSOP The term sysop is a short-form for "SYStem OPerator", and refers to the individual who is responsible for running and maintaining the BBS system. The sysop is usually the only person who has direct access to the local keyboard and computer on which the BBS, BBS utilities and BBS doors are running. SYSOP CHAT See "CHAT MODE". SYSOP PAGE Sysop paging refers to the process whereby a user of the BBS system may call or page for the sysop's attention, when they wish to "chat" with the sysop, and can be thought of as being similar to the ringing of a telephone. When a user pages the sysop, the BBS system will produce some sort of sound, which the sysop may elect to respond to if they are within hearing range of the computer. The most common reasons for a user to page a sysop include the case that they are having difficulty with some aspect of the BBS, that they have a question, or if they are simply interested in having a friendly conversation with the sysop. Obviously, since the sysop may not wish to be disturbed by users paging at certain times (such as when they are in bed), most BBS software provides controls to allow you to control paging. These features might include the ability to set hours for each day of the week during which paging will be permitted, and the ability to temporarily override the ability of some or all callers to page the sysop. USER When applied to computers in general, the term user simply refers to any person using the computer hardware and software. However, when applied particularly to BBSes, the term user refers specifically to a person who calls the BBS, to carry out activities such as communicating via messages or chatting, uploading and downloading files, or using doors. Often, the term user is used in contrast with the term sysop. In this case, users are all of the people who call and user the BBS, other than the sysop themselves. OpenDoors Door Toolkit Manual - Version 4.10 Page 198 WINDOWS Windows, or MicroSoft Windows, is a computer operating environment which runs on IBM PC and compatible computers, and such runs in conjunction with the MS-DOS or PC-DOS operating systems. This version of OpenDoors can only be used to produce DOS-mode programs, which will run under DOS, DESQview, Windows and OS/2. OpenDoors Door Toolkit Manual - Version 4.10 Page 199 -------------------------------------------------------------------------------- INDEX -------------------------------------------------------------------------------- A About This Manual, 20 Access Level, 144 Alias, 137 ANSI Graphics, 30, 112, 133, 193 Archive Contents, 181 ASCII Chart, 70 ASCII Mode, 193 AVATAR Graphics, 30, 100, 112, 134, 193 B Baud Rate, 125 BBS Information, 126 BBS Name, 132 BBS Systems, 24 Before Exit Function, 152 Box Characters, 152 BPS Rate, 125 Built-In Function Keys, 162 C Caller Information, 126 Carrier Detect, 35, 86 Chat, 93 Chat Mode, 27, 196 Colour Attribute Codes, 106 Colour Constants, 110 Colour Customization, 164 Colour Functions, 32 Colours, 94, 106, 109 Common Problems, 171 Compiler Errors, 171-172 Compiling With OpenDoors, 21 Configuration Files, 77 Custom Door Info File, 79 Custom Function Keys, 163 D Debugging, 20, 169 Demo Version, 7 Display Functions, 31,47 Distribution Sites, 176, 179 Door Driver Functions, 31 Door Driver Module, 4, 23, 31, 196 Door Functions, 33 Door Information File, 24, 26, 122, 126 Door Settings, 147 DORINFOx.DEF File, 26 DOS Shell, 27, 152, 172 Download Limit, 136 Drop To BBS Key, 28 OpenDoors Door Toolkit Manual - Version 4.10 Page 200 E Error Free Connection, 137 ErrorLevels, 27 Example Program - Changing Only Foreground/Background Colour, 110 Example Program - Choosing Text Colour, 107 Example Program - Clearing A Line, 42 Example Program - Dialog Box, 50 Example Program - Door And Utility In One Program, 75 Example Program - Drawing A Window, 100 Example Program - Exiting A Door, 66 Example Program - EZVote, 26 Example Program - First Door, 23 Example Program - Hanging Up In CBV Door, 35 Example Program - Hotkeyed Menu, 73 Example Program - Input Key With Echo, 98 Example Program - Pausing In A Door, 86 Example Program - Setting Door Info File Location, 123 Example Program - Shelling To DOS, 116 Example Program - Terminal Emulation, 63 Example Program - Testing Available Door Information, 126 Example Program - Testing Screen Clearing Capabilities, 43 Example Program - Transferring A File Using DSZ, 117 Example Program - User Statistics Door, 96 Example Program - Waiting For CR, 40 Exiting A Door Program, 65 F Features, 4 Feedback Form, 19 File Display Functions, 32 FILES.BBS File, 88 Fossil Driver, 24, 197 FOSSIL port, 125 Function Keys, 27, 86, 161 Future Versions, 191 G Getting In Touch With Us, 174 Graphics Mode, 133-134, 193 H Hangup, 27 History, 182 I IBM Colour Attribute Codes, 106 IEMSI Session Information, 129 Inactivity Timeout, 155 Input Functions, 32, 67-68 K Keyboard Buffer, 39, 86, 98 Keys, 86 L Language Customization, 165 OpenDoors Door Toolkit Manual - Version 4.10 Page 201 Learning OpenDoors, 23 LIBrary Files, 22 Line Number, 124 Linking, 21 Local Mode, 26, 197 Locked, 5, 197 Lockout, 27 M Memory Models, 21-22 Memory Swapping, 159 Modem Port, 125 Modem Settings, 125 N New Version, 182 Node Number, 124 O od_before_exit Variable, 29 od_carrier() Function, 35 od_clear_keybuffer() Function, 30, 39 od_clr_line() Function, 41 od_clr_scr() Function, 30, 43, 171 od_colour_config() Function, 37 od_control Structure, 25, 120 od_disable Variable, 154 od_disp() Function, 45 od_disp_str() Function, 47 od_draw_box() Function, 49 od_edit_str() Function, 52 od_emulate() Function, 63 od_exit() Function, 23, 25, 65, 152, 153 od_get_answer() Function, 67 od_get_key() Function, 23, 39, 68 od_hotkey_menu() Function, 72 od_init() Function, 24, 74, 122 od_init_with_config() Function, 29, 77 od_input_str() Function, 39, 84 od_kernal() Function, 25, 86 od_list_files() Function, 88 od_log_open() Function, 90 od_log_write() Function, 92 od_page() Function, 93, 158 od_printf() Function, 23, 94, 154 od_putch() Function, 98 od_repeat() Function, 100 od_send_file() Function, 30, 102 od_set_attrib() Function, 106 od_set_color() Function, 109 od_set_cursor() Function, 112 od_set_statusline() Function, 114 od_spawn Function, 158 od_spawn() Function, 116 od_spawnvpe() Function, 118 OPENDOOR.H File, 21, 23, 28 OpenDoors Door Toolkit Manual - Version 4.10 Page 202 OpenDoors BBS, 173 OpenDoors Customization, 150 OpenDoors Distribution Network, 176 - 179 OPENDOORS Echo, 174 OpenDoors History, 182 Our Address, 174 Output Functions, 31 Output Window, 26, 198 P Paging Hours, 147-148 Paging The Sysop, 93 Pause Key, 156 Phone Number, 137 Printing Manual, 20 Problems, 20 Product Support, 173 Project Files, 21 R Registration, 7, 9, 13, 17, 174, 198 Registration Form, 11, 17 Running Doors, 24, 26 S Screen Functions, 32 Screen Length, 143 Screen Width, 144 Security Level, 144 Setting Colours, 94, 106, 109 Solutions To Problems, 171 Source Code, 7, 15 Special Thanks, 192 Status Line, 26, 93, 114, 159, 199 Stop Key, 156 Support, 173 Support BBS, 173-174 Swapping, 159 Sysop Chat, 152 Sysop Function Keys, 161 Sysop Keys, 27, 86 Sysop Name, 131 Sysop Next Key, 28 Sysop Next Setting, 148 Sysop Page, 158 Sysop Paging, 93, 199 System Event, 130 System Name, 132 T Terminal Emulator, 63, 102, 103 Terminal Emulator Control Codes, 104 Text Customization, 165 Thank-yous, 192 Time Left, 145 Timeout, 86 OpenDoors Door Toolkit Manual - Version 4.10 Page 203 Troubleshooting, 20 Turbo C, 172 U User Handle (Alias), 137 User Information, 126 User Keyboard Off Key, 28, 39 User Keyboard Setting, 148 User Name, 141 User Password, 142 User Timeout, 86 V Version History, 182 W Want-Chat Setting, 146 OpenDoors Door Toolkit Manual - Version 4.10 Page 204