













                             
                             
                   
                   
                   
                 
               
               
                                                    Door Programming Toolkit
    

                                                            Programmer's Manual


                                                                   Version 5.00


                                     MS-DOS Text Mode, C / C++ Language Edition












	  NOTE: Since you will likely want to refer to this manual while
                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. With the
                exception of this title page, this document contains only
                7-bit ASCII characters.





         (C) Copyright 1991 - 1994 by Brian Pirie. All Rights Reserved.




                              TABLE OF CONTENTS


TABLE OF CONTENTS ..........................................................2

CHAPTER 1 - INTRODUCTION TO OPENDOORS ......................................5
     WELCOME! ..............................................................5
     FEATURES OF THE OPENDOORS DOOR TOOLKIT ................................5

CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING ............................9
     THE DEMO VERSION & BENEFITS OF REGISTERING ............................9
     FILLING OUT THE REGISTRATION FORM .....................................13
     SENDING YOUR ORDER FEE ................................................15
     ORDERING THE SOURCE CODE ..............................................17
     ORDERING THROUGH COMPUSERVE ...........................................19
     OPENDOORS 5.00 ORDER FORM .............................................20
     OPENDOORS DOOR PROGRAMMING TOOLKIT 5.00 - USER FEEDBACK FORM ..........21
     TERMS OF REGISTRATION AND SOURCE CODE USE .............................22

CHAPTER 3 - OPENDOORS TUTORIAL .............................................24
     ABOUT THIS MANUAL .....................................................24
     COMPILING A PROGRAM WITH OPENDOORS ....................................25
     BASICS OF DOOR PROGRAMMING WITH OPENDOORS .............................28
     TOUR OF A SAMPLE DOOR PROGRAM: "EZVOTE" ...............................31
     OTHER EXAMPLE DOORS INCLUDED WITH OPENDOORS ...........................38

CHAPTER 4 - THE OPENDOORS API FUNCTIONS ....................................40
     OVERVIEW ..............................................................40
     TABLE OF MOST COMMONLY USED FUNCTIONS .................................41
     TABLE OF ALL FUNCTIONS ................................................42
     OD_ADD_PERSONALITY() ..................................................46
     OD_AUTODETECT() .......................................................48
     OD_CHAT() .............................................................50
     OD_CARRIER() ..........................................................51
     OD_CLEAR_KEYBUFFER() ..................................................53
     OD_CLR_LINE() .........................................................55
     OD_CLR_SCR() ..........................................................57
     OD_COLOUR_CONFIG() ....................................................59
     OD_DISP() .............................................................60
     OD_DISP_EMU() .........................................................62
     OD_DISP_STR() .........................................................64
     OD_DRAW_BOX() .........................................................66
     OD_EDIT_STR() .........................................................70
     OD_EXIT() .............................................................81
     OD_GET_ANSWER() .......................................................83
     OD_GET_KEY() ..........................................................84
     OD_GETTEXT() ..........................................................88
     OD_HOTKEY_MENU() ......................................................89
     OD_INIT() .............................................................91
     OD_INPUT_STR() ........................................................94
     OD_KERNEL() ...........................................................96
     OD_LIST_FILES() .......................................................98

===============================================================================
OpenDoors 5.00 Manual                                             End of Page 2


     OD_LOG_WRITE() ........................................................100
     OD_PAGE() .............................................................101
     OD_POPUP_MENU() .......................................................102
     OD_PRINTF() ...........................................................105
     OD_PUTCH() ............................................................110
     OD_PUTTEXT() ..........................................................112
     OD_REPEAT() ...........................................................114
     OD_RESTORE_SCREEN() ...................................................116
     OD_SAVE_SCREEN() ......................................................117
     OD_SCROLL() ...........................................................119
     OD_SEND_FILE() ........................................................121
     OD_SET_ATTRIB() .......................................................125
     OD_SET_COLOUR() .......................................................128
     OD_SET_CURSOR() .......................................................131
     OD_SET_DTR() ..........................................................133
     OD_SET_PERSONALITY() ..................................................135
     OD_SET_STATUSLINE() ...................................................136
     OD_SPAWN() ............................................................138
     OD_SPAWNVPE() .........................................................140
     OD_WINDOW_CREATE() ....................................................142
     OD_WINDOW_REMOVE() ....................................................144

CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE ................................145
     INTRODUCTION TO THE CONTROL STRUCTURE .................................145
     CONTROL STRUCTURE - DOOR INFO FILE STATS ..............................147
     CONTROL STRUCTURE - SERIAL PORT SETTINGS ..............................151
     CONTROL STRUCTURE - BBS AND CALLER INFORMATION ........................156
     CONTROL STRUCTURE - DOOR SETTINGS .....................................179
     CONTROL STRUCTURE - DIAGNOSTICS .......................................182
     CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION ...........................184
     CONTROL STRUCTURE - FUNCTION KEYS .....................................206
     CONTROL STRUCTURE - COLOUR CUSTOMIZATION ..............................210
     CONTROL STRUCTURE - TEXT CUSTOMIZATION ................................212

CHAPTER 6 - SPECIAL TOPICS .................................................215
     CONFIGURATION FILE SYSTEM .............................................215
     DEFINING CUSTOM DOOR INFORMATION FILE FORMATS .........................220
     MULTIPLE PERSONALITY SYSTEM ...........................................223
     LOG FILE SYSTEM .......................................................225
     MAKING DOORS MULTI-NODE-AWARE .........................................227

CHAPTER 7 - DEBUGGING AND GETTING ASSISTANCE WITH OPENDOORS ................228
     ABOUT THIS CHAPTER ....................................................228
     TROUBLESHOOTING PROBLEMS ..............................................228
     SOLUTIONS TO COMMON PROBLEMS ..........................................230
     OPENDOORS SUPPORT .....................................................232
     THE OPENDOORS SUPPORT BBS .............................................232
     THE OPENDOORS SUPPORT CONFERENCE ......................................233
     GETTING IN TOUCH WITH ME ..............................................233

APPENDIX A - CONTENTS OF PACKAGE ...........................................236

APPENDIX B - CHANGES FOR THIS VERSION ......................................237


===============================================================================
OpenDoors 5.00 Manual                                             End of Page 3


APPENDIX C - FUTURE VERSIONS ...............................................243

APPENDIX D - SPECIAL THANKS ................................................245

GLOSSARY ...................................................................246

INDEX ......................................................................255
















































===============================================================================
OpenDoors 5.00 Manual                                             End of Page 4


-------------------------------------------------------------------------------
CHAPTER 1 - INTRODUCTION TO OPENDOORS
-------------------------------------------------------------------------------




WELCOME!
-------------------------------------------------------------------------------

               Welcome to OpenDoors! OpenDoors is a powerful and easy to use
               door programming toolkit. OpenDoors provides a complete system
               that allows you to EASILY and QUICKLY write spectacular,
               professional quality BBS doors that automatically support all
               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/RIP graphics
               support and BBS interfacing through 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, and so on. In addition, OpenDoors carries out all
               the work involved in keeping track of carrier detection, user
               timeouts and much, much more. Serial I/O is performed using
               either a FOSSIL driver, or built-in serial I/O capabilities,
               making the use of a FOSSIL driver optional. OpenDoors can also
               be completely customized, allowing you to take as little or as
               much control of your program's behavior as you wish - and
               imposing no limit on the possibilities of what you can do with
               the package.

               This manual is included with the C / C++ version of OpenDoors,
               which can be used in conjunction with C and C++ compilers from
               Microsoft, Borland, and others. It is possible that versions of
               OpenDoors for other programming languages have been made
               available since the time this version was released.



FEATURES OF THE OPENDOORS DOOR TOOLKIT
-------------------------------------------------------------------------------

               OpenDoors is a complete door programming 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. Are you 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 do it much more easily than ever before.


===============================================================================
OpenDoors 5.00 Manual                                             End of Page 5


               Unlike other similar libraries, OpenDoors provides all the
               following features:

               -  OpenDoors handles all the "dirty" work involved in writing
                  door programs. Are you interested in writing doors for BBSes,
                  either your own, or to distribute (even sell!) to other
                  people? Since OpenDoors handles all 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 OpenDoor's simple functions to
                  input, output and control door operation. In fact, many
                  people have converted 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 the
                  modem's carrier detect signal, to automatically recover when
                  a user hangs up - 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. In addition to the many door information file formats
                  supported by OpenDoors, you are also able to define your own
                  custom formats.

               -  OpenDoors also does all the work involved in displaying and
                  automatically updating the door's status line, with
                  information available to the sysop such as user name,
                  location, baud rate, time left, function keys,
                  ANSI/AVATAR/RIP settings, and so on. Using OpenDoors, you can
                  choose from a number of different "personalities". These
                  personalities allows OpenDoors to mimic the status lines and
                  sysop function keys used in various BBS packages. OpenDoors
                  includes personalities that mimic RemoteAccess, PC-Board and
                  Wildcat! OpenDoors also allows you to create your own
                  personalities to mimic any other BBS system.

               -  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, OpenDoors 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

===============================================================================
OpenDoors 5.00 Manual                                             End of Page 6


                  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 behavior. There are even people who begin door
                  programming with OpenDoors, having never programmed in C in
                  the past.

               -  OpenDoors supports both FOSSIL-based and built-in serial I/O
                  capabilities. FOSSIL-based serial I/O can be used for maximum
                  compatibility with various systems and serial ports,
                  including multiple-port serial cards such as DigiBoard.
                  OpenDoors can also operate without a FOSSIL driver, using
                  it's own serial I/O capabilities. OpenDoor's built-in
                  asynchronous communcations supports baud rates of up to
                  115,200 and non-standard serial port configurations.
                  OpenDoors also has the ability to automatically detect which
                  of the two serial I/O methods should be used on a particular
                  system.

               -  OpenDoors also automatically detects when the BBS system is
                  operating in local mode, and supports full local mode
                  operations itself.

               -  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 detect whether the user has screen clearing
                  turned on), and various ANSI/AVATAR/RIP control functions
                  (which again detect if the user has graphics mode turned on).

               -  In addition to the basic display features of OpenDoors there
                  are also a number of advanced screen control functions. These
                  include functions to save and restore the entire screen,
                  along with functions to save, restore or scroll portions of
                  the screen. Other functions allow you to provide overlapping
                  windows and pop-up menus with highlighted selection bars.

               -  OpenDoors has a number of special sub-systems that you may
                  elect to include in your doors. Among these, is 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 5.00 Manual                                             End of Page 7



               -  OpenDoors can also be fully customized in order that you may
                  write door programs that use languages other than English.

               -  Among the ANSI/AVATAR/RIP features found in OpenDoors is the
                  ability to send ANSI/AVATAR/RIP 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 number of
                  example doors, which 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.

               -  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.

               -  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 5.00 Manual                                             End of Page 8


-------------------------------------------------------------------------------
CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING
-------------------------------------------------------------------------------




THE DEMO VERSION & BENEFITS OF REGISTERING
-------------------------------------------------------------------------------

               This archive contains the demonstration version of OpenDoors.
               This version has all the features of the registered version, but
               you are only permitted to use it under limited circumstances:

               1.) The demo (unregistered) version may only be used for a one
                   month period, for evaluation purposes.

               2.) Programs written in this version may not be distributed.

               Also, any program written with the demo version will display a
               message to the user indicating that OpenDoors 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 will 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 US, $34 Canadian, or your
               countries equivalent! (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 receiving ALL future upgrades for free.)

               Also, the source code for OpenDoors is now available to
               registered users for an additional $28US / $34CDN / equivalent!
               Ordering a copy of the source code will allow you to customize

===============================================================================
OpenDoors 5.00 Manual                                             End of Page 9


               OpenDoors for your own use, making any changes or additions that
               you wish. It also gives 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 22.
















































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 10






HOW TO ORDER
-------------------------------------------------------------------------------

PLEASE         Below are detailed instructions for registering OpenDoors.
NOTE           These instructions are not intended to be 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 233.

               OpenDoors can be ordered by either mailing the OpenDoors order
               form, or online on Compuserve. If you are a Compuserve
               subscriber and you wish to order OpenDoors by this means, see
               the secton on ordering through Compuserve, on page 19.
               Otherwise, follow the following three steps:

               1.)  Fill out the registration form. Information on filling out
                    the form is located on page 13.

               2.)  Send the appropriate payment, $28US/$34CDN/equivalent for
                    the registration or $56US/$68CDN/equivalent 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 15. Included in that section is
                    a list of equivalent prices for a number of other
                    countries.

               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 conventional 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 22.

               Also, you may wish to send the OpenDoors feedback form (located
               on page 21), along with your registration. The feedback form
               gives you a chance to tell me what you think of OpenDoors, and

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 11


               what changes you would like to see in future versions. In fact,
               the majority of suggestions made on these forms in the past have
               already been implemented in the current version of OpenDoors.




















































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 12






FILLING OUT THE REGISTRATION FORM
-------------------------------------------------------------------------------

               If you have printed the OpenDoors manual, you can simply remove
               and mail the forms on pages 20 and 21. 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-
               written 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
               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. The following options are
               available:

                         - Having me send the registration and/or source code
                           by conventional mail
                         - Having me call to your BBS
                         - You calling the OpenDoors support BBS
                         - FidoNet "CrashMail"
                         - Internet E-Mail

               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 on ordering the source code,
               which begins on page 22.


-------------------------------------------------------------------------------
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.



===============================================================================
OpenDoors 5.00 Manual                                            End of Page 13


-------------------------------------------------------------------------------
RECEIVING      In order to receive your OpenDoors registration key and/or
ORDER BY       source code by a message and/or upload to your BBS, fill out
CALL TO        the order form and mail it along with your payment as described
YOUR BBS       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
               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      You may choose to receive your OpenDoors registration and/or
ORDER BY       source code by calling the OpenDoors BBS after your registration
CALLING        form and order fee have been received here. If you are unable to
OPENDOORS      receive your order by any other electronic means (such as a call
BBS            to your BBS, or by electronic mail), this may be the quickest
               way for you to recieve your registration information and/or
               source code. The obvious disadvantage with to option is the fact
               that you will have to estimate when your order will arrive here
               in order to receive it as quickly as possible. You may end up
               calling the OpenDoors BBS more than once before your order has
               arrived. After your order form has arrived, your registration
               key and/or source code will be placed on hold for you, and you
               will be able to receive it on your first call to the BBS. The
               phone number of the BBS is:

                         +1 613 526 4466


-------------------------------------------------------------------------------
RECEIVING      If you wish to receive your OpenDoors registration key by
ORDER BY       Internet E-Mail (including Internet E-Nail to a Compuserve
INTERNET       account), fill out the order form and mail it along with your
E-MAIL         payment as described below. Be sure to include your e-mail
               address on your order form. Note that the source code cannot be
               sent via Internet e-mail.


-------------------------------------------------------------------------------
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 5.00 Manual                                            End of Page 14






SENDING YOUR ORDER FEE
-------------------------------------------------------------------------------

               The price of OpenDoors is 34 Canadian Dollars, 28 U.S. Dollars,
               or equivalent for the registration. The source code costs an
               additional 34 Canadian Dollars, 28 U.S. Dollars, or equivalent.
               For your convenience, the equivalent value in a number of other
               country's currencies, at the time of this writing, is as
               follows:

                       -----------------------------------------------
                                                REGISTRATION
                       REGISTRATION ONLY        AND SOURCE CODE
                       -----------------------------------------------
                       34 Canadian Dollars      68 Canadian Dollars
                       28 US Dollars            56 US Dollars
                       18 British Pounds        36 British Pounds
                       150 French Francs        300 French Francs
                       44 German Marks          88 German Marks
                       50 Netherland Gilders    100 Netherland Gilders
                       39 Australian Dollars    78 Australian Dollars
                       -----------------------------------------------

               This order fee may be payed using any of the following methods:

               -Cheque or Money Order in Canadian currency, drawn upon a
                Canadian bank. In this case, your order fee will be either
                $34CDN for just the registration, or $68CDN 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 COUNTRY'S
                CURRENCY, equivalent to 34 Canadian 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 $34 Canadian dollars, drawn on a British
                Bank.

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 15



               -Cash. 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
               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 233.






























===============================================================================
OpenDoors 5.00 Manual                                            End of Page 16






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.

REQUIREMENTS   In order to re-compile the OpenDoors source code, you must be
               using a Borland compiler that supports inline assembly language
               keywords. This includes Turbo C++ or Borland C++ 2.0 or later.

               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 5.00 Manual                                            End of Page 17


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, I cannot send the source code by BBS upload
               or CrashMail to sites outside of North America that operate at
               2400 bps or slower.














































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 18






ORDERING THROUGH COMPUSERVE
-------------------------------------------------------------------------------

               As an alternative to mailing a cheque / money order / cash along
               with the OpenDoors order form, you can order an OpenDoors online
               on Compuserve. The cost of OpenDoors will automatically be
               billed to your CompuServe account. Unless you have previously
               notified me that you wish to receive your order by some other
               means, your order will be set by conventional mail. To order
               OpenDoors online through CompuServe, GO SWREG. The registration
               ID for ordering JUST the OpenDoors registration ($28U.S. at the
               time of this writing) is 3270. The registration ID for ordering
               BOTH your OpenDoors registration and the OpenDoors source code
               ($56U.S. at the time of this writing) is 3271. Note that the
               price for registering OpenDoors through CompuServe may increase
               to 15% more than the price for ordering OpenDoors through the
               mail, due to the high processing fee I am charged by CompuServe.
               However, the price for ordering online through CompuServe is
               currently the same as for ordering by any other means. The price
               that you will be paying to order through CompuServe will be
               displayed before you agree to the registration, so you will know
               whether or not the price has changed before purchasing
               OpenDoors.




























===============================================================================
OpenDoors 5.00 Manual                                            End of Page 19


--------------------------------------------------------------------------
                        OPENDOORS 5.00 ORDER FORM
--------------------------------------------------------------------------

         YOUR NAME : _______________________________   (AS SHOULD APPEAR IN
                                                        REGISTRATION)
    POSTAL ADDRESS : ______________________________________________________

                     ______________________________________________________

VOICE PHONE NUMBER : ______________________

  E-MAIL 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:
          ___                                ___
         |   | - CONVENTIONAL MAIL          |   | - FIDONET "CRASHMAIL"
         |___|                              |___|
          ___                                ___
         |   | - CALL TO MY BBS             |   | - INTERNET E-MAIL
         |___|                              |___|   (REGISTRATION KEY ONLY)
          ___                                ___
         |   | - CALL TO OPENDOORS BBS      |   | - COMPUSERVE MAIL
         |___|                              |___|   (REGISTRATION KEY ONLY)

                        ___
I WOULD LIKE TO ORDER: |   | - JUST MY REGISTRATION KEY
                       |___|   ($28 or EQUIVALENT)
                        ___
                       |   | - JUST THE SOURCE CODE (ONLY IF ALREADY
                       |___|   REGISTERED) ($28 OR EQUIVALENT)
                        ___
                       |   | - BOTH REGISTRATION KEY AND SOURCE CODE
                       |___|   ($56 OR EQUIVALENT)


I AGREE TO THE OPENDOORS TERMS, SET           ____________________________
FORTH ON PAGE 22 OF THE MANUAL                (SIGNATURE)

MAKE CHEQUES PAYABLE TO:   BRIAN PIRIE
                           APT. 1416 - 2201 RIVERSIDE DR.
                           OTTAWA, ONTARIO
                           CANADA
                           K1H 8K9

+-- OFFICIAL USE ONLY ----------------------------------------------------+
|                                                                         |
| Rcvd : _______  Date : _________  S.N. : _________  Key : _____________ |
+-------------------------------------------------------------------------+

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 20


--------------------------------------------------------------------------
          OPENDOORS DOOR PROGRAMMING TOOLKIT 5.00 - USER FEEDBACK FORM
--------------------------------------------------------------------------

         YOUR NAME : _______________________________

    POSTAL ADDRESS : ______________________________________________________

                     ______________________________________________________

VOICE PHONE NUMBER : ______________________

 NETWORK ADDRESSES : ____________________________________   (IF APPLICABLE)


HOW DID YOU FIRST LEARN OF OPENDOORS?

             ____________________________________________________________


WHICH LANGUAGE / COMPILER AND VERSION ARE YOU USING?  (EG. BORLAND C++ 3.10)

             ____________________________________________________________


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 5.00 Manual                                            End of Page 21






TERMS OF REGISTRATION AND SOURCE CODE USE
-----------------------------------------------------------------------------

               When you purchase an OpenDoors registration and/or source code,
               you are entitled to almost unlimited use of all versions of
               OpenDoors. However, in order to protect my investment of time
               and effort in developing OpenDoors, you must also agree to the
               terms outlined below when purchasing an OpenDoors registration
               and/or the source code. These terms are very reasonabl, and are
               in no way intended to limit your use of OpenDoors. The primary
               intent of these terms is that you are not permitted to disclose
               your OpenDoors registration information, or the OpenDoors source
               code, to other individuals. The exception to this requirement is
               when OpenDoors is registered by an organization, the OpenDoors
               registration information and source code may be shared among
               members of that organization, for use within the organization.
               For instance, if OpenDoors is registred to a particular company,
               only a single registration is required for the company, but it
               may not be used by employees for their personal use. The terms
               of registration and source code use are as follows:

               For the purpose of these terms, "OpenDoors" is defined to be the
               library files, header files, example programs and programmer's
               manual of all versions, past and present, for all languages and
               platforms of the OpenDoors door programming toolkit. Upon
               registering OpenDoors, the individual or organization named on
               the registration form (the registree) is entitled to use of all
               versions of OpenDoors, within the terms set forth below.
               Violation of these terms will be considered copyright
               infrindgement, and grounds for the termination of the
               registration agreement. The registree is entitled, at no
               additional cost, to use, distribute or sell the executable (.EXE
               or .COM) files that result from using the OpenDoors door
               programming toolkit. The registree is also entitled to use,
               distribute or sell the example programs, example configuration
               files and portions of the user manual. If purchasing the source
               code, the registree is also entitled to distribute any
               executable files that result from using altered versions of the
               source code, or portions thereof. The registree is NOT entitled
               to distribute the registration key number presented to them at
               registration, or any portions of the OpenDoors source code. For
               the purposes of these terms, an organization is considered to be
               a company or non-profit organization. If the registree is an
               organization, the registration key and source code may be shared
               among members of the organization, under the condition that
               these individuals are using the registration and/or source code
               only for official activities of that organization. These terms
               in no way suggest an agreement on the part of Brian Pirie to
               develop any future versions of OpenDoors, or fix any bugs in
               current versions of OpenDoors. OpenDoors is offered "as is", and

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 22


               no warantees are expressed or implied. In no event shall Brian
               Pirie be liable for any loss of profit or any other damage,
               including but not limited to special, incidental, consequential
               or other damages.



















































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 23




-----------------------------------------------------------------------------
CHAPTER 3 - OPENDOORS TUTORIAL
-----------------------------------------------------------------------------




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 5, serves
               as an introduction and overview of the features of OpenDoors.
               Chapter 2, beginning on page 9, 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 provides information on special
               OpenDoors features and special topics related to door
               programming. Among the subjects discussed in chapter 6 are
               configuration files, multi-node operation, RIP graphics, logfile
               support, defining custom door information file formats, and
               more.

               Chapter 7 (which begins on page 228) 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 255, is an index to
               help you locate more information on specific topics. The manual
               also includes a glossary, on page 246, 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,

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 24


               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. 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.)  You must include the OPENDOOR.H header file.

               2.)  You must link your program with the appropriate OpenDoors
                    library file.


               All programs written with OpenDoors, must "include" the
               OPENDOOR.H header file. If you have placed the OPENDOOR.H header
               file in the same directory as your door's source code, place the
               following line at the beginning of your .C or .CPP file(s):

                    #include "opendoor.h"

               If you have placed the OPENDOOR.H header file in the same
               directory as other standard header files (such as stdio.h),
               place the following line at the beginning of your .C or .CPP
               file(s):

                    #include <opendoor.h>

               In addition to including the OpenDoors header file in your
               source code modules, you must also "link" the OpenDoors library
               file with your program. The procedure for doing this depends
               upon which compiler you are using. The next few paragraphs
               describe how to link with the OpenDoors libraries using a
               various compilers. Following that I explain how to choose the
               appropriate library for the memory model you are using.



===============================================================================
OpenDoors 5.00 Manual                                            End of Page 25


               If you are using Borland Turbo C 2.00 or earlier, you can cause
               your compiler to link your program with the OpenDoors library by
               creating a text file with a .PRJ extension. In this text file,
               you should list the names of your program's .C modules, along
               with the name of the appropriate OpenDoors library file, as
               listed in the table at the end of this section. You should then
               select this Project file from within the Turbo C IDE prior to
               compiling your program.

               If you are using Turbo C++ or Borland C++, you can cause your
               compiler to link your program with the OpenDoors library by
               creating a project file from within the IDE. To do this, choose
               the Open Project command from the Project menu, and eter the
               name for your new project file in the Load Project dialog box.
               Then add the names of your program's .C/.CPP modules, along with
               the name of the appropriate OpenDoors library file, by pressing
               [Insert] in the project window. When you return to Turbo C++ or
               Borland C++ again, you can work with the same project file by
               using the Open command from the Project menu.

               If you are using any Microsoft C compiler, such as Quick C,
               Microsoft C or Visual C++, you can cause your compiler to link
               your program with the OpenDoors library by creating a makefile.
               You can create a new project file from within Quick C by using
               the Set Program List option from the Make menu. You can do this
               from within Visual C++ by using the New command from the Project
               menu. You should add the names of your program's .C/.CPP source
               files, along with the name of the appropriate OpenDoors library
               file, to the newly create makefile.

               For more information on how to link your program with third-
               party library files such as OpenDoors, consult the manuals that
               are included with your compiler.

               There are a number of different library files included with
               OpenDoors, each one for use with a different 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. Whenever you change your compiler to use a different
               memory model, it is important to rebuild all of your source
               files (using the "Build All" or "Rebuild All" command) in
               addition to changing the library that your program is being
               linked with. If you are unfamiliar with the concept of memory
               models, you should refer to your compiler's manuals. If you are
               unsure as to what memory model your compiler is currently using,
               check this setting in the compile options dialog box or command
               line reference information.







===============================================================================
OpenDoors 5.00 Manual                                            End of Page 26


                  +------------------------------------------------+
                  | 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 |
                  |             | (Available separately)           |
                  |             |                                  |
                  | ODOORL.LIB  | The Large memory model library   |
                  |             |                                  |
                  | ODOORH.LIB  | The Huge memory model library    |
                  +------------------------------------------------+

               To understand how to compile a program written with OpenDoors,
               it is a good idea to try compiling one of the example programs,
               such as ex_hello.c, that are included in the OpenDoors package.




































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 27






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. 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
               programs function correctly. You are also encouraged to look at
               the sample doors included with OpenDoors. These programs, which
               are described beginning on page 38, will give you a much better
               idea of what an OpenDoors program will look like, and provides
               you with a starting point for writing your own door programs.

               Probably the best means of introduction to door programming with
               OpenDoors is by doing it yourself. As such, I strongly encourage
               you to try typing in, compiling and running the simple
               introduction program below. For instructions on compiling
               programs written with OpenDoors, see page 25.

                    #include "opendoor.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);
                       }

               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 od_printf() function. od_printf() is
               similar to the printf() function that C programmers will already
               be famailiar with. However, unlike printf(), the od_printf()
               function sends the output to both the modem and the local
               screen. Notice that the lines of text displayed by the
               od_printf() function end with a "\n\r" sequence, instead of the
               normal "\n". This is because hte terminal emulation software
               that is running on the remote user's system usually requires
               both a carriage return and a line feed to correctly begin a new
               line. The next line in our example program is the OpenDoors
               single-key input function, od_get_key(). The TRUE value causes
               OpenDoors to wait for a key to be pressed (again, either from
               remote or local keyboard) before returning.

               Once again, you are encouraged to try compiling and running this
               program on your own BBS setup, as described above.

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 28


               Congratulations, you have written your first door program! Feel
               free to make any changes to this program, and see what effects
               your changes have.

               In case you are not entirely 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) (sometimes called a "drop file") 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, PC-
               Board or whatever), will create a file of information about the
               system, who is currently on-line, and so on. Various BBS
               packages produce various styles of door information files.
               OpenDoors automatically recognizes and reads a wide variety of
               door information file formats. As a result, your doors will be
               able to run on a almost any BBS system.

               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 run the appropriate door program. (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 through the modem.

               Fortunately, OpenDoors takes care of all the work involved in
               detecting and reading the door information file, and then
               initializing and communicating with the serial port 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 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 function, 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/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
               structure will vary. For more information on the od_control

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 29


               structure, see the section on the control structure, beginning
               on page 145.

               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, these shut-down operations are
               automatically performed when your C or C++ program exits
               normally. If you wish to explicitly control OpenDoor's behaviour
               when exiting, you may exit the door program by calling 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.

               One other important OpenDoors function that you should be aware
               of is the od_kernel() function. od_kernel() is the central
               OpenDoors control function, and is responsible for much of
               OpenDoor's updating of the status line, monitoring the carrier
               detect and user timeout status, responding to sysop function
               keys, and so on. The od_kernel() function is called
               automatically by OpenDoors, within the other OpenDoors
               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_kernel() 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 function for
               more than a few seconds, you should then call the od_kernel()
               function yourself. For more information on the od_kernel()
               function, see page 96.

               For more information on the functions available from OpenDoors,
               or the control structure, see the corresponding sections in this
               manual. I would also suggest that you have a look at the sample
               door included with OpenDoors, EZVote.

















===============================================================================
OpenDoors 5.00 Manual                                            End of Page 30






TOUR OF 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 programs. A brief description of each of
               these programs can be found on page 38. This section takes a
               closer look at one of the example programs, "EZVote".

               In your OpenDoors package you will find five .C source files for
               the EZVote program, named EX_VOTE1.C to EX_VOTE5.C. Each of
               these source files shows a further step in the process of
               building the EZVote program. EX_VOTE1.C lays the foundation with
               the code to display the main menu and respond to basic commands
               such as exiting the program. EX_VOTE2.C adds the user interface
               for the remaining commands, EX_VOTE3.C adds the underlying data
               file code, EX_VOTE4.C adds color and EX_VOTE5.C adds the
               finishing touches. You will probably want to begin by looking at
               EX_VOTE1.C, and then proceed to see the additions made to
               subsequent versions of the program. Don't be taken back by the
               complexity of the EZVote program - most of the source code is
               involved in accessing the data files used by this program, which
               is actually more complicated than many door programs will
               require.

               The OpenDoors package includes a compiled version of EZVote,
               which you can run by typing EZVOTE. The OpenDoors package also
               contains a sample door information file, DORINFO1.DEF. You can
               use this file 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                |
               +----------------------------------------------------------+

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 31




               Feel free to make any changes you wish to the EZVote, and
               recompile it. One of the most effective and 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 door programs.

               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, AVATAR
               or RIP 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 theirs 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 user has left, and there will be indicators as
               to whether the user has ANSI/AVATAR/RIP modes turned on, and so
               on. 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 program:


               [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.









===============================================================================
OpenDoors 5.00 Manual                                            End of Page 32


               [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 - Sysop has chosen to return the user to
                                      the BBS
                                  6 - Door has exited normally

                             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. These
                             default errorlevels may be redefined using the
                             od_control.od_errorlevel[] variable.

               [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.

               [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.


               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 EX_VOTE?.C files as well, it would
               probably be a good idea to do so now.

               EX_VOTE1.C Demonstrates the basic elements of any door program.
               This file contains the code to handle display of main menu,
               responding to the user's choice from the main menu, and common

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 33


               commands such as returning to the BBS and paging the system
               operator. This file also demonstrates basics of displaying text
               and retrieving input from user. 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.

               The main() function of the EZVote program has a for(;;) loop
               that repeatedly displays the main menu, obtains a choice from
               the user and responds to the command, until the user chooses to
               exit the program. Before the main menu is displayed, the screen
               is cleared by calling od_clr_scr(). The od_clr_scr() function
               will clear both the local and remote screens, but only if the
               user has screen clearing enabled. Refer to page 57 for
               information on how to force the screen to be cleared, regardless
               of the user's screen clearing setting. The main menu is
               displayed using the od_printf() function, one of the most common
               OpenDoors functions you will use. Next, od_get_answer() is used
               to obtain a menu choice from the user from the specified set of
               keys. Next, a switch() statement is used to respond to the
               user's command appropriately. If the user presses the P key to
               page the system operator, od_page() is called. If the user
               chooses to return to the BBS, od_exit() is called to terminate
               OpenDoor's activities and return control to the BBS. The FALSE
               parameter passed to od_exit() indicates that OpenDoors should
               not disconnect (hangup) before exiting. If the user chooses to
               log off, EZVote first confirms this action with the user, and
               then calls od_exit() with the TRUE parameter. The numerical
               parameter passed to od_exit() sets the errorlevel that OpenDoors
               will exit with.

               EX_VOTE2.C Adds the user interface code to handle the main menu
               commands specific to EZVote, such as answering questions,
               viewing the results of questions, and adding new questions. For
               the most part the new code added to EX_VOTE2.C involves uses the
               same OpenDoors features that we have already looked at. However,
               if you look carefully you will notice some things that we
               haven't encountered before. In its ChooseQuestion() function,
               EZVote uses the OpenDoors function od_get_key(). This function
               is similar to the od_get_answer() function that we have already
               seen. However, unlike od_get_answer() which will wait until the
               user presses some key from the list of possibilities you
               provide, od_get_key() will allow the user to press any key.
               od_get_key() accepts a single parameter. If this parameter is
               TRUE, od_get_key() will wait for the user to press a key before
               returning. If this parameter is FALSE, od_get_key() will return
               immediately with a value of 0 if there are no keys waiting in


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 34


               the inbound buffer, and returning the next key if there are
               characters waiting.

               In a number of places, EX_VOTE2.C also uses the od_input_str()
               function. Unlike od_get_key() and od_get_answer() which return a
               single character, od_input_str() allows the user to input and
               edit a string of many characters. You will only receive the
               string entered by the user after they press the enter key.
               od_input_str() accepts four parameters: the string where the
               user's input should be stored, the maximum number of characters
               to input, the minimum character value to accept and the maximum
               character value to accept.

               Another new feature of OpenDoors that is used by EX_VOTE2.C is
               the OpenDoors control structure, od_control. This global
               structure is documented in chapter 5 of this manual. The
               OpenDoors control structure allows you to access a wide variety
               of information about the user who is currently online, the BBS
               system your program is running on, and also allows you to
               control various OpenDoors settings. For example, EX_VOTE2.C
               compares the current user name (od_control.od_user_name) with
               the name of the system operator (od_control.od_sysop_name) to
               determine whether it is the system operator who using the
               program.

               EX_VOTE3.C adds the code used by EZVote to store the questions
               and users in its data files. EZVote uses two data files, the
               first of which contains a record for every user, and the second
               of which contains a record for every question. EZVote accesses
               these data files in a controlled manner in order to permit the
               program to be running simultaneously on multiple lines on a
               multi-node BBS system. When EZVote needs to update a data file,
               it opens it for exclusive access, so that only one node can
               access the file at any given time. Since the data file could
               have been changed by another node since the time that EZVote
               last read the file, it always reads a record, makes changes to
               it and then re-writes the record while it has the file open for
               exclusive access. It then closes the file as soon as possible
               after opening the file, in order to permit other nodes to once
               again access the file. Because EZVote keeps track of which
               questions each user has voted on, along with the questions and
               results of voting on each question, its data file format is more
               complex than many door programs (although not as complex as
               others).

               EX_VOTE4.C adds the use of colour. One of the easiest ways to
               use different colors in an OpenDoors program is to use the
               OpenDoor's print color-setting extensions. You can change the
               color of text display at any point in an od_printf() format
               string using by enclosing the name of new display color in back
               quote characters (`, not '). For example:

                    od_printf("`red`This is in red `green`This is green\n\r");


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 35


               Would cause the words "This is in red" to be displayed in red,
               and the words "This is in green" to be displayed in green.

               EX_VOTE5.C adds the finishing touches to the EZVote program,
               taking advantage of a number of OpenDoors capabilities that you
               can optionally choose to include in your door programs. You will
               notice that there are a number of new lines at the beginning of
               the main() function, all of which change settings in the
               OpenDoors control structure. The line:

                    od_control.od_config_file = INCLUDE_CONFIG_FILE;

               causes the OpenDoors configuration file system to be included in
               your program. Using this system, OpenDoors automatically reads a
               configuration file that can be used by the system operator to
               change various program settings. Refer to the included door.cfg
               file for an example OpenDoors configuration file. In addition to
               the configuration file settings automatically supported by the
               configuration file system, you can also add your own
               configuration file settings. To do this, you simply supply
               OpenDoors with a callback function that it will call whenever it
               encounters an unrecognized keyword in the configuration file.
               The line:

                    od_control.od_config_function = CustomConfigFunction;

               Causes OpenDoors to call the function CustomConfigFunction() in
               ex_vote5.c for this purpose. You will notice that the
               CustomConfigFunction() receives two parameters - the first is
               the unrecognized keyword, and the second is any parameters that
               follow the keyword in the configuration file. EZVote checks for
               two special configuration file lines - one to set whether or not
               users can add questions, and one to set whether or not users can
               view the results of a question before voting on it.

               The next line in the main() function,

                    od_control.od_mps = INCLUDE_MPS;

               causes the OpenDoors "Multiple Personality System" to be
               included in program. This allows the sysop to choose from a
               number of status line / sysop function key "personalities" that
               mimic a number of different BBS systems, using the Personality
               setting in the configuration file.


               The line:

                    od_control.od_logfile = INCLUDE_LOGFILE;

               causes the OpenDoors log file system to be included in the
               program. The OpenDoors log file system automatically records the
               date and time of program startup, exit and other major actions


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 36


               in the specified file. EZVote also writes its own log file
               entries by calling the od_log_write() function.

               The last major functionally enhancement that is made in the
               EX_VOTE5.C file is the ability for the sysop to provide their
               own ASCII/ANSI/AVATAR/RIP files to be displayed in place of the
               normal main menu. EZVote uses the od_hotkey_menu() function to
               display an EZVOTE.ASC/.ANS/.AVT/.RIP file for the main menu, if
               such a file exists. If the file is not available, the normal
               EZVote menu is used instead. The od_hotkey_menu() function will
               automatically select the appropriate file (.ASC/.ANS/.AVT/.RIP)
               for the current display mode, and the user is able to make a
               menu choice at any time. If a menu choice is made before the
               menu is entirely displayed, the function will stop displaying
               the menu and return immediately.








































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 37






OTHER EXAMPLE DOORS INCLUDED WITH OPENDOORS
------------------------------------------------------------------------------

               In addition to the EZVote door, which is discussed in detail in
               the previous section, a number of other example doors are
               included with OpenDoors. These doors help to demonstrate what is
               possible with OpenDoors. They can also serve as excellent tools
               to help you learn about OpenDoors as quickly as possible. In
               addition, you are free to include any portions of any of these
               example doors in your own door programs. Below is a summary of
               each of these example programs:


-------------------------------------------------------------------------------
EX_HELLO.C     This an example of a very simply door program that displays a
               short message and prompts for the user to press a key. After the
               user presses a key, the door exits and control is returned to
               the main BBS software. Despite the fact that it only consists of
               a few lines of code, EX_HELLO remains a fully functional door
               program. For information on compiling an OpenDoors door program,
               see the section that begins on page 25.


-------------------------------------------------------------------------------
EX_CHAT.C      This program is an example of a multi-window full-screen chat
               door written with OpenDoors. EX_CHAT demonstrates the ease of
               using sophisticated ANSI / AVATAR / RIP terminal features within
               OpenDoors programs. For instructions on how to compile this
               program, see the section that begins on page 25.

               This program create two windows on the screen, separated by a
               bar with user name / sysop name information. This program
               permits communication between the local sysop and remote user by
               displaying the text typed by the user in one window, and the
               text typed by the sysop in the other window. When either
               person's typing reaches the bottom of the window, the contents
               of the window is scrolled up to provide more room for typing.
               Words are also wrapped when either typist reaches the end of a
               line. The advantage of a split-screen chat program is that it
               permits both sysop and user to type at the same time without
               difficulty. The chat function automatically invokes OpenDoor's
               internal chat mode if ANSI, AVATAR or RIP modes are not
               available. The display colours, window sizes and locations, and
               distance to scroll a window's contents are configurable by
               setting the appropriate variables, below. When the Sysop invokes
               a DOS shell, a pop-up window is displayed to indicate to the
               user that the door program has been suspended.




===============================================================================
OpenDoors 5.00 Manual                                            End of Page 38


               The chat feature of this program can also be easily integrated
               into other doors you write, and may be used to replace the
               existing OpenDoors line-oriented chat system.


-------------------------------------------------------------------------------
EX_MUSIC.C     This example door demonstrates how to play "ANSI" music and
               sound effects in an OpenDoors door. Included in this program is
               a function to send "ANSI" music to the remote system, and a
               function to text the remote system's ability to play "ANSI"
               music. You may use both of these functions in your own doors, if
               you wish to add music or sound effect capabilities. This program
               can be compiled by following the instructions that begin on page
                 .                 25


-------------------------------------------------------------------------------
EX_SKI.C       This is a simple but addictive door game that is written using
               OpenDoors. In this action game, the player must control a skier
               through a downhill slalom course. The user may turn the skier
               left or right, and the game ends as soon as the player skis
               outside the marked course. The game begins at an easy level, but
               quickly becomes more and more difficult as the course to be
               navigated becomes more and more narrow. The game maintains a
               list of players with high scores, and this list may be viewed
               from the main menu.


-------------------------------------------------------------------------------
EX_VOTE?.C     The EX_VOTE?.C files contain the source code for the EZVote
               example door, as is described beginning on page 38. The EZVote
               example door allows users to vote on up to 200 different
               "polls", view the results of voting on each question, and
               optionally add their own questions for other users to answer.





















===============================================================================
OpenDoors 5.00 Manual                                            End of Page 39



-------------------------------------------------------------------------------
CHAPTER 4 - THE OPENDOORS API FUNCTIONS
-------------------------------------------------------------------------------




OVERVIEW
------------------------------------------------------------------------------

               All of the door-related activities of an OpenDoors door program
               are coordinated through one of two facilities - the OpenDoors
               API functions, and the OpenDoors door control structure. In
               general, the API functions are used to actually accomplish a
               task, such as displaying something to the user, or retrieving
               input from the user. The OpenDoors control structure, on the
               other hand, is used to alter OpenDoors settings or retrieve
               specific information.

               Any program written with OpenDoors makes use of the OpenDoors
               API functions for all of its door-related input and output. In
               addition to the common input and output tasks, the OpenDoors API
               functions provide access to many special capabilities, such as
               displaying ASCII/ANSI/AVATAR/RIP files, providing pop-up windows
               and menus, and much more. Much of the information about the user
               who is online, information about the system your door is running
               on, and settings which customize OpenDoor's behavior are
               controlled through the OpenDoors control structure. The control
               structure is described in the section beginning on page 145.

               This chapter is divided into the following sections:

                    i.)   TABLE OF MOST COMMONLY USED FUNCTIONS (Page 41)
                   ii.)  TABLE OF ALL OPENDOORS FUNCTIONS (Page 42)
                  iii.) DETAILED INFORMATION ON EACH FUNCTION (Pages 46 - 144)

               The two tables list the names of the OpenDoors functions, along
               with a brief description of the task performed by each function,
               and the page number on which the detailed description of that
               function can be found. The first table lists only the most
               commonly used OpenDoors functions, to allow you to quickly find
               the function you are most likely looking for. The second table
               lists all of the OpenDoors functions, grouped according to
               general categories of functionality.

               The section containing detailed information lists all of the
               functions in alphabetical order, with the information about each
               function beginning on a new page. This section includes a brief
               description of each function's purpose, a detailed description
               of how to use the function, the function call format, a list of
               related functions, and in many cases example source code showing
               you a typical use of the function.


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 40






TABLE OF MOST COMMONLY USED FUNCTIONS
------------------------------------------------------------------------------

               od_printf()         Displays text, with the ability to change
                                   display colour. (page 105)

               od_clr_scr()        Clears the screen. (Page 57)

               od_input_str()      Inputs a string of one or more characters
                                   from the user. (Page 94)

               od_get_answer()     Inputs a single key from a list of possible
                                   choices ignoring upper/lower case. (Page 83)

               od_get_key()        Inputs any single key from the user.
                                   (Page 84)

               od_set_cursor()     Positions the cursor in ANSI/AVATAR/RIP
                                   modes. (Page 131)

               od_hotkey_menu()    Displays an ASCII/ANSI/AVATAR/RIP file, with
                                   the option of watching for a keypress from
                                   the user. (Page 89)

               od_popup_menu()     Displays a popup menu in ANSI/AVATAR/RIP
                                   modes. (Page 102)

               od_window_create()  Creates a popup window in ANSI/AVATAR/RIP
                                   modes. (Page 142)

               od_window_remove()  Removes a popup window in, restoring screen
                                   contents "underneath" window. (Page 144)



















===============================================================================
OpenDoors 5.00 Manual                                            End of Page 41






TABLE OF ALL FUNCTIONS
-------------------------------------------------------------------------------
OUTPUT         TEXT DISPLAY FUNCTIONS
FUNCTIONS      ----------------------
               od_disp_str()            Displays a normal, NULL-terminated
                                        string. (page 64)

               od_disp()                Sends the specified number of
                                        characters to the modem, with or
                                        without local echo. (page 60)

               od_printf()              Performs formatted output, as the
                                        printf() function does. Also allows
                                        imbedded codes to change display
                                        colour. (page 105)

               od_putch()               Displays a single character. (page 110)

               od_disp_emu()            Displays a string, interpreting
                                        imbedded ANSI/AVATAR terminal emulation
                                        codes. (page 62)

               od_repeat()              Displays the same character any number
                                        of times, using AVATAR optimization, if
                                        possible. (page 114)

               COLOUR AND CURSOR CONTROL
               -------------------------
               od_set_colour()          Sets current colour to specified
                                        foreground and background settings.
                                        (page 128)

               od_set_attrib()          Sets current colour to specified IBM-PC
                                        display attribute. (page 125)

               od_set_cursor()          Sets the position of the cursor, if
                                        ANSI/AVATAR/RIP mode is enabled. (page
                                        131)

               SCREEN MANIPULATION
               -------------------
               od_clr_scr()             Clears the screen, if user has screen
                                        clearing enabled. (page 57)

               od_save_screen()         Stores the current contents of the
                                        screen, to be later redisplayed using
                                        od_restore_screen(). Works in all
                                        display modes. (page 117)



===============================================================================
OpenDoors 5.00 Manual                                            End of Page 42


               od_restore_screen()      Restores the contents of the screen, as
                                        previously stored using
                                        od_save_screen(). Works in all display
                                        modes. (page 116)

               BLOCK MANIPULATION
               ------------------
               od_clr_line()            Clears the remainder of current line.
                                        (page 55)

               od_gettext()             Stores any area of the screen, to later
                                        be displayed by od_puttext(). Requires
                                        ANSI/AVATAR/RIP graphics mode. (page
                                        88)

               od_puttext()             Displays text with colour information,
                                        as previously stored using
                                        od_gettext(). Requires ANSI/AVATAR/RIP
                                        graphics mode. (page 112)

               od_scroll()              Scrolls a portion of the screen in
                                        ANSI/AVATAR/RIP graphics modes. (page
                                        119)

               POPUP WINDOWS AND MENUS
               -----------------------
               od_draw_box()            Draws a box on the screen in
                                        ANSI/AVATAR/RIP graphics mode. (page
                                        66)

               od_window_create()       Displays a popup window, storing the
                                        screen contents "under" the window.
                                        Requires ANSI/AVATAR/RIP graphics mode.
                                        (page 142)

               od_window_remove()       Removes a popup window displayed with
                                        od_window_create(), restoring the
                                        original screen contents "under" the
                                        window. Requires ANSI/AVATAR/RIP
                                        graphics mode. (page 144)

               od_popup_menu()          Displays a menu in a popup window,
                                        allowing the user to choose menu items
                                        either by pressing a "hot" key, or
                                        moving a highlighted selection bar.
                                        After menu selection, the menu may be
                                        removed, restoring the original screen
                                        contents "under" the window. Requires
                                        ANSI/AVATAR/RIP graphics mode. (page
                                        102)

               FILE DISPLAY FUNCTIONS
               ----------------------


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 43


               od_send_file()           Displays an ASCII/ANSI/AVATAR/RIP file
                                        (for instance, an .ANS file created by
                                        a program such as "TheDraw" (page 121)

               od_hotkey_menu()         Displays an ASCII/ANSI/AVATAR/RIP menu
                                        file, with hotkeys active. (page 89)

               od_list_files()          Lists the files available for download
                                        in an area, using a FILES.BBS file.
                                        (page 98)


-------------------------------------------------------------------------------
INPUT          od_get_answer()          Inputs a single key from the keyboard,
FUNCTIONS                               allowing only particular responses.
                                        (page 83)

               od_get_key()             Inputs a single key from the keyboard,
                                        optionally waiting if a key is not
                                        available. (page 84)

               od_input_str()           Inputs a string of specified length,
                                        from the keyboard. (page 94)

               od_edit_str()            Formatted string editing function,
                                        requiring ANSI/AVATAR/RIP graphics.
                                        (page 70)

               od_clear_keybuffer()     Removes any waiting keys from the
                                        keyboard input queue. (page 53)


-------------------------------------------------------------------------------
COMMON         od_page()                Allows the user to page the sysop.
DOOR                                    (page 101)
ACTIVITY
FUNCTIONS      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 138)

               od_spawnvpe()            OpenDoors full-featured spawn function.
                                        Executes an external program on a
                                        separate screen, searching the path for
                                        the program, allowing you to specify an
                                        environment to pass to the child
                                        process, and returning the errorlevel
                                        returned by the child process. (page
                                        140)

               od_log_write()           Adds an entry to the end of the log
                                        file. (page 100)


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 44



-------------------------------------------------------------------------------
SPECIAL        od_init()                Begins door operation by setting up
CONTROL                                 the OpenDoors control structure,
FUNCTIONS                               setting up the local screen,
                                        initializing the serial port (if
                                        applicable), and reading the door
                                        information file. (page 91)

               od_colour_config()       Transfers a colour configuration line
                                        to a colour attribute value. (page 59)

               od_add_personality()     Adds a custom status line/control key
                                        personality to OpenDoors. (page 46)

               od_set_statusline()      Temporarily alters the setting of the
                                        current OpenDoors status line. (page
                                        136)

               od_autodetect()          Automatically determines the remote
                                        terminal software's graphical
                                        capabilities. (page 48)

               od_kernel()              The central OpenDoors control function,
                                        which should be executed every few
                                        seconds. (page 96)

               od_exit()                Ends door operations, closing the
                                        serial port driver, re-writing the door
                                        information file, and optionally
                                        returning control to the BBS. (page 81)

               od_carrier()             Allows detection of carrier signal in
                                        programs that have disabled OpenDoors
                                        internal checking. (page 51)

               od_set_dtr()             Controls the DTR signal to the modem.
                                        Can be used to manually disconnect a
                                        remote user, in order to perform
                                        activities such as call back
                                        verification. (page 133)

               od_chat()                Forces OpenDoors to enter chat mode,
                                        even if sysop did not press the "chat"
                                        key. (page 50)










===============================================================================
OpenDoors 5.00 Manual                                            End of Page 45






OD_ADD_PERSONALITY()
-------------------------------------------------------------------------------

PURPOSE        Installs a custom status line / sysop function key personality
               into OpenDoors.


FORMAT         int od_add_personality(char *name, char output_top, char
               output_bottom, void (*function)(unsigned char));


RETURNS        TRUE on success
               FALSE on failure


DESCRIPTION    If used, this function should be called before any other
               OpenDoors API functions. Installs a new personality into
               OpenDoors. The first parameter specifies the string that will be
               used to identify the personality. This is the string that the
               user will be able to supply in the configuration file to select
               this personality, and is also the string that can be passed to
               od_set_personality() to manually switch to this personality. The
               second and third parameters specify the 1-based to and bottom
               line numbers of the output window to be used with this
               personality. For instance, a top value of 1 and bottom value of
               23 would cause all door output to be displayed on the first 23
               lines of the screen, leaving the bottom two lines for use by the
               personality's status line. The last parameter is a pointer to
               the personality function, which OpenDoors will call to perform
               various operations with that involve the personality. OpenDoors
               will pass one of the following values to the personality
               function, indicating the operation that the function should
               perform:

               PEROP_INITIALIZE    Initialize the personality, installing any
                                   custom function keys.
               PEROP_DEINITIALIZE  Deinitialize the personality, returning any
                                   changed settings to their original values.
               PEROP_CUSTOMKEY     Indicates that a custom function key has
                                   been pressed.
               PEROP_DISPLAYx      Where x is a number from 1 to 10. Indicates
                                   that the specified status line should be
                                   drawn from scratch.
               PEROP_UPDATEx       Where x is a number from 1 to 10. Indicates
                                   that the specified status line should be
                                   updated to reflect any changes.

               For more information on personalities and the OpenDoors Multiple
               Personality System, see the section which begins on page 223.


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 46


SEE ALSO       od_set_personality(), od_set_statusline()






















































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 47






OD_AUTODETECT()
-------------------------------------------------------------------------------

PURPOSE        Attempts to automatically determine the terminal capabilities of
               the remote system.


FORMAT         void od_autodetect(int flags);


RETURNS        N/A


DESCRIPTION    This function can be used to determine whether or not the remote
               terminal supports ANSI and/or RIP (Remote Imaging Protocol)
               graphics modes. This information is usually supplied to the door
               by the BBS software, through the door information file. For this
               reason, most door programs do not need to make used of this
               function. However, if your door will be running under any BBS
               software that does not report the ANSI or RIP capabilities of
               the remote system, you may wish to use this function.
               od_autodetect() will set either of the following OpenDoors
               control structure variables to TRUE if the corresponding
               graphics mode is detected:

                    od_control.user_ansi     - TRUE if ANSI mode is available
                    od_control.user_rip      - TRUE if RIP mode is available

               However, if either of these variables have previously been set
               to TRUE (either explicitly by your program, or due to the
               corresponding modes being enabled in the door information file),
               and od_autodetect() does not detect the corresponding graphics
               mode, they will not be set to FALSE. Not all terminal software
               that supports ANSI or RIP graphics mode will necessarily have
               the ability to report their graphics mode capabilities to the
               door. For this reason, failure to detect either of these modes
               does not necessarily indicate that they are not available.
               However, if these modes are detected by od_autodetect(), it is
               safe to assume that the remote system does support the detected
               mode.

               The flags parameter is reserved for future use, and should
               always be set to DETECT_NORMAL.

               This function does not support auto-detection of AVATAR mode,
               because there is no standard means of determining whether a
               remote system supports AVATAR graphics.




===============================================================================
OpenDoors 5.00 Manual                                            End of Page 48


EXAMPLE        Below is an example of using od_autodetect() in determining the
               remote terminal's graphics capabilities. Since not all terminal
               software supports auto-detection, this example will also prompt
               the user to determine their software's capabilities if
               od_autodetect() fails to detect ANSI mode. This code assumes
               that if the terminal software supports the autodetection of ANSI
               mode, that it will also support the autodetection of RIP mode.
               OpenDoors assumes that ANSI mode is always available in
               conjunction with RIP mode.

                    /* Call the automatic terminal detection function */
                    od_autodetect();

                    /* If ANSI mode was not detected, ask the user about
                    if(!od_control.user_ansi)
                       {
                       /* Prompt the user for ANSI capabilities */
                       od_clr_scr();
                       od_printf("Does your system support ANSI graphics?");
                       od_printf(" (Y/N)");

                       /* If the user chooses [Y]es */
                       if(od_get_answer("YN") == 'Y')
                          {
                          /* Turn on ANSI mode */
                          od_control.user_ansi = TRUE;

                          /* Since ANSI mode is present, RIP mode may also */
                          /* be available. Prompt the user for RIP. */
                          od_printf("\r\n\n");
                          od_printf("Does your system support RIP graphics?");
                          od_printf(" (Y/N)");

                          /* If the user chooses [Y]es */
                          if(od_get_answer("YN") == 'Y')
                             /* Turn on RIP mode */
                             od_control.user_rip = TRUE;

                          /* Since ANSI mode is present, AVATAR mode may  */
                          /* also be available. Prompt the user for AVATAR. */
                          od_printf("\r\n\n");
                          od_printf("Does your system support AVATAR ");
                          od_printf("graphics? (Y/N)");

                          /* If the user chooses [Y]es */
                          if(od_get_answer("YN") == 'Y')
                             /* Turn on AVATAR mode */
                             od_control.user_avatar = TRUE;
                          }

                       od_printf("\r\n\n");
                       }



===============================================================================
OpenDoors 5.00 Manual                                            End of Page 49






OD_CHAT()
-------------------------------------------------------------------------------

PURPOSE        Manually invokes sysop chat mode.


FORMAT         void od_chat(void);


RETURNS        N/A


DESCRIPTION    Normally, the OpenDoors sysop chat mode will only be invoked
               when the sysop explicitly requests it using the sysop chat key.
               However, there may be some cases where you wish to manually
               invoke the sysop chat mode. One example is when you are
               replacing the OpenDoors built-in chat mode with your own, but
               still wish to use the OpenDoors chat mode under some
               circumstances. For instance, you may wish to use your own split-
               screen chat routine if ANSI, AVATAR or RIP graphics mode is
               available, and use the OpenDoors line-oriented chat mode if only
               ASCII mode is available.


SEE ALSO       od_page()


EXAMPLE        For an example of using the od_chat() function, see the
               ex_chat.c example door, which is described on page 38.






















===============================================================================
OpenDoors 5.00 Manual                                            End of Page 50






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 246),
               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.


SEE ALSO       od_set_dtr()


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,

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 51


               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;

               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 return with a value of FALSE if the carrier signal does not
               drop, and will return a value of TRUE if it does.

                    char hangup(void)
                       {
                       register long timer;
                       char to_return = FALSE;

                       od_set_dtr(FALSE);                    /* Hangup modem */

                                            /* Wait up to 30secs (546 ticks) */
                       timer=(*(long far *)0x46cL)+546L;
                       while(timer>=*(long far *))
                          { /* If carrier has been lost, return with success */
                          if(!od_carrier())
                             {
                             to_return = TRUE;
                             break;
                             }
                          }

                       od_set_dtr(TRUE);             /* Re-enable DTR signal */
                       return(to_return);
                       }




















===============================================================================
OpenDoors 5.00 Manual                                            End of Page 52






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.




===============================================================================
OpenDoors 5.00 Manual                                            End of Page 53


               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.



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 38. 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 5.00 Manual                                            End of Page 54






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, AVATAR or RIP
               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, AVATAR or RIP modes are active. Also note
               that in ANSI, AVATAR or RIP 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 5.00 Manual                                            End of Page 55




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, AVATAR or RIP 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 5.00 Manual                                            End of Page 56






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 / RIP graphics mode settings.

               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_disp_emu("\xc", TRUE);


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


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 57


               will return a value of FALSE if screen clearing is not
               supported:

               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\n\r");
                  od_disp_str("are 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 5.00 Manual                                            End of Page 58






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 section on the OpenDoors configuration file
               system, which begins on page 215.

               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 array
               od_control.od_colour_names.


EXAMPLE        See the example accompanying in the section on the OpenDoors
               configuration file system, which begins on page 215.







===============================================================================
OpenDoors 5.00 Manual                                            End of Page 59






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 64.

               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_disp_emu()

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 60




EXAMPLES       The following are a few examples of the use of the od_disp()
               function:

               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 5.00 Manual                                            End of Page 61






OD_DISP_EMU()
-------------------------------------------------------------------------------

PURPOSE        Displays a string with ANSI/AVATAR terminal emulation


FORMAT         void od_disp_emu(char *string, char remote_echo);


RETURNS        N/A


DESCRIPTION    The od_disp_emu() function allows you to display your own ANSI /
               AVATAR graphics sequences. 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 121. 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 string passed to od_disp_emu() contains any stream of text
               to display, and may include both normal text and terminal
               emulation control sequences. The OpenDoors terminal emulator
               stores its current state between calls to od_disp_emu(), and so
               control sequences my be broken between calls to od_disp_emu. In
               other words, the call:

                    od_disp_emu("\x1b[1C", TRUE);

               is equivalent to:

                    od_disp_emu("\x1b[", TRUE);
                    od_disp_emu("1C", TRUE);

               If the remote_echo parameter is set to TRUE, the string passed
               to od_disp_emu() will be sent to the remote terminal in addition
               to being displayed locally. If this parameter is set to FALSE,
               the string will only be displayed locally.

               Note that if you wish to display an entire file containing
               ANSI/AVATAR/RIP graphics sequences (perhaps as your program's
               menu or title screen), you can 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 64.

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 62




EXAMPLE        For an example of the use of the od_disp_emu() function, see the
               SpaceRight() and MoveLeft() functions included in the example
               program ex_ski.c. These functions use the ANSI move cursor left
               and move cursor right functions to move the cursor relative to
               the current position, without knowing what the current cursor
               position is.















































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 63






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, AVATAR or RIP graphics control codes, and
               have them emulated on the local screen, use the od_disp_emu()
               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).

               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:

                              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_disp_emu()

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 64




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 5.00 Manual                                            End of Page 65






OD_DRAW_BOX()
-------------------------------------------------------------------------------

PURPOSE        Draws a window on the screen in ANSI, AVATAR or RIP 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, AVATAR or RIP 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()




===============================================================================
OpenDoors 5.00 Manual                                            End of Page 66


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 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();

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 67



                        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
                        {                    // 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
                        }
                     }
                  }


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 68


               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 5.00 Manual                                            End of Page 69






OD_EDIT_STR()
-------------------------------------------------------------------------------

PURPOSE        Allows you to perform formatted input with full line editing
               features, etc., in ANSI/AVATAR/RIP 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/RIP 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, AVATAR and RIP modes. The second
               function, od_edit_str(), allows many formatted input options,
               advanced line editing, and other features, but requires the use
               of ANSI, AVATAR or RIP graphics modes.


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 70


               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 OpenDoors functions. The simple fact that the
               function accepts eight parameters may make 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/RIP 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/RIP graphics to operate, or in the
               case that you program tests for the availability of
               ANSI/AVATAR/RIP graphics, and only calls od_edit_str() if
               graphics is available. If ANSI/AVATAR/RIP 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.



===============================================================================
OpenDoors 5.00 Manual                                            End of Page 71


               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].

               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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 72


               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,
               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. Note
               that since the cursor can be moved to the position immediately
               following the last character, a the input field for a 30
               character string will occupy 31 columns on the screen. 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.

               #    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.



===============================================================================
OpenDoors 5.00 Manual                                            End of Page 73


               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.

               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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 74


                    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.

               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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 75


               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
                         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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 76


                         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.

               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 canceled, and replaced by the original
                         contents of the string. The od_edit_str() function
                         will then exit, indicating that the user has canceled
                         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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 77


                         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
                         "##':'##':'##"), 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 behaviors 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()


===============================================================================
OpenDoors 5.00 Manual                                            End of Page 78



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|
                                    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|

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 79


                                    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);


               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 5.00 Manual                                            End of Page 80






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 close the serial
               port, 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.


SEE ALSO       od_init()


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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 81


               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 5.00 Manual                                            End of Page 82






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\n\rZ");
                    - Valid responses will be: [A], [B], [C], [SPACE],
                      [1], [2], [3], [ENTER], [Z]

















===============================================================================
OpenDoors 5.00 Manual                                            End of Page 83






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 53, 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,

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 84


               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.

               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 5.00 Manual                                            End of Page 85






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 5.00 Manual                                            End of Page 86






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 38.











































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 87






OD_GETTEXT()
-------------------------------------------------------------------------------

PURPOSE        Stores a rectangular region of the screen in an array, to later
               be redrawn using od_puttext(). Requires ANSI, AVATAR or RIP
               modes.


FORMAT         int od_gettext(int left, int top, int right, int bottom, void
               *block);


RETURNS        TRUE on success
               FALSE on failure


DESCRIPTION    This function stores the contents (both text and colour
               information) of the rectangular portion of the screen denoted by
               the variables "left", "top", "right" and "bottom" into the
               buffer pointed to by block. The saved portion of the screen may
               then be restored using od_puttext(). The buffer must be large
               enough to store two bytes for every character in the specified
               rectangle. In other words, the required size of the buffer, in
               bytes, is:

                           length * width * 2

               The parameters "left" and "right" are column numbers from 1 to
               80, and the parameters "top" and "bottom" are row numbers
               between 1 and 23.

               This function has no effect on the current text colour or cursor
               position. ANSI, AVATAR or RIP mode is required for this
               function. If you wish to save and restore the entire screen, you
               may use the od_save_screen() and od_restore_screen() functions,
               which can be used in all display modes.

               If this function fails for any reason, a value of FALSE is
               returned, and the od_control.od_error variable is set to
               indicate the reason for the failure. For more information on the
               od_control.od_error variable, see page 182.


SEE ALSO       od_puttext(), od_save_screen(), od_restore_screen(),
               od_scroll(), od_window_create(), od_window_remove()


EXAMPLE



===============================================================================
OpenDoors 5.00 Manual                                            End of Page 88






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,
               AVATAR or RIP 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 extension is
               provided for the filename, OpenDoors will automatically search
               for matching files ending in .ASC, .ANS and .AVT extensions.
               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, 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 5.00 Manual                                            End of Page 89



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 5.00 Manual                                            End of Page 90






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 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 145.

               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 148.

               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 145.


SEE ALSO       od_exit()


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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 91


               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 5.00 Manual                                            End of Page 92




               void maint(void)
                  {
                  ...               /* Carry out maintenance activities here */
                  }


               void door(void)
                  {
                  ...                      /* Carry out door activities here */
                  }











































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 93






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, AVATAR and RIP modes. The second
               function, od_edit_str(), allows many formatted input options,
               advanced line editing, and other features, but requires the use
               of ANSI, AVATAR or RIP 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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 94


               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, 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 5.00 Manual                                            End of Page 95






OD_KERNEL()
-------------------------------------------------------------------------------

PURPOSE        The OpenDoors Central Control function


FORMAT         void od_kernel(void);


RETURNS        N/A


DESCRIPTION    The od_kernel() 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_kernel() function is
               automatically called on a frequent basis by the other OpenDoors
               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_kernel(), or some other OpenDoors 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 functions for more than a second or so, you should
               call the od_kernel() 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_kernel() function, or any other
               OpenDoors 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_kernel(), or some OpenDoors function. Hence, use of the
               od_kernel() function will improve the quality and response time
               of your program, but calling it or some OpenDoors 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 functions, it
               would be a good idea for you to call the od_kernel() 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_kernel() 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

===============================================================================
OpenDoors 5.00 Manual                                            End of Page 96


               program will be able to respond to events such as the 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_kernel();             /* Repeatedly call od_kernel() */
                     }
                  }








































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 97






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:\BBS\FILES\UPLOADS, simply:

                      od_list_files("C:\\BBS\\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 5.00 Manual                                            End of Page 98



               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 145.


SEE ALSO       od_send_file()








































===============================================================================
OpenDoors 5.00 Manual                                            End of Page 99






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 failure


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       Page 215.


EXAMPLE        Calling the od_log_write() function is as simple as follows:

                    od_log_write("Awarding user with 5 minutes more time");





===============================================================================
OpenDoors 5.00 Manual                                           End of Page 100






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 145.


EXAMPLE        For an example of the use of the od_page() function, see the
               EZVote example door, which is described beginning on page 38.
















===============================================================================
OpenDoors 5.00 Manual                                           End of Page 101






OD_POPUP_MENU()
-------------------------------------------------------------------------------

PURPOSE        Creates a popup menu which allows the user to make a selection
               by pressing a single key, or selecting the item with a highlight
               bar. After the user has made a selection, the menu may be
               removed from the screen, restoring the original screen contents
               "beneath" the window.


FORMAT         int od_popup_menu(char *title, char *text, int left, int top,
               int level, unsigned int flags);


RETURNS        POPUP_ERROR    On error (od_control.od_error is set to
                              indicate type of error).
               POPUP_ESCAPE   If user exited menu by pressing [ESCape].
               POPUP_LEFT     If user exited menu by pressing the left arrow
                              key.
               POPUP_RIGHT    If user exited menu by pressing the right arrow
                              key.

               Or, a postive integer indicating the menu item that was chosen
               if a selection was made.


DESCRIPTION    od_popup_menu() creates a popup window with a menu of choices,
               for use in ANSI/AVATAR/RIP modes. The user is able to choose an
               item from the menu by moving the highlighted selection bar with
               the arrow keys, or by pressing a key associated with a
               particular menu item. The contents of the menu are defined by
               the string pointed to by the text parameter. This menu
               definition string contains each menu option, seperated by a '|'
               (pipe) character. Keys associated with each menu entry can be
               defined by proceeding the letter with a '^' (carat) character.
               For example, the string:

                    "^Save|^Load|E^xit"

               would produce a menu with three options: Save, Load and Exit.
               The user would be able to select the Save option by pressing the
               [S] key, the Load option by pressing the [L] key, and the Exit
               option by pressing the [X] key. Furthermore, the characters
               corresponding to each menu item would be displayed in a
               highlighted color.

               Menus displayed with od_popup_menu() may optionally have a
               title, as specified by the title parameter. If this parameter is
               set to NULL, no title will be displayed. If this parameter is


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 102


               not NULL, the specified string will be displayed as a title on
               the window.

               The left and top parameters specify the left and top locations
               of the menu window, were 1, 1 is the upper right corner of the
               screen. The bottom and right corners of the menu are
               automatically determined by the size and number of menu entries
               in the menu definition string.

               The level parameter specifies the menu level, an integer from 0
               to 9. Unless you are using the MENU_KEEP flag, this parameter
               should always be 0.

               The flags parameter specifies one or more of the following
               options, joined by the bitwise-OR operator (|).

                    MENU_NORMAL         Has no effect.
                    MENU_ALLOW_CANCEL   Allow user to exit menu with [ESCape].
                    MENU_PULLDOWN       Allow exit with arrow keys.
                    MENU_KEEP           Leave menu active on seleion.
                    MENU_DESTROY        Remove a currently active menu.

               If you are not using any of the other flags, you can use
               MENU_NORMAL as a place-holder for this parameter. If you
               sepecify MENU_ALLOW_CANCEL, the user will be able to exit the
               menu without making a selection by pressing the [ESCape] key. If
               the user presses [ESCape], od_popup_menu() returns POPUP_ESCAPE.

               You can use the MENU_PULLDOWN option with od_popup_menu() to
               implement a set of pulldown menus. In this case, if the user
               presses the left arrow key or right arrow key while the menu is
               being displayed, od_popup_menu() returns with POPUP_LEFT or
               POPUP_RIGHT, allowing you to display a different menu.

               Normally, od_popup_menu() will remove the menu from the screen
               as soon as the user makes a selection. However, there may be
               some cases when you want the menu to continue to be visible
               after the user makes a selection. For example, you may want some
               menu options to lead to further sub-menus, or you may wish to
               display a popup window, and return to this menu after the user
               has exited from the popup window. If the MENU_KEEP flag is
               specified, the menu will remain active (on-screen) after the
               user makes a selection. However, the menu will still be
               destroyed if the user cancels out of the menu (this will only
               happen if you have specified MENU_ALLOW_CANCEL), or if the user
               moves to another menu by pressing the left or right arrow keys
               (this will only happen if you have specified MENU_PULLDOWN). If
               MENU_KEEP has been specified, and the user makes a selection,
               you must eventually either return to the menu, or destroy it by
               calling MENU_DESTROY. If you want to return to the menu, simply
               call od_popup_menu() again with the same level value that was
               used to originally create the menu. The user will now be able to
               make another selection from the menu, and od_popup_menu() will
               once again return that selection to you. If you want to destory

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 103


               the menu, simply call od_popup_menu() with the MENU_DESTROY flag
               set, and the same level value that was used to create the
               original menu. If you wish to create another popup menu while
               the first one is still active, simplly call od_popup_menu()
               again, this time with a different level value.

               The colors used by the od_popup_menu() function are set by the
               following OpenDoors control structure settings:

                    char od_control.od_menu_title_col;
                    char od_control.od_menu_border_col;
                    char od_control.od_menu_text_col;
                    char od_control.od_menu_key_col;
                    char od_control.od_menu_highlight_col;
                    char od_control.od_menu_highkey_col;


SEE ALSO       od_window_create(), od_window_remove(), od_draw_box(),
               od_hotkey_menu()




































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 104






OD_PRINTF()
-------------------------------------------------------------------------------

PURPOSE        Performs formatted output (remote & local), with the ability to
               change display colours.


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 64. 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


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 105


               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");

               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 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 determine whether
               the user has ANSI, AVATAR or RIP graphics enabled, 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/AVATAR/RIP 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:

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 106



                       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");

               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 145. 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 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.

               Note that the string to be displayed by od_printf() should not
               exceed 511 characters in size, including the size of color
               sequences and expanded % fields.


SEE ALSO       od_disp_str(), od_disp(), od_putch(), od_repeat(), od_disp_emu()

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 107




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 145.


#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 */
   }


HELPFUL        This section demonstrates use of the od_printf() colour
HINT           sequences imbedded directly in the printf() format string, such
               as:

                         od_printf("Hello `bright green` there!");

               However, there are also other ways that you can take advantage
               of this feature. For example, the C programming language


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 108


               concatenates string constants that are separated only by white
               space or carriage returns. For instance,

                         "Hello " "`bright green`" " there!"

               is equivalent to:

                         "Hello `bright green` there!"

               For this reason, you can create macros for common colour
               sequences in your program, such as:

                         #define HIGHLIGHT "`bright green`"

               You can then use such constants when calling the od_printf()
               function, as follows:

                         od_printf("Hello " HIGHLIGHT " there!");

               You may find this method of setting the display colour to be
               easier to read, and more easily configurable than including the
               colour sequence directly in the format string. Below another use
               of the colour sequences is describe, which allows the colours
               used by od_printf() not be "hard-wired".


               Since colour control sequences are evaluated by od_printf()
               after it evaluates all format sequences (such as "%d"). For this
               reason, it is possible to change the display colour using a
               string variable, instead of using a fixed colour in the string.
               For example, if you program had the variable:

                         char highlight[40];

               which was set at some point to be equal to:

                         "`bright green`"

               you would be able to use od_printf() as follows:

                         od_printf("Hello %s there!", highlight);

               The display colour would then be changed at the location where
               the "%s" appears in the od_printf() format string. The advantage
               of using this method to change display colours is that unlike
               other methods, the value of the highlight variable can be
               changed. This could be used, for example, to allow the sysop to
               configure the colours they wish your door to use. You would only
               need to change the value of the highlight variable in order to
               change the colour set by od_printf().





===============================================================================
OpenDoors 5.00 Manual                                           End of Page 109






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 64. 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 ANSI, AVATAR
               or RIP 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_disp_emu()


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 */
                     }

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 110



                  return(pressed);             /* Return key pressed by user */
                  }

               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 114.
















































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 111






OD_PUTTEXT()
-------------------------------------------------------------------------------

PURPOSE        Displays a rectangular region of text and colour information, as
               previously stored using od_gettext()


FORMAT         int od_puttext(int left, int top, int right, int bottom, void
               *block);


RETURNS        TRUE on success
               FALSE on failure


DESCRIPTION    This function "pastes" a rectangular block of text and colour
               information that has been previously retrieved using
               od_gettext(). The block is placed at the screen location
               indicated by the variables "left", "top", "right" and "bottom",
               where "left" and "right" are column numbers from 1 - 80, and
               "top" and "bottom" are row numbers from 1 - 23. The length and
               width of the rectangle specified by "left", "top", "right" and
               "bottom" must be the same as the length and width of the
               rectangle passed to od_gettext() when storing the block of text.

               This function attempts to display the pasted block as quickly as
               possible, only transmitting information on portions of the block
               that are different than the original screen contents. When this
               function returns, it leaves the cursor at its original position,
               and the display colour at its original setting. This function
               requires ANSI or AVATAR graphics mode.

               The control structure variable od_control.od_full_put may be set
               to TRUE to force od_puttext() to always send all characters in
               the block to be displayed, instead of only displaying the
               portions of the block that differ from the original screen
               contents.

               If you wish to save and restore the entire screen, you may use
               od_save_screen() and od_restore_screen(), which work in all
               display modes.

               You may also use the od_puttext() to display a rectangular block
               of text that you generate manually, instead of retrieving using
               od_gettext(). To do this, you pass an array which contains the
               text and colour information for the rectangular area to be
               painted, in the "block" parameter. The array passed to
               od_puttext() contains a two-byte sequence of information for
               each character in the rectangle. The first byte contains the
               ASCII code of the character to be displayed. The second byte

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 112


               contains the colour attribute value of the character, in the
               same format as used by the od_set_attrib() function (described
               on page 125). These two byte sequences are stored in the order
               in which English is written; the array begins with the two byte
               sequences for all of the characters on the first line, from left
               to right, followed by the characters for the second line, and so
               on. The length of each line must be exactly equal to the width
               of the rectangular region to be painted.

               If od_puttext() fails for any reason, a value of FALSE is
               returned, and the od_control.od_error variable is set to
               indicate the reason for the failure. For more information on the
               od_control.od_error variable, see page 182.


SEE ALSO       od_gettext(), od_save_screen(), od_restore_screen(),
               od_scroll(), od_window_create(), od_window_remove()


EXAMPLE        For an example of the user of the od_puttext() function, see the
               example that accompanies the description of the od_gettext()
               function. The od_gettext() function is documented on page 88.

































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 113






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 64.

               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_disp_emu()


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 66. 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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 114


               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 rates. Note that this window display function requires that
               the user has ANSI, AVATAR or RIP graphics mode enabled.

               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 5.00 Manual                                           End of Page 115






OD_RESTORE_SCREEN()
-------------------------------------------------------------------------------

PURPOSE        Restores the screen contents as previous saved using the
               od_save_screen() function. This function can be used in any
               display mode.


FORMAT         int od_restore_screen(void *buffer);


RETURNS        TRUE on success
               FALSE on failure

DESCRIPTION    This function restores the entire contents of the screen, along
               with the current cursor position and display colour, which was
               previously stored using the od_save_screen() function. Unlike
               the od_get_text() and od_put_text() functions, the
               od_save_screen() and od_restore_screen() functions will work in
               all display modes (ASCII, ANSI, AVATAR and RIP).

               The "buffer" parameter must point to the buffer previously
               passed to od_save_screen(). Note that the od_save_screen() and
               od_restore_screen() functions save the stored information in
               different formats than the od_getttext() and od_puttext()
               functions. For this reason, you cannot save the screen contents
               with od_gettext() and restore them with od_restore_screen(), or
               visa-versa.

               If this function fails for any reason, a value of FALSE is
               returned, and the od_control.od_error variable is set to
               indicate the reason for the failure. For more information on the
               od_control.od_error variable, see page 182.


SEE ALSO       od_save_screen(), od_gettext(), od_puttext(), od_clr_scr()


EXAMPLE        For an example of how to use the od_restore_screen() function,
               see the example which accompanies the od_save_screen() function,
               on page 117.










===============================================================================
OpenDoors 5.00 Manual                                           End of Page 116






OD_SAVE_SCREEN()
-------------------------------------------------------------------------------

PURPOSE        Saves the contents of the screen, to later be restored using
               od_restore_screen(). Can be used in any display mode.


FORMAT         int od_save_screen(void *buffer);


RETURNS        TRUE on success
               FALSE on failure

DESCRIPTION    This function saves the entire contents of the screen, along
               with the current cursor position and display colour, to be later
               restored using the od_restore_screen() function. Unlike the
               od_get_text() and od_put_text() functions, the od_save_screen()
               and od_restore_screen() functions will work in all display modes
               (ASCII, ANSI, AVATAR and RIP).

               The "buffer" parameter should point to a buffer where the
               current screen information is to be stored. This buffer must be
               at least 4004 bytes in size.

               Note that the od_save_screen() and od_restore_screen() functions
               save the stored screen information in different formats than the
               od_getttext() and od_puttext() functions. For this reason, you
               cannot save the screen contents with od_save_screen() and
               restore them with od_puttext(), or visa-versa.

               Also, note that when used in RIP graphics mode, this function
               only saves and restores textual information, and not bit-mapped
               graphical information.

               If this function fails for any reason, a value of FALSE is
               returned, and the od_control.od_error variable is set to
               indicate the reason for the failure. For more information on the
               od_control.od_error variable, see page 182.


SEE ALSO       od_restore_screen(), od_gettext(), od_puttext(), od_clr_scr()


EXAMPLE        One case where you might wish to save and restore the contents
               of the screen is when sysop chat mode is activated. This can be
               accomplished by using the od_control.od_cbefore_chat and
               od_control.od_cafter_chat variables. The following example
               causes the screen contents to be saved and the entire screen
               cleared, prior to entering sysop chat mode when the sysop
               presses the "chat key". When the sysop ends chat mode, the

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 117


               user's original screen is restored, and the user will be able to
               continue working in the door as though nothing had happened.

               Code to perform screen saving and restoring:

                    /* Function prototypes */
                    void before_chat_function(void);
                    void after_chat_function(void);

                    /* Buffer to hold contents of screen prior to chat */
                    char before_chat_buffer[4004];
                    /* Variable to store whether screen save was successful */
                    char before_chat_saved = FALSE;

                    /* Function which is called prior to entering chat mode */
                    void before_chat_function(void)
                       {
                       /* Store current screen contents */
                       before_chat_saved = od_save_screen(before_chat_buffer);

                       /* Present a blank screen for chat mode */
                       od_clr_scr();
                       }

                    /* Function which is called after exiting chat mode */
                    void after_chat_function(void)
                       {
                       /* If screen was successfully saved prior to chat */
                       if(before_chat_saved)
                          {
                          /* Restore original screen contents */
                          od_restore_screen(before_chat_buffer);
                          }
                       }

               Code included in main() function to enable screen saving and
               restoring code:

                    od_control.od_cbefore_chat = before_chat_function;
                    od_control.od_cafter_chat = after_chat_function;















===============================================================================
OpenDoors 5.00 Manual                                           End of Page 118






OD_SCROLL()
-------------------------------------------------------------------------------

PURPOSE        Scrolls any rectangular area of the screen a specified number of
               lines upwards or downwards. Requires ANSI/AVATAR/RIP graphics
               mode to be active.


FORMAT         int od_scroll(int left, int top, int right, int bottom, int
               distance, unsigned int flags);


RETURNS        TRUE on success
               FALSE on FAILURE


DESCRIPTION    This function scrolls a rectangular area of the screen described
               by the parameters "left", "top", "right" and "bottom". The
               parameters "left" and "right" are column numbers from 1 - 80,
               and the parameters "top" and "bottom" are row numbers from 1 -
               23.

               The parameter "distance" indicates the direction and number of
               lines to scroll the text in the specified area. Positive values
               denote moving the text upwards, and negative values denote
               moving the text downwards. Hence, a "distance" of 1 would cause
               the text in the specified area to be scrolled upwards one line,
               with the top line disappearing, and a blank line being created
               at the bottom of this area. A "distance" of -2 would cause the
               text in the specified are to be scrolled downwards two lines.

               The last parameter to od_scroll(), "flags" is not currently used
               by OpenDoors. However, to preserve compatibility with future
               versions of OpenDoors, this should always be 0.

               The new lines created by scrolling text will appear in the
               current colour. When this function returns, it leaves the cursor
               at its original position, and the display colour at its original
               setting. This function requires ANSI or AVATAR modes. If ANSI
               mode is active, this function is equivalent to calling
               od_gettext(), od_puttext(), and then sending addition codes to
               the modem clear the newly created lines. In ANSI mode, scrolling
               can be accomplished more quickly if the area to be scrolled is
               equal in width to the entire screen. This is because the
               clearing of newly created lines is done by sending a simple
               control sequence, instead of a line of space characters. If
               AVATAR mode is active, scrolling of the window is accomplished
               by sending a single 6-byte control sequence.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 119


               If the od_scroll() function fails for any reason, a value of
               FALSE is returned, and the od_control.od_error variable is set
               to indicate the reason for the failure. For more information on
               the od_control.od_error variable, see page 182.


SEE ALSO       od_gettext(), od_puttext(), od_window_create(),
               od_window_remove()


EXAMPLE        For an example of a program which uses the od_scroll() function,
               see the ex_chat.c example door that is included in your
               OpenDoors package. The ex_chat.c example door is described on
               page of 38 this manual.









































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 120






OD_SEND_FILE()
-------------------------------------------------------------------------------

PURPOSE        Sends an ASCII/ANSI/AVATAR/RIP file from 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, AVATAR or
               RIP file. The od_send_file() function can be used to display
               existing BBS text files, such as a "logoff screen", 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 four files,
               MAINMENU.ASC, MAINMENU.ANS, MAINMENU.AVT and MAINMENU.RIP; the
               .ASC file containing no special control codes, the .ANS file
               containing ANSI control codes, the .AVT file containing AVATAR
               control codes, and the .RIP file containing RIP 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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 121


               you do not specify a filename extension), it will look for one
               of the four filename extensions listed below.

               +----------------------------------------------------------+
               | 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      |
               |   .RIP   | Requires RIP graphics mode to be displayed    |
               +----------------------------------------------------------+


               If the user has RIP graphics enabled, od_send_file() will first
               search for the .RIP file. If no file exists with the specified
               filename and a .RIP extension, od_send_file() will then search
               for .AVT, then .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.

               When displaying a .RIP file to the remote system, OpenDoors will
               attempt to locate and display a corresponding .AVT/.ANS/.ASC
               file on the local system. If no such file can be found, a window
               will be displayed, indicating the name of the .RIP file that is
               being sent to the remote system. When a .RIP file is being
               displayed, page pausing is disabled.

               When displaying .AVT/.ANS/.ASC files, 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 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. The interpretation of
               these control codes can be disabled using the
               od_control.od_no_ra_codes variable.


                 +-----------------------------------------------------+
                 | 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           |

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 122


                 |   ^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  |
                 +-----------------------------------------------------+




                 +-----------------------------------------------------+
                 | 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  |

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 123


                 |   ^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_disp_emu(), 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 38.


































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 124






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 105.

               This function will only have an effect if the user has ANSI,
               AVATAR or RIP modes enabled. 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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 125



               Where the left digit (most significant nibble) of the
               hexidecimal number represents the background colour, and the
               right digit (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_disp_emu(), 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 */


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 126


                  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 */
                     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 5.00 Manual                                           End of Page 127






OD_SET_COLOUR()
-------------------------------------------------------------------------------

PURPOSE        Function to change the current display colour in ANSI, AVATAR or
               RIP modes, 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 105.

               This function will only have an effect if the user has ANSI,
               AVATAR or RIP 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 5.00 Manual                                           End of Page 128




               +-------------------+-----------+
               | 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_disp_emu(), 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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 129


               and background colour at the same time. These function presume
               that they are the only functions used within the door to set the
               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 5.00 Manual                                           End of Page 130






OD_SET_CURSOR()
-------------------------------------------------------------------------------

PURPOSE        Function to reposition the text cursor in ANSI, AVATAR or RIP
               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,
               AVATAR or RIP 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_disp_emu(), 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);

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 131


                               od_disp_str("Fifteenth line\n\r");
                               }

                            else        /* If graphics mode is not available */
                               {                             /* Display demo */
                               od_disp_str("Top, Left Corner");
                               od_repeat(' ', 54);
                               od_disp_str("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 5.00 Manual                                           End of Page 132






OD_SET_DTR()
-------------------------------------------------------------------------------

PURPOSE        Controls the DTR (Data Terminal Ready) signal to the modem. Used
               primarily to cause the modem to "hang up".


FORMAT         void od_set_dtr(char high);


RETURNS        N/A


DESCRIPTION    In certain circumstances (such as call back verification doors),
               you may wish to "hang up" the modem without exiting your door
               program. This can be accomplished with most modems by
               controlling the DTR (Data Terminal Ready) signal to the modem.
               Passing a FALSE value to od_set_dtr() causes the DTR signal to
               be set low, and passing a TRUE value causes the DTR signal to be
               set high. Normally, OpenDoors maintains the DTR signal in its
               high state. Since most (but not all) modems are configured to
               disconnect from the remote modem when the DTR signal is set low,
               calling od_set_dtr(FALSE) can be used to hangup the modem. When
               hanging up by this method, you should be sure to set the DTR
               signal high again, after the carrier detect signal has
               disappeared. For more information on determining the state of
               the carrier detect signal, see the od_carrier() function, which
               is described on page 51.

               Note that not all modems will disconnect from the remote user in
               response to your lowering the DTR signal. If your software may
               be used with such modems, you may wish to also provide the
               option of disconnecting the modem by sending a "hang up" command
               sequence to the modem.

               Since OpenDoors normally monitors the carrier detect signal, and
               exits when this signal disappears, you will have to disable
               OpenDoor's carrier detection if you wish your program to
               continue executing after hanging up the modem. OpenDoor's
               automatic carrier detection can be disabled using the
               od_control.od_disable OpenDoors control structure variable, as
               follows:

                    od_control.od_disable |= DIS_CARRIERDETECT;

               To re-enable carrier detection, you should turn off the
               DIS_CARRIERDETECT bit of od_disable, as follows:

                    od_control.od_disable &=~ DIS_CARRIERDETECT;


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 133


               If you wish to hang up the modem when the user exits the door,
               you can simply use the od_exit() function.

SEE ALSO       od_carrier(), od_exit()


EXAMPLE        For an example of using the od_set_dtr() function to "hang up"
               the modem, see the example that accompanies the od_carrier()
               function, on page 52.














































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 134






OD_SET_PERSONALITY()
-------------------------------------------------------------------------------

PURPOSE        Sets the current status line / sysop function key personality to
               be used.


FORMAT         int od_set_personality(char *name);


RETURNS        TRUE on success
               FALSE on failure


DESCRIPTION    This function changes the current status line / sysop function
               key personality. The "name" parameter should contain the string
               which uniquely identifies the personality to be set. This
               function may only be used by OpenDoors programs which include
               the OpenDoors "Multiple Personality System". To enable use of
               the MPS, include the following line before your first call to
               any OpenDoors function:

                         od_control.od_mps=INCLUDE_MPS;

               OpenDoors includes a number of built-in personalities.
               Additional personalities may be added using the
               od_add_personality() function, which is described on page 46.
               The following personalities are included with this version of
               OpenDoors:

                    Name                Description
                    -----------------------------------------------------------
                    Standard            OpenDoors style, similar to RA 1.11
                    PCBoard             Similar to PC-Board
                    RemoteAccess        Similar to RemoteAccess 2.x
                    Wildcat             Similar to Wildcat!

               Personality names are not case sensitive. For more information
               on the OpenDoors Multiple Personality System, see the section
               which begins on page 223.

               This function returns TRUE on success, or FALSE on failure. In
               the case of a failure, the od_control.od_error variable is set
               to indicate the nature of the failure. For more information on
               the od_control.od_error variables, see page 182.


SEE ALSO       od_add_personality(), od_set_statusline()



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 135






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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 136


               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
               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 145.































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 137






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:


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 138


                              od_spawn(getenv("COMSPEC"));

               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 5.00 Manual                                           End of Page 139






OD_SPAWNVPE()
-------------------------------------------------------------------------------

PURPOSE        To facilitate easy execution of child tasks from doors. Allows
               specification of child's environment, returns errorlevel
               returned by child task, and searches 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 parameter 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 extension is not provide, OpenDoors
               will look first for a .COM file, and if not found, for a .EXE
               file. The third parameter is an array of arguments to pass to

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 140


               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()


EXAMPLE        For an example of the use of the od_spawn...() functions, see
               the example accompanying the od_spawn() function. As a specific
               example of the od_spawnvpe function, consider the following code
               which executes the "TEST.EXE" program.

                         od_spawnvpe(P_WAIT,"TEST.EXE",NULL,NULL);








































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 141






OD_WINDOW_CREATE()
-------------------------------------------------------------------------------

PURPOSE        Creates a popup window of the specified size and colour, storing
               the contents of the screen "under" the window. The window can
               later be removed from the screen, restoring the original
               contents of the screen "under" the window, using the
               od_window_remove() function. Requires ANSI, AVATAR or RIP mode.


FORMAT         void *od_window_create(int left, int top, int right, int bottom,
               char *title, char boardcol, char titlecol, char insidecol, int
               reserved);


RETURNS        Pointer to newly allocated window structure on success
               NULL on failure


DESCRIPTION    This function creates a pop-up window on the remote and local
               screens. The contents of the screen beneath the window are
               stored, to allow the window to later be removed from the screen
               using the od_window_remove() function. The window is drawn using
               the boarder characters defined in the already existing
               od_control.od_box_chars[] array. The boarder is displayed using
               the colour attribute specified in "boardcol". The working area
               of the window is created in the colour specified in "insidecol".
               A title may optionally be displayed on the window by specifying
               a string in "title". This title will be displayed in the colour
               specified by "titlecol". If you do not wish a title to be
               displayed, pass an empty string or NULL pointer in "title". On
               success, od_window_create() will return a pointer to a buffer
               which was allocated to store information on the window and the
               contents of the screen "under" the window. This pointer should
               at some point be passed in a call to od_window_remove().

               This function requires ANSI, AVATAR or RIP graphics mode. If
               AVATAR mode is active, this function will take advantage of
               special AVATAR control sequences to display the window much
               faster than is possible in ANSI mode. In ANSI mode, window
               display will be faster if "boardcol" and "titlecol" are equal.
               Note that the "reserved" parameter of this function is not
               currently used. To preserve compatibility with future versions
               of OpenDoors, this parameter should always be set to 0.
               Currently, the size of the buffer allocated to store the window
               information will be (length*witdth*2) + 4 bytes in size.

               Due to the differences between ANSI and AVATAR terminal
               emulation in different software packages, it is not recommended
               to create windows when the remote screen may have been scrolled

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 142


               since the last call to od_clr_scr(). You should also avoid
               creating windows that cover the bottom right-hand corner of the
               screen.

               If od_window_create() fails for any reason, a value of NULL is
               returned, and the od_control.od_error variable is set to
               indicate the reason for the failure. For more information on the
               od_control.od_error variable, see page 182.


SEE ALSO       od_window_remove(), od_draw_box(), od_gettext(), od_puttext(),
               od_save_screen(), od_restore_screen(), od_scroll()


EXAMPLE








































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 143






OD_WINDOW_REMOVE()
-------------------------------------------------------------------------------

PURPOSE        Removes a window previously created using od_window_create(),
               restoring the original screen background.


FORMAT         int od_window_remove(void *info);


RETURNS        TRUE on success
               FALSE on failure


DESCRIPTION    The od_window_remove() function removes a window from the screen
               which was previously created by od_window_create(), and
               deallocates the memory which was allocated to store the window
               information. The contents of the screen beneath the window is
               restored to appear as it did prior to the call to
               od_window_create().

               Note that overlapping windows must be removed in the reverse
               order from which they were created for proper display results.
               The last window to be created must be the first window to be
               removed.

               If od_window_remove() fails for any reason, a value of FALSE is
               returned, and the od_control.od_error variable is set to
               indicate the reason for the failure. For more information on the
               od_control.od_error variable, see page 182.


SEE ALSO       od_window_create(), od_draw_box(), od_gettext(), od_puttext(),
               od_save_screen(), od_restore_screen(), od_scroll()


EXAMPLE        For an example of the use of the od_window_remove() function,
               see the example which accompanies the description of the
               od_window_create() function. The od_window_create() function is
               documented on page 142.











===============================================================================
OpenDoors 5.00 Manual                                           End of Page 144



-------------------------------------------------------------------------------
CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE
-------------------------------------------------------------------------------




INTRODUCTION TO THE CONTROL STRUCTURE
-------------------------------------------------------------------------------

               The OpenDoors "Control Structure" is used by OpenDoors 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 behavior. 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 behavior.

               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 .................147
                         Modem Settings ...................................151
                         BBS and Caller Information .......................156
                         Door Settings ....................................179
                         OpenDoors Behavior Customization .................184
                         Function Keys Customization ......................206
                         Colour Customization .............................227
                         Text Customization ...............................212

               Within each section, variables are listed alphabetically,
               according to their names.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 145


               If you would like more information on C "struct"s, please refer
               to your Turbo C(++)/Borland C++ manuals.

               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 5.00 Manual                                           End of Page 146






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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 147


               from being able to re-read the changes to the door information
               file.

               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:
















===============================================================================
OpenDoors 5.00 Manual                                           End of Page 148


                     +----------------+----------------------------+
                     |  od_info_type  | Door Information File Type |
                     |      Value     |                            |
                     +----------------+----------------------------+
                     | DORINFO1       | DORINFO?.DEF               |
                     | EXITINFO       | EXITINFO.BBS (Normal)      |
                     | RA1EXITINFO    | EXITINFO.BBS (Extended)    |
                     | RA2EXITINFO    | EXITINFO.BBS (RA 2.x)      |
                     | 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.                      |
                     | NO_DOOR_FILE   | No drop file was found.    |
                     +----------------+----------------------------+

               The value of this variable is only valid AFTER od_init() or some
               OpenDoors 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.




===============================================================================
OpenDoors 5.00 Manual                                           End of Page 149



-------------------------------------------------------------------------------
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 5.00 Manual                                           End of Page 150






CONTROL STRUCTURE - SERIAL PORT 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 function, during the od_init() procedure. However,
               you may need to manual set this variables if:

                    - you wish to allow greater configurability of your door
                    - you are reading the door information file yourself
                    - you are using the OpenDoors to write a non-door
                     program

               Some of these variables are always used by OpenDoors, while
               others are only relevant if OpenDoor's built-in serial
               communications code is being used instead of a FOSSIL driver.
               Those that are only used when no FOSSIL driver is present are
               denoted by an [*] in the list below.

               The control structure variables controlling OpenDoor's serial
               port settings are as follows:

               od_control.baud             Serial Port BPS rate

               od_control.od_com_address   Serial Port address [*]

                " " .od_com_fifo_trigger   16550A FIFO trigger szie

               od_control.od_com_irq       Serial Port IRQ number [*}

               od_control.od_com_method    Is FOSSIL or built-in serial I/O
                                           being used

               od_control.od_com_no_fifo   Disables use of 16550A FIFOs [*]

               od_control.od_com_rx_buf    Size of receive buffer [*]

               od_control.od_com_tx_buf    Size of transmit buffer [*]

               od_control.od_no_fossil     Prevents OpenDoors from using a
                                           FOSSIL driver, even if one is
                                           available.

               od_control.port             Serial port number, 0 based.






===============================================================================
OpenDoors 5.00 Manual                                           End of Page 151


-------------------------------------------------------------------------------
baud           unsigned long od_control.baud;

               This variable contains the BPS rate at which the computer is
               communicating with the modem, not to be confused with the BPS
               rate at which the local modem is communicating with the remote
               modem.

               A value of 0 indicates that the door is operating in local mode.

               If a FOSSIL driver is being used for serial I/O, this value is
               ignored if it does not correspond to one of the baud rates that
               an application can directly set a FOSSIL driver to. The BPS
               rates recognized by FOSSIL drivers are: 300, 600, 1200, 2400,
               4800, 9600, 19200, 38400. If any other BPS rate is to be used,
               the FOSSIL driver must be locked at that BPS from the FOSSIL
               driver command-line. When locked, FOSSIL drivers ignore any
               attempt by an application to change the BPS rate of the locked
               port. For this reason, the od_control.baud setting has no effect
               on the FOSSIL driver if it is locked.

               If a FOSSIL driver is not being used for serial I/O, this value
               my be any BPS rate from 2 to 115,200 that is evenly divides
               115,200 (eg: 115200, 57600, 38400, 28800, 23040, 19200, 14400,
               12800, 9600, etc.).

               This variable should only be change prior to calling od_init()
               or the first OpenDoors function.



-------------------------------------------------------------------------------
od_com_        int od_control.od_com_address;
address
               This variable is only used when OpenDoors is NOT performing
               serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
               used, the serial port address can be set from the FOSSIL driver
               command line).

               This variable may optionally be set to specify the base address
               of the serial port to be used. For ports COM1: through COM4:,
               OpenDoors can normally determine the serial port address
               automatically. However, for other serial ports, the port address
               must be specified using this variable. If you are not specifying
               a serial port address with this variable, do not change it's
               default value of 0.

               This variable should only be changed before your first call to
               od_init() or any other OpenDoors function.






===============================================================================
OpenDoors 5.00 Manual                                           End of Page 152


-------------------------------------------------------------------------------
od_com_        char od_control.od_com_fifo_trigger;
fifo_trigger
               This variable is only used when OpenDoors is NOT performing
               serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
               used, the IRQ line can be set from the FOSSIL driver command
               line).

               This variable sets the number of bytes that will be placed in
               the 16550A UART FIFO buffers before an interrupt is triggered,
               if the 16550A UART FIFOs are used. Valid values are 1, 4, 8 and
               14.



-------------------------------------------------------------------------------
od_com_        unsigned char od_control.od_com_irq;
irq
               This variable is only used when OpenDoors is NOT performing
               serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
               used, the IRQ line can be set from the FOSSIL driver command
               line).

               This variable may optionally be set to specify the IRQ line to
               be used for the serial port. By default, OpenDoors uses the
               normal IRQ 4 line for ports COM1: and COM3:, and IRQ 3 for ports
               COM2: and COM4:. To override this default, the IRQ line can be
               set using this variable. If you are not specifying an IRQ line
               with this variable, do not change it's default value of 0.

               This variable should only be changed before your first call to
               od_init() or any other OpenDoors function.



-------------------------------------------------------------------------------
od_com_        char od_control.od_com_method;
method
               This read-only variable reports the method that OpenDoors is
               using for serial I/O. This variable is set during od_init() or
               the first call to an OpenDoors function. This variable can be
               one of the following values:

               COM_FOSSIL     - Indicates that a FOSSIL driver is being used
               COM_INTERNAL   - Indicates that OpenDoor's internal serial I/O
                                code is being used.

               OpenDoors normally automatically determines whether not a FOSSIL
               driver is available, and will attempt to use a FOSSIL driver if
               possible. You can force OpenDoors to always perform serial I/O
               using its internal communications code, bypassing a FOSSIL
               driver if present, by setting the od_control.od_no_fossil
               variable to TRUE.


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 153




-------------------------------------------------------------------------------
od_com_        char od_control.od_com_no_fifo;
no_fifo
               This variable is only used when OpenDoors is NOT performing
               serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
               used, the receive buffer size can be set from the FOSSIL driver
               command line).

               Normally, OpenDoors will use a 16550A FIFO buffer if a 16550A
               UART is installed. You can disable the use of the 16550A FIFO
               buffer by setting this variable to TRUE.



-------------------------------------------------------------------------------
od_com_        unsigned int od_control.od_com_rx_buf;
rx_buf
               This variable is only used when OpenDoors is NOT performing
               serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
               used, the receive buffer size can be set from the FOSSIL driver
               command line).

               This variable allows you to set the size of OpenDoor's serial
               I/O receive buffer. If you do not set this buffer size, a
               default value of 256 characters is used. Normally, this buffer
               size is more than large enough for door programs. However, if
               you find that inbound characters are lost before they can be
               processed by your program, you may wish to increase the size of
               this buffer.

               This variable should only be changed before your first call to
               od_init() or any other OpenDoors function.



-------------------------------------------------------------------------------
od_com_        unsigned int od_control.od_com_rx_buf;
rx_buf
               This variable is only used when OpenDoors is NOT performing
               serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
               used, the receive buffer size can be set from the FOSSIL driver
               command line).

               This variable allows you to set the size of OpenDoor's serial
               I/O receive buffer. If you do not set this buffer size, a
               default value of 256 characters is used. Normally, this buffer
               size is more than large enough for door programs. However, if
               you find that inbound characters are lost before they can be
               processed by your program, you may wish to increase the size of
               this buffer.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 154


               This variable should only be changed before your first call to
               od_init() or any other OpenDoors function.



-------------------------------------------------------------------------------
port           char od_control.port;

               This variable contains the serial port number that the modem is
               connected. This number is 0 based, so that a value of 0
               corresponds to COM1:, a value of 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.




































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 155





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 147. 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)

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 156


                            {
                            od_disp_str(od_control.user_birthday);
                            }
                         else
                            {
                            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 5.00 Manual                                           End of Page 157





               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          |
+-----------------------+-----------------------------------------------+

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 158





+-----------------------+-----------------------------------------------+
| VARIABLE NAME         | VARIABLE CONTENTS                             |
+-----------------------+-----------------------------------------------+
| user_loginsec         | User's security at the beginning of this call |
| 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 5.00 Manual                                           End of Page 159



               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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 160


               to accommodate the event, and if this variable is false, then
               the event can wait until after the user logs off normally. This
               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.





===============================================================================
OpenDoors 5.00 Manual                                           End of Page 161


-------------------------------------------------------------------------------
system_calls   long od_control.system_calls;

               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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 162


               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 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 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 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            |
                       +-----+------+-----------------------+

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 163



               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.



-------------------------------------------------------------------------------
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 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.








===============================================================================
OpenDoors 5.00 Manual                                           End of Page 164


-------------------------------------------------------------------------------
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
               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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 165


               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.



-------------------------------------------------------------------------------
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 deducted 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.








===============================================================================
OpenDoors 5.00 Manual                                           End of Page 166


-------------------------------------------------------------------------------
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 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_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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 167


               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
               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.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 168


               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
               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
               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,

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 169


               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.



-------------------------------------------------------------------------------
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.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 170



-------------------------------------------------------------------------------
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
               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.





===============================================================================
OpenDoors 5.00 Manual                                           End of Page 171


-------------------------------------------------------------------------------
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
               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
               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.


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 172




-------------------------------------------------------------------------------
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 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.



-------------------------------------------------------------------------------
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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 173


               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_rip       char user_rip;

               This variable is set to TRUE if the user has RIP (Remote Imaging
               Protocol) graphics enabled, and FALSE if they do not. This
               setting can be determined from the door information (drop) file
               in many cases. In other cases, you can automatically determine
               whether or not the user's system supports RIP graphics using the
               od_autodetect() function (see page 48).



-------------------------------------------------------------------------------
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 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 value yourself, this variable will
               default to 23. If you are going to set the value of this

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 174


               variable yourself, you should do so after having called
               od_init() or some OpenDoors 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 whether 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 5.00 Manual                                           End of Page 175



-------------------------------------------------------------------------------
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 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.







===============================================================================
OpenDoors 5.00 Manual                                           End of Page 176


-------------------------------------------------------------------------------
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-
               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.







===============================================================================
OpenDoors 5.00 Manual                                           End of Page 177


-------------------------------------------------------------------------------
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 5.00 Manual                                           End of Page 178






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_cur_attrib            The current display attribute, or -1 if
                                        unknown.

               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.

               od_update_stauts_now     Forces immediate update of the status
                                        line.

               sysop_next               Indicates whether or not the sysop has
                                        reserved use of the system after the
                                        current calls.



-------------------------------------------------------------------------------
od_cur         int od_control.od_cur_attrib;
_attrib
               This read-only values stores the current display colour
               attribute, or the value -1 if the current display colour is
               unknown (such as when the door first begins execution).



-------------------------------------------------------------------------------
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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 179


               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 101.



-------------------------------------------------------------------------------
od             unsigned int od_control.od_pageendmin;
_pageendmin
               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 101.



-------------------------------------------------------------------------------
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 101.

-------------------------------------------------------------------------------
od_update      char od_control.od_update_status_now;
_status_now
               Setting this variable to TRUE forces OpenDoors to update the
               status line during the next od_kernel() execution. When the
               status line is updated, this variable is reset to its default
               value of FALSE.







===============================================================================
OpenDoors 5.00 Manual                                           End of Page 180


-------------------------------------------------------------------------------
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 on testing the type of door information file
               available, please see page 156.
























===============================================================================
OpenDoors 5.00 Manual                                           End of Page 181






CONTROL STRUCTURE - DIAGNOSTICS
-------------------------------------------------------------------------------

               To help in diagnosing problems in your OpenDoors programs,
               OpenDoors stores information on the most recent error which
               occurred. When any of the OpenDoors functions return an "error"
               or "failure" state, the reason for this failure is recorded.

               The following OpenDoors control structure variable provides
               diagnostics information:

               od_error                 Stores a "reason code" for the last
                                        failed OpenDoors API function call.




-------------------------------------------------------------------------------
od_error       int od_control.od_error;

               When any of the OpenDoors API functions return an "error" or
               "failure" state (usually denoted by either of the values FALSE
               or NULL), the reason for the failure is recorded in this
               variable. Since successful function calls do not alter the value
               of the od_control.od_error variable, you must be careful not
               only to check the value of the od_control.od_error variable, but
               also to check the OpenDoors function return codes, in order to
               determine which function failed.

               This variable will always store the reason for the most recent
               function call failure, or ERR_NONE if no functions have failed.
               od_error may take on any of the following values:

                    ERR_NONE            Indicates that no error has occurred
                                        yet.

                    ERR_MEMORY          Function was unable to allocate
                                        required memory. This usually indicates
                                        that there is not enough available
                                        memory. This failure may also be due to
                                        memory corruption caused by your
                                        program inadvertently overwriting heap
                                        structures. If your program has been
                                        compiled in either the small or the
                                        medium memory model, try recompiling it
                                        in the compact, large, or huge memory
                                        models. If your program is already
                                        compiled in the compact, large, or huge
                                        memory models, try making more system
                                        memory available to your program.

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 182



                    ERR_NOGRAPHICS      This setting indicates that the
                                        function called requires ANSI, AVATAR
                                        or RIP graphics mode, but none of these
                                        modes are active.

                    ERR_PARAMETER       An invalid parameter was passed to an
                                        OpenDoors functions. Check the
                                        function's description in chapter four,
                                        to determine the required values for
                                        each function parameter.

                    ERR_FILEOPEN        OpenDoors was unable to open a file.
                                        This can be due to the specified
                                        filename not existing, due to the file
                                        being locked for exclusive access by
                                        another process, or due to a hardware
                                        failure.

                    ERR_FILEREAD        OpenDoors was able to open the
                                        specified file, but unable to read the
                                        required data from the file. This error
                                        may be due to an invalid file format,
                                        due to a portion of the file being
                                        locked by another process, or due to a
                                        hardware failure.

                    ERR_LIMIT           An internal function limit has been
                                        exceeded. Refer to the function's
                                        description in chapter four for
                                        information on the function's
                                        limitations.

                    ERR_NOREMOTE        Indicates that a function has been
                                        called which is not valid in local
                                        mode, such as od_carrier() or
                                        od_set_dtr().


















===============================================================================
OpenDoors 5.00 Manual                                           End of Page 183






CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION
-------------------------------------------------------------------------------

               The OpenDoors control structure provides many variables which
               allow you to customize OpenDoor's behavior and appearance. These
               customization variables fit into one of the following
               categories:

                         General Behavior 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 Behavior 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_cfg_lines             Sets the configuration file's custom
                                        door information file line keywords.

               od_cfg_text              Sets the built-in log file keywords
                                        that OpenDoors will recongize.

               od_chat_active           Controls whether or not sysop chat mode
                                        is active.

               od_clear_on_exit         Controls whether the screen is cleared
                                        upon door exit.




===============================================================================
OpenDoors 5.00 Manual                                           End of Page 184


               od_colour_delimiter      Indicates what character should delimit
                                        imbedded colour codes for the
                                        od_printf() function.

               od_colour_names          Strings which OpenDoors recognizes as
                                        the names of various text colours.

               od_config_file           Used to enable or disable the OpenDoors
                                        configuration file system.

               od_config_filename       Sets the filename that will be read by
                                        the configuration file system.

               od_config_function       The callback function that OpenDoors
                                        will call to allow your program to
                                        process custom configuration file
                                        entries.

               od_default_personality   Sets the default personality to be used
                                        with the OpenDoors Multiple Personality
                                        System, and also sets the personality
                                        to use when the MPS is not active.

               od_default_rip_win       Whether OpenDoors should use the
                                        default 43-line RIP window for ANSI
                                        text (TRUE), or a 23-line window
                                        (FALSE).

               od_disable               Disable OpenDoors activities such as
                                        reading door information file and
                                        monitoring carrier detect / remaining
                                        time.

               od_errorlevel            Sets the errorlevel OpenDoors exits
                                        with under various conditions.

               od_force_local           Forces door to operate in local mode,
                                        ignoring any door information file and
                                        using default user settings.

               od_in_buf_size           Sets size of OpenDoor's internal
                                        local/remote inbound buffer.

               od_inactive_warning      Number of seconds before hanging up
                                        that OpenDoors displays the inactivity
                                        timeout warning.

               od_inactivity            Controls user inactivity timeout.

               od_ker_exec              Is called whenever od_kernel()
                                        executes.




===============================================================================
OpenDoors 5.00 Manual                                           End of Page 185


               od_last_input            Indicates whether the last input came
                                        from the remote user (==0) or the local
                                        sysop (==1).

               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               Enables or disables the OpenDoors log
                                        file system.

               od_logfile_disable       Prevents the logfile from being opened,
                                        even if the logfile is enabled by
                                        od_logfile.

               od_logfile_messages      Array of message strings that OpenDoors
                                        will use when writing log file entries.

               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_mps                   Enables or disables the OpenDoors
                                        Multiple Personality System.

               od_no_file_func          Called when no door information file
                                        can be read.

               od_no_ra_codes           Disables translation of RA/QBBS control
                                        codes.

               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.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 186


               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_statusline       Which status line (if any) is activated
                                        when the user pages the sysop.

               od_page_endmin           Indicates the time of day at which
                                        sysop paging is disabled.

               od_prog_name             Stores the name of your program, which
                                        will be written to the log file.

               od_reg_key               Stores the registration key that you
                                        receive when purchasing OpenDoors.

               od_reg_name              Stores your name or your companies name
                                        when you have purchased an OpenDoors
                                        licence (registration).

               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.

               od_swapping_path         Location where disk swap file should be
                                        created.

               od_status_on             Controls whether the status line sub-
                                        system is active.

               od_time_msg_func         Called instead of displaying time limit
                                        warning messages.




-------------------------------------------------------------------------------
od_box         char od_control.od_box_chars[8];
_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:


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 187


               od_box_chars[BOX_UPPERLEFT]  - Upper left corner of box
               od_box_chars[BOX_TOP]        - Top horizontal line
               od_box_chars[BOX_UPPERRIGHT] - Upper right corner of box
               od_box_chars[BOX_LEFT]       - Left Vertical line
               od_box_chars[BOX_LOWERLEFT]  - Lower left corner of box
               od_box_chars[BOX_LOWERRIGHT] - Lower right corner of box
               od_box_chars[BOX_BOTTOM]     - Bottom horizontal line
               od_box_chars[BOX_RIGHT]      - Right horizontal line



-------------------------------------------------------------------------------
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 38.



-------------------------------------------------------------------------------
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 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.








===============================================================================
OpenDoors 5.00 Manual                                           End of Page 188


-------------------------------------------------------------------------------
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. To replace the
               OpenDoors sysop chat facility with your own, simply activate
               your chat mode when this function is called. Your chat mode
               facility should remain active until OpenDoors sets the
               od_control.od_chat_active variable to FALSE. If you wish to
               terminate chat mode prior to this variable being set to FALSE,
               you should set this variable to FALSE yourself if you do not
               wish OpenDoors to activate its own chat mode.



-------------------------------------------------------------------------------
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_cfg_lines   char od_control.cfg_lines[25][33];

               This array contains the strings for the keywords that represent
               various lines in the definition of a custom door information
               file. Each keyword must be 32 character or less in length. These
               keywords are not case sensitive. See page 220 for more
               information on defining custom door information (drop) file
               formats. The default values for this array are as follows:

                    [0]  "Ignore"
                    [1]  "ComPort"
                    [2]  "FossilPort"
                    [3]  "ModemBPS"
                    [4]  "LocalMode"
                    [5]  "UserName"
                    [6]  "UserFirstName"
                    [7]  "UserLastName"
                    [8]  "Alias"
                    [9]  "HoursLeft"

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 189


                    [10] "MinutesLeft"
                    [11] "SecondsLeft"
                    [12] "ANSI"
                    [13] "AVATAR"
                    [14] "PagePausing"
                    [15] "ScreenLength"
                    [16] "ScreenClearing"
                    [17] "Security"
                    [18] "City"
                    [19] "Node"
                    [20] "SysopName"
                    [21] "SysopFirstName"
                    [22] "SysopLastName"
                    [23] "SystemName"
                         "RIP"                      [24] 

               If you wish to change any of these variable, you must do so
               before calling any OpenDoors functions.



-------------------------------------------------------------------------------
od_cfg_text    char od_control.od_cfg_text[47][33];

               This array of strings contains the built-in configuration file
               keywords that are recognized by OpenDoors. These keywords may be
               up to 32 characters in size, and are not case sensitive. If you
               wish to change any of these settings, you must do so before
               calling any OpenDoors functions. The default values for this
               array are as follows:

                    [0]  "Node"
                    [1]  "BBSDir"
                    [2]  "DoorDir"
                    [3]  "LogFileName"
                    [4]  "DisableLogging"
                    [5]  "SundayPagingHours"
                    [6]  "MondayPagingHours"
                    [7]  "TuesdayPagingHours"
                    [8]  "WednesdayPagingHours"
                    [9]  "ThursdayPagingHours"
                    [10] "FridayPagingHours"
                    [11] "SaturdayPagingHours"
                    [12] "MaximumDoorTime"
                    [13] "SysopName"
                    [14] "SystemName"
                    [15] "SwappingDisable"
                    [16] "SwappingDir"
                    [17] "SwappingNoEMS"
                    [18] "LockedBPS"
                    [19] "SerialPort"
                    [20] "CustomFileName"
                    [21] "CustomFileLine"
                    [22] "InactivityTimeout"

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 190


                    [23] "PageDuration"
                    [24] "ChatUserColour"
                    [25] "ChatSysopColour"
                    [26] "FileListTitleColour"
                    [27] "FileListNameColour"
                    [28] "FileListSizeColour"
                    [29] "FileListDescriptionColour"
                    [30] "FileListOfflineColour"
                    [31] "Personality"
                    [32] "NoFossil"
                    [33] "PortAddress"
                    [34] "PortIRQ"
                    [35] "ReceiveBuffer"
                    [36] "TransmitBuffer"
                    [37] "PagePromptColour"
                    [38] "LocalMode"
                    [39] "PopupMenuTitleColour"
                    [40] "PopupMenuBorderColour"
                    [41] "PopupMenuTextColour"
                    [42] "PopupMenuKeyColour"
                    [43] "PopupMenuHighlightColour"
                    [44] "PopupMenuHighKeyColour"
                    [45] "NoFIFO"
                    [46] "FIFOTriggerSize"



-------------------------------------------------------------------------------
od_chat        char od_control.od_chat_active;
_active
               This variable is set to TRUE when sysop chat mode is active, and
               is set to FALSE when sysop chat mode is not active. This
               variable can be used to determine whether or not chat mode is
               active, and to force chat mode to end. When the sysop presses
               the chat mode key ([ALT]-[C] if the default personality is being
               used) while chat mode is active, this variable is set to FALSE.



-------------------------------------------------------------------------------
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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 191


               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;
_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
               105.



-------------------------------------------------------------------------------
od_colour      char od_control.od_colour_names[12][33];
_names
               This array sets the strings that OpenDoors will recognize as
               colour description keywords. These are the keywords that can be
               imbedded in od_printf() format strings, and are also the
               keywords that can be used to change colour settings in the
               OpenDoors configuration file. If you wish to change these
               keywords, you will normally do so before calling any OpenDoors
               functions. These keywords should always be supplied in upper-
               case characters. The defaults values for this array are as
               follows:

                    [0]  "BLACK"
                    [1]  "BLUE"
                    [2]  "GREEN"
                    [3]  "CYAN"
                    [4]  "RED"
                    [5]  "MAGENTA"
                    [6]  "YELLOW"
                    [7]  "WHITE"
                    [8]  "BROWN"
                    [9]  "GREY"
                    [10] "BRIGHT"
                    [11] "FLASHING"






===============================================================================
OpenDoors 5.00 Manual                                           End of Page 192


-------------------------------------------------------------------------------
od_config      void (*od_control.od_config_file)(void);
_file
               Set this variable to INCLUDE_CONFIG_FILE to enable the OpenDoors
               configuration file system, or set it to NO_CONFIG_FILE to
               disable the configuration file system. This variable should only
               be set prior to your first call to an OpenDoors function. For
               more information on the OpenDoors configuration file system, see
               page 215.



-------------------------------------------------------------------------------
od_config      char *od_control.od_config_filename;
_filename
               If set, this variable should point to a string containing the
               filename that you wish the OpenDoors configuration file system
               to read. If this variable has its default value of NULL, the
               filename DOOR.CFG will be used by default.



-------------------------------------------------------------------------------
od_config      void (*od_control.od_config_function)(char *keyword, char
_function      *options);

               If set, this variable should point to the function that
               OpenDoors should call when lines with unrecognized keywords are
               encountered in the configuration file. This allows you to add
               your own configuration file keywords. The first parameter to
               this function will be a pointer to a string containing the
               unrecognized keywords, and the second parameter will be a
               pointer to a string containing any options that were specified
               after the keyword. If no options were specified after the
               keyword, this string will have a length of 0.



-------------------------------------------------------------------------------
od_default     void (*od_control.od_default_personality)(unsigned char
_personality   operation);

               This variable sets the default personality that OpenDoors will
               use if the multiple personality system is active. If the
               multiple personality system is not active, the personality set
               by this variable will be the only personality available. This
               variable should only be set prior to calling an OpenDoors
               function. This variable can be set to point to your own
               personality function, or it can be set to one of the manifest
               constants that represent one of the built-in personalities:

                    PER_OPENDOORS
                    PER_PCBOARD
                    PER_RA

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 193


                    PER_WILDCAT

               For more information on the OpenDoors Multiple Personality
               System, see page 220.



-------------------------------------------------------------------------------
od_default     char od_control.od_default_rip_win;
_rip_win
               This variable defaults to FALSE. When set to FALSE, OpenDoors
               resets the RIP text window to a 23-line window that is most
               appropriate for doors that support both RIP-graphics and non-RIP
               mode. When this variable is set to TRUE, OpenDoors will use the
               default sized text output window, 43 lines in size.



-------------------------------------------------------------------------------
od_disable     unsigned int 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


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 194


                    the carrier detect signal yourself, using the od_carrier()
                    function, which is described on page 51.

               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 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 setting affects OpenDoors' behavior
                    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 configuration 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.

               DIS_BPS_SETTING - When used with a FOSSIL driver, OpenDoors
                    normally changes the BPS rate to that passed from the BBS
                    (if the BBS passes a valid FOSSIL BPS rate). Setting the
                    DIS_BPS_SETTING flag disables this BPS rate setting.

               DIS_LOCAL_INPUT -  The local keyboard may be disabled by setting
                    this bit. This only affects the sysop's input in
                    circumstances that input is also accepted from the remote
                    user; this setting has no effect on the sysop function
                    keys.

               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.



-------------------------------------------------------------------------------
od             unsigned char od_control.od_errorlevel[8];
_errorlevel
               Allows you to configure the errorlevel (program exit code) which
               OpenDoors exits with under various circumstances. The elements
               of this array are as follows:


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 195


               [ERRORLEVEL_ENABLE]     Enables or disables custom errorlevels
               [ERRORLEVEL_CRITICAL]   Critical error errorlevel
               [ERRORLEVEL_NOCARRIER]  Carrier lost errorlevel
               [ERRORLEVEL_HANGUP]     Sysop manually terminated call
               [ERRORLEVEL_TIMEOUT]    User time expired errorlevel
               [ERRORLEVEL_INACTIVITY] Keyboard inactivity timeout errorlevel
               [ERRORLEVEL_DROPTOBBS]  Sysop returned user to BBS errorlevel
               [ERRORLEVEL_NORMAL]     Door has exited normally

               If you wish to override the default errorlevels used by
               OpenDoors, you should set element [ERRORLEVEL_ENABLE] of this
               array to TRUE, and set the remaining array elements to the
               appropriate errorlevels. Note that the settings in this array
               only affect the errorlevels which OpenDoors uses when it causes
               the door to exit for one of the reasons listed above. This
               setting has no effect on the errorlevel returned when your
               program explicitly exits by calling the od_exit() function, or
               your program returns by calling exit() or returning from the
               main() function. For a list of the default errorlevels used by
               OpenDoors, see page 33.



-------------------------------------------------------------------------------
od             char od_control.od_force_local;
_force_local
               This variable defaults to FALSE, which causes OpenDoors to
               behave normally. When this variable is set to TRUE prior to
               calling od_init() or any other OpenDoors functions, OpenDoors
               will operate in local mode. In this case, no door information
               file will be read. Also, the user name will be used if
               od_control.user_name has not been set prior to calling od_init()
               or the first OpenDoors function.

               The default OpenDoors settings when od_control.od_force_local is
               set are as follows:

               - ANSI mode is on
               - Time limit is 60 minutes
               - User's location is the name of the BBS, or "Unknown Location"
               otherwise if BBS name is not known.
               - User name is set to sysop's name ("Sysop" if no sysop name is
               specified in the configuration file).

               You may wish to add a "-local" type parameter to your program's
               command line, which will permit the sysop to easily operate the
               door in local mode, as an interface to the
               od_control.od_force_local setting.







===============================================================================
OpenDoors 5.00 Manual                                           End of Page 196


-------------------------------------------------------------------------------
od_in_buf      unsigned int od_control.od_in_buf_size;
_size
               Specifies the size, in characters, of the OpenDoor's internal
               local/remote inbound buffer size. Two bytes of storage are
               required for each character in this buffer. This variable should
               only be changed prior to calling od_init() or the first
               OpenDoors function. If not set, this variable defaults to a
               value of 256.

               The buffer corresponding to this variable should not be confused
               with the FOSSIL or internal communications receive buffer (which
               is set by od_control.od_com_rx_buf). Unlike the serial I/O
               receive buffer, which is used only for characters received from
               the remote system, this buffer serves as a queue for input from
               both the remote system and the local keyboard. If you find that
               characters are lost when information is being set to your door
               from the user, you may wish to increase the size of this buffer.



-------------------------------------------------------------------------------
od             unsigned int od_control.od_inactivity;
_inactivity
               OpenDoors 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_inactive    int od_control.od_inactive_warning.
_warning
               This variable sets the number of seconds prior to hanging up
               that OpenDoors displays the inactivity timeout warning. This
               variable should only be changed after your first call to an
               OpenDoors API function. If not explicitly set by your program,
               this setting defaults to 10 seconds.







===============================================================================
OpenDoors 5.00 Manual                                           End of Page 197


-------------------------------------------------------------------------------
od_ker_exec    void (*od_control.od_ker_exec)(void);

               When od_control.od_ker_exec is set to point to a function,
               OpenDoors will call this function whenever od_kernel() executes.
               This provides any easy way for you to perform your own
               processing on a regular basis during door execution. The
               od_control.od_ker_exec variable defaults to NULL.



-------------------------------------------------------------------------------
od_last        char od_control.od_last_input;
_input
               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_local       void (*od_control.od_local_input)(int);
_input
               If set, this function is called whenever the sysop presses a
               non-sysop-function key on the local keyboard. The key pressed is


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 198


               passed to the function in the single int parameter that it
               accepts.



-------------------------------------------------------------------------------
od_logfile     void *(od_control.od_logfile)(void);

               To make the OpenDoors log file system available in your program,
               set this variable to INCLUDE_LOGFILE, prior to calling any
               OpenDoors functions. If not set, or if set to NO_LOGFILE, the
               OpenDoors log file system will not automatically be enabled.



-------------------------------------------------------------------------------
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 logfile system is enabled using od_control.od_logfile.



-------------------------------------------------------------------------------
od_logfile     char *od_control.od_logfile_messages[14];
_messages
               This array of pointers to strings contains the messages that
               OpenDoors will automatically write to the log file, if the log
               file system is enabled. If you wish to change the settings of
               this array, you should do so before calling any OpenDoors
               functions. The default strings for this array are as follows:

               [0] "Carrier lost, exiting door"
               [1] "System operator terminating call, exiting door"
               [2] "User's time limit expired, exiting door"
               [3] "User keyboard inactivity time limit exceeded, exiting door"
               [4] "System operator returning user to BBS, exiting door"
               [5] "Exiting door with errorlevel %d,
               [6] "Invoking operating system shell"
               [7] "Returning from operating system shell"
               [8] "User paging system operator"
               [9] "Entering sysop chat mode"
               [10] "Terminating sysop chat mode"
               [11] "%s entering door"
               [12] "Reason for chat: %s"
               [13] "Exiting door"






===============================================================================
OpenDoors 5.00 Manual                                           End of Page 199


-------------------------------------------------------------------------------
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 any
               OpenDoors functions. 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 "DOOR.LOG"
               will be used. If you wish to set this variable, you should do so
               prior to calling od_init() or any OpenDoors 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_mps         void (*od_control.od_mps)(void);

               To make the OpenDoors Multiple Personality system available in
               your program, set this variable to INCLUDE_MPS before calling
               any OpenDoors functions. If this variable is not set, or is set
               to NO_MPS, the Multiple Personality System will be disabled. For
               more information on the OpenDoors Multiple Personality System,
               see page 223.





===============================================================================
OpenDoors 5.00 Manual                                           End of Page 200


-------------------------------------------------------------------------------
od_no_         void (*od_control.od_no_file_func)();
file_func
               If od_no_file_func is set to point to a function, that function
               will be called whenever a door information (drop) file cannot be
               located or read. This provides an easy mechanism to add your own
               door information file reader, or to provide a local login prompt
               when no drop file is present. If you wish the door to operate in
               local mode, you should set od_control.od_force_local to TRUE
               prior to returning from your function. If you have successfully
               read your own door information file format, you should set
               od_control.od_info_type to CUSTOM. If neither of these variables
               are set by the od_no_file_function, OpenDoors will report that
               it is unable to find or read a door information file and will
               exit immediately.



-------------------------------------------------------------------------------
od_no_ra       char od_control.od_no_ra_codes;
_codes
               This variable defaults to FALSE. When set to TRUE, the
               translation of the RemoteAccess/QuickBBS control codes by the
               functions od_sen_file(), od_hotkey_menu() and od_disp_emu() is
               disabled.



-------------------------------------------------------------------------------
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, copyright
               notice and registration information when the program begins
               execution. Set this variable to TRUE to disable the display of
               copyright and associated information. When this variable is set
               to TRUE, OpenDoors also does not change the initial display
               colour on startup. For obvious reasons, this variable does not
               take effect when OpenDoors is operating in unregistered mode.



-------------------------------------------------------------------------------
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
               od_exit() function is called. However, you may optionally set
               this variable to TRUE after od_init() or some OpenDoors function

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 201


               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 serial port and re-writing the door information file
               will be carried out. If you set the od_noexit variable to TRUE,
               you will probably have to provide some mechanism to allow your
               program to detect when OpenDoors shutdowns due to the loss of
               carrier, etc. 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_page        char od_control.od_page_statusline;
_statusline
               This variable controls which status line, if any, is activated
               when the user pages the system operator (via the od_page()
               function). A value between 0 and 9 causes the corresponding
               status line to be activated. A value of -1 prevents any change
               from being made to the current status line setting. This

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 202


               variable will normally be set by personality functions (see page
               223).



-------------------------------------------------------------------------------
od_prog_name   char od_control.od_prog_name[40];

               This variable should contain the full name of your program, up
               to 39 characters. Currently, this variable is only used when
               writing to the OpenDoors log file. However, this variable may
               also be used for other purposes in future versions. If not set,
               OpenDoors will use its name and version information in place of
               this variable. If used, this variable should be set prior to
               calling any OpenDoors functions.



-------------------------------------------------------------------------------
od_reg_key     unsigned log od_control.od_reg_key;

               When you purchase an OpenDoors licence (registration), this
               variable should be set to your registration key, prior to
               calling any OpenDoors functions.



-------------------------------------------------------------------------------
od_reg_name    char od_control.od_reg_name[36];

               When you purchase an OpenDoors licence (registration), this
               variable should be set to your name, or your company's name, as
               is listed in your OpenDoors registration record.



-------------------------------------------------------------------------------
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
               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.







===============================================================================
OpenDoors 5.00 Manual                                           End of Page 203


-------------------------------------------------------------------------------
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 separating 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 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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 204


               page 136. 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 136.



-------------------------------------------------------------------------------
od_time        void (*od_control.od_time_msg_func)(char *string)
_msg_func
               This variable defaults to a value of NULL. If set to point to a
               function, OpenDoors will call this function INSTEAD OF
               displaying time limit warning messages to the user. The messages
               redirected to this function are:

                    - Inactivity timeout warning
                    - Inactivity timeout expired
                    - Less than 4 minutes left today
                    - Daily time limit expired

               Providing your own od_time_msg_func allows you to display these
               messages at a specific screen location, within a popup window,
               etc.

               The function pointed to by od_time_msg_func must accept a single
               parameter of type char *. OpenDoors will pass a pointer to the
               string containing the time limit message in this parameter.









===============================================================================
OpenDoors 5.00 Manual                                           End of Page 205







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 32.) 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 5.00 Manual                                           End of Page 206


                                  }
                               }
                            }


-------------------------------------------------------------------------------
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 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 5.00 Manual                                           End of Page 207





-------------------------------------------------------------------------------
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
KEYS           example, 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 four variables:

                         unsigned char od_control.od_num_keys;
                         unsigned int od_control.od_hot_key[16];
                         unsigned int od_control.od_last_hot;
                         void (*od_control.od_hot_function[16])(void);

               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.

               As an alternative to testing the contents of the
               od_control.od_last_hot variable, you  can also have your program
               respond to custom sysop function keys by providing a callback
               function in the array:

                         void (*od_control.od_hot_function[16])(void);

               The Nth element in this array corresponds to the Nth element in
               the od_control.od_hot_key array. To use this mechanism, simply

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 208


               set the appropriate element of this array to point to the
               function that you wish to have OpenDoors call when the sysop
               presses the corresponding function key. For instance, assume
               that the following function is included in your program's source
               code:

                    void addPoints(void)
                       {
                       /* add ten points to the user's score */
                       currentUser->points += 10;
                       }

               If you wanted to have this function called when the sysop
               presses the [Page Up] key, you could do the following:

                    /* get number of new sysop function key, and increment */
                    /* total number of keys */
                    int new_key = od_control.od_num_keys++;

                    /* Set next sysop hotkey to Page Up */
                    od_control.od_hot_key[new_key] = 0x4900;

                    /* Set corresponding function to addPoints() */
                    od_control.od_hot_function[new_key] = addPoints;































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 209






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 125. 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.         | Color of page pausing prompt that is   |
               | od_continue_col     | displayed at the end of each page      |
               |                     |                                        |
               | 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   |                                        |
               |                     |                                        |
               | od_control.         | Color of the window title as displayed |
               | od_menu_title_col   | by od_popup_menu()                     |
               |                     |                                        |
               | od_control.         | Color of the window border as          |
               | od_menu_border_col  | displayed by od_popup_menu()           |
               |                     |                                        |
               | od_control.         | Color of the normal text displayed     |
               | od_menu_text_col    | by od_popup_menu()                     |
               |                     |                                        |
               | od_control.         | Color of the shortcut keys displayed   |

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 210


               | od_menu_key_col     | by od_popup_menu()                     |
               |                     |                                        |
               | od_control.         | Color of the selection bar as          |
               | od_menu_highlight_  | displayed by od_popup_menu()           |
               | col                 |                                        |
               |                     |                                        |
               | od_control.         | Color of the shortcut keys displayed   |
               | od_menu_highkey_col | on the selected line by od_popup_menu()|
               +---------------------+----------------------------------------+














































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 211






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 API 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"          |
|                       |     |                                              |

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 212


| od_before_chat        |  *  | "\n\rSysop breaking in for chat...\n\r\n\r"  |
|                       |     |                                              |
| 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_hanging_up         |  *  | "Terminating Call"                           |
|                       |     |                                              |
| 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 5.00 - (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"                                        |

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 213


|                       |     |                                              |
| od_month[6]           |  3  | "Jul"                                        |
|                       |     |                                              |
| od_month[7]           |  3  | "Aug"                                        |
|                       |     |                                              |
| od_month[8]           |  3  | "Sep"                                        |
|                       |     |                                              |
| 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_sending_rip        |  *  | "\xb4 Sending RIP File \xc3"                 |
|                       |     |                                              |
| 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_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 5.00 Manual                                           End of Page 214



-------------------------------------------------------------------------------
CHAPTER 6 - SPECIAL TOPICS
-------------------------------------------------------------------------------




CONFIGURATION FILE SYSTEM
-------------------------------------------------------------------------------

               One of the most useful OpenDoors features that you can
               optionally choose to include in your programs is the OpenDoors
               configuration file system. All that is required to enable the
               configuration file system is to include the following line
               before your first call to any OpenDoors function:

                    od_control.od_config_file = INCLUDE_CONFIG_FILE;

               OpenDoors will now search for and read an OpenDoors
               configuration file. If you do not specify the name of this file,
               the default name of DOOR.CFG will be used. Using this
               configuration file, the sysop can set a wide variety of options,
               such as modem and system configuration information, maximum time
               limits for the door, and even define custom door information
               (drop) file formats. The example DOOR.CFG file included in your
               OpenDoors package shows the format and all options that are
               automatically supported by the configuration file system. This
               configuration file format is designed to be easy to use, and the
               example configuration file contains comments which provide a
               complete description of each option. Feel free to redistribute
               DOOR.CFG or a modified version of this file with your door
               programs. In addition to the many configuration file settings
               already supported, you can add your own settings that are
               specific to your particular program.

               To specify your own filename for the configuration file, use the
               od_config_filename control structure variable. For example, the
               following line:

                    od_control.od_config_filename = "MYDOOR.CFG"

               causes OpenDoors to look for the configuration file MYDOOR.CFG
               instead of the default DOOR.CFG.

               OpenDoors fill first search for the configuration file in the
               directory specified in the od_config_filename variable, if a
               specific directory name was supplied. If not found, it will then
               search the current directory. If the configuration file system
               is unable to locate a configuration file, or if any settings are
               omitted from the file, the default values for these settings
               will be used automatically. This means that the configuration
               file is always optional, unless your program has custom settings
               that it requires in order to run.

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 215



               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
               sensitive, but some of the options are. The order of options in
               the configuration file is not significant, with the exception of
               the "CustomFileLine" option. For more information on the
               "CustomFileLine" setting, see the section that begins on page
               220. The built-in configuration options are as follow:

               BBSDir - BBS System directory. Indicates where the door
                    information file (drop file) can be found.

               DoorDir - The door's working directory. This is where the door's
                    system files are located. OpenDoors will automatically
                    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.


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 216


                    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.
               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 port number that the
                    modem is connected to. FOSSIL port 0 usually corresponds to
                    COM1, 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.

               The last two configuration file options, "CustomFileName" and
               "CustomFileLine" allow you or the system operator using your
               program to define your own door information (drop) file formats.
               For more information on this topic, see the section which begins
               on page 220.

               You can also extend OpenDoor's configuration file format to add
               your own options, by supplying a callback function that will be

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 217


               called whenever OpenDoors encounters an unrecognized
               configuration file keyword. The prototype of this function
               should be as follows:

                    custom_line_function(char *keyword, char *options)

               To cause OpenDoors to use your function, you would include the
               following line before your first call to any OpenDoors function:

                    od_control.od_config_function = custom_line_function;

               (You can use a different function name if you wish.) When
               OpenDoors encounters unrecognized keyword, it will now call your
               function, passing a pointer to an upper case version the keyword
               string in the first parameter, and a pointer to any options that
               follow the keyword in the second parameter. 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 would simply be
               ignored.

               The example program below demonstrates how to use the custom
               line function to add your own configuration file options. This
               program looks for three custom configuration file options,
               "RegistrationKey", "DefaultColour" and "DisplayWinners". If the
               "RegistrationKey" option is present, the numerical value
               following this option is stored in the global variable "key". If
               the "DefaultColour" option is present, the color description
               (such as "Bright Red on Black") is translated to an
               od_set_attr() colour code using od_colour_config(). This color
               setting is stored in the global variable default_colour. Since
               this variable is initialized to 0x07 (the value for dark white
               on black), if this option is omitted, that colour is used by
               default. If the "DisplayWinners" option is included in the
               configuration file, the global variable display_winners is set
               to TRUE, regardless of any options that may follow this keyword.


               #include "opendoor.h"                  /* Include opendooor.h */
                                       /* Prototype for custom line function */
               void custom_line_function(char *keyword, char *options);

               unsigned long key=0L; /* Variables for our own config option */
               unsigned char default_colour=0x07;
               char display_winners=FALSE;

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 218



               main()                     /* Program's execution begins here */
                  {            /* Begin door operations, reading config file */
                  od_config_file = INCLUDE_CONFIG_FILE;
                  od_init();

                                        /* Main program's operations go here */

                  od_exit(FALSE,10);                            /* Exit door */
                  }

                                            /* Code for custom line function */
               void custom_line_function(char *keyword, char *options)
                  {                         /* If option is registration key */
                  if(stricmp(keyword,"REGISTRATIONKEY")==0)
                     {
                     key=atol(options);             /* Store key in variable */
                     }                           /* If option is text colour */
                  else if(stricmp(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(stricmp(keyword,"DISPLAYWINNERS")==0)
                     {              /* If keyword is present, turn on option */
                     display_winners=TRUE;
                     }
                  }




























===============================================================================
OpenDoors 5.00 Manual                                           End of Page 219






DEFINING CUSTOM DOOR INFORMATION FILE FORMATS
-------------------------------------------------------------------------------

               As is mentioned in the previous section, the OpenDoors
               configuration file system provides two settings which allow the
               sysop to define a custom door information file format. This
               permits OpenDoors doors to operate directly on any BBS system
               that produces a door information file format not directly
               supported by OpenDoors. 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, the sysop should use the
               BBSDir configuration file setting. 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:

                    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 pseudonym / handle

                    HOURSLEFT - Hours user has left online

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 220



                    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

                    NODE - 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

               As an example of how to define custom door information file
               formats, consider the following imaginary file format, which we
               will name DROPINFO.TXT:

                    Brian Pirie         <-- User name
                    0                   <-- Local mode
                    COM1:               <-- Serial port to use
                    9600                <-- BPS rate
                    22:30:15 05-08-95   <-- File creation time
                    35                  <-- Time remaining (in minutes)
                    1                   <-- ANSI mode
                    Ottawa, Canada      <-- Location

               This format would be defined in an OpenDoors configuration file
               as follows:





===============================================================================
OpenDoors 5.00 Manual                                           End of Page 221


                    CustomFileName DROPINFO.TXT
                    CustomFileLine USERNAME
                    CustomFileLine LOCALMODE
                    CustomFileLine COMPORT
                    CustomFileLine MODEMBPS
                    CustomFileLine IGNORE
                    CustomFileLine MINUTESLEFT
                    CustomFileLine ANSI
                    CustomFileLine CITY

               Notice that the first "CustomFileLine" keyword in the
               configuration file corresponds to the first line in our
               DROPINFO.TXT file, the second "CustomFileLine" to the second
               line, and so on. Also notice that the keyword "IGNORE" is used
               for the line that contains the file creation time, since there
               is no CustomFileLine keyword that allows you to read this
               information.






































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 222






MULTIPLE PERSONALITY SYSTEM
-------------------------------------------------------------------------------

               The OpenDoors Multiple Personality System allows OpenDoors to
               support multiple sysop function key / status line
               "personalities". Most commonly, you will use this feature in
               conjunction with the "Personality" setting in the OpenDoors
               configuration file, to allow the sysop to choose one of the
               built-in personalities that most closely mimics the BBS software
               they are using. OpenDoors includes the following personalities:

                    Configuration Keyword         Manifest constant
                    -----------------------------------------------------------
                    Standard                      PER_OPENDOORS
                    PCBoard                       PER_PCBOARD
                    RemoteAccess                  PER_RA
                    Wildcat                       PER_WILDCAT

               The PCBoard, RemoteAccess and Wildcat personalities mimic the
               status lines and function keys used by the BBS packages with
               those names. The Standard personality, which is the personality
               used by default, is a trimmed down version of the status lines
               provided by OpenDoors 4.10 and earlier.

               In addition to using the personalities supplied with OpenDoors,
               you can create your own personalities. This simply involves
               writing a function which OpenDoors will call to setup the sysop
               function keys and to display the status line.

               Include the following line before your first call to any
               OpenDoors function:

                    od_control.od_mps = INCLUDE_MPS;

               to include the multiple personality system in your program. This
               also enables the Personality setting in the configuration file,
               if you are using the configuration file system.

               You can set the default personality to be used by OpenDoors by
               setting od_control.od_default_personality to one of the manifest
               constants listed in the table above. If you have included the
               multiple personality system in your program, this setting will
               determine the personality to use if the "Personality" option is
               not set in the configuration file, and your program does not
               later change the personality using the od_set_personality()
               function. If you do not include the multiple personality system
               in your program, this setting will determine the personality
               that will always be used.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 223


               Creating your own personality involves writing a single
               function.. Whenever OpenDoors needs to perform an operation that
               involves the personality, it will call this function, passing
               one of the following message values:

               PEROP_INITIALIZE    Initialize the personality, installing any
                                   custom function keys.
               PEROP_DEINITIALIZE  Deinitialize the personality, returning any
                                   changed settings to their original values.
               PEROP_CUSTOMKEY     Indicates that a custom function key has
                                   been pressed.
               PEROP_DISPLAYx      Where x is a number from 1 to 10. Indicates
                                   that the specified status line should be
                                   drawn from scratch.
               PEROP_UPDATEx       Where x is a number from 1 to 10. Indicates
                                   that the specified status line should be
                                   updated to reflect any changes.

               If you have enabled the multiple personality system by setting
               od_control.od_mps to INCLUDE_MPS, you can install your
               personality function into OpenDoors by calling
               od_add_personality(). When you call od_add_personality(), you
               supply a string containing the name of the personality, along
               with the top and bottom output line numbers to use. These line
               numbers specify the portion of the screen to use for door
               output, leaving the remainder of the screen available for
               displaying the personality's status line. Once the personality
               has been installed into OpenDoors, it can be selected by the
               sysop using the "Personality" configuration file option, or
               manually activated using the od_set_personality() function. For
               more information on the od_add_personality() function, see page
               46.

               You can make your personality function the default personality
               by setting od_control.od_default_personality to point to your
               personality function. As is the case with the built-in
               personalities, this setting will be used as the default
               personality if you have enabled the multiple personality system
               by setting od_control.od_mps to INCLUDE_MPS. If you have not
               enabled the multiple personality system in this manner, your
               personality function will become the one and only personality
               used within your program. When creating your own personality,
               you can use the od_control.od_page_statusline variable to set
               which status line (if any) will be activated when the user pages
               the system operator.










===============================================================================
OpenDoors 5.00 Manual                                           End of Page 224






LOG FILE SYSTEM
-------------------------------------------------------------------------------

               In order for the system operator to monitor system activity and
               diagnose problems that have ocurred while the system was
               unattended, it is common for BBS software and door programs to
               record major events in a log file. This log file typically
               records the date and time of evens such as a user logging on or
               off, transferring files, sending messages, paging the system
               operator, and similar activities. Sometimes the system operator
               will configure all of the pieces of software running on a
               paticular node to write to a single log file. In other cases,
               the system operator will prefer to have each program write to
               its own log file. However, software serving one line of a multi-
               node BBS system should never attempt to write to the same log
               file that is used by anothe rnode.

               OpenDoors uses the "FrontDoor format" log file 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 5.00
                         > 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

               To enable the OpenDoors log file system, simply include the
               following line before your first call to any OpenDoors function:

                    od_control.od_log_file = INCLUDE_LOGFILE;

               When OpenDoors is initialized, it will open the log file and
               begin logging activities, unless logging has been disabled with
               the od_control.od_logfile_disable variable. The log file name
               will be taken from the od_control.od_logfile_name variable,
               which is usually set by the configuration file. If no logfile
               name has been set, OpenDoors 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.

               The od_control.od_prog_name variable sets the program name that
               is written to the log file immediately after the current date
               information. If this variable is not set, OpenDoors will write
               its own name and version information in this place.

               When the OpenDoors log file system is enabled, OpenDoors will
               automatically produce logfile entries for the following events:

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 225



                         - User paging sysop
                         - Beginning of sysop chat
                         - Ending of sysop chat
                         - Sysop entering DOS shell
                         - Sysop returning from DOS shell
                         - User inactivity timeout
                         - User time expired
                         - Sysop dropping user back to BBS
                         - Sysop hanging up on user
                         - User hanging 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 array od_control.od_logfile_messages.

               The logfile is automatically closed when your program exits.




































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 226






MAKING DOORS MULTI-NODE-AWARE
-------------------------------------------------------------------------------

               Today, it is common for BBS systems to have multiple nodes
               (phone lines) that can be in use by different users
               simultaneously. As such, it is often possible for door programs
               to be in use concurrently by more than one person, each on a
               different node of the BBS. Some doors are designed to behave on
               multi-node systems just as they would on single-line BBSes
               (except for the fact that more than one person may be using the
               door at once). Other doors take special advantage of multi-node
               environments to permit users to interact or communicate with one
               another in "real time". In either case, there are a number of
               issues that the door programmer must be aware of when writing
               doors for multiple node BBSes that are not of concern in single
               node situations.

               If you expect your door program to be used on a multi-line BBS
               system, the best time to begin planning for multi-node
               capabilities is when you first start to write your door. Writing
               multi-node-aware doors is not usually much more complicated than
               writing doors that are not multi-node-aware. However, the job is
               usually much easier if you plan multi-node capabilities from the
               beginning.

               OpenDoors is designed for use with both single-node and
               multiple-node BBS systems, and many simple doors may not require
               any special attention to multi-node capabilities. However, if
               your door must access any data files or other resources that are
               to be shared among doors, it is your responsibility to
               coordinate access to these resources. While this section deals
               primarily with sharing access to files, similar principles apply
               to coordinating access to other resources such as CD-ROM drives
               or packet network connections.

               When sharing access to files between multiple nodes, there are
               generally two issues that you have to deal with:

                    1. Coordinating write access to files or records within a
                       file in order that only one node is attempting to write
                       to a file at any instant. If you do not do this, the
                       information being written by one node may be overwritten
                       by another node.

                    2. Keeping information read into memory from files up to
                       date.

               Often, these two requirements go hand in hand. For instance,



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 227



-------------------------------------------------------------------------------
CHAPTER 7 - DEBUGGING AND GETTING ASSISTANCE WITH OPENDOORS
-------------------------------------------------------------------------------




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 5.00 Manual                                           End of Page 228



               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 5.00 Manual                                           End of Page 229






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 compiling programs written
               with OpenDoors, see page 25.

               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         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 (this is probably not a good idea), use the function
               call od_disp_emu("\xc", TRUE);


-------------------------------------------------------------------------------
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.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 230


-------------------------------------------------------------------------------
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.

















































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 231






OPENDOORS SUPPORT
-------------------------------------------------------------------------------

               The powerful and easy to use door toolkit and this comprehensive
               manual are only two portions of how OpenDoors helps you to write
               BBS door and similar programs. 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 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.

                    -   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 5.00 Manual                                           End of Page 232


               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 SUPPORT 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***

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 233



                  My Internet address is:

                              brian@bpecomm.ocunix.on.ca

                  My CompuServe ID is:

                              75122,2303

                  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.
               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 228. 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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 234


               conventional mail, it would be easiest for me if you sent your
               suggestions on the suggestion form, located on page 21. 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 5.00 Manual                                           End of Page 235


-------------------------------------------------------------------------------
APPENDIX A - CONTENTS OF PACKAGE
-------------------------------------------------------------------------------




               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 whose name began with ODOORS40.
               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.

               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:00 is part of OpenDoors 4.00. 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.

               MISCALENEOUS FILES
                    FILE_ID.DIZ    Description of the OpenDoors package
                    DORINFO1.DEF   Sample door info file for testing doors
                    DOOR.CFG       Sample OpenDoors configuration file

               EXAMPLE PROGRAMS
                    EX_HELLO.C     Demonstrates how simple a door can be
                    EX_CHAT.C      Split-screen sysop chat program
                    EX_MUSIC.C     Example of ANSI music in OpenDoors
                    EX_SKI.C       Simple slalom skiing action game
                    EX_VOTE1.C     Steps in building EZVote polling program
                    EX_VOTE2.C               "                 "
                    EX_VOTE3.C               "                 "
                    EX_VOTE4.C               "                 "
                    EX_VOTE5.C               "                 "
                    EZVOTE.EXE     Compiled version of EX_VOTE5.C

               THE LIBRARY FILES
                    ODOORS.LIB     Small 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.TXT   OpenDoors programmer's manual; this file



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 236


-------------------------------------------------------------------------------
APPENDIX B - CHANGES FOR THIS VERSION
-------------------------------------------------------------------------------




               Below is a list of enhancements and changes between OpenDoors
               4.10 and OpenDoors 5.00. A File containing a complete history of
               OpenDoors is available for download from the OpenDoors support
               BBS (see page 232).

               Version 5.00 represents several major steps forward for
               OpenDoors. In addition to numerous bug fixes and minor
               improvements, a number of major new features have been added to
               this version. These include an optional multiple personality
               system which allow the sysop to choose the status line and
               function key style they prefer. This version also adds text-mode
               support for RIP (Remote Imaging Protocol) graphics, and adds a
               group of advanced ANSI/AVATAR/RIP functions for scrolling areas
               of the screen, saving and restoring portions of the screen and
               creating pop-up windows and menus. Also new in this version is
               support for compilers other than Borland/Turbo C(++), such as
               compilers from Microsoft. Version 5.00 also adds built-in
               communications support, making the use of a FOSSIL driver
               optional. Furthermore, direct support for additional BBS systems
               has been added. The list below provides more detail of the
               changes and new features in version 5.00:

                    - The nonstop key ([=]) now works correctly during
                      FILES.BBS listing.

                    - New door information file formats now supported include:
                      RA 2.00 EXITINFO.BBS.

                    - If the TASK environment variable is set, OpenDoors will
                      now use its value to determine the current node number.

                    - The od_control.od_spawn_freeze_time variable now works
                      correctly. Previously, the user's time would always be
                      frozen during od_spawn...() execution, regardless of the
                      value of this variable.

                    - A new feature known as the "Multiple Personality System"
                      has been added to this version. If you choose to include
                      the Multiple Personality System in a door, the sysop will
                      be able to specify which of a number of "personalities"
                      should be used. Each personality defines the statusline
                      appearance and function keys seen by the sysop, and has
                      no effect on the door's operation from the user's
                      standpoint. OpenDoors 5.00 includes personality
                      definitions for WildCat, RemoteAccess, PC-Board, and it's
                      own simplified RA style status lines. You can also define
                      your own personalities by writing a personality

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 237


                      definition function. If your choose not to include the
                      Multiple Personality System in a door, you will still be
                      able to define which single personality you wish
                      OpenDoors to use.

                    - This version of OpenDoors can be used with a larger
                      variety of compilers than where supported by the previous
                      version. OpenDoors 5.00 is known to work with all
                      versions of Turbo C, Turbo C++, Borland C++, Microsoft C,
                      Microsoft C++, Quick C and Visual C++. It should also
                      work with any other MS-DOS based ANSI C compiler that
                      supports the Microsoft/DOS .OBJect and .LIBrary file
                      formats.

                    - A new diagnostics feature has been added to OpenDoors,
                      which allows you to determine the reason for the most
                      recent OpenDoors function failure. When any OpenDoors
                      function returns a failure condition, it also sets the
                      new od_control.od_error variable to indicate the reason
                      for the failure.

                    - Added additional definitions to OPENDOOR.H, to map names
                      of OpenDoors functions and variables with the word
                      "colour" from the U.S. spelling "color". In other words,
                      both od_set_colour() and od_set_color() are now
                      recognized by OpenDoors.

                    - The od_list_files() now supports more intelligent path
                      specifications. If the parameter to od_list_files() is
                      NULL or empty, it will search for a FILES.BBS file in the
                      current directory. If a directory path is specified, it
                      will look for a FILES.BBS in that directory. If a full
                      directory and filename are specified, the specified
                      filename will be used in place of FILES.BBS.

                    - To save space, the compact memory model library is no
                      longer included in the normal OpenDoors package. The
                      compact memory model library is now available seperately.

                    - A new function, od_set_dtr(), has been added to allow the
                      DTR line to the modem to be manually controlled. This can
                      be useful in writing programs where you wish to force the
                      modem to hangup, such as a call-back verification door.

                    - Added additional support for various DOS multitasking
                      environments. OpenDoors is now specifically Microsoft
                      Windows aware. OpenDoors also now gives up time to other
                      waiting tasks when it is idle during chat mode.

                    - The od_edit_str() "M" mode now capitializes a character
                      following a dash '-' character.

                    - When transmitting more than one character at a time,
                      OpenDoors now uses the FOSSIL trasfer block function,

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 238


                      instead of multiple calls to the transfer character
                      function. This should help to improve performance over
                      high speed connections when running on slow PCs or under
                      multitasking environments.

                    - OpenDoors 4.10 would not correctly change the display
                      colour from high-intensity back to low-intensity. This
                      problem has been fixed.

                    - OpenDoors now recognizes DORINFO?.DEF filenames with
                      alphabetical identifiers (ie, DORINFOA.DEF thru
                      DORINFOZ.DEF) for nodes 10 thru 35.

                    - Improvements have been made to the logfile system. An
                      exit at errorlevel zero no longer causes garbage to be
                      written to the logfile. The logfile functions have been
                      made more reliable when operating under low stack
                      availability conditions. In the past, if a large number
                      of local variables where allocated on the stack, the
                      logfile functions would fail, often writing garbage to
                      the logfile. When the user pages the sysop for chat, the
                      user's reason for wishing a chat is also written to the
                      logfile.

                    - Support for text-mode RIP (Remote Imaging Protocol)
                      graphics has been added. Because this version of
                      OpenDoors always operates in DOS text-mode, none of the
                      graphics mode RIP features (such as drawing lines,
                      circles and displaying icons) will appear on the local
                      screen. Plans for a version of OpenDoors that will
                      operate in graphics mode and optionally display graphics
                      locally are currently under consideration. In this
                      version, RIP support includes a number of new features.
                      OpenDoors will now recognize the RIP setting passed in an
                      RA 2.00 EXITINFO.BBS file and WildCat DOOR.SYS file, and
                      also allows the RIP setting to be specified in a custom
                      door information file. The od_send_file() and
                      od_hotkey_menu() functions will now search for files with
                      .RIP, .AVT, .ANS and .ASC extensions. When displaying RIP
                      graphics to the remote user, a pop-up window appears on
                      the local screen, indicating to the sysop which file is
                      being displayed.

                    - A set of new functions have been added to permit advanced
                      screen manipulations. These functions include
                      od_gettext() and od_puttext() to save and restore
                      portions of the screen, and od_save_screen() and
                      od_restore_screen() to save and restore the entire
                      screen. od_scroll() can be used to scroll any portion of
                      the screen upwards or downwards. od_save_screen() and
                      od_restore_screen() will operate in any mode, but the
                      other functions require ANSI/AVATAR/RIP mode to be
                      available.


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 239


                    - Three additional functions, od_window_create(),
                      od_window_remove() and od_popup_menu(), have been added
                      to facilitate the creation of popup windows and menus.
                      When such a window or menu is removed from the screen,
                      the are of the screen "under" the window is returned to
                      it's original state. This allows you to create multiple
                      overlapping windows within a door program. The
                      od_popup_menu() function creates a popup window with a
                      menu from a simple menu definition string. The user can
                      select an option from this menu by pressing the key
                      associated with an option, or by moving a menu selection
                      bar using their arrow keys. These three functions require
                      an ANSI/AVATAR/RIP mode to be available.

                    - A new function, od_chat() has been added, to allow you to
                      explicitly invoke the OpenDoors chat mode from within
                      your program.

                    - A new setting variable, od_control.od_always_clear has
                      been added. When set to TRUE, od_clr_scr() will always
                      clear the screen, regardless of the user's screen
                      clearing setting. When set to FALE, od_clr_scr() will
                      only clear the screen if the user has screen clearing
                      enabled.

                    - It is now possible to configure the errorlevels OpenDoors
                      exits with under various circumstances, such as when the
                      user runs out of time remaining online. See the
                      od_control.od_errorlevel variable

                    - A new setting variable, od_control.od_force_local, can be
                      used to easily force OpenDoors to operate in local mode.
                      Using this variable you can easily add a command line
                      parameter such as "-local" to allow the sysop to force
                      your door to operate in local mode. When OpenDoors is
                      forced into local mode using this variable, it does not
                      look for a door information file, and uses default
                      settings for the user's name, etc.

                    - OPENDOOR.H now sets structure packing to single byte
                      alignment for the od_control structure when Borland and
                      Microsoft compilers are being used. In the past,
                      programmers using OpenDoors have experienced difficulties
                      the od_control structure when the compiler has been set
                      to use word packing.

                    - OpenDoors now closes the FOSSIL driver prior to
                      performing a spawn or sysop DOS shell. This allows doors
                      or other communications programs which use the FOSSIL
                      driver to be executed while the door's execution is
                      suspended.

                    - When used with a FOSSIL driver, OpenDoors normally
                      changes the BPS rate to that passed from the BBS (if the

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 240


                      BBS passes a valid FOSSIL BPS rate). This BPS rate
                      setting may now be disabled by setting the
                      DIS_BPS_SETTING bit of the od_control.od_disable
                      variable.

                    - A function hook has been added to allow you to install a
                      function to be called whenever od_kernel() executes
                      (od_control.od_ker_exec). Another function hook,
                      od_control.od_time_msg_func, can be installed to override
                      OpenDoor's time limit warning messages.

                    - A new array, od_control.od_hot_function, allows the you
                      to define functions to be called when any of the
                      programmer-defined sysop hotkeys have been pressed.

                    - A function hook, od_control.od_no_file_func, has been
                      added. This function will be called whenever OpenDoors is
                      unable to find or read a door information file. This
                      allows you to add your own door information file reader,
                      or to provide a local login prompt when no door
                      information file is present.

                    - Previously, OpenDoors would stop correctly updating the
                      user's remaining time at midnight when running under
                      certain BIOSes. This problem has been fixed.

                    - The current display colour attribute can now be accessed
                      through an control structure member,
                      od_control.od_cur_attrib.

                    - od_send_file() and od_hotkey_menu() no longer pause with
                      a "Continue?" prompt prematurely in files that have line
                      lengths greater than 254 characters.

                    - The local keyboard may now be disabled by setting the
                      DIS_LOCAL_INPUT bit of od_control.od_disable. This only
                      affects the sysop's input in circumstances that input is
                      also accepted from the remote user; this setting has no
                      effect on the sysop function keys.

                      A new function hook:                      -

                         void (*od_control.od_local_input)(int);

                      has been added. If set, this function will be called
                      whenever the sysop presses a non-sysop-function key on
                      the local keyboard.

                    - od_control.od_clear_on_exit now controls whether the
                      screen is cleared before shelling or executing
                      od_spawn...(), in addition to before OpenDoors shuts
                      down.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 241


                    - od_page() now restores the original display colour before
                      returning.

                    - It is now possible to display an entire string of
                      characters with terminal emulation, using the new
                      function od_disp_emu().

                    - OpenDoors will now display a small popup window when
                      disconnecting the current connection.

                    - A new variable, od_control.od_in_buf_size, can now be set
                      prior to calling any OpenDoors function to set the size
                      of OpenDoors combined local/remote keyboard input buffer.
                      By default, this buffer is 256 bytes in size.

                    - Previously, there were a number of OpenDoors API
                      functions that would not correctly initialize OpenDoors
                      if they were the first function called in the program.
                      This has been fixed.

                    - To facilitate setting of bps rates up to 115,200,
                      od_control.baud is now an unsigned long.

                    - A new setting, od_control.od_no_ra_codes, has been added
                      to disable the use of RemoteAccess/QuickBBS control codes
                      by od_send_file()/od_hotkey_menu()/od_disp_emu(). The
                      RemoteAccess/QuickBBS ASCII 1 "pause for key" is also now
                      recognized.



























===============================================================================
OpenDoors 5.00 Manual                                           End of Page 242


-------------------------------------------------------------------------------
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
               upcoming versions of OpenDoors include:

                    - Support for additional programming
                      operating systems.

                    - Additional RIP graphics support, including display of RIP
                      images on local screen.

                    - 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 existing OpenDoors features, such as more
                      configuration file options, multiple log file formats,
                      and many smaller changes.

                    - Since the user's time remaining field is not consistently
                      written to the EXITINFO.BBS file (some packages write the
                      actual time remaining, while others write the users total
                      time limit for the connection, to this field), OpenDoors
                      now reads this information from the DORINFOx.DEF file


===============================================================================
OpenDoors 5.00 Manual                                           End of Page 243


                      that must also always be present when an EXITINFO.BBS is
                      used.





















































===============================================================================
OpenDoors 5.00 Manual                                           End of Page 244


-------------------------------------------------------------------------------
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 reluctant 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

                    - All those who participate in the OpenDoors conference,
                      who provide many suggestions, bug reports and words of
                      encouragement.

                    - 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
                              Joel Downer
                              Mike Hartmann
                              Winfried Hirsch
                              Robert La Ferte
                              Ron Le Blanc
                              Bill Meck
                              Bill Pavich
                              Mark Williamson






















===============================================================================
OpenDoors 5.00 Manual                                           End of Page 245


-------------------------------------------------------------------------------
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

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 246


               will indicate whether or not a user has ANSI graphics, whether
               or not the user has screen clearing turned on, and whether or
               not the 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 */
                         }




===============================================================================
OpenDoors 5.00 Manual                                           End of Page 247


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 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.




===============================================================================
OpenDoors 5.00 Manual                                           End of Page 248


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
               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           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.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 249


ECHO           See "Local Echo".


FOSSIL         The FOSSIL driver, or simply FOSSIL, is a TSR program or
DRIVER         device driver which OpenDoors can optionally make use of in
               order to communicate with the modem. The FOSSIL driver 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.) FOSSIL drivers
               are also available for other specialized serial port hardware,
               such as the popular "DigiBoard" multi-port serial card.


LIBRARY        The term "library" or "library file" is a collection of
               precompiled functions and variables that can be used in other
               programs. All of the features, capabilities and functions of
               OpenDoors that you can make use of are contained within the
               OpenDoors library files. (Likewise, the C runtime library,
               consisting of the familiar functions such as fopen(), printf()
               and atoi(), is also contained within a library file.) For more
               information on the different OpenDoors library files, see the
               section that begins on page 25.

               Library files are actually a collection of individual object
               files. When you compile a program that makes use of a library
               file, only those portions of the library file that your program
               actually uses are linked into your program's .EXE file.

               Library files can be identified by a .LIB extension.


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.



===============================================================================
OpenDoors 5.00 Manual                                           End of Page 250


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.


MODEM          A device connected to a computer which permits it to communicate
               with other computers, usually over standard telephone lines.


OBJECT FILE    An object file contains the compiled version of a source code
               file of a program. The source code file may be a .C file, .CPP
               file, .ASM file, .PAS file, .BAS file, or any number of other
               extensions associated with other programming languages. When any
               of these language's source code files are compiled, a .OBJ file
               is created containing information such as the executable code,
               and names of symbols (variables and functions) that are to be
               shared with other .OBJ files. In order to produce a .EXE file
               that may be executed, a process known as linking must be
               performed. During the link process, one or more object files
               composing your program are combined, along with the necessary
               code from any library files being used, in order to produce the
               final .EXE file.


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,

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 251


               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
               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"


RIP            "RIP", "RIPScrip" or "Remote Imaging Protocol" is a popular
               graphical terminal standard that is used with BBS systems.
               Unlike other terminal emulation standards, such as the ANSI and

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 252


               AVATAR modes supported by OpenDoors, RIP operates in bit mapped
               graphics mode, allowing features such as lines, circles and
               icons to be drawn on the remote screen. OpenDoors provides
               support for RIP graphics, although OpenDoors operates in text
               mode itself.


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".


SOURCE CODE    The term "source code" refers to the original file or files that
               where used to produce a library or executable program. The
               source code files contain the language statements or commands
               that are directly written by the programmer. These source code
               files are then compiled to produce an executable file that may
               be "run".


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.

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 253


               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.


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 5.00 Manual                                           End of Page 254


-------------------------------------------------------------------------------
INDEX
-------------------------------------------------------------------------------

About This Manual, 24
Access Level, 175
Alias, 168
ANSI Graphics, 131, 163, 246
Archive Contents, 236
ASCII Chart, 86
ASCII Mode, 246
AVATAR Graphics, 114, 131, 164, 246
Baud Rate, 152
BBS Information, 156
BBS Name, 162
BBS Systems, 29
Before Exit Function, 188
Box Characters, 182, 187
BPS Rate, 152
Built-In Function Keys, 207
Caller Information, 156
Carrier Detect, 51, 96
Chat, 38, 101
Chat Mode, 32, 101, 249
Colour Attribute Codes, 125
Colour Constants, 129
Colour Customization, 210, 220, 223, 227
Colour Functions, 42
Colours, 105, 125, 128
Common Problems, 230
Compiler Errors, 230, 231
Compiling With OpenDoors, 25
Custom Function Keys, 208
Debugging, 24, 228
Demo Version, 9
Display Functions, 42, 64
Displaying Text, 28, 41, 42, 60, 62, 64, 89, 105, 110, 114, 121
Door Driver Functions, 40
Door Driver Module, 5, 28, 40
Door Functions, 45
Door Information File, 29, 31, 147, 156
Door Settings, 179
DORINFOx.DEF File, 31
DOS Shell, 32, 188, 230
Download Limit, 166
Drop To BBS Key, 33
Error Free Connection, 167
ErrorLevels, 33
Example Program - Changing Only Foreground/Background Colour, 129
Example Program - Choosing Text Colour, 126
Example Program - Clearing A Line, 56
Example Program - Dialog Box, 67
Example Program - Door And Utility In One Program, 91
Example Program - Drawing A Window, 114

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 255


Example Program - Exiting A Door, 81
Example Program - EZVote, 31
Example Program - First Door, 28
Example Program - Hanging Up In CBV Door, 51
Example Program - Hotkeyed Menu, 90
Example Program - Input Key With Echo, 110
Example Program - Pausing In A Door, 96
Example Program - Setting Door Info File Location, 148
Example Program - Shelling To DOS, 138
Example Program - Terminal Emulation, 63
Example Program - Testing Available Door Information, 156
Example Program - Testing Screen Clearing Capabilities, 57
Example Program - Transferring A File Using DSZ, 139
Example Program - User Statistics Door, 108
Example Program - Waiting For CR, 54
Exiting A Door Program, 81
Features, 5
Feedback Form, 21
File Display Functions, 43
FILES.BBS File, 98
Fossil Driver, 250
FOSSIL port, 155
Function Keys, 32, 96, 206
Future Versions, 243
Getting In Touch With Us, 233
Graphics Mode, 163, 164, 246
Hangup, 33
History, 237
Hotkeys, 89
IBM Colour Attribute Codes, 125
IEMSI Session Information, 159
Inactivity Timeout, 195, 196, 197
Input Functions, 44, 83, 84
Keyboard Buffer, 53, 96, 110
Keys, 96
Language Customization, 212
Learning OpenDoors, 28
Library, 250
LIBrary Files, 27
Line Number, 149
Linking, 25
Local Mode, 31, 196, 250
Locked, 251
Lockout, 33
Memory Models, 26, 27
Memory Swapping, 204
Modem Port, 155
Modem Settings, 151
New Version, 237
Node Number, 149
Object File, 251
od_autodetect() Function, 48
od_carrier() Function, 51
od_chat() Function, 50

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 256


od_clear_keybuffer() Function, 53
od_clr_line() Function, 55
od_clr_scr() Function, 57, 230
od_colour_config() Function, 59
od_control Structure, 29, 145
od_disable Variable, 194
od_disp() Function, 60
od_disp_emu() Function, 62
od_disp_str() Function, 64
od_draw_box() Function, 66
od_edit_str() Function, 70
od_exit() Function, 30, 81, 188, 191
od_get_answer() Function, 83
od_get_key() Function, 28, 53, 84
od_gettext() Function, 88
od_hotkey_menu() Function, 89
od_init() Function, 29, 91, 147
od_input_str() Function, 53, 94
od_kernal() Function, 30, 96
od_list_files() Function, 98
od_log_write() Function, 100
od_page() Function, 101, 202
od_popup_menu() Function, 102
od_printf() Function, 28, 105, 192
od_putch() Function, 110
od_puttext() Function, 112
od_repeat() Function, 114
od_restore_screen() Function, 116
od_save_screen() Function, 117
od_scroll() Function, 119
od_send_file() Function, 121
od_set_attrib() Function, 125
od_set_color() Function, 128
od_set_cursor() Function, 131
od_set_dtr() Function, 133
od_set_personality() Function, 135
od_set_statusline() Function, 136
od_spawn Function, 203
od_spawn() Function, 138
od_spawnvpe() Function, 140
od_window_create() Function, 142
od_window_remove() Function, 144
OPENDOOR.H File, 25, 28, 34
OpenDoors BBS, 232
OpenDoors Customization, 184
OPENDOORS Echo, 233
OpenDoors History, 237
Our Address, 233
Output Functions, 42
Output Window, 32, 251
Paging Hours, 179, 180
Paging The Sysop, 101
Pause Key, 198
Phone Number, 168

===============================================================================
OpenDoors 5.00 Manual                                           End of Page 257


Printing, 28, 41, 42, 60, 62, 64, 89, 105, 110, 114, 121
Printing Manual, 25
Problems, 24
Product Support, 232
Project Files, 25
Registration, 9, 11, 15, 19, 20, 233, 252
Registration Form, 13, 20
RIP, 252
RIPScrip, 252
Running Doors, 29
Screen Functions, 42
Screen Length, 174
Screen Width, 175
Security Level, 175
Setting Colours, 105, 125, 128
Solutions To Problems, 230
Source Code, 9, 17, 22
Special Thanks, 245
Status Line, 32, 101, 136, 204, 205, 253
Stop Key, 198
Support, 232
Support BBS, 232, 233
Swapping, 204
Sysop Chat, 38, 101, 188
Sysop Function Keys, 206
Sysop Keys, 32, 96
Sysop Name, 161
Sysop Next Key, 33
Sysop Next Setting, 181
Sysop Page, 202
Sysop Paging, 101, 253
System Events, 160
System Name, 162
Terminal Emulator, 62, 121, 122
Terminal Emulator Control Codes, 122
Text Customization, 212
Thank-yous, 245
Time Left, 176
Timeout, 96
Troubleshooting, 24
User Handle (Alias), 168
User Information, 156
User Keyboard Off Key, 33, 53
User Keyboard Setting, 180, 181
User Name, 171
User Password, 173
User Timeout, 96
Version History, 237
Want-Chat Setting, 177






===============================================================================
OpenDoors 5.00 Manual                                           End of Page 258

















