home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / vrac / odoors50.zip / OPENDOOR.TXT < prev    next >
Text File  |  1994-09-24  |  670KB  |  15,238 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.     ██████████                         ███████▄
  16.     ███▀▀▀▀███                         ███▀▀▀███
  17.     ███    ███ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ███   ███ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄ ▄▄▄▄▄▄▄
  18.     ███    ███ ███▀███ ███▀███ ███▀███ ███   ███ ███▀███ ███▀███ ███▀▀▀ ███▀▀▀▀
  19.     ███▄▄▄▄███ ███ ███ ███▀▀▀▀ ███ ███ ███▄▄▄███ ███ ███ ███ ███ ███    ▀▀▀▀███
  20.     ██████████ ███████ ███████ ███ ███ ███████▀  ███████ ███████ ███    ███████
  21.                ███
  22.                ███
  23.                ▀▀▀                                     Door Programming Toolkit
  24.     ───────────────────────────────────────────────────────────────────────────
  25.  
  26.                                                             Programmer's Manual
  27.  
  28.  
  29.                                                                    Version 5.00
  30.  
  31.  
  32.                                      MS-DOS Text Mode, C / C++ Language Edition
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.       NOTE: Since you will likely want to refer to this manual while
  46.                 working with OpenDoors, looking at the sample source code,
  47.                 or writing your own door and utility programs, it is highly
  48.                 recommended that you take a moment to print it out. Simply
  49.                 type COPY OPENDOOR.DOC PRN from your DOS prompt. With the
  50.                 exception of this title page, this document contains only
  51.                 7-bit ASCII characters.
  52.  
  53.  
  54.  
  55.  
  56.  
  57.          (C) Copyright 1991 - 1994 by Brian Pirie. All Rights Reserved.
  58.  
  59.  
  60.  
  61.  
  62.                               TABLE OF CONTENTS
  63.  
  64.  
  65. TABLE OF CONTENTS ..........................................................2
  66.  
  67. CHAPTER 1 - INTRODUCTION TO OPENDOORS ......................................5
  68.      WELCOME! ..............................................................5
  69.      FEATURES OF THE OPENDOORS DOOR TOOLKIT ................................5
  70.  
  71. CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING ............................9
  72.      THE DEMO VERSION & BENEFITS OF REGISTERING ............................9
  73.      FILLING OUT THE REGISTRATION FORM .....................................13
  74.      SENDING YOUR ORDER FEE ................................................15
  75.      ORDERING THE SOURCE CODE ..............................................17
  76.      ORDERING THROUGH COMPUSERVE ...........................................19
  77.      OPENDOORS 5.00 ORDER FORM .............................................20
  78.      OPENDOORS DOOR PROGRAMMING TOOLKIT 5.00 - USER FEEDBACK FORM ..........21
  79.      TERMS OF REGISTRATION AND SOURCE CODE USE .............................22
  80.  
  81. CHAPTER 3 - OPENDOORS TUTORIAL .............................................24
  82.      ABOUT THIS MANUAL .....................................................24
  83.      COMPILING A PROGRAM WITH OPENDOORS ....................................25
  84.      BASICS OF DOOR PROGRAMMING WITH OPENDOORS .............................28
  85.      TOUR OF A SAMPLE DOOR PROGRAM: "EZVOTE" ...............................31
  86.      OTHER EXAMPLE DOORS INCLUDED WITH OPENDOORS ...........................38
  87.  
  88. CHAPTER 4 - THE OPENDOORS API FUNCTIONS ....................................40
  89.      OVERVIEW ..............................................................40
  90.      TABLE OF MOST COMMONLY USED FUNCTIONS .................................41
  91.      TABLE OF ALL FUNCTIONS ................................................42
  92.      OD_ADD_PERSONALITY() ..................................................46
  93.      OD_AUTODETECT() .......................................................48
  94.      OD_CHAT() .............................................................50
  95.      OD_CARRIER() ..........................................................51
  96.      OD_CLEAR_KEYBUFFER() ..................................................53
  97.      OD_CLR_LINE() .........................................................55
  98.      OD_CLR_SCR() ..........................................................57
  99.      OD_COLOUR_CONFIG() ....................................................59
  100.      OD_DISP() .............................................................60
  101.      OD_DISP_EMU() .........................................................62
  102.      OD_DISP_STR() .........................................................64
  103.      OD_DRAW_BOX() .........................................................66
  104.      OD_EDIT_STR() .........................................................70
  105.      OD_EXIT() .............................................................81
  106.      OD_GET_ANSWER() .......................................................83
  107.      OD_GET_KEY() ..........................................................84
  108.      OD_GETTEXT() ..........................................................88
  109.      OD_HOTKEY_MENU() ......................................................89
  110.      OD_INIT() .............................................................91
  111.      OD_INPUT_STR() ........................................................94
  112.      OD_KERNEL() ...........................................................96
  113.      OD_LIST_FILES() .......................................................98
  114.  
  115. ===============================================================================
  116. OpenDoors 5.00 Manual                                             End of Page 2
  117.  
  118.  
  119.      OD_LOG_WRITE() ........................................................100
  120.      OD_PAGE() .............................................................101
  121.      OD_POPUP_MENU() .......................................................102
  122.      OD_PRINTF() ...........................................................105
  123.      OD_PUTCH() ............................................................110
  124.      OD_PUTTEXT() ..........................................................112
  125.      OD_REPEAT() ...........................................................114
  126.      OD_RESTORE_SCREEN() ...................................................116
  127.      OD_SAVE_SCREEN() ......................................................117
  128.      OD_SCROLL() ...........................................................119
  129.      OD_SEND_FILE() ........................................................121
  130.      OD_SET_ATTRIB() .......................................................125
  131.      OD_SET_COLOUR() .......................................................128
  132.      OD_SET_CURSOR() .......................................................131
  133.      OD_SET_DTR() ..........................................................133
  134.      OD_SET_PERSONALITY() ..................................................135
  135.      OD_SET_STATUSLINE() ...................................................136
  136.      OD_SPAWN() ............................................................138
  137.      OD_SPAWNVPE() .........................................................140
  138.      OD_WINDOW_CREATE() ....................................................142
  139.      OD_WINDOW_REMOVE() ....................................................144
  140.  
  141. CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE ................................145
  142.      INTRODUCTION TO THE CONTROL STRUCTURE .................................145
  143.      CONTROL STRUCTURE - DOOR INFO FILE STATS ..............................147
  144.      CONTROL STRUCTURE - SERIAL PORT SETTINGS ..............................151
  145.      CONTROL STRUCTURE - BBS AND CALLER INFORMATION ........................156
  146.      CONTROL STRUCTURE - DOOR SETTINGS .....................................179
  147.      CONTROL STRUCTURE - DIAGNOSTICS .......................................182
  148.      CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION ...........................184
  149.      CONTROL STRUCTURE - FUNCTION KEYS .....................................206
  150.      CONTROL STRUCTURE - COLOUR CUSTOMIZATION ..............................210
  151.      CONTROL STRUCTURE - TEXT CUSTOMIZATION ................................212
  152.  
  153. CHAPTER 6 - SPECIAL TOPICS .................................................215
  154.      CONFIGURATION FILE SYSTEM .............................................215
  155.      DEFINING CUSTOM DOOR INFORMATION FILE FORMATS .........................220
  156.      MULTIPLE PERSONALITY SYSTEM ...........................................223
  157.      LOG FILE SYSTEM .......................................................225
  158.      MAKING DOORS MULTI-NODE-AWARE .........................................227
  159.  
  160. CHAPTER 7 - DEBUGGING AND GETTING ASSISTANCE WITH OPENDOORS ................228
  161.      ABOUT THIS CHAPTER ....................................................228
  162.      TROUBLESHOOTING PROBLEMS ..............................................228
  163.      SOLUTIONS TO COMMON PROBLEMS ..........................................230
  164.      OPENDOORS SUPPORT .....................................................232
  165.      THE OPENDOORS SUPPORT BBS .............................................232
  166.      THE OPENDOORS SUPPORT CONFERENCE ......................................233
  167.      GETTING IN TOUCH WITH ME ..............................................233
  168.  
  169. APPENDIX A - CONTENTS OF PACKAGE ...........................................236
  170.  
  171. APPENDIX B - CHANGES FOR THIS VERSION ......................................237
  172.  
  173.  
  174. ===============================================================================
  175. OpenDoors 5.00 Manual                                             End of Page 3
  176.  
  177.  
  178. APPENDIX C - FUTURE VERSIONS ...............................................243
  179.  
  180. APPENDIX D - SPECIAL THANKS ................................................245
  181.  
  182. GLOSSARY ...................................................................246
  183.  
  184. INDEX ......................................................................255
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233. ===============================================================================
  234. OpenDoors 5.00 Manual                                             End of Page 4
  235.  
  236.  
  237. -------------------------------------------------------------------------------
  238. CHAPTER 1 - INTRODUCTION TO OPENDOORS
  239. -------------------------------------------------------------------------------
  240.  
  241.  
  242.  
  243.  
  244. WELCOME!
  245. -------------------------------------------------------------------------------
  246.  
  247.                Welcome to OpenDoors! OpenDoors is a powerful and easy to use
  248.                door programming toolkit. OpenDoors provides a complete system
  249.                that allows you to EASILY and QUICKLY write spectacular,
  250.                professional quality BBS doors that automatically support all
  251.                the popular BBS systems. With OpenDoors, you can write door
  252.                programs just as you would write any other program - without
  253.                having to worry about any of the internal details of door
  254.                programming. OpenDoors takes care of everything for you: It
  255.                handles all modem communications, ANSI/AVATAR/RIP graphics
  256.                support and BBS interfacing through door information files (such
  257.                as DOOR.SYS, DORINFO1.DEF, etc.). OpenDoors also looks after
  258.                status lines and sysop function keys for DOS shells, chatting,
  259.                hanging up, and so on. In addition, OpenDoors carries out all
  260.                the work involved in keeping track of carrier detection, user
  261.                timeouts and much, much more. Serial I/O is performed using
  262.                either a FOSSIL driver, or built-in serial I/O capabilities,
  263.                making the use of a FOSSIL driver optional. OpenDoors can also
  264.                be completely customized, allowing you to take as little or as
  265.                much control of your program's behavior as you wish - and
  266.                imposing no limit on the possibilities of what you can do with
  267.                the package.
  268.  
  269.                This manual is included with the C / C++ version of OpenDoors,
  270.                which can be used in conjunction with C and C++ compilers from
  271.                Microsoft, Borland, and others. It is possible that versions of
  272.                OpenDoors for other programming languages have been made
  273.                available since the time this version was released.
  274.  
  275.  
  276.  
  277. FEATURES OF THE OPENDOORS DOOR TOOLKIT
  278. -------------------------------------------------------------------------------
  279.  
  280.                OpenDoors is a complete door programming library that allows you
  281.                to write doors that DIRECTLY support one of the largest variety
  282.                of BBS systems, including RemoteAccess, QuickBBS, PC-Board,
  283.                Maximus,  Opus, Wildcat!, WWIV, Spitfire, SuperBBS, Telegard,
  284.                RBBS-PC, TriTel, GAP, and others. Are you interested in writing
  285.                your own utility doors? Perhaps on-line games? Would you even
  286.                like to get into the market of selling your doors for others to
  287.                use? Or would you simply like make your own BBS unique by
  288.                running "custom" doors? With OpenDoors, you can accomplish all
  289.                of these things - and do it much more easily than ever before.
  290.  
  291.  
  292. ===============================================================================
  293. OpenDoors 5.00 Manual                                             End of Page 5
  294.  
  295.  
  296.                Unlike other similar libraries, OpenDoors provides all the
  297.                following features:
  298.  
  299.                -  OpenDoors handles all the "dirty" work involved in writing
  300.                   door programs. Are you interested in writing doors for BBSes,
  301.                   either your own, or to distribute (even sell!) to other
  302.                   people? Since OpenDoors handles all the door-related
  303.                   operations for you, you need do next to nothing different
  304.                   when writing door programs than you would when writing any
  305.                   other program. You simply call OpenDoor's simple functions to
  306.                   input, output and control door operation. In fact, many
  307.                   people have converted non-door programs to door programs in
  308.                   only a matter of minutes using OpenDoors. One of the most
  309.                   common comments I receive about OpenDoors is how easy it is
  310.                   to use.
  311.  
  312.                -  As you would expect, OpenDoors flawlessly monitors the
  313.                   modem's carrier detect signal, to automatically recover when
  314.                   a user hangs up - without your having to do anything extra in
  315.                   your program. OpenDoors also monitors how much time the user
  316.                   has left in the door, and provides a fully adjustable
  317.                   inactivity timeout monitor.
  318.  
  319.                -  OpenDoors takes care of all the work involved in reading and
  320.                   writing BBS door information files, such as DORINFO1.DEF,
  321.                   EXITINFO.BBS, CHAIN.TXT, DOOR.SYS, etc.  If the particular
  322.                   information is available to OpenDoors, it will provide you
  323.                   with just about everything you could ever want to know about
  324.                   the user on-line, the system your door is running under, and
  325.                   so on. In addition to the many door information file formats
  326.                   supported by OpenDoors, you are also able to define your own
  327.                   custom formats.
  328.  
  329.                -  OpenDoors also does all the work involved in displaying and
  330.                   automatically updating the door's status line, with
  331.                   information available to the sysop such as user name,
  332.                   location, baud rate, time left, function keys,
  333.                   ANSI/AVATAR/RIP settings, and so on. Using OpenDoors, you can
  334.                   choose from a number of different "personalities". These
  335.                   personalities allows OpenDoors to mimic the status lines and
  336.                   sysop function keys used in various BBS packages. OpenDoors
  337.                   includes personalities that mimic RemoteAccess, PC-Board and
  338.                   Wildcat! OpenDoors also allows you to create your own
  339.                   personalities to mimic any other BBS system.
  340.  
  341.                -  OpenDoors automatically provides the sysop with all the
  342.                   standard function keys for adjusting user time, hanging up on
  343.                   or even locking out the user, and so on. OpenDoors also
  344.                   provides you with a chat mode, which is available to the
  345.                   sysop by pressing Alt-C. In addition, OpenDoors has full
  346.                   support for sysop shell to DOS, activated by the Alt-J key.
  347.  
  348.                -  What's more, OpenDoors is designed to be very easy to use.
  349.                   Even the most novice `C' programmers are able to write
  350.  
  351. ===============================================================================
  352. OpenDoors 5.00 Manual                                             End of Page 6
  353.  
  354.  
  355.                   professional-quality doors with OpenDoors. It takes care of
  356.                   just about every detail for you, yet still gives you the
  357.                   ability to completely control and customize every detail of
  358.                   your door's behavior. There are even people who begin door
  359.                   programming with OpenDoors, having never programmed in C in
  360.                   the past.
  361.  
  362.                -  OpenDoors supports both FOSSIL-based and built-in serial I/O
  363.                   capabilities. FOSSIL-based serial I/O can be used for maximum
  364.                   compatibility with various systems and serial ports,
  365.                   including multiple-port serial cards such as DigiBoard.
  366.                   OpenDoors can also operate without a FOSSIL driver, using
  367.                   it's own serial I/O capabilities. OpenDoor's built-in
  368.                   asynchronous communcations supports baud rates of up to
  369.                   115,200 and non-standard serial port configurations.
  370.                   OpenDoors also has the ability to automatically detect which
  371.                   of the two serial I/O methods should be used on a particular
  372.                   system.
  373.  
  374.                -  OpenDoors also automatically detects when the BBS system is
  375.                   operating in local mode, and supports full local mode
  376.                   operations itself.
  377.  
  378.                -  Other OpenDoors functions include a built in sysop-page
  379.                   function that will ask the user why they wish to chat, and
  380.                   then proceed to page the sysop, just as any BBS package
  381.                   would. OpenDoors also provides screen clearing functions
  382.                   (which will detect whether the user has screen clearing
  383.                   turned on), and various ANSI/AVATAR/RIP control functions
  384.                   (which again detect if the user has graphics mode turned on).
  385.  
  386.                -  In addition to the basic display features of OpenDoors there
  387.                   are also a number of advanced screen control functions. These
  388.                   include functions to save and restore the entire screen,
  389.                   along with functions to save, restore or scroll portions of
  390.                   the screen. Other functions allow you to provide overlapping
  391.                   windows and pop-up menus with highlighted selection bars.
  392.  
  393.                -  OpenDoors has a number of special sub-systems that you may
  394.                   elect to include in your doors. Among these, is a log-file
  395.                   system that allows you to add log file support to your doors
  396.                   with only a single line of programming.
  397.  
  398.                -  Another valuable OpenDoors sub-system is the configuration
  399.                   file system. Again using only a single line of code, you can
  400.                   add configuration file support to your doors. OpenDoors
  401.                   configuration files permit the sysop using the door to
  402.                   customize the door's performance to their own preferences.
  403.                   Among the settings available in the configuration file are
  404.                   system directories, screen colours, maximum time permitted
  405.                   within the door, sysop paging hours, memory swapping options.
  406.                   The sysop can also specify a custom door information file
  407.                   (drop file) format, to allow your doors to operate on
  408.                   literally ANY BBS system.
  409.  
  410. ===============================================================================
  411. OpenDoors 5.00 Manual                                             End of Page 7
  412.  
  413.  
  414.  
  415.                -  OpenDoors can also be fully customized in order that you may
  416.                   write door programs that use languages other than English.
  417.  
  418.                -  Among the ANSI/AVATAR/RIP features found in OpenDoors is the
  419.                   ability to send ANSI/AVATAR/RIP files from disk. This allows
  420.                   you to easily design program screens, and incorporate them
  421.                   into your doors.
  422.  
  423.                -  OpenDoors also comes with the source code for a number of
  424.                   example doors, which you can modify, or simply extract bits
  425.                   and pieces for use in your own doors. Plus, this manual
  426.                   contains many examples of C source code, to help you in
  427.                   writing nearly any door program you might wish to build.
  428.  
  429.                -  OpenDoors is also DesqView aware. When OpenDoors starts up,
  430.                   it will automatically check for the presence of DesqView, and
  431.                   if available, will perform all of it's screen output through
  432.                   DesqView.
  433.  
  434.                -  You may also elect to purchase the source code for OpenDoors,
  435.                   which will permit you to make modifications to any portion of
  436.                   OpenDoors, use any portions of the OpenDoors source code in
  437.                   other programs you write, or merely learn how communications-
  438.                   type programs are written.
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. ===============================================================================
  470. OpenDoors 5.00 Manual                                             End of Page 8
  471.  
  472.  
  473. -------------------------------------------------------------------------------
  474. CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING
  475. -------------------------------------------------------------------------------
  476.  
  477.  
  478.  
  479.  
  480. THE DEMO VERSION & BENEFITS OF REGISTERING
  481. -------------------------------------------------------------------------------
  482.  
  483.                This archive contains the demonstration version of OpenDoors.
  484.                This version has all the features of the registered version, but
  485.                you are only permitted to use it under limited circumstances:
  486.  
  487.                1.) The demo (unregistered) version may only be used for a one
  488.                    month period, for evaluation purposes.
  489.  
  490.                2.) Programs written in this version may not be distributed.
  491.  
  492.                Also, any program written with the demo version will display a
  493.                message to the user indicating that OpenDoors is not registered.
  494.                This message is, of course, removed in the registered version.
  495.  
  496.                If you decided to purchase OpenDoors, you will become the owner
  497.                of a powerful tool for creating BBS door and utility programs.
  498.                Registered owners of OpenDoors are entitled to:
  499.  
  500.                1.) Unlimited use of OpenDoors. You may write as many programs
  501.                    as you wish using OpenDoors, and do what you please with
  502.                    these programs. They may be freely distributed, or even
  503.                    sold. What's more, there are no additional royalty fees.
  504.                    Your one time purchase of OpenDoors entitles you to use it
  505.                    as you please.
  506.  
  507.                2.) You will also be entitled to free upgrades to newer versions
  508.                    of OpenDoors. In addition to the great many features and the
  509.                    quality that this version of OpenDoors has to offer, I am
  510.                    currently working on a great many additions and enhancements
  511.                    for the next version. (See the end of this document for an
  512.                    outline of features currently "in the works") Any programs
  513.                    you write in this version will also automatically take on
  514.                    these new features when you receive the new version.
  515.  
  516.  
  517.                The best news of all is how cheap OpenDoors is! Other  "door-
  518.                drivers" sell for $50, $75, or even more! However, this version
  519.                of OpenDoors will only cost you $28 US, $34 Canadian, or your
  520.                countries equivalent! (Also, you may be interested in knowing
  521.                that the price will go up in future versions, so if you register
  522.                now, you will save by receiving ALL future upgrades for free.)
  523.  
  524.                Also, the source code for OpenDoors is now available to
  525.                registered users for an additional $28US / $34CDN / equivalent!
  526.                Ordering a copy of the source code will allow you to customize
  527.  
  528. ===============================================================================
  529. OpenDoors 5.00 Manual                                             End of Page 9
  530.  
  531.  
  532.                OpenDoors for your own use, making any changes or additions that
  533.                you wish. It also gives you the opportunity to see how OpenDoors
  534.                works, and to use any portions of the OpenDoors code in any
  535.                other programs you wish to write. If you think you might be
  536.                interested in ordering the OpenDoors source code, please be sure
  537.                to read the section entitled "Ordering The Source Code", located
  538.                on page 22.
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587. ===============================================================================
  588. OpenDoors 5.00 Manual                                            End of Page 10
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595. HOW TO ORDER
  596. -------------------------------------------------------------------------------
  597.  
  598. PLEASE         Below are detailed instructions for registering OpenDoors.
  599. NOTE           These instructions are not intended to be confusing or
  600.                complicated; they are simply meant to answer almost any question
  601.                that you might have about registering. However, note that it is
  602.                probably not necessary for you to worry about whether you are
  603.                following these steps to the letter - I'm not that picky. So
  604.                long as you send your registration form and fee by some means,
  605.                there should not be any difficulty in processing your
  606.                registration. If you do have any questions or uncertainties
  607.                about your registration, please feel more than free to contact
  608.                me. For information on how to contact me, please see page 233.
  609.  
  610.                OpenDoors can be ordered by either mailing the OpenDoors order
  611.                form, or online on Compuserve. If you are a Compuserve
  612.                subscriber and you wish to order OpenDoors by this means, see
  613.                the secton on ordering through Compuserve, on page 19.
  614.                Otherwise, follow the following three steps:
  615.  
  616.                1.)  Fill out the registration form. Information on filling out
  617.                     the form is located on page 13.
  618.  
  619.                2.)  Send the appropriate payment, $28US/$34CDN/equivalent for
  620.                     the registration or $56US/$68CDN/equivalent for both the
  621.                     registration and source code. If you wish more detailed
  622.                     instructions on sending the registration fee, see the
  623.                     section that begins page on 15. Included in that section is
  624.                     a list of equivalent prices for a number of other
  625.                     countries.
  626.  
  627.                3.)  Send the above two items (along with a diskette and
  628.                     envelope if you are ordering the source code, and wish to
  629.                     receive it by conventional mail) to me at:
  630.  
  631.                               Brian Pirie
  632.                               Apt. 1416 - 2201 Riverside Dr.
  633.                               Ottawa, Ontario
  634.                               Canada
  635.                               K1H 8K9
  636.  
  637.  
  638.                If you think you might also be interested in the OpenDoors
  639.                source code, be sure to read the section on the source code,
  640.                which begins on page 22.
  641.  
  642.                Also, you may wish to send the OpenDoors feedback form (located
  643.                on page 21), along with your registration. The feedback form
  644.                gives you a chance to tell me what you think of OpenDoors, and
  645.  
  646. ===============================================================================
  647. OpenDoors 5.00 Manual                                            End of Page 11
  648.  
  649.  
  650.                what changes you would like to see in future versions. In fact,
  651.                the majority of suggestions made on these forms in the past have
  652.                already been implemented in the current version of OpenDoors.
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705. ===============================================================================
  706. OpenDoors 5.00 Manual                                            End of Page 12
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713. FILLING OUT THE REGISTRATION FORM
  714. -------------------------------------------------------------------------------
  715.  
  716.                If you have printed the OpenDoors manual, you can simply remove
  717.                and mail the forms on pages 20 and 21. If you have not already                                                   
  718.                printed a copy of the manual, and you have a printer, you can
  719.                quickly print these forms by printing the ORDER.FRM file
  720.                included in the OpenDoors distribution archive. (Type COPY
  721.                ORDER.FRM PRN from your DOS prompt.)
  722.  
  723. NO PRINTER?    Alternatively, if you do not have a printer, simply send a hand-
  724.                written version of the order form.
  725.  
  726.                If you have any special instructions for me, or anything that
  727.                you would like to say when you register, feel free to write this
  728.                on the back of the registration form, or on a separate piece of
  729.                paper.
  730.  
  731.                When filling out the OpenDoors registration form, be sure to
  732.                indicate how you would prefer to receive your OpenDoors
  733.                registration key and/or source code. The following options are
  734.                available:
  735.  
  736.                          - Having me send the registration and/or source code
  737.                            by conventional mail
  738.                          - Having me call to your BBS
  739.                          - You calling the OpenDoors support BBS
  740.                          - FidoNet "CrashMail"
  741.                          - Internet E-Mail
  742.  
  743.                Once you have decided which means you would prefer to receive
  744.                your order by, please read the detailed instructions on your
  745.                order method, below. Also, if you are ordering the source code,
  746.                please be sure to read the section on ordering the source code,
  747.                which begins on page 22.
  748.  
  749.  
  750. -------------------------------------------------------------------------------
  751. RECEIVING      In order to receive your OpenDoors registration key and/or
  752. ORDER          source code by conventional mail, simply fill out the order
  753. BY MAIL        form and mail it along with your payment as described below. I
  754.                will cover the cost of postage. If you are ordering the source
  755.                code (requiring the mailing of a diskette), or your address
  756.                contains non-Arabic characters, also enclose a self-addressed
  757.                envelope.
  758.  
  759.                If you are also ordering the source code, please be sure to
  760.                enclose either a 5-1/4" 360K or 3-1/2" 720K/1.44M floppy disk.
  761.  
  762.  
  763.  
  764. ===============================================================================
  765. OpenDoors 5.00 Manual                                            End of Page 13
  766.  
  767.  
  768. -------------------------------------------------------------------------------
  769. RECEIVING      In order to receive your OpenDoors registration key and/or
  770. ORDER BY       source code by a message and/or upload to your BBS, fill out
  771. CALL TO        the order form and mail it along with your payment as described
  772. YOUR BBS       below. Be sure to include the phone number, baud rate, and my
  773.                login and password for the BBS to which you would like me to
  774.                call. As always, I will cover any long distance costs. If, for
  775.                some reason, I am unable to connect to your BBS (not because it
  776.                is busy, but, for example, if your BBS is no longer online), I
  777.                will send your order by conventional mail instead.
  778.  
  779.  
  780. -------------------------------------------------------------------------------
  781. RECEIVING      You may choose to receive your OpenDoors registration and/or
  782. ORDER BY       source code by calling the OpenDoors BBS after your registration
  783. CALLING        form and order fee have been received here. If you are unable to
  784. OPENDOORS      receive your order by any other electronic means (such as a call
  785. BBS            to your BBS, or by electronic mail), this may be the quickest
  786.                way for you to recieve your registration information and/or
  787.                source code. The obvious disadvantage with to option is the fact
  788.                that you will have to estimate when your order will arrive here
  789.                in order to receive it as quickly as possible. You may end up
  790.                calling the OpenDoors BBS more than once before your order has
  791.                arrived. After your order form has arrived, your registration
  792.                key and/or source code will be placed on hold for you, and you
  793.                will be able to receive it on your first call to the BBS. The
  794.                phone number of the BBS is:
  795.  
  796.                          +1 613 526 4466
  797.  
  798.  
  799. -------------------------------------------------------------------------------
  800. RECEIVING      If you wish to receive your OpenDoors registration key by
  801. ORDER BY       Internet E-Mail (including Internet E-Nail to a Compuserve
  802. INTERNET       account), fill out the order form and mail it along with your
  803. E-MAIL         payment as described below. Be sure to include your e-mail
  804.                address on your order form. Note that the source code cannot be
  805.                sent via Internet e-mail.
  806.  
  807.  
  808. -------------------------------------------------------------------------------
  809. RECEIVING      In order to receive your OpenDoors registration key and/or
  810. ORDER BY       source code by FidoNet CrashMail, simply fill out the order
  811. FIDONET        form and mail it along with your payment as described below.
  812. CRASHMAIL      Be sure to include the FidoNet node address to which you wish to
  813.                have your registration key and/or source code sent to (via
  814.                CrashMail). Again I will cover any long distance costs. If, for
  815.                some reason, I am unable to connect to your FidoNet system, I
  816.                will send your order by conventional mail instead.
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823. ===============================================================================
  824. OpenDoors 5.00 Manual                                            End of Page 14
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831. SENDING YOUR ORDER FEE
  832. -------------------------------------------------------------------------------
  833.  
  834.                The price of OpenDoors is 34 Canadian Dollars, 28 U.S. Dollars,
  835.                or equivalent for the registration. The source code costs an
  836.                additional 34 Canadian Dollars, 28 U.S. Dollars, or equivalent.
  837.                For your convenience, the equivalent value in a number of other
  838.                country's currencies, at the time of this writing, is as
  839.                follows:
  840.  
  841.                        -----------------------------------------------
  842.                                                 REGISTRATION
  843.                        REGISTRATION ONLY        AND SOURCE CODE
  844.                        -----------------------------------------------
  845.                        34 Canadian Dollars      68 Canadian Dollars
  846.                        28 US Dollars            56 US Dollars
  847.                        18 British Pounds        36 British Pounds
  848.                        150 French Francs        300 French Francs
  849.                        44 German Marks          88 German Marks
  850.                        50 Netherland Gilders    100 Netherland Gilders
  851.                        39 Australian Dollars    78 Australian Dollars
  852.                        -----------------------------------------------
  853.  
  854.                This order fee may be payed using any of the following methods:
  855.  
  856.                -Cheque or Money Order in Canadian currency, drawn upon a
  857.                 Canadian bank. In this case, your order fee will be either
  858.                 $34CDN for just the registration, or $68CDN for both the
  859.                 registration and source code.
  860.  
  861.                -Cheque or Money Order in U.S. currency, drawn upon a U.S. bank.
  862.                 In this case, your order fee will be either $28US for just the
  863.                 registration, or $56US for both the registration and source
  864.                 code.
  865.  
  866.                -An International Money Order or International Bank Draft
  867.                 (available from your bank, post office or organization such as
  868.                 American Express), in Canadian currency. Depending on the
  869.                 particular case, your order fee MAY be sent to me by the postal
  870.                 service, and you will mail your order form by itself. You
  871.                 should have the money order drawn in either $28CDN for just the
  872.                 registration, or $56CDN for both the registration and source
  873.                 code.
  874.  
  875.                -A cheque drawn on any bank in the world, IN THAT COUNTRY'S
  876.                 CURRENCY, equivalent to 34 Canadian dollars. For instance, a
  877.                 cheque for the appropriate number of British Pounds, drawn on a
  878.                 British bank, is perfectly acceptable. However, I am unable to
  879.                 accept a cheque for $34 Canadian dollars, drawn on a British
  880.                 Bank.
  881.  
  882. ===============================================================================
  883. OpenDoors 5.00 Manual                                            End of Page 15
  884.  
  885.  
  886.  
  887.                -Cash. Please note that it is not usually recommended that cash
  888.                 be sent in the mail, and that I cannot be responsible for any
  889.                 cash lost in the mail. Simply put, if you wish to order by
  890.                 cash, it is your responsibility to get the cash to me. However,
  891.                 if I do receive your order in the form of cash, it will be
  892.                 perfectly acceptable to me. I would like to mention that many
  893.                 people have already ordered OpenDoors by sending cash, and I
  894.                 have yet to run across any case of cash being lost in the mail.
  895.                 Nonetheless, if you wish to send cash, you may wish to consider
  896.                 doing so by registered mail, for your added security.
  897.  
  898.  
  899.                If you are ordering OpenDoors from within Canada, you will most
  900.                likely choose the first option (a Canadian cheque or money
  901.                order). If you are ordering OpenDoors from within the United
  902.                States, you will most likely choose the second option (an
  903.                American cheque or money order). If you are ordering from
  904.                outside Canada and the U.S., it would be ideal if you could send
  905.                your fee by an international money order. However, it should be
  906.                noted that any of the above order methods will be acceptable
  907.                from any location. Also, it is quite possible that I may be able
  908.                to accept other means of sending your order fee. If you are
  909.                unsure about sending your order fee, please feel free to get in
  910.                touch with me by any of the means listed on page 233.
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941. ===============================================================================
  942. OpenDoors 5.00 Manual                                            End of Page 16
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949. ORDERING THE SOURCE CODE
  950. -----------------------------------------------------------------------------
  951.  
  952.                There are many benefits to also ordering the source code along
  953.                with your OpenDoors registration. Ordering the source code will
  954.                allow you to customize OpenDoors for your own use, use parts of
  955.                the OpenDoors source code in other programs, and learn more
  956.                about how OpenDoors works. If you have any ideas for changes
  957.                that you would like to see in OpenDoors, either large or small,
  958.                ordering the source code will allow you to makes these changes
  959.                yourself, creating your own customized version of OpenDoors. You
  960.                will be able to remove copyright notices, change the way certain
  961.                OpenDoors functions work, or add new capabilities to OpenDoors
  962.                in surprisingly little time. You will also be able to use any of
  963.                the OpenDoors source code, be it the DesqView-aware code,
  964.                EMS/disk swapping routines, configuration file system,
  965.                communications routines, or anything else, in any other programs
  966.                that you may wish to write. Also, ordering the OpenDoors source
  967.                code will allow you to learn more about how OpenDoors works, and
  968.                how to program communications software, door programs, BBS
  969.                utilities, and so on.
  970.  
  971.                As mentioned before, registered users may order the OpenDoors
  972.                source code for an additional $28, either at the same time you
  973.                register OpenDoors, or separately. If you wish to order the
  974.                OpenDoors source code, simply indicate on your order form that
  975.                you wish to order both your OpenDoors registration, and your
  976.                source code, and include the additional fee for ordering the
  977.                source code.
  978.  
  979.                When you order the OpenDoors source code, you will receive the
  980.                source code package. The source code package includes all of the
  981.                source code, with the exception of the registration key decoding
  982.                algorithm. This small piece of code is instead included in the
  983.                form of .OBJect files, one for each memory model. The source
  984.                code package also includes a short "Source Code Manual", with a
  985.                description of how the OpenDoors source code is organized,
  986.                instructions on how to recompile the source code, and more. In
  987.                addition, the source code package includes a full set of batch
  988.                files for automatically re-compiling the OpenDoors libraries.
  989.  
  990. REQUIREMENTS   In order to re-compile the OpenDoors source code, you must be
  991.                using a Borland compiler that supports inline assembly language
  992.                keywords. This includes Turbo C++ or Borland C++ 2.0 or later.
  993.  
  994.                Also, as with your OpenDoors registration, when you order the
  995.                OpenDoors source code, you are entitled to receive all future
  996.                versions of the source code.
  997.  
  998.  
  999.  
  1000. ===============================================================================
  1001. OpenDoors 5.00 Manual                                            End of Page 17
  1002.  
  1003.  
  1004. IMPORTANT      If you wish to order the source code there are a few important
  1005.                things which you should note. First of all, if you choose to
  1006.                receive your source code by mail (as opposed to upload to your
  1007.                BBS, or FidoNet CrashMail), be sure to enclose a Double-Density
  1008.                5-1/4" diskette with mailing envelope, or either Double-Density
  1009.                or High-Density 3-1/2" diskette. Also, due to the costs of over-
  1010.                seas long distance, I cannot send the source code by BBS upload
  1011.                or CrashMail to sites outside of North America that operate at
  1012.                2400 bps or slower.
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059. ===============================================================================
  1060. OpenDoors 5.00 Manual                                            End of Page 18
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067. ORDERING THROUGH COMPUSERVE
  1068. -------------------------------------------------------------------------------
  1069.  
  1070.                As an alternative to mailing a cheque / money order / cash along
  1071.                with the OpenDoors order form, you can order an OpenDoors online
  1072.                on Compuserve. The cost of OpenDoors will automatically be
  1073.                billed to your CompuServe account. Unless you have previously
  1074.                notified me that you wish to receive your order by some other
  1075.                means, your order will be set by conventional mail. To order
  1076.                OpenDoors online through CompuServe, GO SWREG. The registration
  1077.                ID for ordering JUST the OpenDoors registration ($28U.S. at the
  1078.                time of this writing) is 3270. The registration ID for ordering
  1079.                BOTH your OpenDoors registration and the OpenDoors source code
  1080.                ($56U.S. at the time of this writing) is 3271. Note that the
  1081.                price for registering OpenDoors through CompuServe may increase
  1082.                to 15% more than the price for ordering OpenDoors through the
  1083.                mail, due to the high processing fee I am charged by CompuServe.
  1084.                However, the price for ordering online through CompuServe is
  1085.                currently the same as for ordering by any other means. The price
  1086.                that you will be paying to order through CompuServe will be
  1087.                displayed before you agree to the registration, so you will know
  1088.                whether or not the price has changed before purchasing
  1089.                OpenDoors.
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118. ===============================================================================
  1119. OpenDoors 5.00 Manual                                            End of Page 19
  1120.  
  1121.  
  1122. --------------------------------------------------------------------------
  1123.                         OPENDOORS 5.00 ORDER FORM
  1124. --------------------------------------------------------------------------
  1125.  
  1126.          YOUR NAME : _______________________________   (AS SHOULD APPEAR IN
  1127.                                                         REGISTRATION)
  1128.     POSTAL ADDRESS : ______________________________________________________
  1129.  
  1130.                      ______________________________________________________
  1131.  
  1132. VOICE PHONE NUMBER : ______________________
  1133.  
  1134.   E-MAIL ADDRESSES : ____________________________________   (IF APPLICABLE)
  1135.  
  1136.   BBS PHONE NUMBER : ______________________                 (IF APPLICABLE)
  1137.  
  1138.  BEST TIME TO CALL : __________________       BRIAN'S PASSWORD : __________
  1139.           (ONLY IF YOU WISH TO RECEIVE YOUR ORDER BY A MESSAGE ON YOUR BBS)
  1140.  
  1141. I WISH TO RECEIVE MY ORDER BY:
  1142.           ___                                ___
  1143.          |   | - CONVENTIONAL MAIL          |   | - FIDONET "CRASHMAIL"
  1144.          |___|                              |___|
  1145.           ___                                ___
  1146.          |   | - CALL TO MY BBS             |   | - INTERNET E-MAIL
  1147.          |___|                              |___|   (REGISTRATION KEY ONLY)
  1148.           ___                                ___
  1149.          |   | - CALL TO OPENDOORS BBS      |   | - COMPUSERVE MAIL
  1150.          |___|                              |___|   (REGISTRATION KEY ONLY)
  1151.  
  1152.                         ___
  1153. I WOULD LIKE TO ORDER: |   | - JUST MY REGISTRATION KEY
  1154.                        |___|   ($28 or EQUIVALENT)
  1155.                         ___
  1156.                        |   | - JUST THE SOURCE CODE (ONLY IF ALREADY
  1157.                        |___|   REGISTERED) ($28 OR EQUIVALENT)
  1158.                         ___
  1159.                        |   | - BOTH REGISTRATION KEY AND SOURCE CODE
  1160.                        |___|   ($56 OR EQUIVALENT)
  1161.  
  1162.  
  1163. I AGREE TO THE OPENDOORS TERMS, SET           ____________________________
  1164. FORTH ON PAGE 22 OF THE MANUAL                (SIGNATURE)
  1165.  
  1166. MAKE CHEQUES PAYABLE TO:   BRIAN PIRIE
  1167.                            APT. 1416 - 2201 RIVERSIDE DR.
  1168.                            OTTAWA, ONTARIO
  1169.                            CANADA
  1170.                            K1H 8K9
  1171.  
  1172. +-- OFFICIAL USE ONLY ----------------------------------------------------+
  1173. |                                                                         |
  1174. | Rcvd : _______  Date : _________  S.N. : _________  Key : _____________ |
  1175. +-------------------------------------------------------------------------+
  1176.  
  1177. ===============================================================================
  1178. OpenDoors 5.00 Manual                                            End of Page 20
  1179.  
  1180.  
  1181. --------------------------------------------------------------------------
  1182.           OPENDOORS DOOR PROGRAMMING TOOLKIT 5.00 - USER FEEDBACK FORM
  1183. --------------------------------------------------------------------------
  1184.  
  1185.          YOUR NAME : _______________________________
  1186.  
  1187.     POSTAL ADDRESS : ______________________________________________________
  1188.  
  1189.                      ______________________________________________________
  1190.  
  1191. VOICE PHONE NUMBER : ______________________
  1192.  
  1193.  NETWORK ADDRESSES : ____________________________________   (IF APPLICABLE)
  1194.  
  1195.  
  1196. HOW DID YOU FIRST LEARN OF OPENDOORS?
  1197.  
  1198.              ____________________________________________________________
  1199.  
  1200.  
  1201. WHICH LANGUAGE / COMPILER AND VERSION ARE YOU USING?  (EG. BORLAND C++ 3.10)
  1202.  
  1203.              ____________________________________________________________
  1204.  
  1205.  
  1206. WHAT DO YOU LIKE MOST ABOUT OPENDOORS?
  1207.  
  1208.              ____________________________________________________________
  1209.  
  1210.              ____________________________________________________________
  1211.  
  1212.              ____________________________________________________________
  1213.  
  1214.  
  1215. WHAT CHANGES OR ADDITIONS WOULD YOU LIKE TO SEE IN FUTURE VERSIONS?
  1216.  
  1217.              ____________________________________________________________
  1218.  
  1219.              ____________________________________________________________
  1220.  
  1221.              ____________________________________________________________
  1222.  
  1223.  
  1224. DO YOU HAVE ANY ADDITIONAL COMMENTS?
  1225.  
  1226.              ____________________________________________________________
  1227.  
  1228.              ____________________________________________________________
  1229.  
  1230.              ____________________________________________________________
  1231.  
  1232.  
  1233. -----------------------------------------------------------------------------
  1234.  
  1235.  
  1236. ===============================================================================
  1237. OpenDoors 5.00 Manual                                            End of Page 21
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244. TERMS OF REGISTRATION AND SOURCE CODE USE
  1245. -----------------------------------------------------------------------------
  1246.  
  1247.                When you purchase an OpenDoors registration and/or source code,
  1248.                you are entitled to almost unlimited use of all versions of
  1249.                OpenDoors. However, in order to protect my investment of time
  1250.                and effort in developing OpenDoors, you must also agree to the
  1251.                terms outlined below when purchasing an OpenDoors registration
  1252.                and/or the source code. These terms are very reasonabl, and are
  1253.                in no way intended to limit your use of OpenDoors. The primary
  1254.                intent of these terms is that you are not permitted to disclose
  1255.                your OpenDoors registration information, or the OpenDoors source
  1256.                code, to other individuals. The exception to this requirement is
  1257.                when OpenDoors is registered by an organization, the OpenDoors
  1258.                registration information and source code may be shared among
  1259.                members of that organization, for use within the organization.
  1260.                For instance, if OpenDoors is registred to a particular company,
  1261.                only a single registration is required for the company, but it
  1262.                may not be used by employees for their personal use. The terms
  1263.                of registration and source code use are as follows:
  1264.  
  1265.                For the purpose of these terms, "OpenDoors" is defined to be the
  1266.                library files, header files, example programs and programmer's
  1267.                manual of all versions, past and present, for all languages and
  1268.                platforms of the OpenDoors door programming toolkit. Upon
  1269.                registering OpenDoors, the individual or organization named on
  1270.                the registration form (the registree) is entitled to use of all
  1271.                versions of OpenDoors, within the terms set forth below.
  1272.                Violation of these terms will be considered copyright
  1273.                infrindgement, and grounds for the termination of the
  1274.                registration agreement. The registree is entitled, at no
  1275.                additional cost, to use, distribute or sell the executable (.EXE
  1276.                or .COM) files that result from using the OpenDoors door
  1277.                programming toolkit. The registree is also entitled to use,
  1278.                distribute or sell the example programs, example configuration
  1279.                files and portions of the user manual. If purchasing the source
  1280.                code, the registree is also entitled to distribute any
  1281.                executable files that result from using altered versions of the
  1282.                source code, or portions thereof. The registree is NOT entitled
  1283.                to distribute the registration key number presented to them at
  1284.                registration, or any portions of the OpenDoors source code. For
  1285.                the purposes of these terms, an organization is considered to be
  1286.                a company or non-profit organization. If the registree is an
  1287.                organization, the registration key and source code may be shared
  1288.                among members of the organization, under the condition that
  1289.                these individuals are using the registration and/or source code
  1290.                only for official activities of that organization. These terms
  1291.                in no way suggest an agreement on the part of Brian Pirie to
  1292.                develop any future versions of OpenDoors, or fix any bugs in
  1293.                current versions of OpenDoors. OpenDoors is offered "as is", and
  1294.  
  1295. ===============================================================================
  1296. OpenDoors 5.00 Manual                                            End of Page 22
  1297.  
  1298.  
  1299.                no warantees are expressed or implied. In no event shall Brian
  1300.                Pirie be liable for any loss of profit or any other damage,
  1301.                including but not limited to special, incidental, consequential
  1302.                or other damages.
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354. ===============================================================================
  1355. OpenDoors 5.00 Manual                                            End of Page 23
  1356.  
  1357.  
  1358.  
  1359.  
  1360. -----------------------------------------------------------------------------
  1361. CHAPTER 3 - OPENDOORS TUTORIAL
  1362. -----------------------------------------------------------------------------
  1363.  
  1364.  
  1365.  
  1366.  
  1367. ABOUT THIS MANUAL
  1368. -----------------------------------------------------------------------------
  1369.  
  1370.                The OpenDoors programmer's manual is intended to serve as a
  1371.                complete tutorial, guide and reference to writing programs with
  1372.                OpenDoors. Chapter 1 of this manual, beginning on page 5, serves
  1373.                as an introduction and overview of the features of OpenDoors.
  1374.                Chapter 2, beginning on page 9, then contains all of the
  1375.                information related to this demo version of OpenDoors, and how
  1376.                to register your copy. This chapter then serves as a tutorial on
  1377.                OpenDoors and door programming in general. Chapter 4 then deals
  1378.                with the functions which OpenDoors provides for door
  1379.                programming. Chapter 5 deals with the "OpenDoors control
  1380.                structure", which gives you access to a wide array of
  1381.                information, and allows you to customize OpenDoor's appearance
  1382.                and behaviour. Chapter 6 provides information on special
  1383.                OpenDoors features and special topics related to door
  1384.                programming. Among the subjects discussed in chapter 6 are
  1385.                configuration files, multi-node operation, RIP graphics, logfile
  1386.                support, defining custom door information file formats, and
  1387.                more.
  1388.  
  1389.                Chapter 7 (which begins on page 228) is perhaps the most
  1390.                important single part of this manual. This chapter gives
  1391.                detailed instructions on troubleshooting programs written with
  1392.                OpenDoors, lists solutions to common difficulties, and has
  1393.                information about the many sources for OpenDoors support. If at
  1394.                any time you are having difficulty with OpenDoors, be sure to
  1395.                refer to this chapter for complete step-by-step instruction on
  1396.                tracing the source of your problem, and for solutions to common
  1397.                difficulties with OpenDoors. This chapter also directs you to
  1398.                some of the many means of OpenDoors support, including
  1399.                information on the OpenDoors EchoMail conference, the OpenDoors
  1400.                support BBS, and how to get in touch with me.
  1401.  
  1402.                You will also find many useful tools in this manual, which will
  1403.                no doubt come in useful while working with OpenDoors. Beginning
  1404.                on page 2 is a basic table of contents, showing you have the
  1405.                manual is organized, and helping you to locate general topics.
  1406.                At the end of the manual, beginning on page 255, is an index to
  1407.                help you locate more information on specific topics. The manual
  1408.                also includes a glossary, on page 246, which will help you in
  1409.                understanding new terms that you may come across while reading
  1410.                the manual. At the end of the manual, you will also find several
  1411.                useful section, such as a brief history of OpenDoors,
  1412.  
  1413. ===============================================================================
  1414. OpenDoors 5.00 Manual                                            End of Page 24
  1415.  
  1416.  
  1417.                information on how to contact us, and information about new
  1418.                OpenDoors features currently in the works.
  1419.  
  1420.                It is suggested that if you wish to get the most out of
  1421.                OpenDoors, that you carefully read the sections of the manual
  1422.                that describe the use of the features you are using, and at
  1423.                least skim other portions of the manual to find out what
  1424.                additional features are available. Also, you will likely want to
  1425.                print this manual, to make reading and reference while
  1426.                programming easier. To print this manual, simply type the
  1427.                following line from your DOS prompt:
  1428.  
  1429.                               COPY OPENDOOR.DOC PRN:
  1430.  
  1431.  
  1432.  
  1433.  
  1434. COMPILING A PROGRAM WITH OPENDOORS
  1435. -------------------------------------------------------------------------------
  1436.  
  1437.                The process of compiling a program written with OpenDoors is
  1438.                very similar to that of compiling any other program. However,
  1439.                there are two additional steps which you must be sure to
  1440.                remember:
  1441.  
  1442.                1.)  You must include the OPENDOOR.H header file.
  1443.  
  1444.                2.)  You must link your program with the appropriate OpenDoors
  1445.                     library file.
  1446.  
  1447.  
  1448.                All programs written with OpenDoors, must "include" the
  1449.                OPENDOOR.H header file. If you have placed the OPENDOOR.H header
  1450.                file in the same directory as your door's source code, place the
  1451.                following line at the beginning of your .C or .CPP file(s):
  1452.  
  1453.                     #include "opendoor.h"
  1454.  
  1455.                If you have placed the OPENDOOR.H header file in the same
  1456.                directory as other standard header files (such as stdio.h),
  1457.                place the following line at the beginning of your .C or .CPP
  1458.                file(s):
  1459.  
  1460.                     #include <opendoor.h>
  1461.  
  1462.                In addition to including the OpenDoors header file in your
  1463.                source code modules, you must also "link" the OpenDoors library
  1464.                file with your program. The procedure for doing this depends
  1465.                upon which compiler you are using. The next few paragraphs
  1466.                describe how to link with the OpenDoors libraries using a
  1467.                various compilers. Following that I explain how to choose the
  1468.                appropriate library for the memory model you are using.
  1469.  
  1470.  
  1471.  
  1472. ===============================================================================
  1473. OpenDoors 5.00 Manual                                            End of Page 25
  1474.  
  1475.  
  1476.                If you are using Borland Turbo C 2.00 or earlier, you can cause
  1477.                your compiler to link your program with the OpenDoors library by
  1478.                creating a text file with a .PRJ extension. In this text file,
  1479.                you should list the names of your program's .C modules, along
  1480.                with the name of the appropriate OpenDoors library file, as
  1481.                listed in the table at the end of this section. You should then
  1482.                select this Project file from within the Turbo C IDE prior to
  1483.                compiling your program.
  1484.  
  1485.                If you are using Turbo C++ or Borland C++, you can cause your
  1486.                compiler to link your program with the OpenDoors library by
  1487.                creating a project file from within the IDE. To do this, choose
  1488.                the Open Project command from the Project menu, and eter the
  1489.                name for your new project file in the Load Project dialog box.
  1490.                Then add the names of your program's .C/.CPP modules, along with
  1491.                the name of the appropriate OpenDoors library file, by pressing
  1492.                [Insert] in the project window. When you return to Turbo C++ or
  1493.                Borland C++ again, you can work with the same project file by
  1494.                using the Open command from the Project menu.
  1495.  
  1496.                If you are using any Microsoft C compiler, such as Quick C,
  1497.                Microsoft C or Visual C++, you can cause your compiler to link
  1498.                your program with the OpenDoors library by creating a makefile.
  1499.                You can create a new project file from within Quick C by using
  1500.                the Set Program List option from the Make menu. You can do this
  1501.                from within Visual C++ by using the New command from the Project
  1502.                menu. You should add the names of your program's .C/.CPP source
  1503.                files, along with the name of the appropriate OpenDoors library
  1504.                file, to the newly create makefile.
  1505.  
  1506.                For more information on how to link your program with third-
  1507.                party library files such as OpenDoors, consult the manuals that
  1508.                are included with your compiler.
  1509.  
  1510.                There are a number of different library files included with
  1511.                OpenDoors, each one for use with a different memory model. The
  1512.                following chart lists the library file names, along with their
  1513.                corresponding memory model. It is important that you use the
  1514.                library file which corresponds to the memory model you are
  1515.                using. Whenever you change your compiler to use a different
  1516.                memory model, it is important to rebuild all of your source
  1517.                files (using the "Build All" or "Rebuild All" command) in
  1518.                addition to changing the library that your program is being
  1519.                linked with. If you are unfamiliar with the concept of memory
  1520.                models, you should refer to your compiler's manuals. If you are
  1521.                unsure as to what memory model your compiler is currently using,
  1522.                check this setting in the compile options dialog box or command
  1523.                line reference information.
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531. ===============================================================================
  1532. OpenDoors 5.00 Manual                                            End of Page 26
  1533.  
  1534.  
  1535.                   +------------------------------------------------+
  1536.                   | Library     | Memory                           |
  1537.                   | Filename    | Model                            |
  1538.                   |-------------|----------------------------------|
  1539.                   | ODOORS.LIB  | The Small memory model library   |
  1540.                   |             |                                  |
  1541.                   | ODOORM.LIB  | The Medium memory model library  |
  1542.                   |             |                                  |
  1543.                   | ODOORC.LIB  | The Compact memory model library |
  1544.                   |             | (Available separately)           |
  1545.                   |             |                                  |
  1546.                   | ODOORL.LIB  | The Large memory model library   |
  1547.                   |             |                                  |
  1548.                   | ODOORH.LIB  | The Huge memory model library    |
  1549.                   +------------------------------------------------+
  1550.  
  1551.                To understand how to compile a program written with OpenDoors,
  1552.                it is a good idea to try compiling one of the example programs,
  1553.                such as ex_hello.c, that are included in the OpenDoors package.
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590. ===============================================================================
  1591. OpenDoors 5.00 Manual                                            End of Page 27
  1592.  
  1593.  
  1594.  
  1595.  
  1596.  
  1597.  
  1598. BASICS OF DOOR PROGRAMMING WITH OPENDOORS
  1599. -------------------------------------------------------------------------------
  1600.  
  1601.                This section provides a complete tutorial to the basics of door
  1602.                programming with OpenDoors. It is important that you read this
  1603.                section. While OpenDoors allows you to write door programs in
  1604.                almost the same manner as you would any "normal" program, there
  1605.                are a few things which you must keep in mind, in order that your
  1606.                programs function correctly. You are also encouraged to look at
  1607.                the sample doors included with OpenDoors. These programs, which
  1608.                are described beginning on page 38, will give you a much better
  1609.                idea of what an OpenDoors program will look like, and provides
  1610.                you with a starting point for writing your own door programs.
  1611.  
  1612.                Probably the best means of introduction to door programming with
  1613.                OpenDoors is by doing it yourself. As such, I strongly encourage
  1614.                you to try typing in, compiling and running the simple
  1615.                introduction program below. For instructions on compiling
  1616.                programs written with OpenDoors, see page 25.
  1617.  
  1618.                     #include "opendoor.h"
  1619.  
  1620.                     main()
  1621.                        {
  1622.                        od_printf("Welcome to my first Door!\n\r");
  1623.                        od_printf("Press a key to return to BBS!\n\r");
  1624.                        od_get_key(TRUE);
  1625.                        }
  1626.  
  1627.                Keep in mind that even this simple program will automatically
  1628.                have all of the door capabilities we have already mentioned.
  1629.                Notice the inclusion of the OPENDOOR.H file. All doors written
  1630.                with OpenDoors must include the OPENDOOR.H header file in order
  1631.                to compile correctly. The first two lines in the main function
  1632.                simply call the OpenDoors od_printf() function. od_printf() is
  1633.                similar to the printf() function that C programmers will already
  1634.                be famailiar with. However, unlike printf(), the od_printf()
  1635.                function sends the output to both the modem and the local
  1636.                screen. Notice that the lines of text displayed by the
  1637.                od_printf() function end with a "\n\r" sequence, instead of the
  1638.                normal "\n". This is because hte terminal emulation software
  1639.                that is running on the remote user's system usually requires
  1640.                both a carriage return and a line feed to correctly begin a new
  1641.                line. The next line in our example program is the OpenDoors
  1642.                single-key input function, od_get_key(). The TRUE value causes
  1643.                OpenDoors to wait for a key to be pressed (again, either from
  1644.                remote or local keyboard) before returning.
  1645.  
  1646.                Once again, you are encouraged to try compiling and running this
  1647.                program on your own BBS setup, as described above.
  1648.  
  1649. ===============================================================================
  1650. OpenDoors 5.00 Manual                                            End of Page 28
  1651.  
  1652.  
  1653.                Congratulations, you have written your first door program! Feel
  1654.                free to make any changes to this program, and see what effects
  1655.                your changes have.
  1656.  
  1657.                In case you are not entirely familiar with the operation of door
  1658.                programs, we will now provide an introduction to the internals
  1659.                of a door's operation. Keep in mind that OpenDoors automatically
  1660.                carries out most of these tasks for you. When any door program
  1661.                starts up, one of the first things it must do is to read the
  1662.                door information file(s) (sometimes called a "drop file") passed
  1663.                to it by the BBS. When a user is on-line, and wishes to run a
  1664.                door, they will most likely select a command from a menu. At
  1665.                this point, the BBS system (such as RemoteAccess, Maximus, PC-
  1666.                Board or whatever), will create a file of information about the
  1667.                system, who is currently on-line, and so on. Various BBS
  1668.                packages produce various styles of door information files.
  1669.                OpenDoors automatically recognizes and reads a wide variety of
  1670.                door information file formats. As a result, your doors will be
  1671.                able to run on a almost any BBS system.
  1672.  
  1673.                The door itself will actually be loaded in one of two manners.
  1674.                Either the BBS will perform a "shell" and run the door while the
  1675.                BBS system resides in memory (sometimes called a type 7 exit),
  1676.                or it will exit to a batch file, which will trap an errorlevel
  1677.                and run the appropriate door program. (sometimes called a type
  1678.                15 exit). In either case, when the door gains control, it will
  1679.                first read the door information file(s), and then begin to
  1680.                communicate through the modem.
  1681.  
  1682.                Fortunately, OpenDoors takes care of all the work involved in
  1683.                detecting and reading the door information file, and then
  1684.                initializing and communicating with the serial port for you. In
  1685.                order to carry out these tasks, along with setting up the status
  1686.                line, and so on, OpenDoors provides a function called od_init().
  1687.                If you do not explicitly call this function, the first call to
  1688.                any other OpenDoors function (such as the first time your door
  1689.                program outputs anything) will automatically cause the od_init()
  1690.                function to be called. As a result, upon the first call to an
  1691.                OpenDoors function, all of the initialization tasks for the door
  1692.                will automatically be carried out. However, there may be times
  1693.                when you will want your program to have access information about
  1694.                the user who is on-line, or carry out other actions which
  1695.                require od_init() to have been executed - prior to the point
  1696.                where you call any other OpenDoors functions. In this case, you
  1697.                will have to call od_init() yourself before you do any of these
  1698.                things.
  1699.  
  1700.                OpenDoors provides you with a C/C++ structure, by the name of
  1701.                od_control, which allows you to access all the available
  1702.                information about the user who is on-line, the system your door
  1703.                is running on, and also allows you to adjust various OpenDoors
  1704.                parameters. Depending on what BBS system your door is running
  1705.                under, the actual information available from the od_control
  1706.                structure will vary. For more information on the od_control
  1707.  
  1708. ===============================================================================
  1709. OpenDoors 5.00 Manual                                            End of Page 29
  1710.  
  1711.  
  1712.                structure, see the section on the control structure, beginning
  1713.                on page 145.
  1714.  
  1715.                Once the door has initialized itself, it will then begin
  1716.                communications with the user who is online. OpenDoors takes care
  1717.                of all communications, through its various input and display
  1718.                functions. When the door has finished, it will then write any
  1719.                information that has changed back to the door information file
  1720.                (if applicable), finish communicating with the modem, and return
  1721.                to the BBS. In OpenDoors, these shut-down operations are
  1722.                automatically performed when your C or C++ program exits
  1723.                normally. If you wish to explicitly control OpenDoor's behaviour
  1724.                when exiting, you may exit the door program by calling the
  1725.                od_exit() function. This function will terminate the door's
  1726.                activity, OPTIONALLY hang up on the user (allowing you to
  1727.                provide either return to BBS or logoff options for exiting), and
  1728.                then exit with the specified errorlevel.
  1729.  
  1730.                One other important OpenDoors function that you should be aware
  1731.                of is the od_kernel() function. od_kernel() is the central
  1732.                OpenDoors control function, and is responsible for much of
  1733.                OpenDoor's updating of the status line, monitoring the carrier
  1734.                detect and user timeout status, responding to sysop function
  1735.                keys, and so on. The od_kernel() function is called
  1736.                automatically by OpenDoors, within the other OpenDoors
  1737.                functions. As a result, since most door programs will call some
  1738.                OpenDoors function on a regular basis, you will most often have
  1739.                no need to call the od_kernel() function yourself. However, if
  1740.                your door is going to perform some action, such as updating data
  1741.                files, during which it will not call any OpenDoors function for
  1742.                more than a few seconds, you should then call the od_kernel()
  1743.                function yourself. For more information on the od_kernel()
  1744.                function, see page 96.
  1745.  
  1746.                For more information on the functions available from OpenDoors,
  1747.                or the control structure, see the corresponding sections in this
  1748.                manual. I would also suggest that you have a look at the sample
  1749.                door included with OpenDoors, EZVote.
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767. ===============================================================================
  1768. OpenDoors 5.00 Manual                                            End of Page 30
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775. TOUR OF A SAMPLE DOOR PROGRAM: "EZVOTE"
  1776. ------------------------------------------------------------------------------
  1777.  
  1778.                One of the best ways to see how OpenDoors works, and the
  1779.                potential that it has, is to look at the source code for the
  1780.                included sample door programs. A brief description of each of
  1781.                these programs can be found on page 38. This section takes a
  1782.                closer look at one of the example programs, "EZVote".
  1783.  
  1784.                In your OpenDoors package you will find five .C source files for
  1785.                the EZVote program, named EX_VOTE1.C to EX_VOTE5.C. Each of
  1786.                these source files shows a further step in the process of
  1787.                building the EZVote program. EX_VOTE1.C lays the foundation with
  1788.                the code to display the main menu and respond to basic commands
  1789.                such as exiting the program. EX_VOTE2.C adds the user interface
  1790.                for the remaining commands, EX_VOTE3.C adds the underlying data
  1791.                file code, EX_VOTE4.C adds color and EX_VOTE5.C adds the
  1792.                finishing touches. You will probably want to begin by looking at
  1793.                EX_VOTE1.C, and then proceed to see the additions made to
  1794.                subsequent versions of the program. Don't be taken back by the
  1795.                complexity of the EZVote program - most of the source code is
  1796.                involved in accessing the data files used by this program, which
  1797.                is actually more complicated than many door programs will
  1798.                require.
  1799.  
  1800.                The OpenDoors package includes a compiled version of EZVote,
  1801.                which you can run by typing EZVOTE. The OpenDoors package also
  1802.                contains a sample door information file, DORINFO1.DEF. You can
  1803.                use this file to test any doors in local mode. If you wish to
  1804.                manually create your own DORINFO1.DEF file, you can do so very
  1805.                easily. The DORINFO1.DEF door information file is a simple text
  1806.                file which lists a different piece of information on each line,
  1807.                in the following format:
  1808.  
  1809.                +----------------------------------------------------------+
  1810.                | LINE NUMBER | DESCRIPTION            | EXAMPLE           |
  1811.                +-------------+------------------------+-------------------|
  1812.                |     1       | Name of the BBS        | MY OWN BBS        |
  1813.                |     2       | Sysop's first name     | BRIAN             |
  1814.                |     3       | Sysop's last name      | PIRIE             |
  1815.                |     4       | Com Port modem is on   | COM0              |
  1816.                |     5       | Baud rate, etc.        | 0 BAUD,N,8,1      |
  1817.                |     6       | Unused                 | 0                 |
  1818.                |     7       | User's first name      | JOHN              |
  1819.                |     8       | User's last name       | PUBLIC            |
  1820.                |     9       | Caller's location      | OTTAWA, ON        |
  1821.                |     10      | ANSI mode (0=off, 1=on)| 1                 |
  1822.                |     11      | User's security level  | 32000             |
  1823.                |     12      | User's time left       | 60                |
  1824.                +----------------------------------------------------------+
  1825.  
  1826. ===============================================================================
  1827. OpenDoors 5.00 Manual                                            End of Page 31
  1828.  
  1829.  
  1830.  
  1831.  
  1832.                Feel free to make any changes you wish to the EZVote, and
  1833.                recompile it. One of the most effective and enjoyable ways to
  1834.                learn OpenDoors is by experimenting. If you are a registered
  1835.                owner of OpenDoors, you may even distribute your own versions of
  1836.                this door. Also, you may find that EZVote serves as a good
  1837.                framework for building your own door programs.
  1838.  
  1839.                The EZVote door behaves similarly to most other door programs,
  1840.                and will have a fair bit in common with any other door you write
  1841.                in OpenDoors. What you see in the output window is identical to
  1842.                what a remote user will be seeing. If the user has ANSI, AVATAR
  1843.                or RIP mode turned on, you will see the same colours as they do,
  1844.                and if they have screen clearing turned on, your screen will be
  1845.                cleared when theirs is. The status line at the bottom of the
  1846.                screen will list the name of the user currently on-line (if you
  1847.                are using the sample DORINFO1.DEF file, the user's name will be
  1848.                "The Sysop"), the user's location, and the user's baud rate (0
  1849.                if the door is operating in local mode). You will also be told
  1850.                how much time the user has left, and there will be indicators as
  1851.                to whether the user has ANSI/AVATAR/RIP modes turned on, and so
  1852.                on. If the user wishes to Chat with the sysop (ie, they have
  1853.                paged the sysop, but haven't receive a response yet), a [Want-
  1854.                Chat] indicator will be flashing on the status line. Try Paging
  1855.                the sysop, using OpenDoors built in sysop page feature. The
  1856.                following function keys will also be available to the sysop in
  1857.                any OpenDoors program:
  1858.  
  1859.  
  1860.                [UP]/[DOWN] - Use the arrow keys to increase or decrease the
  1861.                              amount of time which the user has left in the
  1862.                              door.
  1863.  
  1864.                [Alt]-[C] -   Allows the sysop to break into chat with the user
  1865.                              at any time. [Alt]-[C] again, or [ESC] will end
  1866.                              chat mode. (Notice that the Want-Chat indicator
  1867.                              will also be turned off, if it was flashing. If
  1868.                              your door is running under Apex, RemoteAccess or
  1869.                              QuickBBS, paging from within the door will even
  1870.                              cause the Want-Chat indicator to stay lit when the
  1871.                              user returns to the BBS)
  1872.  
  1873.                [Alt]-[J] -   Allows the sysop to shell to DOS, if enough memory
  1874.                              is available. Simply type EXIT to return to the
  1875.                              door again.
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885. ===============================================================================
  1886. OpenDoors 5.00 Manual                                            End of Page 32
  1887.  
  1888.  
  1889.                [Alt]-[H] -   Hang up on the user. When the sysop does this,
  1890.                              OpenDoors will optionally call a function you have
  1891.                              indicated in the OpenDoors control structure, to
  1892.                              allow you to close files, etc. OpenDoors will then
  1893.                              exit with the appropriate errorlevel:
  1894.  
  1895.                                   0 - A critical error has occurred
  1896.                                   1 - Carrier lost, user off-line
  1897.                                   2 - Sysop terminated call, user off-line
  1898.                                   3 - User time used up, user STILL ON-LINE
  1899.                                   4 - Keyboard inactivity timeout, user
  1900.                                       off-line
  1901.                                   5 - Sysop has chosen to return the user to
  1902.                                       the BBS
  1903.                                   6 - Door has exited normally
  1904.  
  1905.                              These errorlevel will allow sysops using your door
  1906.                              to optionally log the user back on-line, place the
  1907.                              BBS in "wait for call" mode, or whatever they
  1908.                              wish, depending on how the door exited. These
  1909.                              default errorlevels may be redefined using the
  1910.                              od_control.od_errorlevel[] variable.
  1911.  
  1912.                [Alt]-[L] -   This key locks the user out of the BBS. It first
  1913.                              hangs up on the user, and then sets their security
  1914.                              level to 0, to prevent them from ever logging on
  1915.                              again. This feature may require use of the
  1916.                              EXITINFO.BBS file, depending on what system the
  1917.                              door is running under.
  1918.  
  1919.                [Alt]-[K] -   The "User Keyboard-Off" key allows the sysop to
  1920.                              temporarily prevent the user from typing anything
  1921.                              on their keyboard. This has no effect on the local
  1922.                              keyboard, but causes OpenDoors to ignore any
  1923.                              keystrokes from remote.
  1924.  
  1925.                [Alt]-[N] -   The "Sysop Next" key, this function reserves the
  1926.                              system for use by the sysop after the user logs
  1927.                              off, if the door is running under an Apex or RA
  1928.                              1.00 or later system.
  1929.  
  1930.                [Alt]-[D] -   "Drop to BBS" key. This function allows the sysop
  1931.                              to exit the door and return the user to the BBS,
  1932.                              without hanging up.
  1933.  
  1934.  
  1935.                Now, let us take a closer look at the actual source code for the
  1936.                EZVote door. If you have not already printed out a copy of this
  1937.                manual, and possibly the EX_VOTE?.C files as well, it would
  1938.                probably be a good idea to do so now.
  1939.  
  1940.                EX_VOTE1.C Demonstrates the basic elements of any door program.
  1941.                This file contains the code to handle display of main menu,
  1942.                responding to the user's choice from the main menu, and common
  1943.  
  1944. ===============================================================================
  1945. OpenDoors 5.00 Manual                                            End of Page 33
  1946.  
  1947.  
  1948.                commands such as returning to the BBS and paging the system
  1949.                operator. This file also demonstrates basics of displaying text
  1950.                and retrieving input from user. Notice that near the top of the
  1951.                program, along with all the standard header files, the
  1952.                OPENDOOR.H file is included. This file must be included in all
  1953.                programs written under OpenDoors. If you are placing the
  1954.                OPENDOOR.H file in the same directory as the door you are
  1955.                compiling, simply include the line:
  1956.  
  1957.                                     #include "opendoor.h"
  1958.  
  1959.                in your program.
  1960.  
  1961.                The main() function of the EZVote program has a for(;;) loop
  1962.                that repeatedly displays the main menu, obtains a choice from
  1963.                the user and responds to the command, until the user chooses to
  1964.                exit the program. Before the main menu is displayed, the screen
  1965.                is cleared by calling od_clr_scr(). The od_clr_scr() function
  1966.                will clear both the local and remote screens, but only if the
  1967.                user has screen clearing enabled. Refer to page 57 for
  1968.                information on how to force the screen to be cleared, regardless
  1969.                of the user's screen clearing setting. The main menu is
  1970.                displayed using the od_printf() function, one of the most common
  1971.                OpenDoors functions you will use. Next, od_get_answer() is used
  1972.                to obtain a menu choice from the user from the specified set of
  1973.                keys. Next, a switch() statement is used to respond to the
  1974.                user's command appropriately. If the user presses the P key to
  1975.                page the system operator, od_page() is called. If the user
  1976.                chooses to return to the BBS, od_exit() is called to terminate
  1977.                OpenDoor's activities and return control to the BBS. The FALSE
  1978.                parameter passed to od_exit() indicates that OpenDoors should
  1979.                not disconnect (hangup) before exiting. If the user chooses to
  1980.                log off, EZVote first confirms this action with the user, and
  1981.                then calls od_exit() with the TRUE parameter. The numerical
  1982.                parameter passed to od_exit() sets the errorlevel that OpenDoors
  1983.                will exit with.
  1984.  
  1985.                EX_VOTE2.C Adds the user interface code to handle the main menu
  1986.                commands specific to EZVote, such as answering questions,
  1987.                viewing the results of questions, and adding new questions. For
  1988.                the most part the new code added to EX_VOTE2.C involves uses the
  1989.                same OpenDoors features that we have already looked at. However,
  1990.                if you look carefully you will notice some things that we
  1991.                haven't encountered before. In its ChooseQuestion() function,
  1992.                EZVote uses the OpenDoors function od_get_key(). This function
  1993.                is similar to the od_get_answer() function that we have already
  1994.                seen. However, unlike od_get_answer() which will wait until the
  1995.                user presses some key from the list of possibilities you
  1996.                provide, od_get_key() will allow the user to press any key.
  1997.                od_get_key() accepts a single parameter. If this parameter is
  1998.                TRUE, od_get_key() will wait for the user to press a key before
  1999.                returning. If this parameter is FALSE, od_get_key() will return
  2000.                immediately with a value of 0 if there are no keys waiting in
  2001.  
  2002.  
  2003. ===============================================================================
  2004. OpenDoors 5.00 Manual                                            End of Page 34
  2005.  
  2006.  
  2007.                the inbound buffer, and returning the next key if there are
  2008.                characters waiting.
  2009.  
  2010.                In a number of places, EX_VOTE2.C also uses the od_input_str()
  2011.                function. Unlike od_get_key() and od_get_answer() which return a
  2012.                single character, od_input_str() allows the user to input and
  2013.                edit a string of many characters. You will only receive the
  2014.                string entered by the user after they press the enter key.
  2015.                od_input_str() accepts four parameters: the string where the
  2016.                user's input should be stored, the maximum number of characters
  2017.                to input, the minimum character value to accept and the maximum
  2018.                character value to accept.
  2019.  
  2020.                Another new feature of OpenDoors that is used by EX_VOTE2.C is
  2021.                the OpenDoors control structure, od_control. This global
  2022.                structure is documented in chapter 5 of this manual. The
  2023.                OpenDoors control structure allows you to access a wide variety
  2024.                of information about the user who is currently online, the BBS
  2025.                system your program is running on, and also allows you to
  2026.                control various OpenDoors settings. For example, EX_VOTE2.C
  2027.                compares the current user name (od_control.od_user_name) with
  2028.                the name of the system operator (od_control.od_sysop_name) to
  2029.                determine whether it is the system operator who using the
  2030.                program.
  2031.  
  2032.                EX_VOTE3.C adds the code used by EZVote to store the questions
  2033.                and users in its data files. EZVote uses two data files, the
  2034.                first of which contains a record for every user, and the second
  2035.                of which contains a record for every question. EZVote accesses
  2036.                these data files in a controlled manner in order to permit the
  2037.                program to be running simultaneously on multiple lines on a
  2038.                multi-node BBS system. When EZVote needs to update a data file,
  2039.                it opens it for exclusive access, so that only one node can
  2040.                access the file at any given time. Since the data file could
  2041.                have been changed by another node since the time that EZVote
  2042.                last read the file, it always reads a record, makes changes to
  2043.                it and then re-writes the record while it has the file open for
  2044.                exclusive access. It then closes the file as soon as possible
  2045.                after opening the file, in order to permit other nodes to once
  2046.                again access the file. Because EZVote keeps track of which
  2047.                questions each user has voted on, along with the questions and
  2048.                results of voting on each question, its data file format is more
  2049.                complex than many door programs (although not as complex as
  2050.                others).
  2051.  
  2052.                EX_VOTE4.C adds the use of colour. One of the easiest ways to
  2053.                use different colors in an OpenDoors program is to use the
  2054.                OpenDoor's print color-setting extensions. You can change the
  2055.                color of text display at any point in an od_printf() format
  2056.                string using by enclosing the name of new display color in back
  2057.                quote characters (`, not '). For example:
  2058.  
  2059.                     od_printf("`red`This is in red `green`This is green\n\r");
  2060.  
  2061.  
  2062. ===============================================================================
  2063. OpenDoors 5.00 Manual                                            End of Page 35
  2064.  
  2065.  
  2066.                Would cause the words "This is in red" to be displayed in red,
  2067.                and the words "This is in green" to be displayed in green.
  2068.  
  2069.                EX_VOTE5.C adds the finishing touches to the EZVote program,
  2070.                taking advantage of a number of OpenDoors capabilities that you
  2071.                can optionally choose to include in your door programs. You will
  2072.                notice that there are a number of new lines at the beginning of
  2073.                the main() function, all of which change settings in the
  2074.                OpenDoors control structure. The line:
  2075.  
  2076.                     od_control.od_config_file = INCLUDE_CONFIG_FILE;
  2077.  
  2078.                causes the OpenDoors configuration file system to be included in
  2079.                your program. Using this system, OpenDoors automatically reads a
  2080.                configuration file that can be used by the system operator to
  2081.                change various program settings. Refer to the included door.cfg
  2082.                file for an example OpenDoors configuration file. In addition to
  2083.                the configuration file settings automatically supported by the
  2084.                configuration file system, you can also add your own
  2085.                configuration file settings. To do this, you simply supply
  2086.                OpenDoors with a callback function that it will call whenever it
  2087.                encounters an unrecognized keyword in the configuration file.
  2088.                The line:
  2089.  
  2090.                     od_control.od_config_function = CustomConfigFunction;
  2091.  
  2092.                Causes OpenDoors to call the function CustomConfigFunction() in
  2093.                ex_vote5.c for this purpose. You will notice that the
  2094.                CustomConfigFunction() receives two parameters - the first is
  2095.                the unrecognized keyword, and the second is any parameters that
  2096.                follow the keyword in the configuration file. EZVote checks for
  2097.                two special configuration file lines - one to set whether or not
  2098.                users can add questions, and one to set whether or not users can
  2099.                view the results of a question before voting on it.
  2100.  
  2101.                The next line in the main() function,
  2102.  
  2103.                     od_control.od_mps = INCLUDE_MPS;
  2104.  
  2105.                causes the OpenDoors "Multiple Personality System" to be
  2106.                included in program. This allows the sysop to choose from a
  2107.                number of status line / sysop function key "personalities" that
  2108.                mimic a number of different BBS systems, using the Personality
  2109.                setting in the configuration file.
  2110.  
  2111.  
  2112.                The line:
  2113.  
  2114.                     od_control.od_logfile = INCLUDE_LOGFILE;
  2115.  
  2116.                causes the OpenDoors log file system to be included in the
  2117.                program. The OpenDoors log file system automatically records the
  2118.                date and time of program startup, exit and other major actions
  2119.  
  2120.  
  2121. ===============================================================================
  2122. OpenDoors 5.00 Manual                                            End of Page 36
  2123.  
  2124.  
  2125.                in the specified file. EZVote also writes its own log file
  2126.                entries by calling the od_log_write() function.
  2127.  
  2128.                The last major functionally enhancement that is made in the
  2129.                EX_VOTE5.C file is the ability for the sysop to provide their
  2130.                own ASCII/ANSI/AVATAR/RIP files to be displayed in place of the
  2131.                normal main menu. EZVote uses the od_hotkey_menu() function to
  2132.                display an EZVOTE.ASC/.ANS/.AVT/.RIP file for the main menu, if
  2133.                such a file exists. If the file is not available, the normal
  2134.                EZVote menu is used instead. The od_hotkey_menu() function will
  2135.                automatically select the appropriate file (.ASC/.ANS/.AVT/.RIP)
  2136.                for the current display mode, and the user is able to make a
  2137.                menu choice at any time. If a menu choice is made before the
  2138.                menu is entirely displayed, the function will stop displaying
  2139.                the menu and return immediately.
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180. ===============================================================================
  2181. OpenDoors 5.00 Manual                                            End of Page 37
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188. OTHER EXAMPLE DOORS INCLUDED WITH OPENDOORS
  2189. ------------------------------------------------------------------------------
  2190.  
  2191.                In addition to the EZVote door, which is discussed in detail in
  2192.                the previous section, a number of other example doors are
  2193.                included with OpenDoors. These doors help to demonstrate what is
  2194.                possible with OpenDoors. They can also serve as excellent tools
  2195.                to help you learn about OpenDoors as quickly as possible. In
  2196.                addition, you are free to include any portions of any of these
  2197.                example doors in your own door programs. Below is a summary of
  2198.                each of these example programs:
  2199.  
  2200.  
  2201. -------------------------------------------------------------------------------
  2202. EX_HELLO.C     This an example of a very simply door program that displays a
  2203.                short message and prompts for the user to press a key. After the
  2204.                user presses a key, the door exits and control is returned to
  2205.                the main BBS software. Despite the fact that it only consists of
  2206.                a few lines of code, EX_HELLO remains a fully functional door
  2207.                program. For information on compiling an OpenDoors door program,
  2208.                see the section that begins on page 25.
  2209.  
  2210.  
  2211. -------------------------------------------------------------------------------
  2212. EX_CHAT.C      This program is an example of a multi-window full-screen chat
  2213.                door written with OpenDoors. EX_CHAT demonstrates the ease of
  2214.                using sophisticated ANSI / AVATAR / RIP terminal features within
  2215.                OpenDoors programs. For instructions on how to compile this
  2216.                program, see the section that begins on page 25.
  2217.  
  2218.                This program create two windows on the screen, separated by a
  2219.                bar with user name / sysop name information. This program
  2220.                permits communication between the local sysop and remote user by
  2221.                displaying the text typed by the user in one window, and the
  2222.                text typed by the sysop in the other window. When either
  2223.                person's typing reaches the bottom of the window, the contents
  2224.                of the window is scrolled up to provide more room for typing.
  2225.                Words are also wrapped when either typist reaches the end of a
  2226.                line. The advantage of a split-screen chat program is that it
  2227.                permits both sysop and user to type at the same time without
  2228.                difficulty. The chat function automatically invokes OpenDoor's
  2229.                internal chat mode if ANSI, AVATAR or RIP modes are not
  2230.                available. The display colours, window sizes and locations, and
  2231.                distance to scroll a window's contents are configurable by
  2232.                setting the appropriate variables, below. When the Sysop invokes
  2233.                a DOS shell, a pop-up window is displayed to indicate to the
  2234.                user that the door program has been suspended.
  2235.  
  2236.  
  2237.  
  2238.  
  2239. ===============================================================================
  2240. OpenDoors 5.00 Manual                                            End of Page 38
  2241.  
  2242.  
  2243.                The chat feature of this program can also be easily integrated
  2244.                into other doors you write, and may be used to replace the
  2245.                existing OpenDoors line-oriented chat system.
  2246.  
  2247.  
  2248. -------------------------------------------------------------------------------
  2249. EX_MUSIC.C     This example door demonstrates how to play "ANSI" music and
  2250.                sound effects in an OpenDoors door. Included in this program is
  2251.                a function to send "ANSI" music to the remote system, and a
  2252.                function to text the remote system's ability to play "ANSI"
  2253.                music. You may use both of these functions in your own doors, if
  2254.                you wish to add music or sound effect capabilities. This program
  2255.                can be compiled by following the instructions that begin on page
  2256.                  .                 25
  2257.  
  2258.  
  2259. -------------------------------------------------------------------------------
  2260. EX_SKI.C       This is a simple but addictive door game that is written using
  2261.                OpenDoors. In this action game, the player must control a skier
  2262.                through a downhill slalom course. The user may turn the skier
  2263.                left or right, and the game ends as soon as the player skis
  2264.                outside the marked course. The game begins at an easy level, but
  2265.                quickly becomes more and more difficult as the course to be
  2266.                navigated becomes more and more narrow. The game maintains a
  2267.                list of players with high scores, and this list may be viewed
  2268.                from the main menu.
  2269.  
  2270.  
  2271. -------------------------------------------------------------------------------
  2272. EX_VOTE?.C     The EX_VOTE?.C files contain the source code for the EZVote
  2273.                example door, as is described beginning on page 38. The EZVote
  2274.                example door allows users to vote on up to 200 different
  2275.                "polls", view the results of voting on each question, and
  2276.                optionally add their own questions for other users to answer.
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298. ===============================================================================
  2299. OpenDoors 5.00 Manual                                            End of Page 39
  2300.  
  2301.  
  2302.  
  2303. -------------------------------------------------------------------------------
  2304. CHAPTER 4 - THE OPENDOORS API FUNCTIONS
  2305. -------------------------------------------------------------------------------
  2306.  
  2307.  
  2308.  
  2309.  
  2310. OVERVIEW
  2311. ------------------------------------------------------------------------------
  2312.  
  2313.                All of the door-related activities of an OpenDoors door program
  2314.                are coordinated through one of two facilities - the OpenDoors
  2315.                API functions, and the OpenDoors door control structure. In
  2316.                general, the API functions are used to actually accomplish a
  2317.                task, such as displaying something to the user, or retrieving
  2318.                input from the user. The OpenDoors control structure, on the
  2319.                other hand, is used to alter OpenDoors settings or retrieve
  2320.                specific information.
  2321.  
  2322.                Any program written with OpenDoors makes use of the OpenDoors
  2323.                API functions for all of its door-related input and output. In
  2324.                addition to the common input and output tasks, the OpenDoors API
  2325.                functions provide access to many special capabilities, such as
  2326.                displaying ASCII/ANSI/AVATAR/RIP files, providing pop-up windows
  2327.                and menus, and much more. Much of the information about the user
  2328.                who is online, information about the system your door is running
  2329.                on, and settings which customize OpenDoor's behavior are
  2330.                controlled through the OpenDoors control structure. The control
  2331.                structure is described in the section beginning on page 145.
  2332.  
  2333.                This chapter is divided into the following sections:
  2334.  
  2335.                     i.)   TABLE OF MOST COMMONLY USED FUNCTIONS (Page 41)
  2336.                    ii.)  TABLE OF ALL OPENDOORS FUNCTIONS (Page 42)
  2337.                   iii.) DETAILED INFORMATION ON EACH FUNCTION (Pages 46 - 144)
  2338.  
  2339.                The two tables list the names of the OpenDoors functions, along
  2340.                with a brief description of the task performed by each function,
  2341.                and the page number on which the detailed description of that
  2342.                function can be found. The first table lists only the most
  2343.                commonly used OpenDoors functions, to allow you to quickly find
  2344.                the function you are most likely looking for. The second table
  2345.                lists all of the OpenDoors functions, grouped according to
  2346.                general categories of functionality.
  2347.  
  2348.                The section containing detailed information lists all of the
  2349.                functions in alphabetical order, with the information about each
  2350.                function beginning on a new page. This section includes a brief
  2351.                description of each function's purpose, a detailed description
  2352.                of how to use the function, the function call format, a list of
  2353.                related functions, and in many cases example source code showing
  2354.                you a typical use of the function.
  2355.  
  2356.  
  2357. ===============================================================================
  2358. OpenDoors 5.00 Manual                                            End of Page 40
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365. TABLE OF MOST COMMONLY USED FUNCTIONS
  2366. ------------------------------------------------------------------------------
  2367.  
  2368.                od_printf()         Displays text, with the ability to change
  2369.                                    display colour. (page 105)
  2370.  
  2371.                od_clr_scr()        Clears the screen. (Page 57)
  2372.  
  2373.                od_input_str()      Inputs a string of one or more characters
  2374.                                    from the user. (Page 94)
  2375.  
  2376.                od_get_answer()     Inputs a single key from a list of possible
  2377.                                    choices ignoring upper/lower case. (Page 83)
  2378.  
  2379.                od_get_key()        Inputs any single key from the user.
  2380.                                    (Page 84)
  2381.  
  2382.                od_set_cursor()     Positions the cursor in ANSI/AVATAR/RIP
  2383.                                    modes. (Page 131)
  2384.  
  2385.                od_hotkey_menu()    Displays an ASCII/ANSI/AVATAR/RIP file, with
  2386.                                    the option of watching for a keypress from
  2387.                                    the user. (Page 89)
  2388.  
  2389.                od_popup_menu()     Displays a popup menu in ANSI/AVATAR/RIP
  2390.                                    modes. (Page 102)
  2391.  
  2392.                od_window_create()  Creates a popup window in ANSI/AVATAR/RIP
  2393.                                    modes. (Page 142)
  2394.  
  2395.                od_window_remove()  Removes a popup window in, restoring screen
  2396.                                    contents "underneath" window. (Page 144)
  2397.  
  2398.  
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416. ===============================================================================
  2417. OpenDoors 5.00 Manual                                            End of Page 41
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424. TABLE OF ALL FUNCTIONS
  2425. -------------------------------------------------------------------------------
  2426. OUTPUT         TEXT DISPLAY FUNCTIONS
  2427. FUNCTIONS      ----------------------
  2428.                od_disp_str()            Displays a normal, NULL-terminated
  2429.                                         string. (page 64)
  2430.  
  2431.                od_disp()                Sends the specified number of
  2432.                                         characters to the modem, with or
  2433.                                         without local echo. (page 60)
  2434.  
  2435.                od_printf()              Performs formatted output, as the
  2436.                                         printf() function does. Also allows
  2437.                                         imbedded codes to change display
  2438.                                         colour. (page 105)
  2439.  
  2440.                od_putch()               Displays a single character. (page 110)
  2441.  
  2442.                od_disp_emu()            Displays a string, interpreting
  2443.                                         imbedded ANSI/AVATAR terminal emulation
  2444.                                         codes. (page 62)
  2445.  
  2446.                od_repeat()              Displays the same character any number
  2447.                                         of times, using AVATAR optimization, if
  2448.                                         possible. (page 114)
  2449.  
  2450.                COLOUR AND CURSOR CONTROL
  2451.                -------------------------
  2452.                od_set_colour()          Sets current colour to specified
  2453.                                         foreground and background settings.
  2454.                                         (page 128)
  2455.  
  2456.                od_set_attrib()          Sets current colour to specified IBM-PC
  2457.                                         display attribute. (page 125)
  2458.  
  2459.                od_set_cursor()          Sets the position of the cursor, if
  2460.                                         ANSI/AVATAR/RIP mode is enabled. (page
  2461.                                         131)
  2462.  
  2463.                SCREEN MANIPULATION
  2464.                -------------------
  2465.                od_clr_scr()             Clears the screen, if user has screen
  2466.                                         clearing enabled. (page 57)
  2467.  
  2468.                od_save_screen()         Stores the current contents of the
  2469.                                         screen, to be later redisplayed using
  2470.                                         od_restore_screen(). Works in all
  2471.                                         display modes. (page 117)
  2472.  
  2473.  
  2474.  
  2475. ===============================================================================
  2476. OpenDoors 5.00 Manual                                            End of Page 42
  2477.  
  2478.  
  2479.                od_restore_screen()      Restores the contents of the screen, as
  2480.                                         previously stored using
  2481.                                         od_save_screen(). Works in all display
  2482.                                         modes. (page 116)
  2483.  
  2484.                BLOCK MANIPULATION
  2485.                ------------------
  2486.                od_clr_line()            Clears the remainder of current line.
  2487.                                         (page 55)
  2488.  
  2489.                od_gettext()             Stores any area of the screen, to later
  2490.                                         be displayed by od_puttext(). Requires
  2491.                                         ANSI/AVATAR/RIP graphics mode. (page
  2492.                                         88)
  2493.  
  2494.                od_puttext()             Displays text with colour information,
  2495.                                         as previously stored using
  2496.                                         od_gettext(). Requires ANSI/AVATAR/RIP
  2497.                                         graphics mode. (page 112)
  2498.  
  2499.                od_scroll()              Scrolls a portion of the screen in
  2500.                                         ANSI/AVATAR/RIP graphics modes. (page
  2501.                                         119)
  2502.  
  2503.                POPUP WINDOWS AND MENUS
  2504.                -----------------------
  2505.                od_draw_box()            Draws a box on the screen in
  2506.                                         ANSI/AVATAR/RIP graphics mode. (page
  2507.                                         66)
  2508.  
  2509.                od_window_create()       Displays a popup window, storing the
  2510.                                         screen contents "under" the window.
  2511.                                         Requires ANSI/AVATAR/RIP graphics mode.
  2512.                                         (page 142)
  2513.  
  2514.                od_window_remove()       Removes a popup window displayed with
  2515.                                         od_window_create(), restoring the
  2516.                                         original screen contents "under" the
  2517.                                         window. Requires ANSI/AVATAR/RIP
  2518.                                         graphics mode. (page 144)
  2519.  
  2520.                od_popup_menu()          Displays a menu in a popup window,
  2521.                                         allowing the user to choose menu items
  2522.                                         either by pressing a "hot" key, or
  2523.                                         moving a highlighted selection bar.
  2524.                                         After menu selection, the menu may be
  2525.                                         removed, restoring the original screen
  2526.                                         contents "under" the window. Requires
  2527.                                         ANSI/AVATAR/RIP graphics mode. (page
  2528.                                         102)
  2529.  
  2530.                FILE DISPLAY FUNCTIONS
  2531.                ----------------------
  2532.  
  2533.  
  2534. ===============================================================================
  2535. OpenDoors 5.00 Manual                                            End of Page 43
  2536.  
  2537.  
  2538.                od_send_file()           Displays an ASCII/ANSI/AVATAR/RIP file
  2539.                                         (for instance, an .ANS file created by
  2540.                                         a program such as "TheDraw" (page 121)
  2541.  
  2542.                od_hotkey_menu()         Displays an ASCII/ANSI/AVATAR/RIP menu
  2543.                                         file, with hotkeys active. (page 89)
  2544.  
  2545.                od_list_files()          Lists the files available for download
  2546.                                         in an area, using a FILES.BBS file.
  2547.                                         (page 98)
  2548.  
  2549.  
  2550. -------------------------------------------------------------------------------
  2551. INPUT          od_get_answer()          Inputs a single key from the keyboard,
  2552. FUNCTIONS                               allowing only particular responses.
  2553.                                         (page 83)
  2554.  
  2555.                od_get_key()             Inputs a single key from the keyboard,
  2556.                                         optionally waiting if a key is not
  2557.                                         available. (page 84)
  2558.  
  2559.                od_input_str()           Inputs a string of specified length,
  2560.                                         from the keyboard. (page 94)
  2561.  
  2562.                od_edit_str()            Formatted string editing function,
  2563.                                         requiring ANSI/AVATAR/RIP graphics.
  2564.                                         (page 70)
  2565.  
  2566.                od_clear_keybuffer()     Removes any waiting keys from the
  2567.                                         keyboard input queue. (page 53)
  2568.  
  2569.  
  2570. -------------------------------------------------------------------------------
  2571. COMMON         od_page()                Allows the user to page the sysop.
  2572. DOOR                                    (page 101)
  2573. ACTIVITY
  2574. FUNCTIONS      od_spawn()               OpenDoors "quick" spawn function.
  2575.                                         Executes an external program (eg. file
  2576.                                         compressor, external protocol, etc.) on
  2577.                                         a separate screen, restoring the
  2578.                                         OpenDoors screen afterwards. (page 138)
  2579.  
  2580.                od_spawnvpe()            OpenDoors full-featured spawn function.
  2581.                                         Executes an external program on a
  2582.                                         separate screen, searching the path for
  2583.                                         the program, allowing you to specify an
  2584.                                         environment to pass to the child
  2585.                                         process, and returning the errorlevel
  2586.                                         returned by the child process. (page
  2587.                                         140)
  2588.  
  2589.                od_log_write()           Adds an entry to the end of the log
  2590.                                         file. (page 100)
  2591.  
  2592.  
  2593. ===============================================================================
  2594. OpenDoors 5.00 Manual                                            End of Page 44
  2595.  
  2596.  
  2597.  
  2598. -------------------------------------------------------------------------------
  2599. SPECIAL        od_init()                Begins door operation by setting up
  2600. CONTROL                                 the OpenDoors control structure,
  2601. FUNCTIONS                               setting up the local screen,
  2602.                                         initializing the serial port (if
  2603.                                         applicable), and reading the door
  2604.                                         information file. (page 91)
  2605.  
  2606.                od_colour_config()       Transfers a colour configuration line
  2607.                                         to a colour attribute value. (page 59)
  2608.  
  2609.                od_add_personality()     Adds a custom status line/control key
  2610.                                         personality to OpenDoors. (page 46)
  2611.  
  2612.                od_set_statusline()      Temporarily alters the setting of the
  2613.                                         current OpenDoors status line. (page
  2614.                                         136)
  2615.  
  2616.                od_autodetect()          Automatically determines the remote
  2617.                                         terminal software's graphical
  2618.                                         capabilities. (page 48)
  2619.  
  2620.                od_kernel()              The central OpenDoors control function,
  2621.                                         which should be executed every few
  2622.                                         seconds. (page 96)
  2623.  
  2624.                od_exit()                Ends door operations, closing the
  2625.                                         serial port driver, re-writing the door
  2626.                                         information file, and optionally
  2627.                                         returning control to the BBS. (page 81)
  2628.  
  2629.                od_carrier()             Allows detection of carrier signal in
  2630.                                         programs that have disabled OpenDoors
  2631.                                         internal checking. (page 51)
  2632.  
  2633.                od_set_dtr()             Controls the DTR signal to the modem.
  2634.                                         Can be used to manually disconnect a
  2635.                                         remote user, in order to perform
  2636.                                         activities such as call back
  2637.                                         verification. (page 133)
  2638.  
  2639.                od_chat()                Forces OpenDoors to enter chat mode,
  2640.                                         even if sysop did not press the "chat"
  2641.                                         key. (page 50)
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.  
  2648.  
  2649.  
  2650.  
  2651.  
  2652. ===============================================================================
  2653. OpenDoors 5.00 Manual                                            End of Page 45
  2654.  
  2655.  
  2656.  
  2657.  
  2658.  
  2659.  
  2660. OD_ADD_PERSONALITY()
  2661. -------------------------------------------------------------------------------
  2662.  
  2663. PURPOSE        Installs a custom status line / sysop function key personality
  2664.                into OpenDoors.
  2665.  
  2666.  
  2667. FORMAT         int od_add_personality(char *name, char output_top, char
  2668.                output_bottom, void (*function)(unsigned char));
  2669.  
  2670.  
  2671. RETURNS        TRUE on success
  2672.                FALSE on failure
  2673.  
  2674.  
  2675. DESCRIPTION    If used, this function should be called before any other
  2676.                OpenDoors API functions. Installs a new personality into
  2677.                OpenDoors. The first parameter specifies the string that will be
  2678.                used to identify the personality. This is the string that the
  2679.                user will be able to supply in the configuration file to select
  2680.                this personality, and is also the string that can be passed to
  2681.                od_set_personality() to manually switch to this personality. The
  2682.                second and third parameters specify the 1-based to and bottom
  2683.                line numbers of the output window to be used with this
  2684.                personality. For instance, a top value of 1 and bottom value of
  2685.                23 would cause all door output to be displayed on the first 23
  2686.                lines of the screen, leaving the bottom two lines for use by the
  2687.                personality's status line. The last parameter is a pointer to
  2688.                the personality function, which OpenDoors will call to perform
  2689.                various operations with that involve the personality. OpenDoors
  2690.                will pass one of the following values to the personality
  2691.                function, indicating the operation that the function should
  2692.                perform:
  2693.  
  2694.                PEROP_INITIALIZE    Initialize the personality, installing any
  2695.                                    custom function keys.
  2696.                PEROP_DEINITIALIZE  Deinitialize the personality, returning any
  2697.                                    changed settings to their original values.
  2698.                PEROP_CUSTOMKEY     Indicates that a custom function key has
  2699.                                    been pressed.
  2700.                PEROP_DISPLAYx      Where x is a number from 1 to 10. Indicates
  2701.                                    that the specified status line should be
  2702.                                    drawn from scratch.
  2703.                PEROP_UPDATEx       Where x is a number from 1 to 10. Indicates
  2704.                                    that the specified status line should be
  2705.                                    updated to reflect any changes.
  2706.  
  2707.                For more information on personalities and the OpenDoors Multiple
  2708.                Personality System, see the section which begins on page 223.
  2709.  
  2710.  
  2711. ===============================================================================
  2712. OpenDoors 5.00 Manual                                            End of Page 46
  2713.  
  2714.  
  2715. SEE ALSO       od_set_personality(), od_set_statusline()
  2716.  
  2717.  
  2718.  
  2719.  
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770. ===============================================================================
  2771. OpenDoors 5.00 Manual                                            End of Page 47
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778. OD_AUTODETECT()
  2779. -------------------------------------------------------------------------------
  2780.  
  2781. PURPOSE        Attempts to automatically determine the terminal capabilities of
  2782.                the remote system.
  2783.  
  2784.  
  2785. FORMAT         void od_autodetect(int flags);
  2786.  
  2787.  
  2788. RETURNS        N/A
  2789.  
  2790.  
  2791. DESCRIPTION    This function can be used to determine whether or not the remote
  2792.                terminal supports ANSI and/or RIP (Remote Imaging Protocol)
  2793.                graphics modes. This information is usually supplied to the door
  2794.                by the BBS software, through the door information file. For this
  2795.                reason, most door programs do not need to make used of this
  2796.                function. However, if your door will be running under any BBS
  2797.                software that does not report the ANSI or RIP capabilities of
  2798.                the remote system, you may wish to use this function.
  2799.                od_autodetect() will set either of the following OpenDoors
  2800.                control structure variables to TRUE if the corresponding
  2801.                graphics mode is detected:
  2802.  
  2803.                     od_control.user_ansi     - TRUE if ANSI mode is available
  2804.                     od_control.user_rip      - TRUE if RIP mode is available
  2805.  
  2806.                However, if either of these variables have previously been set
  2807.                to TRUE (either explicitly by your program, or due to the
  2808.                corresponding modes being enabled in the door information file),
  2809.                and od_autodetect() does not detect the corresponding graphics
  2810.                mode, they will not be set to FALSE. Not all terminal software
  2811.                that supports ANSI or RIP graphics mode will necessarily have
  2812.                the ability to report their graphics mode capabilities to the
  2813.                door. For this reason, failure to detect either of these modes
  2814.                does not necessarily indicate that they are not available.
  2815.                However, if these modes are detected by od_autodetect(), it is
  2816.                safe to assume that the remote system does support the detected
  2817.                mode.
  2818.  
  2819.                The flags parameter is reserved for future use, and should
  2820.                always be set to DETECT_NORMAL.
  2821.  
  2822.                This function does not support auto-detection of AVATAR mode,
  2823.                because there is no standard means of determining whether a
  2824.                remote system supports AVATAR graphics.
  2825.  
  2826.  
  2827.  
  2828.  
  2829. ===============================================================================
  2830. OpenDoors 5.00 Manual                                            End of Page 48
  2831.  
  2832.  
  2833. EXAMPLE        Below is an example of using od_autodetect() in determining the
  2834.                remote terminal's graphics capabilities. Since not all terminal
  2835.                software supports auto-detection, this example will also prompt
  2836.                the user to determine their software's capabilities if
  2837.                od_autodetect() fails to detect ANSI mode. This code assumes
  2838.                that if the terminal software supports the autodetection of ANSI
  2839.                mode, that it will also support the autodetection of RIP mode.
  2840.                OpenDoors assumes that ANSI mode is always available in
  2841.                conjunction with RIP mode.
  2842.  
  2843.                     /* Call the automatic terminal detection function */
  2844.                     od_autodetect();
  2845.  
  2846.                     /* If ANSI mode was not detected, ask the user about
  2847.                     if(!od_control.user_ansi)
  2848.                        {
  2849.                        /* Prompt the user for ANSI capabilities */
  2850.                        od_clr_scr();
  2851.                        od_printf("Does your system support ANSI graphics?");
  2852.                        od_printf(" (Y/N)");
  2853.  
  2854.                        /* If the user chooses [Y]es */
  2855.                        if(od_get_answer("YN") == 'Y')
  2856.                           {
  2857.                           /* Turn on ANSI mode */
  2858.                           od_control.user_ansi = TRUE;
  2859.  
  2860.                           /* Since ANSI mode is present, RIP mode may also */
  2861.                           /* be available. Prompt the user for RIP. */
  2862.                           od_printf("\r\n\n");
  2863.                           od_printf("Does your system support RIP graphics?");
  2864.                           od_printf(" (Y/N)");
  2865.  
  2866.                           /* If the user chooses [Y]es */
  2867.                           if(od_get_answer("YN") == 'Y')
  2868.                              /* Turn on RIP mode */
  2869.                              od_control.user_rip = TRUE;
  2870.  
  2871.                           /* Since ANSI mode is present, AVATAR mode may  */
  2872.                           /* also be available. Prompt the user for AVATAR. */
  2873.                           od_printf("\r\n\n");
  2874.                           od_printf("Does your system support AVATAR ");
  2875.                           od_printf("graphics? (Y/N)");
  2876.  
  2877.                           /* If the user chooses [Y]es */
  2878.                           if(od_get_answer("YN") == 'Y')
  2879.                              /* Turn on AVATAR mode */
  2880.                              od_control.user_avatar = TRUE;
  2881.                           }
  2882.  
  2883.                        od_printf("\r\n\n");
  2884.                        }
  2885.  
  2886.  
  2887.  
  2888. ===============================================================================
  2889. OpenDoors 5.00 Manual                                            End of Page 49
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896. OD_CHAT()
  2897. -------------------------------------------------------------------------------
  2898.  
  2899. PURPOSE        Manually invokes sysop chat mode.
  2900.  
  2901.  
  2902. FORMAT         void od_chat(void);
  2903.  
  2904.  
  2905. RETURNS        N/A
  2906.  
  2907.  
  2908. DESCRIPTION    Normally, the OpenDoors sysop chat mode will only be invoked
  2909.                when the sysop explicitly requests it using the sysop chat key.
  2910.                However, there may be some cases where you wish to manually
  2911.                invoke the sysop chat mode. One example is when you are
  2912.                replacing the OpenDoors built-in chat mode with your own, but
  2913.                still wish to use the OpenDoors chat mode under some
  2914.                circumstances. For instance, you may wish to use your own split-
  2915.                screen chat routine if ANSI, AVATAR or RIP graphics mode is
  2916.                available, and use the OpenDoors line-oriented chat mode if only
  2917.                ASCII mode is available.
  2918.  
  2919.  
  2920. SEE ALSO       od_page()
  2921.  
  2922.  
  2923. EXAMPLE        For an example of using the od_chat() function, see the
  2924.                ex_chat.c example door, which is described on page 38.
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947. ===============================================================================
  2948. OpenDoors 5.00 Manual                                            End of Page 50
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955. OD_CARRIER()
  2956. -------------------------------------------------------------------------------
  2957.  
  2958. PURPOSE        To determine the status of the carrier detect signal, in
  2959.                programs where OpenDoors' internal carrier detection has been
  2960.                disabled.
  2961.  
  2962.  
  2963. FORMAT         int od_carrier(void);
  2964.  
  2965.  
  2966. RETURNS        TRUE if a carrier is present, or
  2967.                FALSE if no carrier is present, or in local mode.
  2968.  
  2969.  
  2970. DESCRIPTION    Usually, you will not have any use for the od_carrier()
  2971.                function, as OpenDoors automatically monitor's the carrier
  2972.                detect signal, and will correctly recover if the carrier detect
  2973.                signal is lost while the door is operating in remote mode.
  2974.                However, in some programs, you may wish to disable OpenDoors'
  2975.                internal carrier detection routines, using the
  2976.                od_control.od_disable variable. Two such cases in which you
  2977.                might want to do this, are a call-back verification door, which
  2978.                disconnects the user and attempts to call them back, or in a
  2979.                terminal program, which is in fact not a door at all (and as
  2980.                such you would not want to have OpenDoors exit when the carrier
  2981.                detect signal is lost). In cases like these, you will then be
  2982.                able to use the od_carrier() function in order to determine the
  2983.                state of the carrier detect signal.
  2984.  
  2985.                This function will return a Boolean value (for more information
  2986.                on Boolean values, see the Glossary which begins on page 246),
  2987.                of either TRUE or FALSE. If a carrier detect signal is present
  2988.                when the function is called, it will return TRUE, and if no
  2989.                carrier detect signal is detected, it will return FALSE. Since
  2990.                there is no remote connection, and thus no carrier when
  2991.                OpenDoors is operating in local mode, this function will always
  2992.                return a value of FALSE in local mode.
  2993.  
  2994.  
  2995. SEE ALSO       od_set_dtr()
  2996.  
  2997.  
  2998. EXAMPLE        As an example of the use of this function, let us consider a
  2999.                call back verification door, which hangs up on the user, and
  3000.                then calls the user back at their entered phone number, in order
  3001.                to verify the correctness of that number. This program would
  3002.                probably contain a function that is responsible for
  3003.                disconnecting the user, waiting for the connection to be broken,
  3004.                and then phoning the user. At some point in this function,
  3005.  
  3006. ===============================================================================
  3007. OpenDoors 5.00 Manual                                            End of Page 51
  3008.  
  3009.  
  3010.                likely just prior to the point where the function hangs up on
  3011.                the user, you would disable OpenDoors' internal carrier
  3012.                detection, using the line:
  3013.  
  3014.                     od_control.od_disable |= DIS_CARRIERDETECT;
  3015.  
  3016.                You would then want to have a piece of code which would simply
  3017.                wait up to a given amount of time for the carrier signal to
  3018.                drop. If this occurs, you would continue to place the call, and
  3019.                if it does not occur, you would probably try your hangup
  3020.                procedure one or two more times. In this example, the function
  3021.                will return with a value of FALSE if the carrier signal does not
  3022.                drop, and will return a value of TRUE if it does.
  3023.  
  3024.                     char hangup(void)
  3025.                        {
  3026.                        register long timer;
  3027.                        char to_return = FALSE;
  3028.  
  3029.                        od_set_dtr(FALSE);                    /* Hangup modem */
  3030.  
  3031.                                             /* Wait up to 30secs (546 ticks) */
  3032.                        timer=(*(long far *)0x46cL)+546L;
  3033.                        while(timer>=*(long far *))
  3034.                           { /* If carrier has been lost, return with success */
  3035.                           if(!od_carrier())
  3036.                              {
  3037.                              to_return = TRUE;
  3038.                              break;
  3039.                              }
  3040.                           }
  3041.  
  3042.                        od_set_dtr(TRUE);             /* Re-enable DTR signal */
  3043.                        return(to_return);
  3044.                        }
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.  
  3054.  
  3055.  
  3056.  
  3057.  
  3058.  
  3059.  
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065. ===============================================================================
  3066. OpenDoors 5.00 Manual                                            End of Page 52
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073. OD_CLEAR_KEYBUFFER()
  3074. -------------------------------------------------------------------------------
  3075.  
  3076. PURPOSE        Function to clear the input keyboard buffer
  3077.  
  3078.  
  3079. FORMAT         void od_clear_keybuffer(void);
  3080.  
  3081.  
  3082. RETURNS        N/A
  3083.  
  3084.  
  3085. DESCRIPTION    OpenDoors maintains its own keyboard input buffer, in order to
  3086.                permit the user to "type ahead" - to send input to the door
  3087.                prior to the time when it is ready to process those key presses.
  3088.                For example, the user could begin to type a command while a menu
  3089.                is still being displayed, and when your door reaches the point
  3090.                of inputting the menu command, the characters already typed by
  3091.                the user will already be waiting for the OpenDoors input
  3092.                functions. Note that the keyboard input buffer will include both
  3093.                the keys hit by the user on-line, and the non-function keys (ie,
  3094.                Alt-C will not appear in the OpenDoors keyboard buffer), hit by
  3095.                the sysop. This allows both the user on-line and the sysop to
  3096.                control the door at any time. If the sysop wishes to temporarily
  3097.                prevent the user from having any control over the door, the
  3098.                sysop may use the Alt-K (user-keyboard off) key. The key strokes
  3099.                placed in the OpenDoors type-ahead buffer will be retrieved by
  3100.                the od_get_key() and od_input_str() functions. The keyboard
  3101.                buffer can contain a maximum of 64 user keystrokes in this
  3102.                version of OpenDoors, after which any additional keystrokes will
  3103.                simply be discarded by OpenDoors.
  3104.  
  3105.                There are times, however, when you will want to erase any keys
  3106.                that have been hit by the user, to prevent them from typing
  3107.                ahead. For example, if your door has been busy doing some
  3108.                processing for a few moments, they user may have been pressing
  3109.                keys on their keyboard - perhaps in the hope that doing so will
  3110.                speed things up. These keys will be waiting in the type-ahead
  3111.                buffer, and if one of the keys the user entered was a valid
  3112.                response to the next prompt in your door, the user may find that
  3113.                they have accidentally made a choice they did not wish to. A
  3114.                well designed door will simply erase the contents of the type-
  3115.                ahead buffer after any long period of internal processing, etc.
  3116.                Keep in mind that too much use of the od_clear_keybuffer()
  3117.                function can be just as undesirable as not using it all, as
  3118.                there are times when the presence of the keyboard buffer can
  3119.                prove to be very useful for the user of a door.
  3120.  
  3121.  
  3122.  
  3123.  
  3124. ===============================================================================
  3125. OpenDoors 5.00 Manual                                            End of Page 53
  3126.  
  3127.  
  3128.                To erase the contents of the type-ahead buffer, you simply call
  3129.                the od_clear_keybuffer() function. This function takes no
  3130.                parameters, and does not return any value.
  3131.  
  3132.  
  3133.  
  3134. SEE ALSO       od_get_key(), od_input_str(), od_edit_str()
  3135.  
  3136.  
  3137. EXAMPLE        For one example of the use of the od_clear_keybuffer() function,
  3138.                see the example door program EZVote, which is described
  3139.                beginning on page 38. Below is another example of using this
  3140.                function. In this case, we present a simple function,
  3141.                wait_for_return(), which simply pauses for the user to press
  3142.                their [Enter]/[Return] key. The function begins by displaying a
  3143.                prompt asking for the [Enter] or [Return] key to be pressed. The
  3144.                function then clears the keyboard input buffer, and waits until
  3145.                the user presses the carriage return key, using the od_get_key()
  3146.                function. Note also that this function will only continue if the
  3147.                user has pressed the correct key. This is a good idea in all
  3148.                door programs, as it allows your door to distinguish between a
  3149.                character pressed by the user, and a "line noise" character.
  3150.  
  3151.                     void wait_for_return(void)
  3152.                        {                                   /* Display prompt */
  3153.                        od_disp_str("Please Press [Enter] to continue...\n\r");
  3154.                        od_clear_keybuffer();        /* Clear keyboard buffer */
  3155.                        while(od_get_key(TRUE)!=13);    /* Wait for Enter key */
  3156.                        }
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183. ===============================================================================
  3184. OpenDoors 5.00 Manual                                            End of Page 54
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191. OD_CLR_LINE()
  3192. -------------------------------------------------------------------------------
  3193.  
  3194. PURPOSE        Clears the rest of the current display line
  3195.  
  3196.  
  3197. FORMAT         void od_clr_line(void);
  3198.  
  3199.  
  3200. RETURNS        N/A
  3201.  
  3202.  
  3203. DESCRIPTION    This function clears the line that the cursor is on, from the
  3204.                cursor position to the end of the line. After the rest of the
  3205.                line is cleared, the cursor is automatically returned to the
  3206.                position it was at prior to issuing the command. Hence, if the
  3207.                display line the cursor was located on looked as follows, with
  3208.                the underscore (_) character representing the cursor position:
  3209.  
  3210.                         This is a_line of text!
  3211.  
  3212.                With the cursor between the words "a" and "line", after the
  3213.                od_clr_line command is issued, the line would appear as follows:
  3214.  
  3215.                         This is a_
  3216.  
  3217.                With the cursor directly following the word "a". Note that this
  3218.                function places a space character at the cursor location, and
  3219.                every location up to the end of the line.
  3220.  
  3221.                When the door is running in plain ASCII mode, this command will
  3222.                simply clear the rest of the line by manually sending a series
  3223.                of space and backspace characters. When ANSI, AVATAR or RIP
  3224.                modes are active, the corresponding ANSI/AVATAR control sequence
  3225.                will be sent in order to accomplish the line clear. Since the
  3226.                graphics mode sequences are much shorter than the sequence that
  3227.                would be required to clear the line manually, the use of this
  3228.                function will cause your door's graphics to display much more
  3229.                quickly when ANSI, AVATAR or RIP modes are active. Also note
  3230.                that in ANSI, AVATAR or RIP graphics modes, the line will be
  3231.                cleared with the currently selected colour attribute. Thus, if
  3232.                you wanted to place a blue background on a particular line, you
  3233.                would use the od_set_colour() (or od_set_attrib()) function,
  3234.                then use the od_set_cursor() function to locate the cursor at
  3235.                the beginning of the desired line, followed by the od_clr_line()
  3236.                function. Just such a procedure is demonstrated in the example,
  3237.                below.
  3238.  
  3239.  
  3240. SEE ALSO       od_clr_scr(), od_set_cursor()
  3241.  
  3242. ===============================================================================
  3243. OpenDoors 5.00 Manual                                            End of Page 55
  3244.  
  3245.  
  3246.  
  3247.  
  3248. EXAMPLE        Below, is an example of a function that clears an entire line
  3249.                with a specified colour. Since this function performs operations
  3250.                that require ANSI, AVATAR or RIP graphics mode, it should only
  3251.                be used in a case where these modes are known to be available.
  3252.                For example, this function would be useful in a full-screen
  3253.                editor or viewer, or when performing ANSI animations. The
  3254.                function accepts three parameters: the line to be cleared (where
  3255.                1 is the first line, 2 the second, and so on), the foreground
  3256.                colour of this line, and the background colour of this line.
  3257.  
  3258.                This function differs from the od_clr_line() function itself in
  3259.                several important manners. First of all, this function clears
  3260.                the entire line, whereas the od_clr_line() function can be used
  3261.                to clear only the remaining characters of the line, after any
  3262.                particular location. Also, as mentioned before, this function
  3263.                selects a colour to clear the line to, and moves the cursor to
  3264.                the line which is to be cleared - neither of which is done by
  3265.                the od_clr_line() function.
  3266.  
  3267.  
  3268.                void clear_line(char line_number,char foreground,char
  3269.                background)
  3270.                   {
  3271.                   od_set_cursor(line_number,1);      /* move to correct line */
  3272.                   od_set_colour(foreground,background);        /* set colour */
  3273.                   od_clr_line();                        /* clear entire line */
  3274.                   }
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301. ===============================================================================
  3302. OpenDoors 5.00 Manual                                            End of Page 56
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309. OD_CLR_SCR()
  3310. ------------------------------------------------------------------------------
  3311.  
  3312. PURPOSE        The OpenDoors clear screen function
  3313.  
  3314.  
  3315. FORMAT         void od_clr_scr(void);
  3316.  
  3317.  
  3318. RETURNS        N/A
  3319.  
  3320.  
  3321. DESCRIPTION    The od_clr_scr() function can be used to clear the door screen.
  3322.                (ie, the user's screen and local screen with the exception of
  3323.                the status line are cleared.) Also, if your door is running
  3324.                under a system, such as RemoteAccess, Apex or QuickBBS, which
  3325.                produce an EXITINFO.BBS file, this function will detect the
  3326.                user's screen clearing setting, and only clear the screen if
  3327.                screen clearing is turned on. If an EXITINFO.BBS file is not
  3328.                available, this function will always clear the screen (as
  3329.                OpenDoors will not be able to determine whether or not the user
  3330.                has screen clearing enabled). If your door will be running under
  3331.                BBS systems that do not pass the user's screen clearing setting
  3332.                to the door, you may wish to determine yourself whether or not
  3333.                the user's system supports screen clearing codes, during the
  3334.                first time the user uses the door. You will then be able to
  3335.                store this setting in a data file. The example below
  3336.                demonstrates how to detect whether or not the user's system
  3337.                supports screen clearing.
  3338.  
  3339.                You should note that the ability for the user's terminal to
  3340.                support screen clearing codes is independent of the user's ANSI
  3341.                / AVATAR / RIP graphics mode settings.
  3342.  
  3343.                For more information on the user's screen clearing setting,
  3344.                please refer to the user_attrib variable in the OpenDoors
  3345.                Control Structure chapter of this manual. If you wish to force a
  3346.                screen clear, regardless of the user's screen clearing setting,
  3347.                simply use the function call:
  3348.  
  3349.                          od_disp_emu("\xc", TRUE);
  3350.  
  3351.  
  3352. SEE ALSO       od_clr_line()
  3353.  
  3354.  
  3355. EXAMPLE        Below is an example of a function which determines whether or
  3356.                not the user's system supports screen clearing. This function
  3357.                will return a value of TRUE if screen clearing is supported, and
  3358.  
  3359.  
  3360. ===============================================================================
  3361. OpenDoors 5.00 Manual                                            End of Page 57
  3362.  
  3363.  
  3364.                will return a value of FALSE if screen clearing is not
  3365.                supported:
  3366.  
  3367.                int user_supports_screen_clearing(void)
  3368.                   {
  3369.                   char answer;
  3370.                                              /* display instructions to user */
  3371.                   od_disp_str("In order for this door to function\n\r");
  3372.                   od_disp_str("correctly, we must know whether or not\n\r");
  3373.                   od_disp_str("your system supports screen clearing.\n\r");
  3374.                   od_disp_str("In a moment, we will attempt to clear\n\r");
  3375.                   od_disp_str("your screen in order to test your
  3376.                system's\n\r");
  3377.                   od_disp_str("capabilities.\n\r\n\r");
  3378.  
  3379.                   od_disp_str("Please press [Enter]/[Return] when you\n\r");
  3380.                   od_disp_str("are ready to perform this test.\n\r");
  3381.                   while(od_get_key(TRUE)!=13);      /* wait for [Return] key */
  3382.  
  3383.                   od_clr_scr();                   /* attempt to clear screen */
  3384.                                          /* ask user if their screen cleared */
  3385.                   od_disp_str("Did your screen just clear? (Y/N)\n\r");
  3386.                   for(;;)           /* loop until user chooses [Y]es or [N]o */
  3387.                      {
  3388.                      answer=od_get_key(TRUE);           /* Get user's answer */
  3389.                      if(answer=='y' || answer=='Y') return(TRUE);
  3390.                      if(answer=='n' || answer=='N') return(FALSE);
  3391.                      }
  3392.                   }
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419. ===============================================================================
  3420. OpenDoors 5.00 Manual                                            End of Page 58
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427. OD_COLOUR_CONFIG()
  3428. -------------------------------------------------------------------------------
  3429.  
  3430. PURPOSE        Parses a colour configuration line from the configuration file,
  3431.                generating a colour attribute value.
  3432.  
  3433.  
  3434. FORMAT         unsigned char od_colour_config(char *config_line);
  3435.  
  3436.  
  3437. RETURNS        Colour attribute value
  3438.  
  3439.  
  3440. DESCRIPTION    This function will be of use if you are using the configuration
  3441.                file system of OpenDoors, and wish to allow the sysop to specify
  3442.                text colours to be used in your door. While OpenDoors
  3443.                automatically recognizes colour configuration settings for
  3444.                things such as sysop chat mode and FILES.BBS listings, you may
  3445.                wish to add additional colour configuration options. In this
  3446.                case, you could call the od_colour_config() function from your
  3447.                custom line function. For more information on the custom line
  3448.                function, see the section on the OpenDoors configuration file
  3449.                system, which begins on page 215.
  3450.  
  3451.                To use this function, simply pass the configuration file line
  3452.                you wish to have parsed to the function in it's single
  3453.                parameter. The function will then return a colour attribute
  3454.                value in the same format that is used but the od_set_attrib()
  3455.                function. Colours are specified using a string of the format:
  3456.  
  3457.                     {Flashing} {Bright} [foregoround] on [background]
  3458.  
  3459.                Where "Flashing" is an optional keyword indicating that the text
  3460.                should be flashing. "Bright" is an optional keyword indicating
  3461.                that the foreground colour should be bright. Foreground is the
  3462.                name of a foreground colour, and background is the name of a
  3463.                background colour. Case (upper or lower) is not significant.
  3464.  
  3465.                The colour keywords are language configurable, using the array
  3466.                od_control.od_colour_names.
  3467.  
  3468.  
  3469. EXAMPLE        See the example accompanying in the section on the OpenDoors
  3470.                configuration file system, which begins on page 215.
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478. ===============================================================================
  3479. OpenDoors 5.00 Manual                                            End of Page 59
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486. OD_DISP()
  3487. ------------------------------------------------------------------------------
  3488.  
  3489. PURPOSE        Sends a buffer of text with optional local echo
  3490.  
  3491.  
  3492. FORMAT         void od_disp(char *buffer, int size, char local_echo);
  3493.  
  3494.  
  3495. RETURNS        N/A
  3496.  
  3497.  
  3498. DESCRIPTION    This function allows you to send a buffer of text of any
  3499.                specified length, with the option of enabling or disabling local
  3500.                echo. You will probably have little use for this function -
  3501.                instead you will most likely display strings using either the
  3502.                od_disp_str() or od_printf() functions, depending on whether or
  3503.                not you wish to use printf()'s formatting options. For a
  3504.                breakdown of the uses of the various OpenDoors display
  3505.                functions, see the description of the od_disp_str() function, on
  3506.                page 64.
  3507.  
  3508.                There are two cases when this function will come in useful:
  3509.  
  3510.                1.)      If you wish to display a buffer of characters of known
  3511.                         length, which may contain null (ASCII 0) characters.
  3512.                         Since this character is used by the C language to
  3513.                         indicate the end of a string, the other two string
  3514.                         display functions (od_disp_str() and od_printf()) will
  3515.                         not send this character to the remote system.
  3516.  
  3517.                2.)      If you wish to send text to the remote system without
  3518.                         having it displayed on the local screen, or if you wish
  3519.                         to send strings to the modem when it is in command
  3520.                         mode, without having these characters displayed on the
  3521.                         local screen.
  3522.  
  3523.                The od_disp() function is called with three parameters. The
  3524.                first parameter, *buffer, is a pointer to a buffer of characters
  3525.                you wish to have displayed. The second parameter, size, is
  3526.                simply the number of characters in the buffer to be displayed.
  3527.                If the third parameter, local_echo, is set to TRUE, then all
  3528.                characters sent to the modem will also be displayed on the local
  3529.                screen. If the third parameter is set to FALSE, then the buffer
  3530.                will be sent to the modem without being echoed to the sysop's
  3531.                screen.
  3532.  
  3533.  
  3534. SEE ALSO       od_disp_str(), od_printf(), od_putch(), od_repeat(),
  3535.                od_disp_emu()
  3536.  
  3537. ===============================================================================
  3538. OpenDoors 5.00 Manual                                            End of Page 60
  3539.  
  3540.  
  3541.  
  3542.  
  3543. EXAMPLES       The following are a few examples of the use of the od_disp()
  3544.                function:
  3545.  
  3546.                In order to display a single character, contained in the
  3547.                variable "character", without echo to the local screen:
  3548.  
  3549.                     od_disp(&character,1,FALSE);
  3550.  
  3551.  
  3552.                In order to send a command to the modem (only if you know that
  3553.                the modem is in command mode), with the command contained in the
  3554.                null-terminated string "string":
  3555.  
  3556.                     od_disp(string,strlen(string),FALSE);
  3557.  
  3558.  
  3559.                In order to send exactly 5 characters from the buffer "buffer",
  3560.                WITH echo to the local screen:
  3561.  
  3562.                     od_disp(buffer,5,TRUE);
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596. ===============================================================================
  3597. OpenDoors 5.00 Manual                                            End of Page 61
  3598.  
  3599.  
  3600.  
  3601.  
  3602.  
  3603.  
  3604. OD_DISP_EMU()
  3605. -------------------------------------------------------------------------------
  3606.  
  3607. PURPOSE        Displays a string with ANSI/AVATAR terminal emulation
  3608.  
  3609.  
  3610. FORMAT         void od_disp_emu(char *string, char remote_echo);
  3611.  
  3612.  
  3613. RETURNS        N/A
  3614.  
  3615.  
  3616. DESCRIPTION    The od_disp_emu() function allows you to display your own ANSI /
  3617.                AVATAR graphics sequences. This function passes the characters
  3618.                you wish to display to the OpenDoors terminal emulator, which is
  3619.                fully documented in the description of the od_send_file()
  3620.                function, on page 121. As a result, this function can be used to
  3621.                send these control sequences to the user's terminal, and also
  3622.                have them displayed on the local screen as they will appear to
  3623.                the user.
  3624.  
  3625.                The string passed to od_disp_emu() contains any stream of text
  3626.                to display, and may include both normal text and terminal
  3627.                emulation control sequences. The OpenDoors terminal emulator
  3628.                stores its current state between calls to od_disp_emu(), and so
  3629.                control sequences my be broken between calls to od_disp_emu. In
  3630.                other words, the call:
  3631.  
  3632.                     od_disp_emu("\x1b[1C", TRUE);
  3633.  
  3634.                is equivalent to:
  3635.  
  3636.                     od_disp_emu("\x1b[", TRUE);
  3637.                     od_disp_emu("1C", TRUE);
  3638.  
  3639.                If the remote_echo parameter is set to TRUE, the string passed
  3640.                to od_disp_emu() will be sent to the remote terminal in addition
  3641.                to being displayed locally. If this parameter is set to FALSE,
  3642.                the string will only be displayed locally.
  3643.  
  3644.                Note that if you wish to display an entire file containing
  3645.                ANSI/AVATAR/RIP graphics sequences (perhaps as your program's
  3646.                menu or title screen), you can use the od_send_file() function.
  3647.  
  3648.  
  3649. SEE ALSO       od_send_file(), od_disp(), od_disp_str() od_printf(),
  3650.                od_putch(), od_repeat().
  3651.  
  3652.                For a breakdown of the uses of the various OpenDoors display
  3653.                functions, see the od_disp_str() function, on page 64.
  3654.  
  3655. ===============================================================================
  3656. OpenDoors 5.00 Manual                                            End of Page 62
  3657.  
  3658.  
  3659.  
  3660.  
  3661. EXAMPLE        For an example of the use of the od_disp_emu() function, see the
  3662.                SpaceRight() and MoveLeft() functions included in the example
  3663.                program ex_ski.c. These functions use the ANSI move cursor left
  3664.                and move cursor right functions to move the cursor relative to
  3665.                the current position, without knowing what the current cursor
  3666.                position is.
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714. ===============================================================================
  3715. OpenDoors 5.00 Manual                                            End of Page 63
  3716.  
  3717.  
  3718.  
  3719.  
  3720.  
  3721.  
  3722. OD_DISP_STR()
  3723. -------------------------------------------------------------------------------
  3724.  
  3725. PURPOSE        Displays a string to the screen (remote and local)
  3726.  
  3727.  
  3728. FORMAT         void od_disp_str(char *string);
  3729.  
  3730.  
  3731. RETURNS        N/A
  3732.  
  3733.  
  3734. DESCRIPTION    The two functions most often used for displaying strings within
  3735.                a door are the od_disp_str() and od_printf() functions. The
  3736.                od_printf() function allows for formatted output, whereas the
  3737.                od_disp_str function simply displays the actual contents of the
  3738.                string passed to it. If you wish to display a single character,
  3739.                use the od_putch() function. If you wish to send a string or
  3740.                buffer to the modem without local echo, use the od_disp()
  3741.                function. If you wish to send a sequence of the same character
  3742.                to the modem, the od_repeat() function will use graphics control
  3743.                codes, if available to display the sequence much faster than
  3744.                simply sending the same character in repetition. Also, if you
  3745.                wish to send ANSI, AVATAR or RIP graphics control codes, and
  3746.                have them emulated on the local screen, use the od_disp_emu()
  3747.                function.
  3748.  
  3749.                The od_disp_str() function displays the contents of the null-
  3750.                terminated string pointed to by *string. Display is sent to both
  3751.                the local screen and modem (presuming the door is not running in
  3752.                local mode).
  3753.  
  3754.                An important thing to keep in mind when using the od_disp_str()
  3755.                function, is that you should use "/n/r" instead of simply "/n"
  3756.                for a new line. This is due to the fact that terminal programs
  3757.                usually require a carriage-return line-feed sequence (/n/r),
  3758.                instead of just a line-feed (/n). For example, instead of using:
  3759.  
  3760.                               od_disp_str("Hello world!\n");
  3761.  
  3762.                You should use:
  3763.  
  3764.                               od_disp_str("Hello world!\n\r");
  3765.  
  3766.                To change the cursor colour or location of output with the
  3767.                od_disp_str() function, refer to the od_set_cursor() and the
  3768.                od_set_attrib() functions.
  3769.  
  3770.  
  3771. SEE ALSO       od_disp(), od_printf(), od_putch(), od_repeat(), od_disp_emu()
  3772.  
  3773. ===============================================================================
  3774. OpenDoors 5.00 Manual                                            End of Page 64
  3775.  
  3776.  
  3777.  
  3778.  
  3779. EXAMPLES       Below are a few examples of various uses of the od_disp_str()
  3780.                function:
  3781.  
  3782.                Displaying three string constants on separate lines:
  3783.  
  3784.                          od_disp_str("This is an example\n\r");
  3785.                          od_disp_str("of the OpenDoors\n\r");
  3786.                          od_disp_str("od_disp_str() function\n\r");
  3787.  
  3788.  
  3789.                Displaying three string constants on the same line:
  3790.  
  3791.                          od_disp_str("Another ");
  3792.                          od_disp_str("od_disp_str() ");
  3793.                          od_disp_str("example\n\r");
  3794.  
  3795.  
  3796.                Displaying a string variable:
  3797.  
  3798.                          char string[80];
  3799.  
  3800.                          strcpy(string,"This is a string!\n\r");
  3801.                          od_disp_str(string);
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832. ===============================================================================
  3833. OpenDoors 5.00 Manual                                            End of Page 65
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.  
  3840. OD_DRAW_BOX()
  3841. -------------------------------------------------------------------------------
  3842.  
  3843. PURPOSE        Draws a window on the screen in ANSI, AVATAR or RIP graphics
  3844.                modes.
  3845.  
  3846.  
  3847. FORMAT         int od_draw_box(char left, char top, char right, char bottom);
  3848.  
  3849.  
  3850. RETURNS        TRUE on success, FALSE on failure
  3851.  
  3852.  
  3853. DESCRIPTION    This function is for use in ANSI, AVATAR or RIP graphics modes.
  3854.                This function will draw a window in the current display
  3855.                attribute, at the specified location on the screen. The boarder
  3856.                of the window is made up of the characters specified in the
  3857.                od_control. od_box_chars[] array. If AVATAR graphics mode is
  3858.                available, this function uses AVATAR control codes to display
  3859.                the window in less than 1/10 the length of time required to
  3860.                display the window in ANSI mode.
  3861.  
  3862.                The first two parameters of this function, "left" and "top",
  3863.                specify the coordinates of the top, left-hand corner of the
  3864.                window to be draw. The third and fourth parameters, "right" and
  3865.                "bottom", specify the coordinates of the bottom, left-hand
  3866.                corner of the window. Like the values passed to the
  3867.                od_set_cursor() function, these coordinates are relative to the
  3868.                upper left-hand corner of the screen, with the position (1,1)
  3869.                being this corner.
  3870.  
  3871.                As mentioned above, this function will display the window in the
  3872.                current text colour. Thus, before calling this function, you
  3873.                should use either the od_set_colour() or the od_set_attrib()
  3874.                function to specify the colour in which you would like to have
  3875.                the window displayed.
  3876.  
  3877.                Normally, the boarder of the window will be displayed using the
  3878.                IBM extended ASCII characters which produce a single line
  3879.                boarder. However, you may wish to have the boarder displayed
  3880.                using different characters. In this case, the characters used to
  3881.                display the boarder can be specified by the od_control.
  3882.                od_box_chars variable, described in the OpenDoors control
  3883.                structure section of this manual.
  3884.  
  3885. SEE ALSO       od_set_colour(), od_set_attrib(), od_clr_scr(), od_edit_str(),
  3886.                od_set_cursor()
  3887.  
  3888.  
  3889.  
  3890.  
  3891. ===============================================================================
  3892. OpenDoors 5.00 Manual                                            End of Page 66
  3893.  
  3894.  
  3895. EXAMPLE        As an example of the use of the od_draw_box() function in
  3896.                conjunction with the od_edit_str() function, we show a portion
  3897.                of a program which displays a window, and allows the user to
  3898.                input the name of a file they would like to upload, a
  3899.                description of the file, and whether they want it to be a
  3900.                private upload. The user is able to move among fields using the
  3901.                tab key, and select a "continue" button when they are finished.
  3902.                The function returns TRUE if the user selects continue, and
  3903.                FALSE if the user presses [ESCape].
  3904.  
  3905.                                                   // Main "dialog box" function
  3906.                int get_information(char *filename, char *description,
  3907.                                     char *private)
  3908.                   {
  3909.                   char current_field=1;             // Currently selected field
  3910.                   int choice;                                  // User's choice
  3911.  
  3912.                   od_set_colour(L_WHITE,D_BLUE);              // Display window
  3913.                   od_draw_box(10,5,70,13);
  3914.  
  3915.                   od_set_cursor(5,25);                  // Display window title
  3916.                   od_set_colour(L_GREEN,D_BLUE);
  3917.                   od_disp_str(" ENTER FILENAME INFORMATION ");
  3918.  
  3919.                   od_set_colour(L_CYAN,D_BLUE);    // Display fields and titles
  3920.                   od_set_cursor(6,15);
  3921.                   od_disp_str("FILENAME : ");
  3922.                   od_repeat(176,13);
  3923.                   od_set_cursor(7,12);
  3924.                   od_disp_str("DESCRIPTION : ");
  3925.                   od_repeat(176,43);
  3926.                   od_set_cursor(8,16);
  3927.                   od_disp_str("PRIVATE : ");
  3928.                   od_repeat(176,2);
  3929.                   draw_button();
  3930.  
  3931.                   filename[0]='\0';    // Blank out contents of input variables
  3932.                   description[0]='\0';
  3933.                   private[0]='\0';
  3934.  
  3935.                   for(;;)                               // Main dialog box loop
  3936.                      {
  3937.                      if(current_field==4)             // If field is the button
  3938.                         {
  3939.                         od_set_colour(L_GREEN,D_BLUE);      // Highlight button
  3940.                         draw_button();
  3941.  
  3942.                         do  // Loop until user presses [TAB], [ENTER], or [ESC]
  3943.                            {
  3944.                            choice=od_get_key(TRUE);
  3945.                            } while(choice!=9 && choice!=13 && choice!=27);
  3946.  
  3947.                         od_set_colour(L_CYAN,D_BLUE);    // Un-highlight button
  3948.                         draw_button();
  3949.  
  3950. ===============================================================================
  3951. OpenDoors 5.00 Manual                                            End of Page 67
  3952.  
  3953.  
  3954.  
  3955.                         if(choice==13) return(TRUE);  // If [ENTER] was pressed
  3956.                         if(choice==27) return(FALSE);   // If [ESC] was pressed
  3957.                         current_field=1;        // Otherwise, [TAB] was pressed
  3958.                         }
  3959.  
  3960.                     switch(current_field)        // According to selected field
  3961.                         {                    // Input from the appropriate line
  3962.                         case 1:
  3963.                            choice=od_edit_str(filename,"FFFFFFFFFFFF",6,26,
  3964.                                               0x1b,0x1a,176,
  3965.                                               EDIT_FLAG_EDIT_STRING|
  3966.                                               EDIT_FLAG_ALLOW_CANCEL|
  3967.                                               EDIT_FLAG_FIELD_MODE|
  3968.                                               EDIT_FLAG_KEEP_BLANK);
  3969.                            break;
  3970.                         case 2:
  3971.                            choice=od_edit_str(description,
  3972.                                               "*******************",
  3973.                                               7,26,0x1b,0x1a,176,
  3974.                                               EDIT_FLAG_EDIT_STRING|
  3975.                                               EDIT_FLAG_ALLOW_CANCEL|
  3976.                                               EDIT_FLAG_FIELD_MODE|
  3977.                                               EDIT_FLAG_KEEP_BLANK);
  3978.  
  3979.                            break;
  3980.                         case 3:
  3981.                            choice=od_edit_str(private,"Y",8,26,
  3982.                                               0x1b,0x1a,176,
  3983.                                               EDIT_FLAG_EDIT_STRING|
  3984.                                               EDIT_FLAG_ALLOW_CANCEL|
  3985.                                               EDIT_FLAG_FIELD_MODE);
  3986.                         }
  3987.                                                     // If user pressed [ESCape]
  3988.                      if(choice==EDIT_RETURN_CANCEL) return(FALSE);
  3989.                                       // If user choice to go to previous field
  3990.                      if(choice==EDIT_RETURN_PREVIOUS)
  3991.                         {
  3992.                         if(current_field==1)               // If at first field
  3993.                            {
  3994.                            current_field=4;                 // Go to last field
  3995.                            }
  3996.                         else                           // If not at first field
  3997.                            {
  3998.                            --current_field;             // Go to previous field
  3999.                            }
  4000.                         }
  4001.                      else                           // If user chose next field
  4002.                         {
  4003.                         ++current_field;                    // Go to next field
  4004.                         }
  4005.                      }
  4006.                   }
  4007.  
  4008.  
  4009. ===============================================================================
  4010. OpenDoors 5.00 Manual                                            End of Page 68
  4011.  
  4012.  
  4013.                void draw_button(void)         // Function to display the button
  4014.                   {
  4015.                   od_draw_box(12,10,23,12);              // Draw box for button
  4016.                   od_set_cursor(11,14);
  4017.                   od_disp_str("Continue");            // Display text in button
  4018.                   }
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.  
  4038.  
  4039.  
  4040.  
  4041.  
  4042.  
  4043.  
  4044.  
  4045.  
  4046.  
  4047.  
  4048.  
  4049.  
  4050.  
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.  
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068. ===============================================================================
  4069. OpenDoors 5.00 Manual                                            End of Page 69
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076. OD_EDIT_STR()
  4077. -------------------------------------------------------------------------------
  4078.  
  4079. PURPOSE        Allows you to perform formatted input with full line editing
  4080.                features, etc., in ANSI/AVATAR/RIP graphics mode.
  4081.  
  4082.  
  4083. FORMAT         unsigned int od_edit_str(char *input_string, char
  4084.                *format_string, int row, int col, unsigned char normal_colour,
  4085.                unsigned char highlight_colour, char character, unsigned int
  4086.                flags);
  4087.  
  4088.  
  4089. RETURNS        This function will return one of the following values. Note that
  4090.                some of these values will only be applicable in certain cases.
  4091.                For example, EDIT_RETURN_CANCEL will never be returned if you
  4092.                have not enabled the cancel feature of this function.
  4093.  
  4094.                EDIT_RETURN_ERROR        Indicates that an error has occurred,
  4095.                                         and the edit function was unable to
  4096.                                         run. This will occur if there is an
  4097.                                         error in one of the parameters, or if
  4098.                                         ANSI/AVATAR/RIP graphics is not
  4099.                                         available
  4100.  
  4101.                EDIT_RETURN_CANCEL       Indicates that the user pressed the
  4102.                                         cancel key [ESC], and that the string
  4103.                                         was left unaltered.
  4104.  
  4105.                EDIT_RETURN_ACCEPT       Indicates that the user pressed the
  4106.                                         accept key [Enter], or that the auto-
  4107.                                         enter feature was activated.
  4108.  
  4109.                EDIT_RETURN_PREVIOUS     Indicates that the user wishes to move
  4110.                                         to the previous field, by pressing [UP
  4111.                                         ARROW], [SHIFT]-[TAB], etc.
  4112.  
  4113.                EDIT_RETURN_NEXT         Indicates that the user wishes to move
  4114.                                         to the next field, by pressing [DOWN
  4115.                                         ARROW], [TAB], etc.
  4116.  
  4117.  
  4118. DESCRIPTION    To perform string input within OpenDoors, one of two functions
  4119.                can be used, od_input_str() and od_edit_str(). The first
  4120.                function, od_input_str(), allows simple line input and editing,
  4121.                and can be used in ASCII, ANSI, AVATAR and RIP modes. The second
  4122.                function, od_edit_str(), allows many formatted input options,
  4123.                advanced line editing, and other features, but requires the use
  4124.                of ANSI, AVATAR or RIP graphics modes.
  4125.  
  4126.  
  4127. ===============================================================================
  4128. OpenDoors 5.00 Manual                                            End of Page 70
  4129.  
  4130.  
  4131.                The od_edit_str() function provides a great deal of features and
  4132.                functionality, and as such, may appear to be one of the most
  4133.                complicated OpenDoors functions. The simple fact that the
  4134.                function accepts eight parameters may make the od_edit_str()
  4135.                function seem daunting. However, you need not concern yourself
  4136.                with all of the features available from the od_edit_str()
  4137.                function in order to make use of it. Reading through this
  4138.                section should give you some idea of what is possible with the
  4139.                od_edit_str() function, and the following examples should help
  4140.                to demonstrate the use of this function.
  4141.  
  4142.                The first thing to remember about the od_edit_str() function is
  4143.                that it requires ANSI/AVATAR/RIP graphics, as the graphics
  4144.                control codes are needed for the advanced editing capabilities
  4145.                provided by the od_edit_str() function. Thus, you will only want
  4146.                to use the od_edit_str() in one of two cases; either in a door
  4147.                which requires ANSI/AVATAR/RIP graphics to operate, or in the
  4148.                case that you program tests for the availability of
  4149.                ANSI/AVATAR/RIP graphics, and only calls od_edit_str() if
  4150.                graphics is available. If ANSI/AVATAR/RIP graphics is not
  4151.                available, your program should use the od_input_str() function
  4152.                instead.
  4153.  
  4154.                As mentioned above, the od_edit_str() function allows for
  4155.                advanced line editing, such as inputting and deleting text from
  4156.                the middle of the string (whereas the od_input_str() function
  4157.                only allows editing from the end of the string, such as
  4158.                backspacing to erase a mistake). The edit functions available
  4159.                from the od_edit_str() are listed below. Note that some of these
  4160.                functions may or may not be available, depending upon the
  4161.                capabilities of the user's terminal program. While there is no
  4162.                single standard used for the transmission of special edit keys
  4163.                such as the arrow keys, the od_edit_str() function makes as much
  4164.                effort as possible to make all of the edit features available to
  4165.                most terminal programs. Many of the edit functions can be
  4166.                accesses using either [CONTROL]-key combinations or special keys
  4167.                such as the arrow keys, delete key, and so on. OpenDoors will
  4168.                recognize most of these special control keys when sent as either
  4169.                an ANSI control sequence (which is sent by most terminal
  4170.                programs), or as a DoorWay style scan code / ASCII code sequence
  4171.                (which is also available from many terminal programs, but is not
  4172.                usually required). The od_edit_str() edit functions are as
  4173.                follows. Note that all edit functions are always available from
  4174.                the local keyboard.
  4175.  
  4176.                HOME - Moves the cursor to the beginning of the line being
  4177.                          edited. Press the [HOME] key, either in DoorWay mode
  4178.                          or from the local keyboard.
  4179.  
  4180.                END - Moves the cursor to the end of the line being edited.
  4181.                          Press the [END] key, either in DoorWay mode or from
  4182.                          the local keyboard.
  4183.  
  4184.  
  4185.  
  4186. ===============================================================================
  4187. OpenDoors 5.00 Manual                                            End of Page 71
  4188.  
  4189.  
  4190.                DELETE CHARACTER - Deletes the character under the cursor. Press
  4191.                          [DELete] on the local keyboard, in DoorWay mode, and
  4192.                          under many terminal programs without DoorWay mode.
  4193.                          Alternatively, press [CONTROL]-[G].
  4194.  
  4195.                BACKSPACE - Deletes the character left of the cursor. Press
  4196.                          [BACKSPACE] or [CONTROL]-[H].
  4197.  
  4198.                TOGGLE INSERT MODE - Switches the od_edit_str() function between
  4199.                          insert mode and overwrite mode. Press [INSert], either
  4200.                          in DoorWay mode, or from the local keyboard.
  4201.                          Alternatively, press [CONTROL]-[V].
  4202.  
  4203.                CURSOR LEFT - Moves the cursor left one character. Press [LEFT
  4204.                          ARROW] on the local keyboard, in DoorWay mode, and
  4205.                          under many terminal programs without DoorWay mode.
  4206.                          Alternatively, press [CONTROL]-[S].
  4207.  
  4208.                CURSOR RIGHT - Moves the cursor right one character. Press
  4209.                          [RIGHT ARROW] on the local keyboard, in DoorWay mode,
  4210.                          and under many terminal programs without DoorWay mode.
  4211.                          Alternatively, press [CONTROL]-[D].
  4212.  
  4213.                ERASE ENTIRE LINE - Press [CONTROL]-[Y].
  4214.  
  4215.                ACCEPT INPUT - Press the [ENTER] / [RETURN] line to accept the
  4216.                          input. Alternatively, press [CONTROL]-[Z]. Note that
  4217.                          this key will only work when the current input is
  4218.                          "valid" (ie, it conforms to the format string, which
  4219.                          is described below)
  4220.  
  4221.                CANCEL INPUT - Only available if specifically enabled on the
  4222.                          od_edit_str() command line. Press [ESCape].
  4223.  
  4224.                NEXT FIELD - If enabled, allows the user to move to the next
  4225.                          field in a dialog box / form. Press [DOWN ARROW] in
  4226.                          DoorWay mode and under many terminal programs without
  4227.                          DoorWay mode. Alternatively, press [TAB]. Note that
  4228.                          the [DOWN ARROW] key is NOT usually available from the
  4229.                          local keyboard, as it is usually used to adjust the
  4230.                          user's remaining time.
  4231.  
  4232.                PREVIOUS FIELD - If enabled, allows the user to move to the
  4233.                          previous field in a dialog box / form. Press [UP
  4234.                          ARROW] in DoorWay mode and under many terminal
  4235.                          programs without DoorWay mode. Alternatively, press
  4236.                          [SHIFT]-[TAB] on the local keyboard or in DoorWay
  4237.                          mode. Again, note that the [UP ARROW] key is NOT
  4238.                          usually available from the local keyboard, as it is
  4239.                          usually used to adjust the user's remaining time.
  4240.  
  4241.  
  4242.                Let us now look at the parameters which the od_edit_str()
  4243.                function accepts. The first parameter, input_string, is a
  4244.  
  4245. ===============================================================================
  4246. OpenDoors 5.00 Manual                                            End of Page 72
  4247.  
  4248.  
  4249.                pointer to the string where the user's input should be stored.
  4250.                It is important that this string be long enough to accommodate
  4251.                the longest input your format string will permit, including the
  4252.                '\0' C string terminator (ie, the string should be one character
  4253.                greater than the length of the format string, not including the
  4254.                format string's ' and " characters).
  4255.  
  4256.                The second parameter, format_string, is a pointer to a string
  4257.                which specifies the format and maximum length of the input the
  4258.                od_edit_str() function should accept. Using the format string,
  4259.                not only do you specify the length of the input field, but you
  4260.                can also force the user's input into certain formats. For
  4261.                example, if you wished to input a North American style phone
  4262.                number, you could use a format string of "###-###-####". Then
  4263.                regardless of whether the user typed any dash character or not,
  4264.                their input would be converted, as they type, to the format of
  4265.                the phone number 613-526-4466. You could also specify a format
  4266.                string such of "MMMMMMMMMMMMMMMMMMMMMMMMMMMMMM", which would
  4267.                permit the user to enter a name of up to 30 characters. Note
  4268.                that since the cursor can be moved to the position immediately
  4269.                following the last character, a the input field for a 30
  4270.                character string will occupy 31 columns on the screen. The
  4271.                od_edit_str() function would then automatically capitalize the
  4272.                name, so that the first character of each word is capitalized,
  4273.                and the remain characters of the word is in lower case. Even if
  4274.                the user were to move the cursor to the middle of the string
  4275.                they had entered, and add or delete a space (and thus either
  4276.                make one work two or two words one), od_edit_str() would re-
  4277.                format the string to reflect the change. The valid characters
  4278.                for the format sting, along with their meanings, are listed
  4279.                below. Note that the format string is NOT case sensitive (except
  4280.                for literal strings delimited by the '' or "" characters), and
  4281.                space characters can be added at any point to increase
  4282.                legibility.
  4283.  
  4284.                #    Indicates that numeric characters from '0' to '9' are valid
  4285.                     for this position
  4286.  
  4287.                %    Indicates that numeric characters from '0' to '9', and the
  4288.                     space character (' ') are valid for this position.
  4289.  
  4290.                9    Indicates that numeric characters from '0' to '9', along
  4291.                     with '.', '-' and '+' are valid for this position. This
  4292.                     format style is intended for floating-point numeric input.
  4293.  
  4294.                ?    Indicates that any character is valid for this position.
  4295.  
  4296.                *    Indicates that any printable character, from ASCII 32 to
  4297.                     ASCII 127, is valid for this position.
  4298.  
  4299.                A    Indicates that alphabetical characters 'A' to 'Z', 'a' to
  4300.                     'z' and space (' ') are valid for this position.
  4301.  
  4302.  
  4303.  
  4304. ===============================================================================
  4305. OpenDoors 5.00 Manual                                            End of Page 73
  4306.  
  4307.  
  4308.                C    Indicates that city name characters are valid for this
  4309.                     position. As with the 'M' format character, words are
  4310.                     automatically capitalized so that the first letter is in
  4311.                     upper case, and all subsequent letters are in lower case.
  4312.                     In addition to permitting alphabetical characters and the
  4313.                     space (' ') character, the ',' and '.' characters are also
  4314.                     accepted in this position.
  4315.  
  4316.                D    Indicates that date characters '0' to '9', '-' and '/' are
  4317.                     valid for this position.
  4318.  
  4319.                F    Indicates that MS-DOS filename characters are valid for
  4320.                     this position.
  4321.  
  4322.                H    Indicates that hexidecimal character '0' to '9', 'A' to 'F'
  4323.                     and 'a' to 'f' are valid for this position.
  4324.  
  4325.                L    Indicates that only lower case alphabetical characters 'a'
  4326.                     to 'z', and the space (' ') character is valid for this
  4327.                     position. However, if the user attempts to enter an upper
  4328.                     case alphabetical character in this position, it will
  4329.                     automatically be converted to the lower case equivalent.
  4330.  
  4331.                M    Indicates that name characters are valid for this position.
  4332.                     These characters are the alphabetical characters 'A' to
  4333.                     'Z', 'a' to 'z', and the space character (' '). A
  4334.                     character's case is converted such that the first character
  4335.                     of a word is in upper case, and all other letters are in
  4336.                     lower case.
  4337.  
  4338.                T    Indicates that telephone number character '0' to '9', '(',
  4339.                     ')', '-' and ' ' are valid for this position.
  4340.  
  4341.                U    Indicates that only upper case alphabetical characters 'A'
  4342.                     to 'Z', and the space (' ') character is valid for this
  4343.                     position. However, if the user attempts to enter a lower
  4344.                     case alphabetical character in this position, it will
  4345.                     automatically be converted to the upper case equivalent.
  4346.  
  4347.                W    Indicates that MS-DOS filename characters are permitted in
  4348.                     this position, including the '*' and '?' wildcard
  4349.                     characters.
  4350.  
  4351.                X    Indicates that alphanumeric characters 'A' to 'Z', 'a' to
  4352.                     'z', '0' to '9' and ' ' are valid for this position.
  4353.  
  4354.                Y    Indicates that yes/no characters 'Y', 'N', 'y', 'n' are
  4355.                     valid for this position. The characters are automatically
  4356.                     converted to upper case.
  4357.  
  4358.                '/"  Single or double quotes can be used to specify sequences of
  4359.                     characters that should appear at the same location in the
  4360.                     input string (referred to elsewhere as "literal strings").
  4361.                     When the user is entering the string, these characters are
  4362.  
  4363. ===============================================================================
  4364. OpenDoors 5.00 Manual                                            End of Page 74
  4365.  
  4366.  
  4367.                     automatically supplied, and the user is not required to
  4368.                     type them. Literal strings must begin and end with the same
  4369.                     quote character. Remember that the double quote (")
  4370.                     character must be imbedded in C strings by preceding the
  4371.                     quote character with a \ (backslash) character.
  4372.  
  4373.                The third and fourth parameters, row and col specify the
  4374.                location on the screen where the first (left most) character of
  4375.                the input field should be located. These parameters are
  4376.                identical to the row and col parameters passed to the
  4377.                od_set_cursor() function. In other words, row specifies the line
  4378.                number on the screen, where 1 is the first line, and col
  4379.                specifies the column across the screen, where 1 is the first
  4380.                column.
  4381.  
  4382.                The fifth and sixth parameters, normal_colour and
  4383.                highlight_colour, allow you to specify the colour of the input
  4384.                field. The fifth parameter, normal_colour, specifies the colour
  4385.                of the input field when input is not taking place and the sixth
  4386.                parameter, highlight_colour, specifies the colour of the field
  4387.                while input is taking place. Thus, if you had several input
  4388.                fields on the screen at one time, you would be able to make is
  4389.                easier for the user to identify the currently active field by
  4390.                having the field currently accepting input highlighted in a
  4391.                colour distinct from the other fields. When the od_edit_str()
  4392.                function begins, it will change the current colour of the field
  4393.                from the normal colour to the highlighted colour. Then, when the
  4394.                od_edit_str() function exits, it will change the current colour
  4395.                of the field back to its normal colour. If you do not wish to
  4396.                have the field highlighted, you can set both of these parameters
  4397.                to the same value, and disable field re-drawing by using the
  4398.                eighth parameter, flags.
  4399.  
  4400.                The seventh parameter accepted by the od_edit_str() function,
  4401.                character, will serve one of two purposes. Normally, this
  4402.                parameter will specify a background character to display in the
  4403.                unfilled portion at the end of the input field. This can be set
  4404.                to a character, such as the ASCII 177 grey block character, to
  4405.                produce a visual background to the field. Doing this will show
  4406.                the user visually how long the field is, and how many character
  4407.                they will be permitted to type into the field. Normally, this
  4408.                field will be displayed during input, and removed when the
  4409.                od_edit_str() function exits. However, you may cause the
  4410.                background to remain in place using the eighth parameter, flags.
  4411.                If you do not wish to have this "background" visual field
  4412.                effect, simply set the character parameter to a space (ASCII
  4413.                32). In password input mode, this parameter will instead specify
  4414.                the character to display in place of characters typed by the
  4415.                user. In this case, the background display character defaults to
  4416.                the space (ASCII 32) character.
  4417.  
  4418.                The eighth, and last, parameter accepted by the od_edit_str()
  4419.                function is the flags parameter. This parameter is a bit-mapped
  4420.                flags variable which allows you to control special features of
  4421.  
  4422. ===============================================================================
  4423. OpenDoors 5.00 Manual                                            End of Page 75
  4424.  
  4425.  
  4426.                the od_edit_str() function. More than one of these settings may
  4427.                be specified by listing a chain of the values, separated by the
  4428.                bitwise-or (|) operator. If you do not wish to turn on any of
  4429.                these modes, simply pass the EDIT_FLAG_NORMAL value as the flags
  4430.                parameter.
  4431.  
  4432.                EDIT_FLAG_NORMAL - Default setting, use this value of none of
  4433.                          the other flags below are active.
  4434.  
  4435.                EDIT_FLAG_NO_REDRAW - When set, prevents the od_edit_str()
  4436.                          function from re-drawing the input string and field
  4437.                          when it starts up and exits. If you set this flag, the
  4438.                          normal_colour and highlight colour should contain the
  4439.                          same value. If background character (the character
  4440.                          parameter) is not a space (ASCII 32) character, you
  4441.                          must draw the field background prior to calling
  4442.                          od_edit_str(). Also, if you are calling od_edit_str()
  4443.                          with the EDIT_FLAG_EDIT_STRING flag set, you must
  4444.                          display the existing string in the field prior to
  4445.                          calling od_edit_str().
  4446.  
  4447.                EDIT_FLAG_FIELD_MODE - Setting this flag specifies that
  4448.                          od_edit_str() should operate in field input mode. In
  4449.                          field input mode, the user may finish entering their
  4450.                          input by pressing the previous field or next field
  4451.                          button (arrow keys, tab keys, etc.), as described
  4452.                          above. If the user chooses to finish and accept their
  4453.                          input by pressing one of these keys, the od_edit_str()
  4454.                          return value will reflect which choice they made. This
  4455.                          will allow you to make it possible for the user to
  4456.                          move between a number of input fields in a form /
  4457.                          dialog box, as demonstrated in the example
  4458.                          accompanying the od_draw_box() function.
  4459.  
  4460.                EDIT_FLAG_EDIT_STRING - Setting this flag specifies that
  4461.                          od_edit_str() should edit a pre-existing string,
  4462.                          instead of starting with a blank string. In this case,
  4463.                          the input_string parameter MUST point to an
  4464.                          initialized string. This string may either contain
  4465.                          some text, or be empty, but od_edit_str() will expect
  4466.                          to find a string terminator ('\0') character, and will
  4467.                          begin editing the contents of the string prior to that
  4468.                          character. If you do not set the EDIT_FLAG_EDIT_STRING
  4469.                          flag, the previous contents of the input_string
  4470.                          parameter is not significant, as od_edit_str() will
  4471.                          automatically start with a blank string.
  4472.  
  4473.                EDIT_FLAG_STRICT_INPUT - Setting this flag causes the
  4474.                          od_edit_str() function to operate in "strict" input
  4475.                          mode, which may be desirable if your input format
  4476.                          contains more than one type of input. Normally, if you
  4477.                          were inputting such a string, the user would be able
  4478.                          to move to the middle of the string, and insert any
  4479.                          text. Doing so would cause the rest of the input line
  4480.  
  4481. ===============================================================================
  4482. OpenDoors 5.00 Manual                                            End of Page 76
  4483.  
  4484.  
  4485.                          to shift right. However, in cases where your format
  4486.                          string specifies different types of character to be
  4487.                          permitted in different positions, this can cause the
  4488.                          input to be changed so that it no longer conforms to
  4489.                          the format string. In this case, the user's input will
  4490.                          no longer be valid, and the user will not be able to
  4491.                          exit the function by pressing [ENTER] (although
  4492.                          [ESCAPE] will still be available, if you activated it)
  4493.                          until they change their input. However, when strict
  4494.                          input mode is turned on, od_edit_str() will restrict
  4495.                          the ways in which the user is permitted to edit the
  4496.                          string, to prevent just such a case from occurring.
  4497.  
  4498.                EDIT_FLAG_PASSWORD_MODE - Setting this flag causes the
  4499.                          od_edit_str() function to operate in "password" mode.
  4500.                          In password mode, the characters typed by the user
  4501.                          will be hidden, displayed instead as the blank
  4502.                          character specified in the "character" parameter.
  4503.  
  4504.                EDIT_FLAG_ALLOW_CANCEL - When this flag is set, the user will be
  4505.                          able to cancel their current input and abort the
  4506.                          editing process by pressing their [ESCAPE] key. When
  4507.                          they do so, any changes they have made to the input
  4508.                          field will be canceled, and replaced by the original
  4509.                          contents of the string. The od_edit_str() function
  4510.                          will then exit, indicating that the user has canceled
  4511.                          their input.
  4512.  
  4513.                EDIT_FLAG_FILL_STRING - When set, this flag will force the user
  4514.                          to enter a string that fills the entire length of the
  4515.                          format string. Normally, the user will be able to
  4516.                          enter a string of any length up to the maximum length
  4517.                          specified by the format string. However in some cases,
  4518.                          such as when inputting a date, you will want to have
  4519.                          the input field filled. (Otherwise, the user would be
  4520.                          able to enter only the first part of the date.)
  4521.  
  4522.                EDIT_FLAG_AUTO_ENTER - When set, this flag will cause the
  4523.                          od_edit_str() function to automatically simulate
  4524.                          pressing of the [ENTER] key when the string is filled.
  4525.                          This can be used to cause the od_edit_str() function
  4526.                          to finish inputting as soon as a valid string is
  4527.                          entered, instead of having to wait for the user to
  4528.                          press [ENTER] / [RETURN].
  4529.  
  4530.                EDIT_FLAG_AUTO_DELETE - When set, along with the
  4531.                          EDIT_FLAG_EDIT_STRING flag, this flag will activate
  4532.                          the auto-delete feature of the od_edit_str() function.
  4533.                          When auto-delete is active, if the first key pressed
  4534.                          by the user is not an edit control key, the existing
  4535.                          text will automatically be deleted, and a totally new
  4536.                          string accepted from the user. This could be useful
  4537.                          when you are allowing the user to go back to edit a
  4538.                          previous input. If the user wishes to only change part
  4539.  
  4540. ===============================================================================
  4541. OpenDoors 5.00 Manual                                            End of Page 77
  4542.  
  4543.  
  4544.                          of the old string, they can move the cursor to the
  4545.                          location where they wish to make the change, and
  4546.                          perform their editing. However, if the user wishes to
  4547.                          completely replace the old string with a new one, they
  4548.                          can simply begin to type, and the old string will
  4549.                          automatically be deleted, and the new string accepted.
  4550.  
  4551.                EDIT_FLAG_KEEP_BLANK - Normally, OpenDoors will only display the
  4552.                          input field background (as passed in the "character"
  4553.                          parameter) while the user is editing the string, and
  4554.                          will remove it when the od_edit_str() function exits.
  4555.                          However, you may wish to continue having this field
  4556.                          displayed after input has taken place, and the
  4557.                          od_edit_str() function has exited. In this case,
  4558.                          setting this flag will cause the background characters
  4559.                          to remain visible after input has finished.
  4560.  
  4561.                EDIT_FLAG_PERMALITERAL - When the format string contains literal
  4562.                          characters (such as forcing a ':' character to be
  4563.                          added to a time input by using the format string
  4564.                          "##':'##':'##"), the od_edit_str() function can
  4565.                          operate in one of two modes. In the default mode, the
  4566.                          literal characters will only be displayed when they
  4567.                          have been automatically added to the string. For
  4568.                          instance, if you were inputting the current time using
  4569.                          the above format string, this mode would result in the
  4570.                          input field initially being blank. When the user types
  4571.                          the first digit of the time, that number would appear.
  4572.                          When the user types the second digit of the time, that
  4573.                          number will appear, and then the colon character will
  4574.                          automatically be added by OpenDoors. However, you can
  4575.                          also set the od_edit_str() function to operate in
  4576.                          "PermaLiteral" mode, by setting this flag. When the
  4577.                          EDIT_FLAG_PERMALITERAL flag is set, the input field
  4578.                          will initially contain the literal characters (ie, the
  4579.                          colons in our example), with the cursor still located
  4580.                          at the leftmost position in the input field. In this
  4581.                          mode, the literal character become a permanent part of
  4582.                          the input field, and can not be moved or deleted by
  4583.                          the user - instead the cursor simply skips over the
  4584.                          literal character's position.
  4585.  
  4586.                EDIT_FLAG_LEAVE_BLANK - This flag applies to the special case
  4587.                          where the first character or characters of the format
  4588.                          string are literals. By default, the od_edit_str()
  4589.                          function will always return a string containing at
  4590.                          least these first literal characters. However, you can
  4591.                          alter this behaviors by setting this flag. When set,
  4592.                          if no non-literal characters have been entered in the
  4593.                          string, od_edit_str() will return an empty string.
  4594.  
  4595.  
  4596. SEE ALSO       od_input_str(), od_get_char(), od_clear_keybuffer()
  4597.  
  4598.  
  4599. ===============================================================================
  4600. OpenDoors 5.00 Manual                                            End of Page 78
  4601.  
  4602.  
  4603.  
  4604. EXAMPLE        Below are several examples of typical uses of the od_edit_str()
  4605.                function. For the sake of simplicity, all of these examples
  4606.                perform their input beginning at the top, left hand corner of
  4607.                the screen, and store the user's input in the string variable
  4608.                named "string". For an example of the user of the od_edit_str()
  4609.                function in a dialog-box / form entry application, see the
  4610.                example accompanying the od_draw_box() function.
  4611.  
  4612.                To input a name with a maximum of 25 characters, having the
  4613.                first letter of each word automatically capitalized:
  4614.  
  4615.                         od_edit_str(string, "MMMMMMMMMMMMMMMMMMMMMMMMM", 1, 1,
  4616.                                     0x03, 0x21, 176, EDIT_FLAG_NORMAL);
  4617.  
  4618.  
  4619.                To input a North American style phone number, requiring that all
  4620.                digits be filled, and running in "strict input" mode:
  4621.  
  4622.                         od_edit_str(string, "###'-'###'-'####",
  4623.                                     1, 1, 0x03, 0x21, 176,
  4624.                                     EDIT_FLAG_FILL_STRING|
  4625.                                     EDIT_FLAG_STRICT_INPUT);
  4626.  
  4627.  
  4628.                To allow the user to edit a previously entered 20 character
  4629.                string, with auto-delete mode on. Any characters will be
  4630.                permitted in the string. Remember that when the
  4631.                EDIT_FLAG_EDIT_STRING flag is set, the string must be
  4632.                initialized prior to calling the od_edit_str() function.
  4633.  
  4634.                         od_edit_str(string, "????????????????????",
  4635.                                     1, 1, 0x03, 0x21, 176,
  4636.                                     EDIT_FLAG_EDIT_STRING|
  4637.                                     EDIT_FLAG_AUTO_DELETE);
  4638.  
  4639.  
  4640.                To input a password of up to 16 characters from the user. Here,
  4641.                the password will only be permitted to contain upper case
  4642.                characters, and the od_edit_str() password mode is used, with a
  4643.                small block displayed in place of any characters typed:
  4644.  
  4645.                          od_edit_str(string, "UUUUUUUUUUUUUUUU",
  4646.                                      1, 1, 0x03, 0x21, 254,
  4647.                                      EDIT_FLAG_PASSWORD_MODE);
  4648.  
  4649.  
  4650.                To input a two-digit number from the user, requiring that both
  4651.                digits be filled, and automatically accepting the input after
  4652.                the two digits have been entered (not requiring the user to
  4653.                press [ENTER]):
  4654.  
  4655.                         od_edit_str(string, "##", 1, 1, 0x03, 0x21, 176,
  4656.                                     EDIT_FLAG_FILL_STRING|
  4657.  
  4658. ===============================================================================
  4659. OpenDoors 5.00 Manual                                            End of Page 79
  4660.  
  4661.  
  4662.                                     EDIT_FLAG_AUTO_ENTER);
  4663.  
  4664.  
  4665.                To input a filename to download, as a field in a dialog box.
  4666.                Here, the filename will be permitted to contain valid filename
  4667.                characters, and the od_input_str() function will operate in
  4668.                field mode, with the cancel [ESCape] key enabled. Also, string
  4669.                edit mode will be enabled, allowing the user to edit a
  4670.                previously entered line, and the EDIT_FLAG_KEEP_BLANK flag will
  4671.                be set, causing the field background to remain displayed after
  4672.                the user exits. This time, however, auto-delete mode will not be
  4673.                used. Note that this combination of parameters expects that the
  4674.                field and it's contents will have already been displayed, prior
  4675.                to calling the od_edit_str() function.
  4676.  
  4677.                         od_edit_str(string, "WWWWWWWWWWWW",
  4678.                                     1, 1, 0x03, 0x21, 176,
  4679.                                     EDIT_FLAG_EDIT_STRING|
  4680.                                     EDIT_FLAG_FIELD_MODE|
  4681.                                     EDIT_FLAG_ALLOW_CANCEL|
  4682.                                     EDIT_FLAG_KEEP_BLANK);
  4683.  
  4684.  
  4685.                To input a string without the field background and line
  4686.                redrawing before and after input takes place:
  4687.  
  4688.                         od_edit_str(string, "******************************",
  4689.                                     1, 1, 0x07, 0x07, ' ',
  4690.                                     EDIT_FLAG_NO_REDRAW);
  4691.  
  4692.  
  4693.                To input a date, using permaliteral mode. Here, the month is
  4694.                entered by a three digit short form ("JAN", "FEB", etc.), and
  4695.                the literal characters such as the '-' and the "19" are a
  4696.                permanent part of the input field:
  4697.  
  4698.                         od_edit_str(string,"UUU'-'##'-19'##",
  4699.                                     1, 1, 0x03, 0x21, 176,
  4700.                                     EDIT_FLAG_PERMALITERAL|
  4701.                                     EDIT_FLAG_FILL_STRING);
  4702.  
  4703.  
  4704.  
  4705.  
  4706.  
  4707.  
  4708.  
  4709.  
  4710.  
  4711.  
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717. ===============================================================================
  4718. OpenDoors 5.00 Manual                                            End of Page 80
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725. OD_EXIT()
  4726. -------------------------------------------------------------------------------
  4727.  
  4728. PURPOSE        The OpenDoors program termination function
  4729.  
  4730.  
  4731. FORMAT         void od_exit(int errorlevel,char term_call);
  4732.  
  4733.  
  4734. RETURNS        N/A
  4735.  
  4736.  
  4737. DESCRIPTION    When writing a door program, you MUST USE THIS FUNCTION when you
  4738.                want your Door to exit. This function will close the serial
  4739.                port, re-write changed information to the EXITINFO.BBS file,
  4740.                call your end-of-program function (if any), and then exit with
  4741.                the errorlevel specified in the first parameter.
  4742.  
  4743.                Also, if the second parameter, "term_call", is set to TRUE,
  4744.                od_exit() will also log the user off (for options such as
  4745.                logging off within the door - as shown in the example below).
  4746.                This is accomplished by lowering the DTR line to the modem,
  4747.                causing the modem to hangup. When control is returned to the
  4748.                BBS, it will then detect that the user is no longer online, and
  4749.                will carry out its own logoff processing.
  4750.  
  4751.                If you wish for your program to always perform any activities
  4752.                prior to exiting, such as updating or closing data files, you
  4753.                should set a function to be executed from within the od_exit()
  4754.                function. This is accomplished by using the od_control.
  4755.                od_before_exit variable, as described in the section on the
  4756.                OpenDoors control structure in chapter 5. Use of this variable
  4757.                will allow your program to always carry out these activates,
  4758.                even if OpenDoors decides to call the od_exit() function itself,
  4759.                such as when a user hangs up on the door.
  4760.  
  4761.                Note that in special cases, you may use the
  4762.                od_control.od_disable variable to prevent the od_exit() function
  4763.                from re-writing the door information file. Also, you may use the
  4764.                od_control.od_noexit variable to shutdown door operations
  4765.                without actually exiting your program. Both of these variables
  4766.                are described in chapter 5.
  4767.  
  4768.  
  4769. SEE ALSO       od_init()
  4770.  
  4771.  
  4772. EXAMPLE        The example below demonstrates a function which a door could
  4773.                execute when the user chooses to exit the door. This function
  4774.                will ask the user whether they wish to exit the door and return
  4775.  
  4776. ===============================================================================
  4777. OpenDoors 5.00 Manual                                            End of Page 81
  4778.  
  4779.  
  4780.                to the BBS, simply logoff of the BBS, or continue using the
  4781.                door. The example function will then call od_exit() if the user
  4782.                wishes to exit the door, or return control to the function which
  4783.                called it, if the user does not wish to exit:
  4784.  
  4785.                void goodbye(void)
  4786.                   {
  4787.                   char pressed;
  4788.                                                   /* Display choices to user */
  4789.                   od_disp_str("You have chosen to exit this door.\n\r");
  4790.                   od_disp_str("Do you wish to:\n\r");
  4791.                   od_disp_str("      [R]eturn to the BBS\n\r");
  4792.                   od_disp_str("      [L]ogoff of the BBS\n\r");
  4793.                   od_disp_str("      [C]ontinue using the door\n\r");
  4794.  
  4795.                   for(;;)              /* loop until user makes valid choice */
  4796.                      {
  4797.                      pressed=od_get_key(TRUE);          /* Get key from user */
  4798.  
  4799.                                /* If user selects R, exit without hanging up */
  4800.                      if(pressed=='R' || pressed=='r') od_exit(40,FALSE);
  4801.  
  4802.                                   /* If user selects L, hangup and then exit */
  4803.                      if(pressed=='L' || pressed=='l') od_exit(41,TRUE);
  4804.  
  4805.                      /* If user selects C, return and allow door to continue */
  4806.                      if(pressed=='C' || pressed=='c') return;
  4807.                      }
  4808.                   }
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.  
  4825.  
  4826.  
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.  
  4833.  
  4834.  
  4835. ===============================================================================
  4836. OpenDoors 5.00 Manual                                            End of Page 82
  4837.  
  4838.  
  4839.  
  4840.  
  4841.  
  4842.  
  4843. OD_GET_ANSWER()
  4844. -------------------------------------------------------------------------------
  4845.  
  4846. PURPOSE        Function to allow the user to respond to a prompt using only
  4847.                certain keys.
  4848.  
  4849.  
  4850. FORMAT         char od_get_answer(char *string);
  4851.  
  4852.  
  4853. RETURNS        User's response to prompt
  4854.  
  4855.  
  4856. DESCRIPTION    This function can be used to get a response from the user, when
  4857.                only particular responses should be accepted. The parameter to
  4858.                the od_get_answer() function is simply a string listing the
  4859.                valid responses. The function will wait until the user selects
  4860.                one of the valid responses, and then return that response. The
  4861.                function is case insensitive, and will return the character in
  4862.                the same case that was supplied to it in the string.
  4863.  
  4864.  
  4865. SEE ALSO       od_get_key(), od_hotkey_menu()
  4866.  
  4867.  
  4868. EXAMPLES       od_get_answer("YN");
  4869.                     - If the user presses 'y', will return 'Y'.
  4870.  
  4871.                od_get_answer("yn");
  4872.                     - If the user presses 'y', will return 'y'.
  4873.  
  4874.                od_get_answer("ABC 123\n\rZ");
  4875.                     - Valid responses will be: [A], [B], [C], [SPACE],
  4876.                       [1], [2], [3], [ENTER], [Z]
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.  
  4892.  
  4893.  
  4894. ===============================================================================
  4895. OpenDoors 5.00 Manual                                            End of Page 83
  4896.  
  4897.  
  4898.  
  4899.  
  4900.  
  4901.  
  4902. OD_GET_KEY()
  4903. -------------------------------------------------------------------------------
  4904.  
  4905. PURPOSE        Function to input a key from the user
  4906.  
  4907.  
  4908. FORMAT         int od_get_key(int wait);
  4909.  
  4910.  
  4911. RETURNS        The next key waiting from the keyboard, or 0 if none.
  4912.  
  4913.  
  4914. DESCRIPTION    This function retrieves the next key waiting in the OpenDoors
  4915.                keyboard buffer (see the description of the od_clear_keybuffer()
  4916.                function, on page 53, for more information on the OpenDoors
  4917.                keyboard buffer). The od_get_key() function allows your door to
  4918.                retrieve both those keystrokes pressed by the user, and the
  4919.                keystrokes pressed on the sysop keyboard (other than the sysop
  4920.                function keys), in the sequence they were pressed. Since input
  4921.                is accepted from both sources, it is possible for the sysop, as
  4922.                well as the remote user, to make selections and control the
  4923.                door.
  4924.  
  4925.                Door input with OpenDoors can be accomplished with this
  4926.                function, with the od_input_str() function or with the
  4927.                od_edit_str() function. The od_input_str() and od_edit_str()
  4928.                functions is used to input an entire sequence of characters from
  4929.                the user (a string), and requires the user to press the [Enter]
  4930.                key when they are finished typing their input. On the other
  4931.                hand, the od_get_key() function is used to input a single
  4932.                keystroke (one character) from the user, and allows the user to
  4933.                make choices without having to press the enter key.
  4934.  
  4935.                The od_get_key() function accepts a single parameter, which
  4936.                determines whether or not it should wait for the user to press a
  4937.                key, if they have not already done so. If you pass a FALSE value
  4938.                to od_get_key(), then the function will not wait for a key to be
  4939.                pressed at the keyboard, but instead return a 0 if there are no
  4940.                keys waiting in the buffer. If you pass a TRUE value to
  4941.                od_get_key(), then this function will instead wait for a key to
  4942.                be pressed. Also, while waiting for the user to press a key, the
  4943.                od_get_key() function will give up the processor to other
  4944.                waiting programs, if you door is running under DesqView.
  4945.  
  4946.                If you are waiting for the user to make a choice from a menu or
  4947.                list of options, you will most likely pass a TRUE to the
  4948.                od_get_key() function, indicating that you wish for it to wait
  4949.                until a key is pressed. However, if you wish to continue other
  4950.                processing if no key is yet available from the keyboard, you
  4951.                should pass a FALSE to the od_get_key() function. For example,
  4952.  
  4953. ===============================================================================
  4954. OpenDoors 5.00 Manual                                            End of Page 84
  4955.  
  4956.  
  4957.                if you are displaying a screen of text, and wish to allow the
  4958.                user to pause or abort the display, you would simply call the
  4959.                od_get_key() function every few moments, passing it a value of
  4960.                FALSE. You would then be able to check if any control keys have
  4961.                been pressed, and if not, continue displaying text.
  4962.  
  4963.                The od_get_key() function returns the ASCII value representing
  4964.                the keystroke that was made. If you are waiting for the user to
  4965.                make a particular choice, perhaps from a menu, you will most
  4966.                likely store the value returned by od_get_key() in a variable of
  4967.                type char. For example:
  4968.  
  4969.                       char key;
  4970.  
  4971.                       ...
  4972.  
  4973.                       key=od_get_key(TRUE);
  4974.  
  4975.                You would then be able to determine which key the user pressed
  4976.                by testing the value of key, either by comparing it's numerical
  4977.                ASCII value, or by comparing it to a character constant. If you
  4978.                are testing for a non-character key, such as [ESCape], [Tab] or
  4979.                [Return], you may wish to use the ASCII value of that key. For
  4980.                example, if you wished to take some action in the case that the
  4981.                user presses the [Enter]/[Return] key, who's ASCII value is 13,
  4982.                you could do:
  4983.  
  4984.                       key=od_get_key(TRUE);        /* Get keypress from user */
  4985.                       if(key==13)             /* If key was [Enter]/[Return] */
  4986.                          {
  4987.                          ...                      /* Whatever you want to do */
  4988.                          }
  4989.  
  4990.                A complete reference of all the ASCII values is listed below.
  4991.  
  4992.                To determine whether input originated from the local or remote
  4993.                keyboards, see the OpenDoors control structure variable
  4994.                od_last_input.
  4995.  
  4996.                If you wish, instead, to respond to the user pressing a
  4997.                character key (perhaps as a choice from a menu), you can do so
  4998.                by using character constants, such as 'c', '6', or 'F'. Also,
  4999.                when testing for an alphabetical character, you will probably
  5000.                want to check for the user pressing either the upper or lower-
  5001.                case version of the letter. For example, if you wished to have
  5002.                the user press the [Y] key to continue, you could test for
  5003.                either an upper or lower-case Y as follows:
  5004.  
  5005.                        key=od_get_key(TRUE);       /* Get keypress from user */
  5006.                        if(key=='y' || key=='Y')        /* If key was [y]/[Y] */
  5007.                           {
  5008.                           ...                     /* Whatever you want to do */
  5009.                           }
  5010.  
  5011.  
  5012. ===============================================================================
  5013. OpenDoors 5.00 Manual                                            End of Page 85
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020. The chart below lists the decimal value and corresponding keystroke(s) of each
  5021. of the ASCII values from 0 to 127.
  5022.  
  5023.  
  5024. ASCII  KEYSTROKE                       |  ASCII   KEYSTROKE
  5025. -----  ------------------------------  |  -----   ----------------------
  5026.   0    [Control]-[@]                   |   15     [Control]-[O]
  5027.   1    [Control]-[A]                   |   16     [Control]-[P]
  5028.   2    [Control]-[B]                   |   17     [Control]-[Q]
  5029.   3    [Control]-[C]                   |   18     [Control]-[R]
  5030.   4    [Control]-[D]                   |   19     [Control]-[S]
  5031.   5    [Control]-[E]                   |   20     [Control]-[T]
  5032.   6    [Control]-[F]                   |   21     [Control]-[U]
  5033.   7    [Control]-[G]                   |   22     [Control]-[V]
  5034.   8    [Control]-[H]/[Backspace]       |   23     [Control]-[W]
  5035.   9    [Control]-[I]/[Tab]             |   24     [Control]-[X]
  5036.  10    [Control]-[J]                   |   25     [Control]-[Y]
  5037.  11    [Control]-[K]                   |   26     [Control]-[Z]
  5038.  12    [Control]-[L]                   |   27     [ESCape]
  5039.  13    [Control]-[M]/[Enter]/[Return]  |   32     [SpaceBar]
  5040.  14    [Control]-[N]                   |
  5041.  
  5042.  
  5043.  
  5044. ASCII  KEYSTROKE | ASCII  KEYSTROKE | ASCII  KEYSTROKE | ASCII  KEYSTROKE
  5045. -----  --------- | -----  --------- | -----  --------- | -----  ---------
  5046.  33       '!'    |  57       '9'    |  80       'P'    |  104      'h'
  5047.  34       '"'    |  58       ':'    |  81       'Q'    |  105      'i'
  5048.  35       '#'    |  59       ';'    |  82       'R'    |  106      'j'
  5049.  36       '$'    |  60       '<'    |  83       'S'    |  107      'k'
  5050.  37       '%'    |  61       '='    |  84       'T'    |  108      'l'
  5051.  38       '&'    |  62       '>'    |  85       'U'    |  109      'm'
  5052.  39    '\''  (') |  63       '?'    |  86       'V'    |  110      'n'
  5053.  40       '('    |  64       '@'    |  87       'W'    |  111      'o'
  5054.  41       ')'    |  65       'A'    |  88       'X'    |  112      'p'
  5055.  42       '*'    |  66       'B'    |  89       'Y'    |  113      'q'
  5056.  43       '+'    |  67       'C'    |  90       'Z'    |  114      'r'
  5057.  44       ','    |  68       'D'    |  91       '['    |  115      's'
  5058.  45       '-'    |  69       'E'    |  92    '\\'  (\) |  116      't'
  5059.  46       '.'    |  70       'F'    |  93       ']'    |  117      'u'
  5060.  47       '/'    |  71       'G'    |  94       '^'    |  118      'v'
  5061.  48       '0'    |  72       'H'    |  95       '_'    |  119      'w'
  5062.  49       '1'    |  73       'I'    |  96       '`'    |  120      'x'
  5063.  50       '2'    |  74       'J'    |  98       'b'    |  121      'y'
  5064.  51       '3'    |  75       'K'    |  99       'c'    |  122      'z'
  5065.  52       '4'    |  76       'L'    |  100      'd'    |  123      '{'
  5066.  53       '5'    |  77       'M'    |  101      'e'    |  124      '|'
  5067.  54       '6'    |  78       'N'    |  102      'f'    |  125      '}'
  5068.  55       '7'    |  79       'O'    |  103      'g'    |  126      '~'
  5069.  56       '8'    |                  |                  |  127    [DELete]
  5070.  
  5071. ===============================================================================
  5072. OpenDoors 5.00 Manual                                            End of Page 86
  5073.  
  5074.  
  5075.  
  5076.  
  5077.  
  5078.  
  5079. SEE ALSO       od_input_str(), od_edit_str(), od_clear_keybuffer()
  5080.  
  5081.  
  5082. EXAMPLE        For examples of the use of the od_get_key() function, see the
  5083.                examples in the description portion, above, and the examples for
  5084.                the od_exit() and od_clear_keybuffer() functions. For further
  5085.                examples of this function, see the example door EZVote,
  5086.                described in the section beginning  on page 38.
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.  
  5093.  
  5094.  
  5095.  
  5096.  
  5097.  
  5098.  
  5099.  
  5100.  
  5101.  
  5102.  
  5103.  
  5104.  
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.  
  5111.  
  5112.  
  5113.  
  5114.  
  5115.  
  5116.  
  5117.  
  5118.  
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130. ===============================================================================
  5131. OpenDoors 5.00 Manual                                            End of Page 87
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138. OD_GETTEXT()
  5139. -------------------------------------------------------------------------------
  5140.  
  5141. PURPOSE        Stores a rectangular region of the screen in an array, to later
  5142.                be redrawn using od_puttext(). Requires ANSI, AVATAR or RIP
  5143.                modes.
  5144.  
  5145.  
  5146. FORMAT         int od_gettext(int left, int top, int right, int bottom, void
  5147.                *block);
  5148.  
  5149.  
  5150. RETURNS        TRUE on success
  5151.                FALSE on failure
  5152.  
  5153.  
  5154. DESCRIPTION    This function stores the contents (both text and colour
  5155.                information) of the rectangular portion of the screen denoted by
  5156.                the variables "left", "top", "right" and "bottom" into the
  5157.                buffer pointed to by block. The saved portion of the screen may
  5158.                then be restored using od_puttext(). The buffer must be large
  5159.                enough to store two bytes for every character in the specified
  5160.                rectangle. In other words, the required size of the buffer, in
  5161.                bytes, is:
  5162.  
  5163.                            length * width * 2
  5164.  
  5165.                The parameters "left" and "right" are column numbers from 1 to
  5166.                80, and the parameters "top" and "bottom" are row numbers
  5167.                between 1 and 23.
  5168.  
  5169.                This function has no effect on the current text colour or cursor
  5170.                position. ANSI, AVATAR or RIP mode is required for this
  5171.                function. If you wish to save and restore the entire screen, you
  5172.                may use the od_save_screen() and od_restore_screen() functions,
  5173.                which can be used in all display modes.
  5174.  
  5175.                If this function fails for any reason, a value of FALSE is
  5176.                returned, and the od_control.od_error variable is set to
  5177.                indicate the reason for the failure. For more information on the
  5178.                od_control.od_error variable, see page 182.
  5179.  
  5180.  
  5181. SEE ALSO       od_puttext(), od_save_screen(), od_restore_screen(),
  5182.                od_scroll(), od_window_create(), od_window_remove()
  5183.  
  5184.  
  5185. EXAMPLE
  5186.  
  5187.  
  5188.  
  5189. ===============================================================================
  5190. OpenDoors 5.00 Manual                                            End of Page 88
  5191.  
  5192.  
  5193.  
  5194.  
  5195.  
  5196.  
  5197. OD_HOTKEY_MENU()
  5198. -------------------------------------------------------------------------------
  5199.  
  5200. PURPOSE        Function to display a menu file with hotkeys
  5201.  
  5202.  
  5203. FORMAT         char od_hotkey_menu(char *filename, char *hotkeys, char wait);
  5204.  
  5205.  
  5206. RETURNS        Key pressed in response to menu, or '\0' if none.
  5207.  
  5208.  
  5209. DESCRIPTION    This function can be used to display a menu from an ASCII, ANSI,
  5210.                AVATAR or RIP file, allowing the user to select an option at any
  5211.                time while the menu is being displayed. The od_hotkey_menu()
  5212.                function is quite similar to the od_send_file() function, and
  5213.                you should probably familiarize yourself with that function if
  5214.                you are going to use od_hotkey_menu(). Like od_send_file(),
  5215.                od_hotkey_menu() will display the file specified by filename,
  5216.                using the appropriate terminal emulation. If no extension is
  5217.                provided for the filename, OpenDoors will automatically search
  5218.                for matching files ending in .ASC, .ANS and .AVT extensions.
  5219.                OpenDoors will the select the appropriate file to display, based
  5220.                on the available files and available terminal emulation.
  5221.  
  5222.                The second parameter, hotkeys, is a string specifying the valid
  5223.                responses to the menu, in the same format as the string passed
  5224.                to the od_get_answer() function. If any of the characters listed
  5225.                in this string are pressed, either uppercase or lowercase
  5226.                versions, OpenDoors will immediately stop displaying the menu,
  5227.                and return with the value of the key pressed. The case (upper or
  5228.                lower) returned will always be identical to the case used in the
  5229.                hotkeys string. You can include the [ENTER] key as a valid hot
  5230.                key by including the \n character in the hotkey string.
  5231.  
  5232.                The third parameter passed to od_hotkey_menu(), wait, specifies
  5233.                whether OpenDoors should wait after displaying the menu for the
  5234.                user to make a valid selection from the menu (TRUE), or if it
  5235.                should exit immediately (FALSE). Normally, you will want to use
  5236.                the TRUE value when calling this function. This will allow you
  5237.                to use a single function call that will display the menu and
  5238.                always return the user's selection. If you wish to gain control
  5239.                as soon as OpenDoors has displayed the menu, you may specify
  5240.                FALSE for this parameter. In this case, if the user does not
  5241.                press any of the valid hot keys while the menu is being sent,
  5242.                the function will return the character '\0'.
  5243.  
  5244.  
  5245. SEE ALSO       od_send_file(), od_get_answer()
  5246.  
  5247.  
  5248. ===============================================================================
  5249. OpenDoors 5.00 Manual                                            End of Page 89
  5250.  
  5251.  
  5252.  
  5253. EXAMPLE        As an example of the use of the od_hotkey_menu() function,
  5254.                consider the following code fragment:
  5255.  
  5256.  
  5257.                     for(;;)                              /* Main pogram loop */
  5258.                          {             /* Display menu and get user's choice */
  5259.                          char choice=od_hotkey_menu("MAINMENU","123Q",TRUE");
  5260.  
  5261.                          switch(choice)    /* Perform the appropriate action */
  5262.                               {
  5263.                               case '1':
  5264.                                    od_printf("You selected one.\n\r");
  5265.                                    break;
  5266.  
  5267.                               case '2':
  5268.                                    od_printf("You selected two.\n\r");
  5269.                                    break;
  5270.  
  5271.                               case '3':
  5272.                                    od_printf("You selected three.\n\r");
  5273.                                    break;
  5274.  
  5275.                               case 'Q':
  5276.                                    od_exit(FALSE,10);
  5277.                               }
  5278.                          }
  5279.  
  5280.                This is an example of the main menu loop of a simple door that
  5281.                uses the od_hotkey_menu() function. The program will continue
  5282.                executing the for(;;) loop until the user chooses to exit the
  5283.                door. On each iteration of the loop, the od_hotkey_menu()
  5284.                function is called, to display the door's menu from the file
  5285.                MAINMENU.A??. The appropriate .ASC/.ANS/.AVT file will be chosen
  5286.                and displayed as the menu. The possible choices that may be made
  5287.                from the menu are specified by the string "123Q". Thus, whenever
  5288.                the user presses one of the keys [1], [2], [3] or [Q], the
  5289.                od_hotkey_menu() function will return immediately with the value
  5290.                of the key pressed. If the menu is still being displayed at the
  5291.                time when the key was pressed, menu display will cease at that
  5292.                moment. The program then executes a case statement, to respond
  5293.                to the user's key appropriately. If the user presses [1], [2] or
  5294.                [3] this door will output a simple message to the screen. If the
  5295.                user presses the [Q] key, the door will pass control back to the
  5296.                BBS.
  5297.  
  5298.  
  5299.  
  5300.  
  5301.  
  5302.  
  5303.  
  5304.  
  5305.  
  5306.  
  5307. ===============================================================================
  5308. OpenDoors 5.00 Manual                                            End of Page 90
  5309.  
  5310.  
  5311.  
  5312.  
  5313.  
  5314.  
  5315. OD_INIT()
  5316. -------------------------------------------------------------------------------
  5317.  
  5318. PURPOSE        To initialize OpenDoors activities
  5319.  
  5320.  
  5321. FORMAT         void od_init(void);
  5322.  
  5323.  
  5324. RETURNS        N/A
  5325.  
  5326.  
  5327. DESCRIPTION    This function initializes any door running under OpenDoors. This
  5328.                function must be called manually if you wish to access data
  5329.                about the user, etc., before you call any other OpenDoors
  5330.                functions. However, if you do not explicitly call the od_init()
  5331.                function, it will be called automatically on the first call to
  5332.                any other OpenDoors function. The od_init() function reads
  5333.                information from the door information file, initializes
  5334.                communications with the modem, displays the status line, and
  5335.                sets up OpenDoors' internal data structures. For more
  5336.                information on what data is and is not available before
  5337.                od_init() has been called, please refer to the chapter on the
  5338.                OpenDoors control structure, which begins on page 145.
  5339.  
  5340.                The od_init() function will read the door information file which
  5341.                is located in the directory specified by the variable
  5342.                od_control.info_path. If this variable has not been set prior to
  5343.                calling the od_init() function, OpenDoors will expect to find
  5344.                the door information file in the current directory. Thus, if you
  5345.                wish your door to be able to be run in a directory other than
  5346.                the BBS system directory, it would be a good idea to allow the
  5347.                sysop using your door to specify the location of the door
  5348.                information file. For an example of setting the
  5349.                od_control.info_path variable, please see the example program
  5350.                located on page 148.
  5351.  
  5352.                Also note that you can prevent the od_init() function from
  5353.                carrying out some of it's normal activities, such as attempting
  5354.                to read a door information file, by the use of the
  5355.                od_control.od_disable variable, as described in the section on
  5356.                the OpenDoors control structure, which begins on page 145.
  5357.  
  5358.  
  5359. SEE ALSO       od_exit()
  5360.  
  5361.  
  5362. EXAMPLE        At times, you may wish to write a door program which will
  5363.                require a maintenance utility to be run on a regular basis. For
  5364.                example, a game door may have to have its system files updated
  5365.  
  5366. ===============================================================================
  5367. OpenDoors 5.00 Manual                                            End of Page 91
  5368.  
  5369.  
  5370.                on a daily basis, by having a utility program run in a system
  5371.                event each day at midnight. One way of accomplishing this would
  5372.                be to have your door package include two .EXE files, one being
  5373.                the actual door program, and the other being a utility program.
  5374.                However, another option would be to have both the door and
  5375.                maintenance functions to be accessible from a single .EXE file,
  5376.                in order to simplify use of the door for the sysop. In this
  5377.                case, you would want to test the command line to determine
  5378.                whether your program should run in door mode or maintenance
  5379.                mode. You would then only execute the od_init() function, along
  5380.                with the rest of your door code, if you program were running in
  5381.                "door mode".
  5382.  
  5383.                The program below demonstrates one method of doing just this. In
  5384.                this case, the program would include two functions, door(),
  5385.                which would carry out all of the door-related activities, and
  5386.                maint(), which would carry out all of the maintenance-related
  5387.                activities. In this simple example, if the command line includes
  5388.                a "-M" or "/M", the program will run in maintenance mode,
  5389.                otherwise it will run in door mode. Also, if it is running in
  5390.                door mode, the program will take the first command-line
  5391.                parameter, if any, as a path to the location of the door
  5392.                information file.
  5393.  
  5394.  
  5395.                #include "opendoor.h"
  5396.  
  5397.                void door(void);
  5398.                void maint(void);
  5399.  
  5400.  
  5401.                int main(int argc, char *argv[])
  5402.                   {
  5403.                   int counter;
  5404.  
  5405.                            /* Check any command line parameters for /M or -M */
  5406.                   for(counter=1;counter<argc;++counter)
  5407.                      {
  5408.                      if((argv[counter])[1]=='m' || (argv[counter])[1]=='M')
  5409.                         {
  5410.                         maint();               /* Then carry out maintenance */
  5411.                         exit(20);                                /* And exit */
  5412.                         }
  5413.                      }
  5414.                           /* If there was no -M or /M, then run in door mode */
  5415.  
  5416.                   /* If there are any command-line parameters take the first */
  5417.                                  /* as the path to the door information file */
  5418.                   if(argc>1) strncpy(od_control.info_path,argv[1],59);
  5419.  
  5420.                   od_init();                  /* call the od_init() function */
  5421.                   door();             /* Run the door portion of the program */
  5422.                   od_exit(30,FALSE);                    /* Shutdown the door */
  5423.                   }
  5424.  
  5425. ===============================================================================
  5426. OpenDoors 5.00 Manual                                            End of Page 92
  5427.  
  5428.  
  5429.  
  5430.  
  5431.                void maint(void)
  5432.                   {
  5433.                   ...               /* Carry out maintenance activities here */
  5434.                   }
  5435.  
  5436.  
  5437.                void door(void)
  5438.                   {
  5439.                   ...                      /* Carry out door activities here */
  5440.                   }
  5441.  
  5442.  
  5443.  
  5444.  
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.  
  5454.  
  5455.  
  5456.  
  5457.  
  5458.  
  5459.  
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.  
  5473.  
  5474.  
  5475.  
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.  
  5483.  
  5484. ===============================================================================
  5485. OpenDoors 5.00 Manual                                            End of Page 93
  5486.  
  5487.  
  5488.  
  5489.  
  5490.  
  5491.  
  5492. OD_INPUT_STR()
  5493. -------------------------------------------------------------------------------
  5494.  
  5495. PURPOSE        Inputs a string from the user
  5496.  
  5497.  
  5498. FORMAT         void od_input_str(char *string,int max_len,char minchar, char
  5499.                maxchar);
  5500.  
  5501.  
  5502. RETURNS        N/A
  5503.  
  5504.  
  5505. DESCRIPTION    To perform string input within OpenDoors, one of two functions
  5506.                can be used, od_input_str() and od_edit_str(). The first
  5507.                function, od_input_str(), allows simple line input and editing,
  5508.                and can be used in ASCII, ANSI, AVATAR and RIP modes. The second
  5509.                function, od_edit_str(), allows many formatted input options,
  5510.                advanced line editing, and other features, but requires the use
  5511.                of ANSI, AVATAR or RIP graphics modes.
  5512.  
  5513.                The od_input_str() function allows you to input a string from
  5514.                the user. The string will be permitted to have up to the number
  5515.                of characters specified by the max_len parameter, and all
  5516.                characters must be between the values of the min_char and
  5517.                max_char parameters. This function will wait until the user
  5518.                presses the [Enter] key to finish inputting the string.
  5519.  
  5520.                The first parameter passed to this function should be a pointer
  5521.                to the string where the user's input should be stored. So, if
  5522.                you wanted to store a string of up to 30 characters inputted by
  5523.                the user, you might define this string as follows:
  5524.  
  5525.                          char input_string[31];
  5526.  
  5527.                Notice here than the string must be long enough to hold the
  5528.                thirty characters which can be entered by the user, along with
  5529.                the additional "null" character which is used to indicate the
  5530.                end of a string in C. Hence, the length of the string should
  5531.                always be at least one greater than the total number of
  5532.                characters the user is permitted to enter, passed in the max_len
  5533.                parameter.
  5534.  
  5535.                The second parameter passed to the od_input_str() function
  5536.                should be an integer value indicating the maximum number of
  5537.                characters which can be input by the user. For example, if this
  5538.                parameter had a value of 10, the user would be able to enter a
  5539.                string containing any number of characters up to and including
  5540.                10 characters. If this parameter had a value of 1, the user
  5541.                would only be able to enter a single character. However, the
  5542.  
  5543. ===============================================================================
  5544. OpenDoors 5.00 Manual                                            End of Page 94
  5545.  
  5546.  
  5547.                user would be able to backspace, change the character, and press
  5548.                [Enter] when they were satisfied with their entry. Note that
  5549.                even if you only ask the od_input_str() function to input a
  5550.                single character, it will still expect a STRING to be passed to
  5551.                it, and will return a string with either zero or one character,
  5552.                followed by a null (string terminator) character.
  5553.  
  5554.                The third and fourth parameters passed to this function allow
  5555.                you to control what characters the user will be permitted to
  5556.                enter as part of the string. For example, you could set the
  5557.                minimum character to the '0' character and the maximum character
  5558.                to the '9' character, permitting the user to only enter numeric
  5559.                characters. On the other hand, you could permit the user to
  5560.                enter all ASCII characters in the range from 32 to 127. The
  5561.                od_input_str() function will permit characters in the range
  5562.                beginning with the character passed as minchar, up to and
  5563.                including the character passed as maxchar.
  5564.  
  5565.  
  5566. SEE ALSO       od_edit_str(), od_get_key(), od_clear_keybuffer()
  5567.  
  5568.  
  5569. EXAMPLE        Below are a number of examples of the use of the od_input_str()
  5570.                function in various applications:
  5571.  
  5572.                  - To input a two character number (only digits from 0-9):
  5573.  
  5574.                         od_input_str(string,2,'0','9');
  5575.  
  5576.                  - To input a 35 character name (characters from Space to
  5577.                    ASCII 127):
  5578.  
  5579.                         od_input_str(string,35,32,127);
  5580.  
  5581.  
  5582.  
  5583.  
  5584.  
  5585.  
  5586.  
  5587.  
  5588.  
  5589.  
  5590.  
  5591.  
  5592.  
  5593.  
  5594.  
  5595.  
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602. ===============================================================================
  5603. OpenDoors 5.00 Manual                                            End of Page 95
  5604.  
  5605.  
  5606.  
  5607.  
  5608.  
  5609.  
  5610. OD_KERNEL()
  5611. -------------------------------------------------------------------------------
  5612.  
  5613. PURPOSE        The OpenDoors Central Control function
  5614.  
  5615.  
  5616. FORMAT         void od_kernel(void);
  5617.  
  5618.  
  5619. RETURNS        N/A
  5620.  
  5621.  
  5622. DESCRIPTION    The od_kernel() function is responsible for many vital OpenDoors
  5623.                tasks, such as monitoring the carrier detect signal, monitoring
  5624.                the amount of time that the user has remaining, updating the
  5625.                status line, responding to sysop hotkeys, and reading characters
  5626.                which are received from the modem. The od_kernel() function is
  5627.                automatically called on a frequent basis by the other OpenDoors
  5628.                functions, so most often you will not need to be concerned with
  5629.                this function. However, in order that OpenDoors can carry out
  5630.                the activities mentioned above with a quick response, it is
  5631.                important that od_kernel(), or some other OpenDoors function be
  5632.                called at least once every second. Thus, if your program will be
  5633.                carrying out some processing, in which it will not be calling
  5634.                any OpenDoors functions for more than a second or so, you should
  5635.                call the od_kernel() function yourself. The example below
  5636.                demonstrates one method of doing just this.
  5637.  
  5638.                Note that if for some reason or other, it is not possible for
  5639.                your program to call the od_kernel() function, or any other
  5640.                OpenDoors functions for a period of several seconds, this will
  5641.                not cause your door to crash or fail in any way. The only
  5642.                problem will be that OpenDoors will not be able to respond to
  5643.                any action, such as the sysop pressing a function key, or the
  5644.                user dropping carrier, until such time as you next call
  5645.                od_kernel(), or some OpenDoors function. Hence, use of the
  5646.                od_kernel() function will improve the quality and response time
  5647.                of your program, but calling it or some OpenDoors function on a
  5648.                regular basis is not absolutely vital.
  5649.  
  5650.  
  5651. EXAMPLE        As mentioned above, if it is possible that several seconds may
  5652.                pass between your program calling any OpenDoors functions, it
  5653.                would be a good idea for you to call the od_kernel() function on
  5654.                a regular basis. Below is an example of a door_sleep() function,
  5655.                which will pause for the specified amount of time, while
  5656.                continually calling the od_kernel() function. This function will
  5657.                thus allow a door program to pause for a given length of time,
  5658.                perhaps after having displayed its title screen, or in order to
  5659.                add special effects to an ANSI animation. In this case, the
  5660.  
  5661. ===============================================================================
  5662. OpenDoors 5.00 Manual                                            End of Page 96
  5663.  
  5664.  
  5665.                program will be able to respond to events such as the sysop
  5666.                pressing function keys, or the user dropping carrier, while it
  5667.                is pausing.
  5668.  
  5669.  
  5670.                void door_sleep(int seconds)
  5671.                   {                /* Calculate the timer tick to wait until */
  5672.                   long until=(*(long far *)0x46cL)+(18L*(long)seconds);
  5673.  
  5674.                   /* Loop until the specified number of seconds have expired */
  5675.                   while(until>*(long far *)0x46cL)
  5676.                      {
  5677.                      od_kernel();             /* Repeatedly call od_kernel() */
  5678.                      }
  5679.                   }
  5680.  
  5681.  
  5682.  
  5683.  
  5684.  
  5685.  
  5686.  
  5687.  
  5688.  
  5689.  
  5690.  
  5691.  
  5692.  
  5693.  
  5694.  
  5695.  
  5696.  
  5697.  
  5698.  
  5699.  
  5700.  
  5701.  
  5702.  
  5703.  
  5704.  
  5705.  
  5706.  
  5707.  
  5708.  
  5709.  
  5710.  
  5711.  
  5712.  
  5713.  
  5714.  
  5715.  
  5716.  
  5717.  
  5718.  
  5719.  
  5720. ===============================================================================
  5721. OpenDoors 5.00 Manual                                            End of Page 97
  5722.  
  5723.  
  5724.  
  5725.  
  5726.  
  5727.  
  5728. OD_LIST_FILES()
  5729. -------------------------------------------------------------------------------
  5730.  
  5731. PURPOSE        Lists files in a particular file area (using FILES.BBS)
  5732.  
  5733.  
  5734. FORMAT         int od_list_files(char *directory);
  5735.  
  5736.  
  5737. RETURNS        TRUE if successful, FALSE if unsuccessful
  5738.  
  5739.  
  5740. DESCRIPTION    This function allows you to display a list of files available
  5741.                for download from a particular file area, as any BBS system
  5742.                would. The file names and descriptions are taken from the
  5743.                FILES.BBS located in the directory pointed to by *directory.
  5744.                Thus, to list the files available for download in
  5745.                C:\BBS\FILES\UPLOADS, simply:
  5746.  
  5747.                       od_list_files("C:\\BBS\\FILES\\UPLOADS");
  5748.  
  5749.                OpenDoors uses a third-generation FILES.BBS format, that is
  5750.                compatible with other FILES.BBS formats, but adds some
  5751.                additional features. Each line in the FILES.BBS file lists a
  5752.                filename, along with it's description. Thus, a typical FILES.BBS
  5753.                file might look as follows:
  5754.  
  5755.                         PKZ110.EXE    PKZip file compressor, version 1.10
  5756.                         ODOORS40.LZH  The newest version of OpenDoors!
  5757.                         EZVOTE40.ZIP  EZVote user voting door.
  5758.                         BID12.ZIP     BBS info. door for new BBS users
  5759.  
  5760.                When displayed, OpenDoors will list the size of each file found
  5761.                in the FILES.BBS file beside it's name, if the file is found. If
  5762.                the file does not exist, then a "[OFFLINE]" string is displayed
  5763.                in the file size column. Title lines may also be added to the
  5764.                FILES.BBS, by indenting them one or more columns. Thus, you
  5765.                could have something like:
  5766.  
  5767.                            NEWEST UPLOADS
  5768.                            ~~~~~~~~~~~~~~
  5769.                         PKZ110.EXE    PKZip file compressor, version 1.10
  5770.                         ODOORS40.LZH  The newest version of OpenDoors!
  5771.                         EZVOTE40.ZIP  EZVote user voting door.
  5772.                         BID12.ZIP     BBS info. door for new BBS users
  5773.  
  5774.                In addition to this standard FILES.BBS format, OpenDoors will
  5775.                also permit wildcards to be used in FILES.BBS filenames (ie
  5776.                FNEWS???.*), or full directory paths to allow files from several
  5777.                different directories to be included in the same files area.
  5778.  
  5779. ===============================================================================
  5780. OpenDoors 5.00 Manual                                            End of Page 98
  5781.  
  5782.  
  5783.  
  5784.                You may alter the colours used to display the various portions
  5785.                of the files list using the od_control variables:
  5786.  
  5787.                          od_control.od_list_title_col
  5788.                          od_control.od_list_name_col
  5789.                          od_control.od_list_size_col
  5790.                          od_control.od_list_comment_col
  5791.                          od_control.od_list_offline_col
  5792.  
  5793.                which are documented in the OpenDoors control structure section
  5794.                on this manual, which begins on page 145.
  5795.  
  5796.  
  5797. SEE ALSO       od_send_file()
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.  
  5819.  
  5820.  
  5821.  
  5822.  
  5823.  
  5824.  
  5825.  
  5826.  
  5827.  
  5828.  
  5829.  
  5830.  
  5831.  
  5832.  
  5833.  
  5834.  
  5835.  
  5836.  
  5837.  
  5838. ===============================================================================
  5839. OpenDoors 5.00 Manual                                            End of Page 99
  5840.  
  5841.  
  5842.  
  5843.  
  5844.  
  5845.  
  5846. OD_LOG_WRITE()
  5847. -------------------------------------------------------------------------------
  5848.  
  5849. PURPOSE        Function to write an entry to the log file
  5850.  
  5851.  
  5852. FORMAT         int od_log_write(char *message);
  5853.  
  5854.  
  5855. RETURNS        TRUE on success, or FALSE on failure
  5856.  
  5857.  
  5858. DESCRIPTION    This function can be used to write entries to the log file. If
  5859.                the logfile has not already been opened when you call this
  5860.                function for the first time, OpenDoors will automatically open
  5861.                the log file at that time.
  5862.  
  5863.                To create an entry in the log file, simply call the
  5864.                od_log_write() function, passing to it the string of the text
  5865.                you wish to write. You should not include any control characters
  5866.                in this string, simply the text that should appear on the line.
  5867.                OpenDoors will automatically format the log file, adding the
  5868.                time information and other control characters. It is recommended
  5869.                that the length of the string passed to od_log_write() not
  5870.                exceed 67 characters, in order that logfile lines will all be
  5871.                less than 80 characters in length.
  5872.  
  5873.                Log file entries do not usually contain periods or other
  5874.                punctuation at the end of the line. Also, log file entries are
  5875.                usually written in the present tense. The first character of the
  5876.                entry is usually upper-case, with all other entries in lower
  5877.                case. Also, since excessive numbers or lengths of log file
  5878.                entries can quickly use a lot of disk space, it is best to think
  5879.                carefully about what events should be recorded in the log file.
  5880.                It is also a good idea to minimize the number of words used in
  5881.                the entry, without being too cryptic. As an example, "User
  5882.                entering options menu" should be used instead of "user entered
  5883.                the options menu."
  5884.  
  5885.  
  5886. SEE ALSO       Page 215.
  5887.  
  5888.  
  5889. EXAMPLE        Calling the od_log_write() function is as simple as follows:
  5890.  
  5891.                     od_log_write("Awarding user with 5 minutes more time");
  5892.  
  5893.  
  5894.  
  5895.  
  5896.  
  5897. ===============================================================================
  5898. OpenDoors 5.00 Manual                                           End of Page 100
  5899.  
  5900.  
  5901.  
  5902.  
  5903.  
  5904.  
  5905. OD_PAGE()
  5906. -------------------------------------------------------------------------------
  5907.  
  5908. PURPOSE        Function to allow user to page the sysop
  5909.  
  5910.  
  5911. FORMAT         void od_page(void);
  5912.  
  5913.  
  5914. RETURNS        N/A
  5915.  
  5916.  
  5917. DESCRIPTION    This function can be called to allow the user to page the sysop.
  5918.                This function will ask the user why they wish to chat with the
  5919.                sysop, and then page the sysop. The sysop will then be free to
  5920.                break into chat at any time. Sysop paging will also be aborted
  5921.                by the user, simply by pressing [Enter] when asked for a reason
  5922.                for chat. When the user pages the sysop, the [Wants-Chat]
  5923.                indicator will begin to flash on the main status line, and the
  5924.                status line will switch to show the user's reason for wanting to
  5925.                chat. Also, the user's total number of pages will be
  5926.                incremented.
  5927.  
  5928.                Depending upon the setting of the od_control.od_okaytopage
  5929.                variable, this function will also optionally check sysop paging
  5930.                hours, and only allow the user to page the sysop during valid
  5931.                paging hours. For information on the variables containing the
  5932.                user's total number of pages, the user's want-chat status, valid
  5933.                sysop paging hours, and the od_control.od_okaytopage variable,
  5934.                see the section on the OpenDoors control structure, which begins
  5935.                on page 145.
  5936.  
  5937.  
  5938. EXAMPLE        For an example of the use of the od_page() function, see the
  5939.                EZVote example door, which is described beginning on page 38.
  5940.  
  5941.  
  5942.  
  5943.  
  5944.  
  5945.  
  5946.  
  5947.  
  5948.  
  5949.  
  5950.  
  5951.  
  5952.  
  5953.  
  5954.  
  5955.  
  5956. ===============================================================================
  5957. OpenDoors 5.00 Manual                                           End of Page 101
  5958.  
  5959.  
  5960.  
  5961.  
  5962.  
  5963.  
  5964. OD_POPUP_MENU()
  5965. -------------------------------------------------------------------------------
  5966.  
  5967. PURPOSE        Creates a popup menu which allows the user to make a selection
  5968.                by pressing a single key, or selecting the item with a highlight
  5969.                bar. After the user has made a selection, the menu may be
  5970.                removed from the screen, restoring the original screen contents
  5971.                "beneath" the window.
  5972.  
  5973.  
  5974. FORMAT         int od_popup_menu(char *title, char *text, int left, int top,
  5975.                int level, unsigned int flags);
  5976.  
  5977.  
  5978. RETURNS        POPUP_ERROR    On error (od_control.od_error is set to
  5979.                               indicate type of error).
  5980.                POPUP_ESCAPE   If user exited menu by pressing [ESCape].
  5981.                POPUP_LEFT     If user exited menu by pressing the left arrow
  5982.                               key.
  5983.                POPUP_RIGHT    If user exited menu by pressing the right arrow
  5984.                               key.
  5985.  
  5986.                Or, a postive integer indicating the menu item that was chosen
  5987.                if a selection was made.
  5988.  
  5989.  
  5990. DESCRIPTION    od_popup_menu() creates a popup window with a menu of choices,
  5991.                for use in ANSI/AVATAR/RIP modes. The user is able to choose an
  5992.                item from the menu by moving the highlighted selection bar with
  5993.                the arrow keys, or by pressing a key associated with a
  5994.                particular menu item. The contents of the menu are defined by
  5995.                the string pointed to by the text parameter. This menu
  5996.                definition string contains each menu option, seperated by a '|'
  5997.                (pipe) character. Keys associated with each menu entry can be
  5998.                defined by proceeding the letter with a '^' (carat) character.
  5999.                For example, the string:
  6000.  
  6001.                     "^Save|^Load|E^xit"
  6002.  
  6003.                would produce a menu with three options: Save, Load and Exit.
  6004.                The user would be able to select the Save option by pressing the
  6005.                [S] key, the Load option by pressing the [L] key, and the Exit
  6006.                option by pressing the [X] key. Furthermore, the characters
  6007.                corresponding to each menu item would be displayed in a
  6008.                highlighted color.
  6009.  
  6010.                Menus displayed with od_popup_menu() may optionally have a
  6011.                title, as specified by the title parameter. If this parameter is
  6012.                set to NULL, no title will be displayed. If this parameter is
  6013.  
  6014.  
  6015. ===============================================================================
  6016. OpenDoors 5.00 Manual                                           End of Page 102
  6017.  
  6018.  
  6019.                not NULL, the specified string will be displayed as a title on
  6020.                the window.
  6021.  
  6022.                The left and top parameters specify the left and top locations
  6023.                of the menu window, were 1, 1 is the upper right corner of the
  6024.                screen. The bottom and right corners of the menu are
  6025.                automatically determined by the size and number of menu entries
  6026.                in the menu definition string.
  6027.  
  6028.                The level parameter specifies the menu level, an integer from 0
  6029.                to 9. Unless you are using the MENU_KEEP flag, this parameter
  6030.                should always be 0.
  6031.  
  6032.                The flags parameter specifies one or more of the following
  6033.                options, joined by the bitwise-OR operator (|).
  6034.  
  6035.                     MENU_NORMAL         Has no effect.
  6036.                     MENU_ALLOW_CANCEL   Allow user to exit menu with [ESCape].
  6037.                     MENU_PULLDOWN       Allow exit with arrow keys.
  6038.                     MENU_KEEP           Leave menu active on seleion.
  6039.                     MENU_DESTROY        Remove a currently active menu.
  6040.  
  6041.                If you are not using any of the other flags, you can use
  6042.                MENU_NORMAL as a place-holder for this parameter. If you
  6043.                sepecify MENU_ALLOW_CANCEL, the user will be able to exit the
  6044.                menu without making a selection by pressing the [ESCape] key. If
  6045.                the user presses [ESCape], od_popup_menu() returns POPUP_ESCAPE.
  6046.  
  6047.                You can use the MENU_PULLDOWN option with od_popup_menu() to
  6048.                implement a set of pulldown menus. In this case, if the user
  6049.                presses the left arrow key or right arrow key while the menu is
  6050.                being displayed, od_popup_menu() returns with POPUP_LEFT or
  6051.                POPUP_RIGHT, allowing you to display a different menu.
  6052.  
  6053.                Normally, od_popup_menu() will remove the menu from the screen
  6054.                as soon as the user makes a selection. However, there may be
  6055.                some cases when you want the menu to continue to be visible
  6056.                after the user makes a selection. For example, you may want some
  6057.                menu options to lead to further sub-menus, or you may wish to
  6058.                display a popup window, and return to this menu after the user
  6059.                has exited from the popup window. If the MENU_KEEP flag is
  6060.                specified, the menu will remain active (on-screen) after the
  6061.                user makes a selection. However, the menu will still be
  6062.                destroyed if the user cancels out of the menu (this will only
  6063.                happen if you have specified MENU_ALLOW_CANCEL), or if the user
  6064.                moves to another menu by pressing the left or right arrow keys
  6065.                (this will only happen if you have specified MENU_PULLDOWN). If
  6066.                MENU_KEEP has been specified, and the user makes a selection,
  6067.                you must eventually either return to the menu, or destroy it by
  6068.                calling MENU_DESTROY. If you want to return to the menu, simply
  6069.                call od_popup_menu() again with the same level value that was
  6070.                used to originally create the menu. The user will now be able to
  6071.                make another selection from the menu, and od_popup_menu() will
  6072.                once again return that selection to you. If you want to destory
  6073.  
  6074. ===============================================================================
  6075. OpenDoors 5.00 Manual                                           End of Page 103
  6076.  
  6077.  
  6078.                the menu, simply call od_popup_menu() with the MENU_DESTROY flag
  6079.                set, and the same level value that was used to create the
  6080.                original menu. If you wish to create another popup menu while
  6081.                the first one is still active, simplly call od_popup_menu()
  6082.                again, this time with a different level value.
  6083.  
  6084.                The colors used by the od_popup_menu() function are set by the
  6085.                following OpenDoors control structure settings:
  6086.  
  6087.                     char od_control.od_menu_title_col;
  6088.                     char od_control.od_menu_border_col;
  6089.                     char od_control.od_menu_text_col;
  6090.                     char od_control.od_menu_key_col;
  6091.                     char od_control.od_menu_highlight_col;
  6092.                     char od_control.od_menu_highkey_col;
  6093.  
  6094.  
  6095. SEE ALSO       od_window_create(), od_window_remove(), od_draw_box(),
  6096.                od_hotkey_menu()
  6097.  
  6098.  
  6099.  
  6100.  
  6101.  
  6102.  
  6103.  
  6104.  
  6105.  
  6106.  
  6107.  
  6108.  
  6109.  
  6110.  
  6111.  
  6112.  
  6113.  
  6114.  
  6115.  
  6116.  
  6117.  
  6118.  
  6119.  
  6120.  
  6121.  
  6122.  
  6123.  
  6124.  
  6125.  
  6126.  
  6127.  
  6128.  
  6129.  
  6130.  
  6131.  
  6132.  
  6133. ===============================================================================
  6134. OpenDoors 5.00 Manual                                           End of Page 104
  6135.  
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141. OD_PRINTF()
  6142. -------------------------------------------------------------------------------
  6143.  
  6144. PURPOSE        Performs formatted output (remote & local), with the ability to
  6145.                change display colours.
  6146.  
  6147.  
  6148. FORMAT         void od_printf(char *format,...);
  6149.  
  6150.  
  6151. RETURNS        N/A
  6152.  
  6153.  
  6154. DESCRIPTION    This is one of two OpenDoors function which allows you to
  6155.                display a string of characters, the other being the
  6156.                od_disp_str() function. For a complete comparison of the various
  6157.                OpenDoors display function, see the description of the
  6158.                od_disp_str() function, on page 64. Like the od_disp_str()
  6159.                function, the od_printf() function will display its output both
  6160.                on the local screen, and on the remote user's screen (if the
  6161.                door is not operating in local mode). However, the od_printf()
  6162.                function also allows for formatted output, just as the printf()
  6163.                function does. In addition to providing all of the features of
  6164.                the normal C printf() function, the od_printf() function allows
  6165.                you to include codes to change the colour of the display of
  6166.                text. This unique feature allows you to display multi-coloured
  6167.                text, without having to use chains of alternating od_disp_str()
  6168.                and od_set_colour() calls.
  6169.  
  6170.                As with the printf() function, the od_printf() function accepts
  6171.                one or more parameters, the first parameter being the format
  6172.                string to be displayed, and the additional parameters being data
  6173.                to be displayed within the string. The OpenDoors od_printf()
  6174.                function recognizes all of the control characters and options
  6175.                recognized by the normal printf() function. For example, to
  6176.                display the amount of time that a user has left online, the
  6177.                following line would be a valid use of the od_printf() function:
  6178.  
  6179.                     od_printf("Time Left:%d\n\r", od_control.user_timelimit);
  6180.  
  6181.                Note that a full discussion of the printf() function is beyond
  6182.                the scope of this manual. For more information on using
  6183.                printf(), please see your Turbo C(++) / Borland C++ manuals.
  6184.  
  6185.                In addition to the normal control sequences, such as "%s", "%d",
  6186.                or "%12.12s", the od_printf() function also allows you to
  6187.                include special colour-setting codes within the format string.
  6188.                These colour code sequences BEGIN and END with a delimiter
  6189.                character, which is used to indicate that the sequence is a
  6190.  
  6191.  
  6192. ===============================================================================
  6193. OpenDoors 5.00 Manual                                           End of Page 105
  6194.  
  6195.  
  6196.                colour setting. Consider, for example, the following line of
  6197.                code, which displays text in various colours:
  6198.  
  6199.                        od_printf("`blue`Blue `green`Green `red`Red  \n\r");
  6200.  
  6201.                In this case (assuming of course that a colour monitor is being
  6202.                used) the word "Blue" will be displayed in the colour blue, the
  6203.                word "Green" will be displayed in the colour green, and the word
  6204.                "Red" will be displayed in the colour red. In this case, the
  6205.                sequence `blue` sets the display colour to dark blue on black.
  6206.                Here, the back-quote (`) is the delimiter character which
  6207.                indicates the beginning and end of the colour sequence. Be sure
  6208.                not to confuse the back-quote character (`) with the normal
  6209.                forward quote ('). THIS IS THE MOST COMMON DIFFICULTY
  6210.                EXPERIENCED WITH THE OD_PRINTF() FUNCTION. The text between the
  6211.                back-quote characters indicates the colour that should be set.
  6212.                This text can include the name of the foreground colour, the
  6213.                name of the background colour, the "bright" keyword and the
  6214.                "flashing" keyword. The first colour mentioned is taken to be
  6215.                the foreground colour, and the second the background colour.
  6216.                Case is not sensitive, additional words can be included for
  6217.                legibility. Thus:
  6218.  
  6219.                          `bright white cyan`
  6220.  
  6221.                is equivalent to:
  6222.  
  6223.                          `Bright white on a cyan background`.
  6224.  
  6225.                The "bright" keyword indicates that the foreground colour should
  6226.                be displayed in high intensity, and the "flashing" keyword
  6227.                indicates that the text should be flashing. If no background is
  6228.                specified, the background colour defaults to black. If no
  6229.                foreground or background colours are specified, the colour
  6230.                defaults to white on black.
  6231.  
  6232.                The od_printf() function will automatically determine whether
  6233.                the user has ANSI, AVATAR or RIP graphics enabled, and will send
  6234.                the appropriate colour codes to change the colour of displayed
  6235.                text. If the user does not have either ANSI or AVATAR graphics
  6236.                modes turned on, then the od_printf() function will not send any
  6237.                colour codes. Thus, a door program using colour codes would work
  6238.                just as well when ANSI/AVATAR/RIP graphics are not available,
  6239.                except that all text will appear in the same colour.
  6240.  
  6241.                You may prefer to set colours by using the od_set_colour() or
  6242.                od_set_attrib() functions, instead of using these cryptic colour
  6243.                codes imbedded in od_printf() functions. In some cases, however,
  6244.                it will be much more advantageous to place the colour codes
  6245.                within your od_printf() strings. As a case in point, consider
  6246.                the single od_printf() statement in the example, above. To
  6247.                accomplish the same result using the od_disp_str() and
  6248.                od_set_colour() functions, you would have to use the following
  6249.                SIX function calls:
  6250.  
  6251. ===============================================================================
  6252. OpenDoors 5.00 Manual                                           End of Page 106
  6253.  
  6254.  
  6255.  
  6256.                        od_set_colour(D_BLUE,D_BLACK);
  6257.                        od_disp_str("Blue ");
  6258.                        od_set_colour(D_GREEN,D_BLACK);
  6259.                        od_disp_str("Green ");
  6260.                        od_set_colour(D_RED,D_BLACK);
  6261.                        od_disp_str("Red  \n\r");
  6262.  
  6263.                While this method MAY be easier understand, it certainly
  6264.                requires many more line of code to accomplish. However, either
  6265.                method will work, and the choice is up to you as to which method
  6266.                you prefer. Keep in mind, however, that if the colour to be set
  6267.                is stored in a variable, instead of always being the same
  6268.                colour, you must use either the od_set_colour() or
  6269.                od_set_attrib() function to set the display colour.
  6270.  
  6271.                While the back-quote (`) character is normally used to delimit a
  6272.                colour sequence in the od_printf() function, you may wish to be
  6273.                able to print a back-quote character using the od_printf()
  6274.                function. In this case, you may configure OpenDoors to use a
  6275.                different character to represent colour code sequences. To do
  6276.                this, simply use the od_control.od_colour_delimiter variable,
  6277.                which is described in the OpenDoors control structure section,
  6278.                beginning on page 145. For example, if you wished to use the
  6279.                tilde (~) character instead of the back-quote character to
  6280.                change colours, simply place the following line within your
  6281.                program, at some point after having called od_init() or some
  6282.                OpenDoors function:
  6283.  
  6284.                        od_control.od_colour_delimiter='~';
  6285.  
  6286.                Also, you may disable the colour code interpretation within the
  6287.                od_printf() function altogether, by setting the
  6288.                od_control.od_colour_delimiter variable to 0.
  6289.  
  6290.                Note that the od_printf() function interprets the colour codes
  6291.                AFTER parsing the other control sequences, such as "%d" or "%s".
  6292.                Thus, if you used the command:
  6293.  
  6294.                        od_printf("%s",string);
  6295.  
  6296.                Any colour codes contained in the string "string" would also be
  6297.                interpreted. If you did not wish to have any colour code
  6298.                characters which might be contained in the string "string"
  6299.                treated as such, you could again disable od_printf()'s colour
  6300.                code interpretation, by setting the od_control.od_colour_char
  6301.                variable to 0.
  6302.  
  6303.                Note that the string to be displayed by od_printf() should not
  6304.                exceed 511 characters in size, including the size of color
  6305.                sequences and expanded % fields.
  6306.  
  6307.  
  6308. SEE ALSO       od_disp_str(), od_disp(), od_putch(), od_repeat(), od_disp_emu()
  6309.  
  6310. ===============================================================================
  6311. OpenDoors 5.00 Manual                                           End of Page 107
  6312.  
  6313.  
  6314.  
  6315.  
  6316. EXAMPLE        Below is a simple example of a user statistics door program,
  6317.                which displays various pieces of information to the user, by
  6318.                using the od_printf() function. Notice the use of colour code
  6319.                sequences in order to display the titles in a different colour
  6320.                from the information fields. Note that since the information
  6321.                available to this door will depend on the BBS system under which
  6322.                it is running, not all of the information displayed by this door
  6323.                will be available under all BBS systems. For a description of
  6324.                what information is available under what BBS systems, see the
  6325.                OpenDoors control structure portion of this manual, which begins
  6326.                on page 145.
  6327.  
  6328.  
  6329. #include "opendoor.h"
  6330.  
  6331. int main(int argc,char *argv[])
  6332.    {
  6333.    od_init();                                     /* Begin OpenDoors program */
  6334.  
  6335.    od_printf("`bright white` YOUR STATISTICS\n\r");         /* Display title */
  6336.    od_printf("---------------\n\r\n\r");
  6337.  
  6338.                                                        /* Display statistics */
  6339.    od_printf("`red`NAME :             `blue`%s\n\r",od_control.user_logintime);
  6340.    od_printf("`red`LOCATION :         `blue`%s\n\r",od_control.user_location);
  6341.    od_printf("`red`PHONE NUMBER :     `blue`%s\n\r",od_control.user_homephone);
  6342.    od_printf("`red`LAST CALL :        `blue`%s\n\r",od_control.user_lastdate);
  6343.    od_printf("`red`NUMBER OF CALLS :  `blue`%u\n\r",od_control.user_numcalls);
  6344.    od_printf("`red`NUMBER OF PAGES :  `blue`%u\n\r",od_control.user_numpages);
  6345.    od_printf("`red`REMAINING TIME :   `blue`%d\n\r",od_control.user_timelimit);
  6346.    od_printf("`red`# OF DOWNLOADS :   `blue`%u\n\r",od_control.user_downloads);
  6347.    od_printf("`red`# OF UPLOADS :     `blue`%u\n\r",od_control.user_uploads);
  6348.    od_printf("`red`KBYTES DL TODAY :  `blue`%u\n\r",od_control.user_todayk);
  6349.  
  6350.                                                 /* Ask user to press [Enter] */
  6351.    od_printf("`bright green on green`Press [Enter] to return to BBS...\n\r");
  6352.  
  6353.    while(od_get_key(TRUE)!=13);            /* Wait for user to press [Enter] */
  6354.  
  6355.    od_exit(20,FALSE);                                       /* Return to BBS */
  6356.    }
  6357.  
  6358.  
  6359. HELPFUL        This section demonstrates use of the od_printf() colour
  6360. HINT           sequences imbedded directly in the printf() format string, such
  6361.                as:
  6362.  
  6363.                          od_printf("Hello `bright green` there!");
  6364.  
  6365.                However, there are also other ways that you can take advantage
  6366.                of this feature. For example, the C programming language
  6367.  
  6368.  
  6369. ===============================================================================
  6370. OpenDoors 5.00 Manual                                           End of Page 108
  6371.  
  6372.  
  6373.                concatenates string constants that are separated only by white
  6374.                space or carriage returns. For instance,
  6375.  
  6376.                          "Hello " "`bright green`" " there!"
  6377.  
  6378.                is equivalent to:
  6379.  
  6380.                          "Hello `bright green` there!"
  6381.  
  6382.                For this reason, you can create macros for common colour
  6383.                sequences in your program, such as:
  6384.  
  6385.                          #define HIGHLIGHT "`bright green`"
  6386.  
  6387.                You can then use such constants when calling the od_printf()
  6388.                function, as follows:
  6389.  
  6390.                          od_printf("Hello " HIGHLIGHT " there!");
  6391.  
  6392.                You may find this method of setting the display colour to be
  6393.                easier to read, and more easily configurable than including the
  6394.                colour sequence directly in the format string. Below another use
  6395.                of the colour sequences is describe, which allows the colours
  6396.                used by od_printf() not be "hard-wired".
  6397.  
  6398.  
  6399.                Since colour control sequences are evaluated by od_printf()
  6400.                after it evaluates all format sequences (such as "%d"). For this
  6401.                reason, it is possible to change the display colour using a
  6402.                string variable, instead of using a fixed colour in the string.
  6403.                For example, if you program had the variable:
  6404.  
  6405.                          char highlight[40];
  6406.  
  6407.                which was set at some point to be equal to:
  6408.  
  6409.                          "`bright green`"
  6410.  
  6411.                you would be able to use od_printf() as follows:
  6412.  
  6413.                          od_printf("Hello %s there!", highlight);
  6414.  
  6415.                The display colour would then be changed at the location where
  6416.                the "%s" appears in the od_printf() format string. The advantage
  6417.                of using this method to change display colours is that unlike
  6418.                other methods, the value of the highlight variable can be
  6419.                changed. This could be used, for example, to allow the sysop to
  6420.                configure the colours they wish your door to use. You would only
  6421.                need to change the value of the highlight variable in order to
  6422.                change the colour set by od_printf().
  6423.  
  6424.  
  6425.  
  6426.  
  6427.  
  6428. ===============================================================================
  6429. OpenDoors 5.00 Manual                                           End of Page 109
  6430.  
  6431.  
  6432.  
  6433.  
  6434.  
  6435.  
  6436. OD_PUTCH()
  6437. -------------------------------------------------------------------------------
  6438.  
  6439. PURPOSE        Function to display a single character.
  6440.  
  6441.  
  6442. FORMAT         void od_putch(int character);
  6443.  
  6444.  
  6445. RETURNS        N/A
  6446.  
  6447.  
  6448. DESCRIPTION    This function performs a similar function to the other OpenDoors
  6449.                display functions. For information on the uses of the various
  6450.                OpenDoors display functions, see the description of the
  6451.                od_disp_str() function, on page 64. This function is most
  6452.                similar to the od_disp() and od_disp_str() functions, except
  6453.                that it only displays a single character at a time.
  6454.  
  6455.                This function will display the character passed to it at the
  6456.                cursor position in the output window, and then advance the
  6457.                cursor to the next display position. If OpenDoors is not
  6458.                operating in local mode, the character will also be sent to the
  6459.                modem, and thus displayed on the user's screen in the same
  6460.                manner that it is displayed on the local screen. If ANSI, AVATAR
  6461.                or RIP graphics mode is activated the character will be
  6462.                displayed in the current colour.
  6463.  
  6464.  
  6465. SEE ALSO       od_disp_str(), od_disp(), od_printf(), od_repeat(),
  6466.                od_disp_emu()
  6467.  
  6468.  
  6469. EXAMPLE        Below is an example of the use of the od_putch() function. This
  6470.                example is a function which you could use in place of the
  6471.                od_get_key() function. This function inputs a single character
  6472.                from the keyboard, just as the od_get_key() function does.
  6473.                However, if the character entered is a printable character, the
  6474.                function will also echo the character to the local screen, using
  6475.                the od_putch() function. This is helpful for a user to know what
  6476.                key they have pressed within your door.
  6477.  
  6478.                char get_key_with_echo(int wait)
  6479.                   {
  6480.                   char pressed=od_get_key(wait);        /* Get key from user */
  6481.  
  6482.                   if(pressed>=32 && pressed<=126)     /* If key is printable */
  6483.                      {
  6484.                      od_putch(pressed);             /* Display the character */
  6485.                      }
  6486.  
  6487. ===============================================================================
  6488. OpenDoors 5.00 Manual                                           End of Page 110
  6489.  
  6490.  
  6491.  
  6492.                   return(pressed);             /* Return key pressed by user */
  6493.                   }
  6494.  
  6495.                For a further example of the user of the od_putch() function,
  6496.                see the example accompanying the od_repeat() function, which is
  6497.                described on page 114.
  6498.  
  6499.  
  6500.  
  6501.  
  6502.  
  6503.  
  6504.  
  6505.  
  6506.  
  6507.  
  6508.  
  6509.  
  6510.  
  6511.  
  6512.  
  6513.  
  6514.  
  6515.  
  6516.  
  6517.  
  6518.  
  6519.  
  6520.  
  6521.  
  6522.  
  6523.  
  6524.  
  6525.  
  6526.  
  6527.  
  6528.  
  6529.  
  6530.  
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.  
  6539.  
  6540.  
  6541.  
  6542.  
  6543.  
  6544.  
  6545.  
  6546. ===============================================================================
  6547. OpenDoors 5.00 Manual                                           End of Page 111
  6548.  
  6549.  
  6550.  
  6551.  
  6552.  
  6553.  
  6554. OD_PUTTEXT()
  6555. -------------------------------------------------------------------------------
  6556.  
  6557. PURPOSE        Displays a rectangular region of text and colour information, as
  6558.                previously stored using od_gettext()
  6559.  
  6560.  
  6561. FORMAT         int od_puttext(int left, int top, int right, int bottom, void
  6562.                *block);
  6563.  
  6564.  
  6565. RETURNS        TRUE on success
  6566.                FALSE on failure
  6567.  
  6568.  
  6569. DESCRIPTION    This function "pastes" a rectangular block of text and colour
  6570.                information that has been previously retrieved using
  6571.                od_gettext(). The block is placed at the screen location
  6572.                indicated by the variables "left", "top", "right" and "bottom",
  6573.                where "left" and "right" are column numbers from 1 - 80, and
  6574.                "top" and "bottom" are row numbers from 1 - 23. The length and
  6575.                width of the rectangle specified by "left", "top", "right" and
  6576.                "bottom" must be the same as the length and width of the
  6577.                rectangle passed to od_gettext() when storing the block of text.
  6578.  
  6579.                This function attempts to display the pasted block as quickly as
  6580.                possible, only transmitting information on portions of the block
  6581.                that are different than the original screen contents. When this
  6582.                function returns, it leaves the cursor at its original position,
  6583.                and the display colour at its original setting. This function
  6584.                requires ANSI or AVATAR graphics mode.
  6585.  
  6586.                The control structure variable od_control.od_full_put may be set
  6587.                to TRUE to force od_puttext() to always send all characters in
  6588.                the block to be displayed, instead of only displaying the
  6589.                portions of the block that differ from the original screen
  6590.                contents.
  6591.  
  6592.                If you wish to save and restore the entire screen, you may use
  6593.                od_save_screen() and od_restore_screen(), which work in all
  6594.                display modes.
  6595.  
  6596.                You may also use the od_puttext() to display a rectangular block
  6597.                of text that you generate manually, instead of retrieving using
  6598.                od_gettext(). To do this, you pass an array which contains the
  6599.                text and colour information for the rectangular area to be
  6600.                painted, in the "block" parameter. The array passed to
  6601.                od_puttext() contains a two-byte sequence of information for
  6602.                each character in the rectangle. The first byte contains the
  6603.                ASCII code of the character to be displayed. The second byte
  6604.  
  6605. ===============================================================================
  6606. OpenDoors 5.00 Manual                                           End of Page 112
  6607.  
  6608.  
  6609.                contains the colour attribute value of the character, in the
  6610.                same format as used by the od_set_attrib() function (described
  6611.                on page 125). These two byte sequences are stored in the order
  6612.                in which English is written; the array begins with the two byte
  6613.                sequences for all of the characters on the first line, from left
  6614.                to right, followed by the characters for the second line, and so
  6615.                on. The length of each line must be exactly equal to the width
  6616.                of the rectangular region to be painted.
  6617.  
  6618.                If od_puttext() fails for any reason, a value of FALSE is
  6619.                returned, and the od_control.od_error variable is set to
  6620.                indicate the reason for the failure. For more information on the
  6621.                od_control.od_error variable, see page 182.
  6622.  
  6623.  
  6624. SEE ALSO       od_gettext(), od_save_screen(), od_restore_screen(),
  6625.                od_scroll(), od_window_create(), od_window_remove()
  6626.  
  6627.  
  6628. EXAMPLE        For an example of the user of the od_puttext() function, see the
  6629.                example that accompanies the description of the od_gettext()
  6630.                function. The od_gettext() function is documented on page 88.
  6631.  
  6632.  
  6633.  
  6634.  
  6635.  
  6636.  
  6637.  
  6638.  
  6639.  
  6640.  
  6641.  
  6642.  
  6643.  
  6644.  
  6645.  
  6646.  
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.  
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.  
  6661.  
  6662.  
  6663.  
  6664. ===============================================================================
  6665. OpenDoors 5.00 Manual                                           End of Page 113
  6666.  
  6667.  
  6668.  
  6669.  
  6670.  
  6671.  
  6672. OD_REPEAT()
  6673. -------------------------------------------------------------------------------
  6674.  
  6675. PURPOSE        Repeatedly display the specified character any number of times,
  6676.                using special graphics codes for greater speed, if possible.
  6677.  
  6678.  
  6679. FORMAT         void od_repeat(char value,unsigned char times);
  6680.  
  6681.  
  6682. RETURNS        N/A
  6683.  
  6684.  
  6685. DESCRIPTION    This display function will repeatedly display the character
  6686.                "value", "times" times. For a complete breakdown of the various
  6687.                OpenDoors display functions, see the description of the
  6688.                od_disp_str() function, located on page 64.
  6689.  
  6690.                The advantage of using this function to display a series of
  6691.                identical characters is that this function will use special
  6692.                graphics-mode control sequences to display the repeated
  6693.                character very efficiently, if the required graphics mode is
  6694.                available. For example, in AVATAR mode, this function can
  6695.                display an entire line of one character, by sending a control
  6696.                sequence to the modem that is only three characters long. If
  6697.                graphics mode is not turned on, then the od_disp_str() function
  6698.                will simply send the specified character the appropriate number
  6699.                of times. As with the other display functions, the output of
  6700.                this function is sent to both the local and remote screens.
  6701.  
  6702.  
  6703. SEE ALSO       od_putch(), od_disp_str(), od_disp(), od_printf(), od_disp_emu()
  6704.  
  6705.  
  6706. EXAMPLE        The example function below demonstrates the use of the
  6707.                od_repeat() function in drawing a window (a square box) on the
  6708.                screen. This function is essentially a simplified version of the
  6709.                od_draw_box() function, which is described on page 66. Unlike
  6710.                this function, the od_draw_box() function allows the
  6711.                customization of the characters used to draw the box's boarder,
  6712.                and if possible uses additional AVATAR graphics codes to display
  6713.                the window even faster than this function does. Thus, the
  6714.                function below is really provided for demonstration purposes
  6715.                only.
  6716.  
  6717.                This function accepts four parameters, which indicate the
  6718.                location of the upper left and lower right corners of the window
  6719.                to be displayed. The function then displays the window with the
  6720.                current colour attribute settings. Since this function uses the
  6721.                od_repeat() function, if AVATAR graphics are available, it can
  6722.  
  6723. ===============================================================================
  6724. OpenDoors 5.00 Manual                                           End of Page 114
  6725.  
  6726.  
  6727.                display the entire window in a fraction of a second, even if it
  6728.                is displaying a window the size of the entire screen at slow
  6729.                baud rates. Note that this window display function requires that
  6730.                the user has ANSI, AVATAR or RIP graphics mode enabled.
  6731.  
  6732.                void draw_window(char left, char top, char right, char bottom)
  6733.                   {
  6734.                   char line_counter;   /* Number of current line being drawn */
  6735.                   char between_size=(right-left)-1;      /* X size of window */
  6736.  
  6737.                   od_set_cursor(top,left);             /* move to top corner */
  6738.                   od_putch(218);                 /* display corner character */
  6739.                   od_repeat(196,between_size);           /* display top line */
  6740.                   od_putch(191);                 /* display corner character */
  6741.                                       /* loop through middle lines of window */
  6742.                   for(line_counter=top+1;line_counter<bottom;++line_counter)
  6743.                      {
  6744.                      od_set_cursor(line_counter,left); /* move to line start */
  6745.                      od_putch(179);                /* display left line char */
  6746.                      od_repeat(' ',between_size);      /* display blank area */
  6747.                      od_putch(179);               /* display right line char */
  6748.                      }
  6749.  
  6750.                   od_set_cursor(bottom,left);       /* move to bottom corner */
  6751.                   od_putch(192);                 /* display corner character */
  6752.                   od_repeat(196,between_size);        /* display bottom line */
  6753.                   od_putch(217);                 /* display corner character */
  6754.                   }
  6755.  
  6756.  
  6757.  
  6758.  
  6759.  
  6760.  
  6761.  
  6762.  
  6763.  
  6764.  
  6765.  
  6766.  
  6767.  
  6768.  
  6769.  
  6770.  
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.  
  6777.  
  6778.  
  6779.  
  6780.  
  6781.  
  6782. ===============================================================================
  6783. OpenDoors 5.00 Manual                                           End of Page 115
  6784.  
  6785.  
  6786.  
  6787.  
  6788.  
  6789.  
  6790. OD_RESTORE_SCREEN()
  6791. -------------------------------------------------------------------------------
  6792.  
  6793. PURPOSE        Restores the screen contents as previous saved using the
  6794.                od_save_screen() function. This function can be used in any
  6795.                display mode.
  6796.  
  6797.  
  6798. FORMAT         int od_restore_screen(void *buffer);
  6799.  
  6800.  
  6801. RETURNS        TRUE on success
  6802.                FALSE on failure
  6803.  
  6804. DESCRIPTION    This function restores the entire contents of the screen, along
  6805.                with the current cursor position and display colour, which was
  6806.                previously stored using the od_save_screen() function. Unlike
  6807.                the od_get_text() and od_put_text() functions, the
  6808.                od_save_screen() and od_restore_screen() functions will work in
  6809.                all display modes (ASCII, ANSI, AVATAR and RIP).
  6810.  
  6811.                The "buffer" parameter must point to the buffer previously
  6812.                passed to od_save_screen(). Note that the od_save_screen() and
  6813.                od_restore_screen() functions save the stored information in
  6814.                different formats than the od_getttext() and od_puttext()
  6815.                functions. For this reason, you cannot save the screen contents
  6816.                with od_gettext() and restore them with od_restore_screen(), or
  6817.                visa-versa.
  6818.  
  6819.                If this function fails for any reason, a value of FALSE is
  6820.                returned, and the od_control.od_error variable is set to
  6821.                indicate the reason for the failure. For more information on the
  6822.                od_control.od_error variable, see page 182.
  6823.  
  6824.  
  6825. SEE ALSO       od_save_screen(), od_gettext(), od_puttext(), od_clr_scr()
  6826.  
  6827.  
  6828. EXAMPLE        For an example of how to use the od_restore_screen() function,
  6829.                see the example which accompanies the od_save_screen() function,
  6830.                on page 117.
  6831.  
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.  
  6838.  
  6839.  
  6840.  
  6841. ===============================================================================
  6842. OpenDoors 5.00 Manual                                           End of Page 116
  6843.  
  6844.  
  6845.  
  6846.  
  6847.  
  6848.  
  6849. OD_SAVE_SCREEN()
  6850. -------------------------------------------------------------------------------
  6851.  
  6852. PURPOSE        Saves the contents of the screen, to later be restored using
  6853.                od_restore_screen(). Can be used in any display mode.
  6854.  
  6855.  
  6856. FORMAT         int od_save_screen(void *buffer);
  6857.  
  6858.  
  6859. RETURNS        TRUE on success
  6860.                FALSE on failure
  6861.  
  6862. DESCRIPTION    This function saves the entire contents of the screen, along
  6863.                with the current cursor position and display colour, to be later
  6864.                restored using the od_restore_screen() function. Unlike the
  6865.                od_get_text() and od_put_text() functions, the od_save_screen()
  6866.                and od_restore_screen() functions will work in all display modes
  6867.                (ASCII, ANSI, AVATAR and RIP).
  6868.  
  6869.                The "buffer" parameter should point to a buffer where the
  6870.                current screen information is to be stored. This buffer must be
  6871.                at least 4004 bytes in size.
  6872.  
  6873.                Note that the od_save_screen() and od_restore_screen() functions
  6874.                save the stored screen information in different formats than the
  6875.                od_getttext() and od_puttext() functions. For this reason, you
  6876.                cannot save the screen contents with od_save_screen() and
  6877.                restore them with od_puttext(), or visa-versa.
  6878.  
  6879.                Also, note that when used in RIP graphics mode, this function
  6880.                only saves and restores textual information, and not bit-mapped
  6881.                graphical information.
  6882.  
  6883.                If this function fails for any reason, a value of FALSE is
  6884.                returned, and the od_control.od_error variable is set to
  6885.                indicate the reason for the failure. For more information on the
  6886.                od_control.od_error variable, see page 182.
  6887.  
  6888.  
  6889. SEE ALSO       od_restore_screen(), od_gettext(), od_puttext(), od_clr_scr()
  6890.  
  6891.  
  6892. EXAMPLE        One case where you might wish to save and restore the contents
  6893.                of the screen is when sysop chat mode is activated. This can be
  6894.                accomplished by using the od_control.od_cbefore_chat and
  6895.                od_control.od_cafter_chat variables. The following example
  6896.                causes the screen contents to be saved and the entire screen
  6897.                cleared, prior to entering sysop chat mode when the sysop
  6898.                presses the "chat key". When the sysop ends chat mode, the
  6899.  
  6900. ===============================================================================
  6901. OpenDoors 5.00 Manual                                           End of Page 117
  6902.  
  6903.  
  6904.                user's original screen is restored, and the user will be able to
  6905.                continue working in the door as though nothing had happened.
  6906.  
  6907.                Code to perform screen saving and restoring:
  6908.  
  6909.                     /* Function prototypes */
  6910.                     void before_chat_function(void);
  6911.                     void after_chat_function(void);
  6912.  
  6913.                     /* Buffer to hold contents of screen prior to chat */
  6914.                     char before_chat_buffer[4004];
  6915.                     /* Variable to store whether screen save was successful */
  6916.                     char before_chat_saved = FALSE;
  6917.  
  6918.                     /* Function which is called prior to entering chat mode */
  6919.                     void before_chat_function(void)
  6920.                        {
  6921.                        /* Store current screen contents */
  6922.                        before_chat_saved = od_save_screen(before_chat_buffer);
  6923.  
  6924.                        /* Present a blank screen for chat mode */
  6925.                        od_clr_scr();
  6926.                        }
  6927.  
  6928.                     /* Function which is called after exiting chat mode */
  6929.                     void after_chat_function(void)
  6930.                        {
  6931.                        /* If screen was successfully saved prior to chat */
  6932.                        if(before_chat_saved)
  6933.                           {
  6934.                           /* Restore original screen contents */
  6935.                           od_restore_screen(before_chat_buffer);
  6936.                           }
  6937.                        }
  6938.  
  6939.                Code included in main() function to enable screen saving and
  6940.                restoring code:
  6941.  
  6942.                     od_control.od_cbefore_chat = before_chat_function;
  6943.                     od_control.od_cafter_chat = after_chat_function;
  6944.  
  6945.  
  6946.  
  6947.  
  6948.  
  6949.  
  6950.  
  6951.  
  6952.  
  6953.  
  6954.  
  6955.  
  6956.  
  6957.  
  6958.  
  6959. ===============================================================================
  6960. OpenDoors 5.00 Manual                                           End of Page 118
  6961.  
  6962.  
  6963.  
  6964.  
  6965.  
  6966.  
  6967. OD_SCROLL()
  6968. -------------------------------------------------------------------------------
  6969.  
  6970. PURPOSE        Scrolls any rectangular area of the screen a specified number of
  6971.                lines upwards or downwards. Requires ANSI/AVATAR/RIP graphics
  6972.                mode to be active.
  6973.  
  6974.  
  6975. FORMAT         int od_scroll(int left, int top, int right, int bottom, int
  6976.                distance, unsigned int flags);
  6977.  
  6978.  
  6979. RETURNS        TRUE on success
  6980.                FALSE on FAILURE
  6981.  
  6982.  
  6983. DESCRIPTION    This function scrolls a rectangular area of the screen described
  6984.                by the parameters "left", "top", "right" and "bottom". The
  6985.                parameters "left" and "right" are column numbers from 1 - 80,
  6986.                and the parameters "top" and "bottom" are row numbers from 1 -
  6987.                23.
  6988.  
  6989.                The parameter "distance" indicates the direction and number of
  6990.                lines to scroll the text in the specified area. Positive values
  6991.                denote moving the text upwards, and negative values denote
  6992.                moving the text downwards. Hence, a "distance" of 1 would cause
  6993.                the text in the specified area to be scrolled upwards one line,
  6994.                with the top line disappearing, and a blank line being created
  6995.                at the bottom of this area. A "distance" of -2 would cause the
  6996.                text in the specified are to be scrolled downwards two lines.
  6997.  
  6998.                The last parameter to od_scroll(), "flags" is not currently used
  6999.                by OpenDoors. However, to preserve compatibility with future
  7000.                versions of OpenDoors, this should always be 0.
  7001.  
  7002.                The new lines created by scrolling text will appear in the
  7003.                current colour. When this function returns, it leaves the cursor
  7004.                at its original position, and the display colour at its original
  7005.                setting. This function requires ANSI or AVATAR modes. If ANSI
  7006.                mode is active, this function is equivalent to calling
  7007.                od_gettext(), od_puttext(), and then sending addition codes to
  7008.                the modem clear the newly created lines. In ANSI mode, scrolling
  7009.                can be accomplished more quickly if the area to be scrolled is
  7010.                equal in width to the entire screen. This is because the
  7011.                clearing of newly created lines is done by sending a simple
  7012.                control sequence, instead of a line of space characters. If
  7013.                AVATAR mode is active, scrolling of the window is accomplished
  7014.                by sending a single 6-byte control sequence.
  7015.  
  7016.  
  7017.  
  7018. ===============================================================================
  7019. OpenDoors 5.00 Manual                                           End of Page 119
  7020.  
  7021.  
  7022.                If the od_scroll() function fails for any reason, a value of
  7023.                FALSE is returned, and the od_control.od_error variable is set
  7024.                to indicate the reason for the failure. For more information on
  7025.                the od_control.od_error variable, see page 182.
  7026.  
  7027.  
  7028. SEE ALSO       od_gettext(), od_puttext(), od_window_create(),
  7029.                od_window_remove()
  7030.  
  7031.  
  7032. EXAMPLE        For an example of a program which uses the od_scroll() function,
  7033.                see the ex_chat.c example door that is included in your
  7034.                OpenDoors package. The ex_chat.c example door is described on
  7035.                page of 38 this manual.
  7036.  
  7037.  
  7038.  
  7039.  
  7040.  
  7041.  
  7042.  
  7043.  
  7044.  
  7045.  
  7046.  
  7047.  
  7048.  
  7049.  
  7050.  
  7051.  
  7052.  
  7053.  
  7054.  
  7055.  
  7056.  
  7057.  
  7058.  
  7059.  
  7060.  
  7061.  
  7062.  
  7063.  
  7064.  
  7065.  
  7066.  
  7067.  
  7068.  
  7069.  
  7070.  
  7071.  
  7072.  
  7073.  
  7074.  
  7075.  
  7076.  
  7077. ===============================================================================
  7078. OpenDoors 5.00 Manual                                           End of Page 120
  7079.  
  7080.  
  7081.  
  7082.  
  7083.  
  7084.  
  7085. OD_SEND_FILE()
  7086. -------------------------------------------------------------------------------
  7087.  
  7088. PURPOSE        Sends an ASCII/ANSI/AVATAR/RIP file from disk, using terminal
  7089.                emulation. Also interprets RA/QBBS style information control
  7090.                codes.
  7091.  
  7092.  
  7093. FORMAT         int od_send_file(char *filename);
  7094.  
  7095.  
  7096. RETURNS        TRUE if the file was successfully sent
  7097.                FALSE if OpenDoors was unable to send the file
  7098.  
  7099.  
  7100. DESCRIPTION:   This powerful function will display any ASCII, ANSI, AVATAR or
  7101.                RIP file. The od_send_file() function can be used to display
  7102.                existing BBS text files, such as a "logoff screen", before your
  7103.                door hangs up on the user. You can also make use of the
  7104.                od_send_file() function to build many of your door screens as
  7105.                external files. This will allow you to easily create these
  7106.                screens in an ANSI editor program, such as "TheDraw". It will
  7107.                could also optionally allow sysops to customize your door for
  7108.                use on their own BBS.
  7109.  
  7110.                The od_send_file() function is called with the full path and
  7111.                filename of the file you wish to have displayed. Thus, if you
  7112.                wished to send the ANSI file MAINMENU.SCR, you would simply
  7113.                call:
  7114.  
  7115.                             od_send_file("MAINMENU.SCR");
  7116.  
  7117.                In many cases, instead of having just one file that you want
  7118.                displayed in particular, you will have several different files,
  7119.                and will want a different one displayed according to the user's
  7120.                graphics mode. For example, you might have the four files,
  7121.                MAINMENU.ASC, MAINMENU.ANS, MAINMENU.AVT and MAINMENU.RIP; the
  7122.                .ASC file containing no special control codes, the .ANS file
  7123.                containing ANSI control codes, the .AVT file containing AVATAR
  7124.                control codes, and the .RIP file containing RIP graphics control
  7125.                codes. In this case, you can have the od_send_file() function
  7126.                automatically select the appropriate file according to the
  7127.                user's current display mode, by omitting the extension
  7128.                altogether. Thus, a call to:
  7129.  
  7130.                             od_send_file("MAINMENU");
  7131.  
  7132.                would cause OpenDoors to automatically send the appropriate
  7133.                file, according to the user's graphics mode settings. When the
  7134.                od_send_file() function is used in this "automatic mode" (where
  7135.  
  7136. ===============================================================================
  7137. OpenDoors 5.00 Manual                                           End of Page 121
  7138.  
  7139.  
  7140.                you do not specify a filename extension), it will look for one
  7141.                of the four filename extensions listed below.
  7142.  
  7143.                +----------------------------------------------------------+
  7144.                | Extension| File type                                     |
  7145.                +----------+-----------------------------------------------|
  7146.                |   .ASC   | Does not require any graphics mode to display |
  7147.                |   .ANS   | Requires ANSI graphics mode to display        |
  7148.                |   .AVT   | Requires AVATAR graphics mode to display      |
  7149.                |   .RIP   | Requires RIP graphics mode to be displayed    |
  7150.                +----------------------------------------------------------+
  7151.  
  7152.  
  7153.                If the user has RIP graphics enabled, od_send_file() will first
  7154.                search for the .RIP file. If no file exists with the specified
  7155.                filename and a .RIP extension, od_send_file() will then search
  7156.                for .AVT, then .ANS, and if not found .ASC. If the user has only
  7157.                ANSI graphics enabled, od_send_file() will attempt first to
  7158.                display the .ANS file, and if not found will search for .ASC. In
  7159.                the case that the user is using plain-ASCII mode, this function
  7160.                will attempt only to display the .ASC file.
  7161.  
  7162.                When displaying a .RIP file to the remote system, OpenDoors will
  7163.                attempt to locate and display a corresponding .AVT/.ANS/.ASC
  7164.                file on the local system. If no such file can be found, a window
  7165.                will be displayed, indicating the name of the .RIP file that is
  7166.                being sent to the remote system. When a .RIP file is being
  7167.                displayed, page pausing is disabled.
  7168.  
  7169.                When displaying .AVT/.ANS/.ASC files, od_send_file() will send
  7170.                any ANSI or AVATAR codes in the file directly to the remote
  7171.                terminal, and interpret them to display on the local screen
  7172.                (regardless of the actual filename extension). This
  7173.                interpretation is accomplished by OpenDoor's built in terminal
  7174.                emulator. The terminal emulator fully supports all ANSI and
  7175.                AVATAR level 0 and level 0+ control codes. The terminal emulator
  7176.                will also translate Apex/Remote Access/QuickBBS style control
  7177.                codes. The control codes supported by OpenDoors are listed in
  7178.                the chart on the following pages. When these control codes are
  7179.                inserted into the file, OpenDoors will replace them with various
  7180.                pieces of user or system information. The interpretation of
  7181.                these control codes can be disabled using the
  7182.                od_control.od_no_ra_codes variable.
  7183.  
  7184.  
  7185.                  +-----------------------------------------------------+
  7186.                  | CONTROL | ASCII |                                   |
  7187.                  |  CODE   | VALUE | DESCRIPTION                       |
  7188.                  +---------+-------+-----------------------------------|
  7189.                  |   ^FA   | 06,65 | Displays the user's full name     |
  7190.                  |   ^FB   | 06,66 | Location the user is calling from |
  7191.                  |   ^FC   | 06,67 | Displays the user's password      |
  7192.                  |   ^FD   | 06,68 | Business/data phone number        |
  7193.                  |   ^FE   | 06,69 | Home/voice phone number           |
  7194.  
  7195. ===============================================================================
  7196. OpenDoors 5.00 Manual                                           End of Page 122
  7197.  
  7198.  
  7199.                  |   ^FF   | 06,70 | Date of the user's last call      |
  7200.                  |   ^FG   | 06,71 | Time of day of the last call      |
  7201.                  |   ^FH   | 06,72 | The user's `A' flags settings     |
  7202.                  |   ^FI   | 06,73 | The user's `B' flags settings     |
  7203.                  |   ^FJ   | 06,74 | The user's `C' flags settings     |
  7204.                  |   ^FK   | 06,75 | The user's `D' flags settings     |
  7205.                  |   ^FL   | 06,76 | User's remaining netmail credit   |
  7206.                  |   ^FM   | 06,77 | Number of messages posted by user |
  7207.                  |   ^FN   | 06,78 | Last read message number by user  |
  7208.                  |   ^FO   | 06,79 | Displays security level of user   |
  7209.                  |   ^FP   | 06,80 | Number of times user has called   |
  7210.                  |   ^FQ   | 06,81 | Total # of uploads by user        |
  7211.                  |   ^FR   | 06,82 | Total KBytes uploaded by user     |
  7212.                  |   ^FS   | 06,83 | Total # of downloads by user      |
  7213.                  |   ^FT   | 06,84 | Total Kbytes downloaded by user   |
  7214.                  |   ^FU   | 06,85 | # of minute user has used today   |
  7215.                  |   ^FV   | 06,86 | User's screen length setting      |
  7216.                  |   ^FW   | 06,87 | User's first name only            |
  7217.                  |   ^FX   | 06,88 | User's ANSI setting               |
  7218.                  |   ^FY   | 06,89 | User's "continue?" prompt setting |
  7219.                  |   ^FZ   | 06,90 | Does user have screen clearing on |
  7220.                  |   ^F0   | 06,48 | User's Full-screen editor setting |
  7221.                  |   ^F1   | 06,49 | User's Quiet mode setting         |
  7222.                  |   ^F2   | 06,50 | User's hot-keys setting           |
  7223.                  |   ^F3   | 06,51 | Displays the user's alias         |
  7224.                  |   ^F4   | 06,52 | The date of the User's first call |
  7225.                  |   ^F5   | 06,53 | The user's date of birth          |
  7226.                  |   ^F6   | 06,54 | User's subscription expiry date   |
  7227.                  |   ^F7   | 06,55 | Number of days until expiry       |
  7228.                  |   ^F8   | 06,56 | User's AVATAR setting             |
  7229.                  |   ^F9   | 06,57 | The user's upload:download ratio  |
  7230.                  |   ^F:   | 06,58 | User's Upload K:download K ratio  |
  7231.                  +-----------------------------------------------------+
  7232.  
  7233.  
  7234.  
  7235.  
  7236.                  +-----------------------------------------------------+
  7237.                  | CONTROL | ASCII |                                   |
  7238.                  |  CODE   | VALUE | DESCRIPTION                       |
  7239.                  +---------+-------+-----------------------------------|
  7240.                  |   ^F;   | 06,59 | Full-screen message reader        |
  7241.                  |   ^KA   | 11,65 | Total # of calls BBS has received |
  7242.                  |   ^KB   | 11,66 | Name of the last caller to BBS    |
  7243.                  |   ^KC   | 11,67 | Total # of active messages on BBS |
  7244.                  |   ^KD   | 11,68 | Displays # of the first message   |
  7245.                  |   ^KE   | 11,69 | Displays # of the last message    |
  7246.                  |   ^KF   | 11,70 | # of times user has paged sysop   |
  7247.                  |   ^KG   | 11,71 | Full name of the current weekday  |
  7248.                  |   ^KH   | 11,72 | Displays total number of users    |
  7249.                  |   ^KI   | 11,73 | Displays the current time         |
  7250.                  |   ^KJ   | 11,74 | Displays the current date         |
  7251.                  |   ^KK   | 11,75 | Minutes the user has been online  |
  7252.                  |   ^KL   | 11,76 | Seconds the user has been online  |
  7253.  
  7254. ===============================================================================
  7255. OpenDoors 5.00 Manual                                           End of Page 123
  7256.  
  7257.  
  7258.                  |   ^KM   | 11,77 | Minutes the user has used today   |
  7259.                  |   ^KN   | 11,78 | Seconds the user has used today   |
  7260.                  |   ^KO   | 11,79 | Minutes remaining for user today  |
  7261.                  |   ^KP   | 11,80 | Seconds remaining for user today  |
  7262.                  |   ^KQ   | 11,81 | The user's daily time limit       |
  7263.                  |   ^KR   | 11,82 | Displays the current baud rate    |
  7264.                  |   ^KS   | 11,83 | The current weekday in short-form |
  7265.                  |   ^KT   | 11,84 | The user's daily download limit   |
  7266.                  |   ^KU   | 11,85 | # of minutes until the next event |
  7267.                  |   ^KV   | 11,86 | Time of the next system event     |
  7268.                  |   ^KW   | 11,87 | # of node user is currently on    |
  7269.                  |   ^KX   | 11,88 | Disconnects the user              |
  7270.                  +-----------------------------------------------------+
  7271.  
  7272.  
  7273. SEE ALSO       od_disp_emu(), od_list_files(), od_hotkey_menu()
  7274.  
  7275.  
  7276. EXAMPLE        For an example of the use of the od_send_file() function in
  7277.                displaying a custom door menu, see the EZVote example door,
  7278.                which is described beginning on page 38.
  7279.  
  7280.  
  7281.  
  7282.  
  7283.  
  7284.  
  7285.  
  7286.  
  7287.  
  7288.  
  7289.  
  7290.  
  7291.  
  7292.  
  7293.  
  7294.  
  7295.  
  7296.  
  7297.  
  7298.  
  7299.  
  7300.  
  7301.  
  7302.  
  7303.  
  7304.  
  7305.  
  7306.  
  7307.  
  7308.  
  7309.  
  7310.  
  7311.  
  7312.  
  7313. ===============================================================================
  7314. OpenDoors 5.00 Manual                                           End of Page 124
  7315.  
  7316.  
  7317.  
  7318.  
  7319.  
  7320.  
  7321. OD_SET_ATTRIB()
  7322. -------------------------------------------------------------------------------
  7323.  
  7324. PURPOSE        Function to change the text colour in ANSI or AVATAR mode, using
  7325.                a single IBM-PC colour attribute value.
  7326.  
  7327.  
  7328. FORMAT         void od_set_attrib(int colour);
  7329.  
  7330.  
  7331. RETURNS        N/A
  7332.  
  7333.  
  7334. DESCRIPTION    od_set_attrib() is one of two functions which change the colour
  7335.                of the currently displayed text. This function allows you to set
  7336.                the text colour using a single IBM-PC style colour attribute. On
  7337.                the other hand, the od_set_colour() function allows you to set
  7338.                the display colour by specifying a foreground and background
  7339.                text colour. Generally speaking, which of these two functions
  7340.                you use will be only a matter of personal preference. You will,
  7341.                however, most likely find it more convenient to use the
  7342.                od_set_colour() function for changing display colour. However
  7343.                the od_set_attrib() offers the advantage of allowing you to
  7344.                manipulate the colour to be displayed as a single value, instead
  7345.                of two separate values. This could be convenient, for example,
  7346.                when displaying text in a user configured colour. Using a single
  7347.                byte to represent the colour will likely be easier than using
  7348.                two. An alternative method of setting the colour of displayed
  7349.                text is to include the colour codes within a string displayed by
  7350.                the od_printf() function. The benefits of doing this, along with
  7351.                instructions on how to do this, are described in the section on
  7352.                the od_printf() function, which begins on page 105.
  7353.  
  7354.                This function will only have an effect if the user has ANSI,
  7355.                AVATAR or RIP modes enabled. As a result, you can use this
  7356.                function within your door program, and have your text
  7357.                automatically displayed in multiple colours if graphics mode is
  7358.                available, and displayed without colours if graphics mode is not
  7359.                available.
  7360.  
  7361.                Note that the colour to be set is passed to this function as an
  7362.                IBM-style screen attribute. Hence, you can set the colour of
  7363.                text to be displayed by a single hexidecimal value, encoded as
  7364.                follows:
  7365.  
  7366.                               +------------- Background colour
  7367.                               |
  7368.                             0x7f
  7369.                                |
  7370.                                +------------ Foreground colour
  7371.  
  7372. ===============================================================================
  7373. OpenDoors 5.00 Manual                                           End of Page 125
  7374.  
  7375.  
  7376.  
  7377.                Where the left digit (most significant nibble) of the
  7378.                hexidecimal number represents the background colour, and the
  7379.                right digit (least significant nibble) represents the foreground
  7380.                colour. Each of the possible colours, along with their
  7381.                corresponding hexidecimal values, are listed in the charts,
  7382.                below.
  7383.  
  7384.                +-----------------------+  +--------------------------+
  7385.                |   Foreground colours  |  |   Background  | Flashing |
  7386.                +-----------------------|  +---------------+----------|
  7387.                |  0  | Black           |  |  0  | Black   |   Off    |
  7388.                |  1  | Blue            |  |  1  | Blue    |   Off    |
  7389.                |  2  | Green           |  |  2  | Green   |   Off    |
  7390.                |  3  | Cyan            |  |  3  | Cyan    |   Off    |
  7391.                |  4  | Red             |  |  4  | Red     |   Off    |
  7392.                |  5  | Magenta         |  |  5  | Magenta |   Off    |
  7393.                |  6  | Brown           |  |  6  | Brown   |   Off    |
  7394.                |  7  | White (grey)    |  |  7  | White   |   Off    |
  7395.                |  8  | Bright Black    |  |  8  | Black   |    On    |
  7396.                |  9  | Bright Blue     |  |  9  | Blue    |    On    |
  7397.                |  a  | Bright Green    |  |  a  | Green   |    On    |
  7398.                |  b  | Bright Cyan     |  |  b  | Cyan    |    On    |
  7399.                |  c  | Bright Red      |  |  c  | Red     |    On    |
  7400.                |  d  | Bright Magenta  |  |  d  | Magenta |    On    |
  7401.                |  e  | Yellow          |  |  e  | Brown   |    On    |
  7402.                |  f  | White (bright)  |  |  f  | White   |    On    |
  7403.                +-----------------------+  +--------------------------+
  7404.  
  7405.                Hence, od_set_attrib(0x0e) would set the display colour to
  7406.                yellow on a black background, and od_set_attrib(0x70) would set
  7407.                the display colour to black on a while background.
  7408.  
  7409.  
  7410. SEE ALSO       od_set_colour(), od_disp_emu(), od_clr_scr(), od_clr_line(),
  7411.                od_set_cursor()
  7412.  
  7413.  
  7414. EXAMPLE        At times, you may wish to allow the user to select the colour of
  7415.                text they wish to have displayed, perhaps to configure your door
  7416.                for the ideal colours to be displayed on their system. To
  7417.                demonstrate the use of the od_set_attrib() function, we show
  7418.                another function, which shows the user all 256 possible colours
  7419.                that can be displayed, and allows the user to choose which
  7420.                colour they prefer. The function will then return the colour
  7421.                attribute value of the user's chosen colour, which can later be
  7422.                passed to od_set_attrib() to set the displayed text colour to
  7423.                the colour which was chosen by the user.
  7424.  
  7425.                unsigned char choose_colour(void)
  7426.                   {
  7427.                   register unsigned char counter;  /* for displaying colours */
  7428.                   char string[4];                    /* string input by user */
  7429.  
  7430.  
  7431. ===============================================================================
  7432. OpenDoors 5.00 Manual                                           End of Page 126
  7433.  
  7434.  
  7435.                   od_set_attrib(0x07);                      /* display title */
  7436.                   od_disp_str("Available colours:\n\r\n\r");
  7437.  
  7438.                   for(counter=0;counter<=255;)   /* loop through all colours */
  7439.                      {
  7440.                      od_set_attrib(counter);       /* set appropriate colour */
  7441.                      od_printf("%03.3u",counter); /* display colour's number */
  7442.                      if(((++counter)%16)==0)   /* after every 16 colours ... */
  7443.                         {
  7444.                         od_set_attrib(0x07); /* ... reset display colour ... */
  7445.                         od_disp_str("\n\r");     /* ... and start a new line */
  7446.                         }
  7447.                      }
  7448.  
  7449.                   od_set_attrib(0x07);        /* Allow user to choose colour */
  7450.                   od_disp_str("Which colour do you prefer : ");
  7451.                   od_input_str(string,3,'0','9');
  7452.                   return(atoi(string));              /* Return chosen colour */
  7453.                   }
  7454.  
  7455.  
  7456.  
  7457.  
  7458.  
  7459.  
  7460.  
  7461.  
  7462.  
  7463.  
  7464.  
  7465.  
  7466.  
  7467.  
  7468.  
  7469.  
  7470.  
  7471.  
  7472.  
  7473.  
  7474.  
  7475.  
  7476.  
  7477.  
  7478.  
  7479.  
  7480.  
  7481.  
  7482.  
  7483.  
  7484.  
  7485.  
  7486.  
  7487.  
  7488.  
  7489.  
  7490. ===============================================================================
  7491. OpenDoors 5.00 Manual                                           End of Page 127
  7492.  
  7493.  
  7494.  
  7495.  
  7496.  
  7497.  
  7498. OD_SET_COLOUR()
  7499. -------------------------------------------------------------------------------
  7500.  
  7501. PURPOSE        Function to change the current display colour in ANSI, AVATAR or
  7502.                RIP modes, using foreground and background colour values.
  7503.  
  7504.  
  7505. FORMAT         void od_set_colour(int foreground, int background);
  7506.  
  7507.  
  7508. RETURNS        N/A
  7509.  
  7510.  
  7511. DESCRIPTION    od_set_colour() is one of two functions which change the colour
  7512.                of the currently displayed text. This function allows you to set
  7513.                the text colour using separate foreground an background text
  7514.                colours, whereas od_set_attrib() allows you to set the text
  7515.                colour using a single IBM-PC style colour attribute. Generally
  7516.                speaking, which of these two functions you use is only a matter
  7517.                of personal preference. An alternative method of setting the
  7518.                colour of displayed text is to include the colour codes within a
  7519.                string displayed by the od_printf() function. The benefits of
  7520.                doing this, along with instructions on how to do this, are
  7521.                described in the section on the od_printf() function, which
  7522.                begins on page 105.
  7523.  
  7524.                This function will only have an effect if the user has ANSI,
  7525.                AVATAR or RIP mode turned on. As a result, you can use this
  7526.                function within your door program, and have your text
  7527.                automatically displayed in multiple colours if graphics mode is
  7528.                available, and displayed without colours if graphics mode is not
  7529.                available.
  7530.  
  7531.                The od_set_colour() function accepts two parameters, the first
  7532.                parameter being the foreground colour to be used in displaying
  7533.                text, and the second parameter being the background colour to be
  7534.                used in displaying text. For example,
  7535.  
  7536.                                od_set_colour(L_WHITE,D_BLACK);
  7537.  
  7538.                would set the current colour to Light White on Dark Black. The
  7539.                foreground and background text colours can be any one of the
  7540.                colour values listed on the following page.
  7541.  
  7542.  
  7543.  
  7544.  
  7545.  
  7546.  
  7547.  
  7548.  
  7549. ===============================================================================
  7550. OpenDoors 5.00 Manual                                           End of Page 128
  7551.  
  7552.  
  7553.  
  7554.  
  7555.                +-------------------+-----------+
  7556.                | Foreground Colour | Value     |
  7557.                +-------------------+-----------+
  7558.                | Dark Black        | D_BLACK   |
  7559.                | Dark Blue         | D_BLUE    |
  7560.                | Dark Green        | D_GREEN   |
  7561.                | Dark Cyan         | D_CYAN    |
  7562.                | Dark Red          | D_RED     |
  7563.                | Dark Magenta      | D_MAGENTA |
  7564.                | Dark Brown        | D_BROWN   |
  7565.                | Grey (Dark White) | D_GREY    |
  7566.                | Light Black (Grey)| L_BLACK   |
  7567.                | Light Blue        | L_BLUE    |
  7568.                | Light Green       | L_GREEN   |
  7569.                | Light Cyan        | L_CYAN    |
  7570.                | Light Red         | L_RED     |
  7571.                | Light Magenta     | L_MAGENTA |
  7572.                | Yellow            | L_YELLOW  |
  7573.                | White             | L_WHITE   |
  7574.                +-------------------+-----------+
  7575.  
  7576.  
  7577.                +-------------------+-----------+
  7578.                | Background Colour | Value     |
  7579.                +-------------------+-----------+
  7580.                | Black             | D_BLACK   |
  7581.                | Blue              | D_BLUE    |
  7582.                | Green             | D_GREEN   |
  7583.                | Cyan              | D_CYAN    |
  7584.                | Red               | D_RED     |
  7585.                | Magenta           | D_MAGENTA |
  7586.                | Brown             | D_BROWN   |
  7587.                | Grey              | D_GREY    |
  7588.                | Blinking Black    | B_BLACK   |
  7589.                | Blinking Blue     | B_BLUE    |
  7590.                | Blinking Green    | B_GREEN   |
  7591.                | Blinking Cyan     | B_CYAN    |
  7592.                | Blinking Red      | B_RED     |
  7593.                | Blinking Magenta  | B_MAGENTA |
  7594.                | Blinking Brown    | B_BROWN   |
  7595.                | Blinking Grey     | B_WHITE   |
  7596.                +-------------------+-----------+
  7597.  
  7598.  
  7599. SEE ALSO       od_set_attrib(), od_disp_emu(), od_clr_scr(), od_clr_line(),
  7600.                od_set_cursor()
  7601.  
  7602. EXAMPLE        As an example of using the od_set_colour() function to set the
  7603.                colour of displayed text, we show a pair of two functions. These
  7604.                functions will allow a program to set the foreground OR
  7605.                background colour of text, without setting the other. In
  7606.                contrast, the od_set_colour() function sets both the foreground
  7607.  
  7608. ===============================================================================
  7609. OpenDoors 5.00 Manual                                           End of Page 129
  7610.  
  7611.  
  7612.                and background colour at the same time. These function presume
  7613.                that they are the only functions used within the door to set the
  7614.                colour of displayed text, and that the original text colour
  7615.                prior to calling either of these functions is dark white on
  7616.                black. These function must also have access to the two global
  7617.                variables "current_foreground" and "current_background", as
  7618.                defined below.
  7619.  
  7620.  
  7621.                void set_foreground(char foreground);
  7622.                void set_background(char background);
  7623.                unsigned char current_foreground=D_BLACK;
  7624.                unsigned char current_background=D_GREY;
  7625.  
  7626.                void set_foreground(char foreground)
  7627.                   {                                   /* set new text colour */
  7628.                   od_set_colour(foreground,current_background);
  7629.                   current_foreground=foreground;      /* save new foreground */
  7630.                   }
  7631.  
  7632.                void set_background(char background)
  7633.                   {                                   /* set new text colour */
  7634.                   od_set_colour(current_foreground,background);
  7635.                   current_background=background;      /* save new background */
  7636.                   }
  7637.  
  7638.  
  7639.                Using these functions, you would then be able to set just the
  7640.                foreground text colour by a function call like:
  7641.  
  7642.                          set_foreground(L_YELLOW);
  7643.  
  7644.                Or set just the background text colour by a function call like:
  7645.  
  7646.                          set_background(D_GREY);
  7647.  
  7648.  
  7649.  
  7650.  
  7651.  
  7652.  
  7653.  
  7654.  
  7655.  
  7656.  
  7657.  
  7658.  
  7659.  
  7660.  
  7661.  
  7662.  
  7663.  
  7664.  
  7665.  
  7666.  
  7667. ===============================================================================
  7668. OpenDoors 5.00 Manual                                           End of Page 130
  7669.  
  7670.  
  7671.  
  7672.  
  7673.  
  7674.  
  7675. OD_SET_CURSOR()
  7676. -------------------------------------------------------------------------------
  7677.  
  7678. PURPOSE        Function to reposition the text cursor in ANSI, AVATAR or RIP
  7679.                mode
  7680.  
  7681.  
  7682. FORMAT         void od_set_cursor(int row, int col);
  7683.  
  7684.  
  7685. RETURNS        N/A
  7686.  
  7687.  
  7688. DESCRIPTION    This function will only have an effect if the user has ANSI,
  7689.                AVATAR or RIP graphics mode turned on. In graphics mode, this
  7690.                function can be used to position the cursor anywhere on the
  7691.                screen (cursor is moved both locally and on the remote
  7692.                terminal). The first parameter "row", can normally have a value
  7693.                between 1 to 23, and indicates the row, or y position on the
  7694.                screen, where the cursor should be located. The second
  7695.                parameter, "col",  can have a value between 1 and 80, and
  7696.                indicates the column (x-position) on the screen, where the
  7697.                cursor should be located.
  7698.  
  7699.  
  7700. SEE ALSO       od_disp_emu(), od_clr_scr(), od_clr_line(), od_set_colour(),
  7701.                od_set_attrib()
  7702.  
  7703.  
  7704. EXAMPLE        Below is a simple sample door that demonstrates the use of the
  7705.                od_set_cursor() function. Note that this door detects whether or
  7706.                not graphics mode is available, and if it is not, will carry out
  7707.                the same task without the use of the od_set_cursor() function.
  7708.  
  7709.                          #include "opendoor.h"
  7710.  
  7711.                          int main(int argc,char *argv[])
  7712.                             {
  7713.                             od_init();         /* Initialize door operations */
  7714.                             od_clr_scr();                /* Clear the screen */
  7715.  
  7716.                             if(od_control.user_ansi || od_control.user_avatar)
  7717.                                {            /* If graphics mode is available */
  7718.                                od_set_cursor(1,1);           /* Display demo */
  7719.                                od_disp_str("Top, Left Corner");
  7720.  
  7721.                                od_set_cursor(1,70);
  7722.                                od_disp_str("Top, Right Corner");
  7723.  
  7724.                                od_set_cursor(15,1);
  7725.  
  7726. ===============================================================================
  7727. OpenDoors 5.00 Manual                                           End of Page 131
  7728.  
  7729.  
  7730.                                od_disp_str("Fifteenth line\n\r");
  7731.                                }
  7732.  
  7733.                             else        /* If graphics mode is not available */
  7734.                                {                             /* Display demo */
  7735.                                od_disp_str("Top, Left Corner");
  7736.                                od_repeat(' ', 54);
  7737.                                od_disp_str("Top, Right Corner\n\r"
  7738.                                                             /* Skip 13 lines */
  7739.                                od_disp_str("\n\n\n\n\n\n\n\n\n\n\n\n\n");
  7740.                                od_disp_str("Fifteenth line\n\r");
  7741.                                }
  7742.  
  7743.                             od_get_key(TRUE);  /* Wait for user to press key */
  7744.                             od_exit(FALSE,20);                  /* Exit door */
  7745.                             }
  7746.  
  7747.  
  7748.  
  7749.  
  7750.  
  7751.  
  7752.  
  7753.  
  7754.  
  7755.  
  7756.  
  7757.  
  7758.  
  7759.  
  7760.  
  7761.  
  7762.  
  7763.  
  7764.  
  7765.  
  7766.  
  7767.  
  7768.  
  7769.  
  7770.  
  7771.  
  7772.  
  7773.  
  7774.  
  7775.  
  7776.  
  7777.  
  7778.  
  7779.  
  7780.  
  7781.  
  7782.  
  7783.  
  7784.  
  7785. ===============================================================================
  7786. OpenDoors 5.00 Manual                                           End of Page 132
  7787.  
  7788.  
  7789.  
  7790.  
  7791.  
  7792.  
  7793. OD_SET_DTR()
  7794. -------------------------------------------------------------------------------
  7795.  
  7796. PURPOSE        Controls the DTR (Data Terminal Ready) signal to the modem. Used
  7797.                primarily to cause the modem to "hang up".
  7798.  
  7799.  
  7800. FORMAT         void od_set_dtr(char high);
  7801.  
  7802.  
  7803. RETURNS        N/A
  7804.  
  7805.  
  7806. DESCRIPTION    In certain circumstances (such as call back verification doors),
  7807.                you may wish to "hang up" the modem without exiting your door
  7808.                program. This can be accomplished with most modems by
  7809.                controlling the DTR (Data Terminal Ready) signal to the modem.
  7810.                Passing a FALSE value to od_set_dtr() causes the DTR signal to
  7811.                be set low, and passing a TRUE value causes the DTR signal to be
  7812.                set high. Normally, OpenDoors maintains the DTR signal in its
  7813.                high state. Since most (but not all) modems are configured to
  7814.                disconnect from the remote modem when the DTR signal is set low,
  7815.                calling od_set_dtr(FALSE) can be used to hangup the modem. When
  7816.                hanging up by this method, you should be sure to set the DTR
  7817.                signal high again, after the carrier detect signal has
  7818.                disappeared. For more information on determining the state of
  7819.                the carrier detect signal, see the od_carrier() function, which
  7820.                is described on page 51.
  7821.  
  7822.                Note that not all modems will disconnect from the remote user in
  7823.                response to your lowering the DTR signal. If your software may
  7824.                be used with such modems, you may wish to also provide the
  7825.                option of disconnecting the modem by sending a "hang up" command
  7826.                sequence to the modem.
  7827.  
  7828.                Since OpenDoors normally monitors the carrier detect signal, and
  7829.                exits when this signal disappears, you will have to disable
  7830.                OpenDoor's carrier detection if you wish your program to
  7831.                continue executing after hanging up the modem. OpenDoor's
  7832.                automatic carrier detection can be disabled using the
  7833.                od_control.od_disable OpenDoors control structure variable, as
  7834.                follows:
  7835.  
  7836.                     od_control.od_disable |= DIS_CARRIERDETECT;
  7837.  
  7838.                To re-enable carrier detection, you should turn off the
  7839.                DIS_CARRIERDETECT bit of od_disable, as follows:
  7840.  
  7841.                     od_control.od_disable &=~ DIS_CARRIERDETECT;
  7842.  
  7843.  
  7844. ===============================================================================
  7845. OpenDoors 5.00 Manual                                           End of Page 133
  7846.  
  7847.  
  7848.                If you wish to hang up the modem when the user exits the door,
  7849.                you can simply use the od_exit() function.
  7850.  
  7851. SEE ALSO       od_carrier(), od_exit()
  7852.  
  7853.  
  7854. EXAMPLE        For an example of using the od_set_dtr() function to "hang up"
  7855.                the modem, see the example that accompanies the od_carrier()
  7856.                function, on page 52.
  7857.  
  7858.  
  7859.  
  7860.  
  7861.  
  7862.  
  7863.  
  7864.  
  7865.  
  7866.  
  7867.  
  7868.  
  7869.  
  7870.  
  7871.  
  7872.  
  7873.  
  7874.  
  7875.  
  7876.  
  7877.  
  7878.  
  7879.  
  7880.  
  7881.  
  7882.  
  7883.  
  7884.  
  7885.  
  7886.  
  7887.  
  7888.  
  7889.  
  7890.  
  7891.  
  7892.  
  7893.  
  7894.  
  7895.  
  7896.  
  7897.  
  7898.  
  7899.  
  7900.  
  7901.  
  7902.  
  7903. ===============================================================================
  7904. OpenDoors 5.00 Manual                                           End of Page 134
  7905.  
  7906.  
  7907.  
  7908.  
  7909.  
  7910.  
  7911. OD_SET_PERSONALITY()
  7912. -------------------------------------------------------------------------------
  7913.  
  7914. PURPOSE        Sets the current status line / sysop function key personality to
  7915.                be used.
  7916.  
  7917.  
  7918. FORMAT         int od_set_personality(char *name);
  7919.  
  7920.  
  7921. RETURNS        TRUE on success
  7922.                FALSE on failure
  7923.  
  7924.  
  7925. DESCRIPTION    This function changes the current status line / sysop function
  7926.                key personality. The "name" parameter should contain the string
  7927.                which uniquely identifies the personality to be set. This
  7928.                function may only be used by OpenDoors programs which include
  7929.                the OpenDoors "Multiple Personality System". To enable use of
  7930.                the MPS, include the following line before your first call to
  7931.                any OpenDoors function:
  7932.  
  7933.                          od_control.od_mps=INCLUDE_MPS;
  7934.  
  7935.                OpenDoors includes a number of built-in personalities.
  7936.                Additional personalities may be added using the
  7937.                od_add_personality() function, which is described on page 46.
  7938.                The following personalities are included with this version of
  7939.                OpenDoors:
  7940.  
  7941.                     Name                Description
  7942.                     -----------------------------------------------------------
  7943.                     Standard            OpenDoors style, similar to RA 1.11
  7944.                     PCBoard             Similar to PC-Board
  7945.                     RemoteAccess        Similar to RemoteAccess 2.x
  7946.                     Wildcat             Similar to Wildcat!
  7947.  
  7948.                Personality names are not case sensitive. For more information
  7949.                on the OpenDoors Multiple Personality System, see the section
  7950.                which begins on page 223.
  7951.  
  7952.                This function returns TRUE on success, or FALSE on failure. In
  7953.                the case of a failure, the od_control.od_error variable is set
  7954.                to indicate the nature of the failure. For more information on
  7955.                the od_control.od_error variables, see page 182.
  7956.  
  7957.  
  7958. SEE ALSO       od_add_personality(), od_set_statusline()
  7959.  
  7960.  
  7961.  
  7962. ===============================================================================
  7963. OpenDoors 5.00 Manual                                           End of Page 135
  7964.  
  7965.  
  7966.  
  7967.  
  7968.  
  7969.  
  7970. OD_SET_STATUSLINE()
  7971. -------------------------------------------------------------------------------
  7972.  
  7973. PURPOSE        To set the currently displayed status line.
  7974.  
  7975.  
  7976. FORMAT         void od_set_statusline(char setting);
  7977.  
  7978.  
  7979. RETURNS        N/A
  7980.  
  7981.  
  7982. DESCRIPTION    If you have the OpenDoors status line enabled within your door
  7983.                program (as is the default), the sysop will be able to control
  7984.                the setting of the status line using the F1 - F10 keys on the
  7985.                keyboard. These function keys are as follows:
  7986.  
  7987.                          [F1] -  Display basic door and user information
  7988.                          [F2] -  Display phone numbers and important dates
  7989.                          [F3] -  Display security flags and up/download info
  7990.                          [F4] -  Display system information and current time
  7991.                          [F5] -  Display message info and user's settings
  7992.                          [F6] -  Display chat reason and sysop's comment
  7993.                          [F9] -  Display help information for sysop
  7994.                          [F10] - Turn off the status line
  7995.  
  7996.                Using the od_set_statusline() function, you can manually set
  7997.                which of these status line settings is currently selected. The
  7998.                od_set_statusline() accepts a single parameter, which should be
  7999.                one of the values listed below, which indicates which status
  8000.                line you would like to have selected:
  8001.  
  8002.                +---------------+---------------+------------------------------+
  8003.                |               | Corresponding |                              |
  8004.                | Value         | Function Key  | Meaning                      |
  8005.                +---------------+---------------+------------------------------+
  8006.                | STATUS_NORMAL | [F1]          | Basic door and user info     |
  8007.                | STATUS_NONE   | [F10]         | Turn off status line         |
  8008.                | STATUS_HELP   | [F9]          | Displays help for the sysop  |
  8009.                | STATUS_USER1  | [F2]          | Phone Numbers and dates      |
  8010.                | STATUS_USER2  | [F3]          | Security flags & up/downloads|
  8011.                | STATUS_USER3  | [F5]          | Message info & user settings |
  8012.                | STATUS_USER4  | [F6]          | Chat reason and sysop comment|
  8013.                | STATUS_SYSTEM | [F4]          | System info & current time   |
  8014.                +---------------+---------------+------------------------------+
  8015.                (Note that these keys may be customized using variables in the
  8016.                 OpenDoors control structure.)
  8017.  
  8018.                Keep in mind that the od_set_statusline() function only
  8019.                temporarily changes the current status line setting, and that
  8020.  
  8021. ===============================================================================
  8022. OpenDoors 5.00 Manual                                           End of Page 136
  8023.  
  8024.  
  8025.                the sysop will still be able to change the status line to any of
  8026.                the other settings using the function keys. For instance, if you
  8027.                wished to allow the sysop to normally see all 25 lines of text
  8028.                displayed by your door, but at the same time to still allow the
  8029.                sysop to turn on the status line at any time, you could place
  8030.                the line
  8031.  
  8032.                           od_set_statusline(STATUS_NONE);
  8033.  
  8034.                at the beginning of your program. Similarly, when the user pages
  8035.                the sysop, OpenDoors itself calls
  8036.  
  8037.                          od_set_statusline(STATUS_USER4);
  8038.  
  8039.                in order to display the status line which shows the user's
  8040.                reason for chat, while still allowing the sysop to switch back
  8041.                to any of the other status lines.
  8042.  
  8043.                If you wish to permanently turn off the OpenDoor's status line,
  8044.                without allowing the sysop to be able to turn it back on using
  8045.                the sysop function keys, simply set the
  8046.                "od_control.od_status_on" variable to FALSE. This variable is
  8047.                described in the OpenDoors control structure section of this
  8048.                manual, which begins on page 145.
  8049.  
  8050.  
  8051.  
  8052.  
  8053.  
  8054.  
  8055.  
  8056.  
  8057.  
  8058.  
  8059.  
  8060.  
  8061.  
  8062.  
  8063.  
  8064.  
  8065.  
  8066.  
  8067.  
  8068.  
  8069.  
  8070.  
  8071.  
  8072.  
  8073.  
  8074.  
  8075.  
  8076.  
  8077.  
  8078.  
  8079.  
  8080. ===============================================================================
  8081. OpenDoors 5.00 Manual                                           End of Page 137
  8082.  
  8083.  
  8084.  
  8085.  
  8086.  
  8087.  
  8088. OD_SPAWN()
  8089. -------------------------------------------------------------------------------
  8090.  
  8091. PURPOSE        To facilitate easy execution of child tasks from doors.
  8092.  
  8093.  
  8094. FORMAT         int od_spawn(char *command_line);
  8095.  
  8096.  
  8097. RETURNS        TRUE on success,
  8098.                FALSE on failure
  8099.  
  8100.  
  8101. DESCRIPTION    This function allows you to easily run other programs from
  8102.                within your door programs, such as external file transfer
  8103.                utilities, compression utilities, and so on.
  8104.  
  8105.                This function will attempt to swap OpenDoors and your entire
  8106.                door to expanded memory or disk. OpenDoors swapping can be
  8107.                controlled by the OpenDoors control structure variables,
  8108.                od_swapping_disable, od_swapping_ems and od_swap_path. The
  8109.                od_spawn...() functions first attempt to swap OpenDoors to EMS
  8110.                memory. If enough EMS 3.2 or later memory is available, it will
  8111.                be used. If not, OpenDoors will swap to a disk file in the
  8112.                directory specified by the od_control.od_swap_path variable.
  8113.  
  8114.                Unlike the other Turbo C(++) / Borland C++ library functions
  8115.                such as system() or spawnf(), this function will automatically
  8116.                store the door screen prior to executing the sub-program, and
  8117.                will restore the screen upon return. This function will also
  8118.                store the current drive and directory settings prior to
  8119.                executing the program, and restore them after the program has
  8120.                returned.
  8121.  
  8122.                Normally, the user's time will continue to be decreased during
  8123.                the execution of the od_spawn() function. However, you can
  8124.                freeze the user's time during the spawn process by using the
  8125.                OpenDoors control structure variable od_spawn_freeze_time.
  8126.  
  8127.  
  8128. SEE ALSO       od_spawnvpe()
  8129.  
  8130.  
  8131. EXAMPLE        Below are a few examples of various uses of the od_spawn()
  8132.                function:
  8133.  
  8134.                To run the command processor from within your door program, to
  8135.                allow the sysop access to the DOS shell, simply use the
  8136.                following line of code:
  8137.  
  8138.  
  8139. ===============================================================================
  8140. OpenDoors 5.00 Manual                                           End of Page 138
  8141.  
  8142.  
  8143.                               od_spawn(getenv("COMSPEC"));
  8144.  
  8145.                The following function is an example of using the od_spawn()
  8146.                function to call DSZ, allowing the user to download a file. You
  8147.                pass the name of the file that you wish to send to the user.
  8148.                This function will then ask the user what transfer protocol they
  8149.                would like to use, generate the appropriate DSZ command line,
  8150.                and then transmit the file to the user. Note that in order to
  8151.                use a door which implements this function, the external file
  8152.                transfer program "DSZ" must be available in the current search
  8153.                path. As an alternative, you may want to allow the sysop to
  8154.                specify the location of the DSZ file from within a configuration
  8155.                program. If you wish to receive a file (allow the user to
  8156.                upload), instead of sending one, simply change the "s" in the
  8157.                command line to a "r".
  8158.  
  8159.                char download(char *filename)
  8160.                   {
  8161.                   char commandline[80];/* string containing DSZ command line */
  8162.                   char protocol;   /* character representing chosen protocol */
  8163.  
  8164.                                                     /* display protocol menu */
  8165.                   od_printf("Select File Transfer Protocol:\n\r");
  8166.                   od_printf("   [X] XModem\n\r");
  8167.                   od_printf("   [Y] YModem\n\r");
  8168.                   od_printf("   [Z] ZModem\n\r");
  8169.                   od_printf("or press [A] to abort transfer\n\r");
  8170.  
  8171.                   do            /* loop until valid protocol has been chosen */
  8172.                      {
  8173.                      protocol=od_get_key();                       /* get key */
  8174.                                               /* abort if [A] key is pressed */
  8175.                      if(protocol=='a' || protocol=='A') return(FALSE);
  8176.                      } while(protocol!='x' && protocol!='y' && protocol!='z' &&
  8177.                              protocol!='X' && protocol!='Y' && protocol!='Z');
  8178.  
  8179.                   od_printf("Begin receiving file now or press [CTRL]-[X] to
  8180.                              abort\n\r");
  8181.                                                 /* generate DSZ command line */
  8182.                   sprintf(commandline,"dsz port %d s%c %s",
  8183.                           od_control.port+1,
  8184.                           protocol,
  8185.                           filename);
  8186.  
  8187.                   return(od_spawn(commandline));             /* spawn to DSZ */
  8188.                   }
  8189.  
  8190.  
  8191.  
  8192.  
  8193.  
  8194.  
  8195.  
  8196.  
  8197.  
  8198. ===============================================================================
  8199. OpenDoors 5.00 Manual                                           End of Page 139
  8200.  
  8201.  
  8202.  
  8203.  
  8204.  
  8205.  
  8206. OD_SPAWNVPE()
  8207. -------------------------------------------------------------------------------
  8208.  
  8209. PURPOSE        To facilitate easy execution of child tasks from doors. Allows
  8210.                specification of child's environment, returns errorlevel
  8211.                returned by child task, and searches path for the executable
  8212.                file.
  8213.  
  8214.  
  8215. FORMAT         int od_spawnvpe(int modeflag, char *path, char *argv[],
  8216.                                char *envp[]);
  8217.  
  8218.  
  8219. RETURNS        -1 on failure
  8220.                errorlevel returned by child process on success
  8221.  
  8222.  
  8223. DESCRIPTION    This function behaves very similarly to the od_spawn() function.
  8224.                Thus, to save space in the manual, I will not recapitulate what
  8225.                is already said in the description of the od_spawn() function.
  8226.                Instead, this description concentrates on the additional
  8227.                features available through the od_spawnvpe() function. If you
  8228.                are not already familiar with the od_spawn() function, take a
  8229.                moment now to review the description of that function.
  8230.  
  8231.                The od_spawn() function (the OpenDoors "quick-spawn" function)
  8232.                is designed to be quick and easy to use, but does not have all
  8233.                of the features available in the od_spawnvpe() function. In
  8234.                addition to the features of the od_spawn() function, the
  8235.                od_spawnvpe() function also provides the following features:
  8236.  
  8237.                          - od_spawnvpe() will search the "path" for the file
  8238.                            to be executed.
  8239.  
  8240.                          - od_spawnvpe() allows you to pass an altered
  8241.                            environment to the child process.
  8242.  
  8243.                          - od_spawnvpe() returns the errorlevel returned by
  8244.                            the child process.
  8245.  
  8246.                The parameters passed to the od_spawnvpe() function are
  8247.                identical to those passed to the C spawnvpe() function. The
  8248.                first parameter should usually the be P_WAIT flag. The second
  8249.                parameter is the name of the child program to execute. If a full
  8250.                path to the child program is not specified, and the child
  8251.                program does not exist in the current directory, OpenDoors will
  8252.                search the directories listed by the PATH environment variable.
  8253.                Also, if the .EXE or .COM extension is not provide, OpenDoors
  8254.                will look first for a .COM file, and if not found, for a .EXE
  8255.                file. The third parameter is an array of arguments to pass to
  8256.  
  8257. ===============================================================================
  8258. OpenDoors 5.00 Manual                                           End of Page 140
  8259.  
  8260.  
  8261.                the child process, or NULL if no arguments are to be passed. The
  8262.                fourth parameter is the environment to be passed to the child
  8263.                process, or NULL if the a copy of the current environment should
  8264.                be used.
  8265.  
  8266.  
  8267. SEE ALSO       od_spawn()
  8268.  
  8269.  
  8270. EXAMPLE        For an example of the use of the od_spawn...() functions, see
  8271.                the example accompanying the od_spawn() function. As a specific
  8272.                example of the od_spawnvpe function, consider the following code
  8273.                which executes the "TEST.EXE" program.
  8274.  
  8275.                          od_spawnvpe(P_WAIT,"TEST.EXE",NULL,NULL);
  8276.  
  8277.  
  8278.  
  8279.  
  8280.  
  8281.  
  8282.  
  8283.  
  8284.  
  8285.  
  8286.  
  8287.  
  8288.  
  8289.  
  8290.  
  8291.  
  8292.  
  8293.  
  8294.  
  8295.  
  8296.  
  8297.  
  8298.  
  8299.  
  8300.  
  8301.  
  8302.  
  8303.  
  8304.  
  8305.  
  8306.  
  8307.  
  8308.  
  8309.  
  8310.  
  8311.  
  8312.  
  8313.  
  8314.  
  8315.  
  8316. ===============================================================================
  8317. OpenDoors 5.00 Manual                                           End of Page 141
  8318.  
  8319.  
  8320.  
  8321.  
  8322.  
  8323.  
  8324. OD_WINDOW_CREATE()
  8325. -------------------------------------------------------------------------------
  8326.  
  8327. PURPOSE        Creates a popup window of the specified size and colour, storing
  8328.                the contents of the screen "under" the window. The window can
  8329.                later be removed from the screen, restoring the original
  8330.                contents of the screen "under" the window, using the
  8331.                od_window_remove() function. Requires ANSI, AVATAR or RIP mode.
  8332.  
  8333.  
  8334. FORMAT         void *od_window_create(int left, int top, int right, int bottom,
  8335.                char *title, char boardcol, char titlecol, char insidecol, int
  8336.                reserved);
  8337.  
  8338.  
  8339. RETURNS        Pointer to newly allocated window structure on success
  8340.                NULL on failure
  8341.  
  8342.  
  8343. DESCRIPTION    This function creates a pop-up window on the remote and local
  8344.                screens. The contents of the screen beneath the window are
  8345.                stored, to allow the window to later be removed from the screen
  8346.                using the od_window_remove() function. The window is drawn using
  8347.                the boarder characters defined in the already existing
  8348.                od_control.od_box_chars[] array. The boarder is displayed using
  8349.                the colour attribute specified in "boardcol". The working area
  8350.                of the window is created in the colour specified in "insidecol".
  8351.                A title may optionally be displayed on the window by specifying
  8352.                a string in "title". This title will be displayed in the colour
  8353.                specified by "titlecol". If you do not wish a title to be
  8354.                displayed, pass an empty string or NULL pointer in "title". On
  8355.                success, od_window_create() will return a pointer to a buffer
  8356.                which was allocated to store information on the window and the
  8357.                contents of the screen "under" the window. This pointer should
  8358.                at some point be passed in a call to od_window_remove().
  8359.  
  8360.                This function requires ANSI, AVATAR or RIP graphics mode. If
  8361.                AVATAR mode is active, this function will take advantage of
  8362.                special AVATAR control sequences to display the window much
  8363.                faster than is possible in ANSI mode. In ANSI mode, window
  8364.                display will be faster if "boardcol" and "titlecol" are equal.
  8365.                Note that the "reserved" parameter of this function is not
  8366.                currently used. To preserve compatibility with future versions
  8367.                of OpenDoors, this parameter should always be set to 0.
  8368.                Currently, the size of the buffer allocated to store the window
  8369.                information will be (length*witdth*2) + 4 bytes in size.
  8370.  
  8371.                Due to the differences between ANSI and AVATAR terminal
  8372.                emulation in different software packages, it is not recommended
  8373.                to create windows when the remote screen may have been scrolled
  8374.  
  8375. ===============================================================================
  8376. OpenDoors 5.00 Manual                                           End of Page 142
  8377.  
  8378.  
  8379.                since the last call to od_clr_scr(). You should also avoid
  8380.                creating windows that cover the bottom right-hand corner of the
  8381.                screen.
  8382.  
  8383.                If od_window_create() fails for any reason, a value of NULL is
  8384.                returned, and the od_control.od_error variable is set to
  8385.                indicate the reason for the failure. For more information on the
  8386.                od_control.od_error variable, see page 182.
  8387.  
  8388.  
  8389. SEE ALSO       od_window_remove(), od_draw_box(), od_gettext(), od_puttext(),
  8390.                od_save_screen(), od_restore_screen(), od_scroll()
  8391.  
  8392.  
  8393. EXAMPLE
  8394.  
  8395.  
  8396.  
  8397.  
  8398.  
  8399.  
  8400.  
  8401.  
  8402.  
  8403.  
  8404.  
  8405.  
  8406.  
  8407.  
  8408.  
  8409.  
  8410.  
  8411.  
  8412.  
  8413.  
  8414.  
  8415.  
  8416.  
  8417.  
  8418.  
  8419.  
  8420.  
  8421.  
  8422.  
  8423.  
  8424.  
  8425.  
  8426.  
  8427.  
  8428.  
  8429.  
  8430.  
  8431.  
  8432.  
  8433.  
  8434. ===============================================================================
  8435. OpenDoors 5.00 Manual                                           End of Page 143
  8436.  
  8437.  
  8438.  
  8439.  
  8440.  
  8441.  
  8442. OD_WINDOW_REMOVE()
  8443. -------------------------------------------------------------------------------
  8444.  
  8445. PURPOSE        Removes a window previously created using od_window_create(),
  8446.                restoring the original screen background.
  8447.  
  8448.  
  8449. FORMAT         int od_window_remove(void *info);
  8450.  
  8451.  
  8452. RETURNS        TRUE on success
  8453.                FALSE on failure
  8454.  
  8455.  
  8456. DESCRIPTION    The od_window_remove() function removes a window from the screen
  8457.                which was previously created by od_window_create(), and
  8458.                deallocates the memory which was allocated to store the window
  8459.                information. The contents of the screen beneath the window is
  8460.                restored to appear as it did prior to the call to
  8461.                od_window_create().
  8462.  
  8463.                Note that overlapping windows must be removed in the reverse
  8464.                order from which they were created for proper display results.
  8465.                The last window to be created must be the first window to be
  8466.                removed.
  8467.  
  8468.                If od_window_remove() fails for any reason, a value of FALSE is
  8469.                returned, and the od_control.od_error variable is set to
  8470.                indicate the reason for the failure. For more information on the
  8471.                od_control.od_error variable, see page 182.
  8472.  
  8473.  
  8474. SEE ALSO       od_window_create(), od_draw_box(), od_gettext(), od_puttext(),
  8475.                od_save_screen(), od_restore_screen(), od_scroll()
  8476.  
  8477.  
  8478. EXAMPLE        For an example of the use of the od_window_remove() function,
  8479.                see the example which accompanies the description of the
  8480.                od_window_create() function. The od_window_create() function is
  8481.                documented on page 142.
  8482.  
  8483.  
  8484.  
  8485.  
  8486.  
  8487.  
  8488.  
  8489.  
  8490.  
  8491.  
  8492.  
  8493. ===============================================================================
  8494. OpenDoors 5.00 Manual                                           End of Page 144
  8495.  
  8496.  
  8497.  
  8498. -------------------------------------------------------------------------------
  8499. CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE
  8500. -------------------------------------------------------------------------------
  8501.  
  8502.  
  8503.  
  8504.  
  8505. INTRODUCTION TO THE CONTROL STRUCTURE
  8506. -------------------------------------------------------------------------------
  8507.  
  8508.                The OpenDoors "Control Structure" is used by OpenDoors in order
  8509.                to provide you with a wide range of information about the system
  8510.                on which you door is running, and the user who is currently
  8511.                using the door, along with providing you a means by which to
  8512.                customize much of OpenDoor's behavior. Using the OpenDoors
  8513.                control structure, you can access or alter information about the
  8514.                user who is online, information about the system on which your
  8515.                door is running, and information about OpenDoors itself. You can
  8516.                also use the control structure to customize all of the text
  8517.                displayed by OpenDoors, the function keys to which it responds,
  8518.                and many other aspects of OpenDoor's behavior.
  8519.  
  8520.                The OpenDoors control structure is quite simply a normal C
  8521.                "struct", named od_control, and is defined in the OPENDOOR.H
  8522.                file. This "struct" contains many different variables, which
  8523.                provide you access to the information provided by the control
  8524.                structure. Hence, to access the contents of a control structure
  8525.                variable, for example the variable "system_name" which contains
  8526.                the name of the BBS the door is running under, you would use:
  8527.  
  8528.                                   od_control.system_name
  8529.  
  8530.                The following section of this chapter contains a complete
  8531.                reference to all of the variables which make up the OpenDoors
  8532.                control structure. This reference includes the name, type and
  8533.                complete description of the use of each variable. The reference
  8534.                is divided into the following categories of variables, with the
  8535.                reference to the variables in each section beginning on the
  8536.                listed page.
  8537.  
  8538.                          Door Information File Statistics .................147
  8539.                          Modem Settings ...................................151
  8540.                          BBS and Caller Information .......................156
  8541.                          Door Settings ....................................179
  8542.                          OpenDoors Behavior Customization .................184
  8543.                          Function Keys Customization ......................206
  8544.                          Colour Customization .............................227
  8545.                          Text Customization ...............................212
  8546.  
  8547.                Within each section, variables are listed alphabetically,
  8548.                according to their names.
  8549.  
  8550.  
  8551.  
  8552. ===============================================================================
  8553. OpenDoors 5.00 Manual                                           End of Page 145
  8554.  
  8555.  
  8556.                If you would like more information on C "struct"s, please refer
  8557.                to your Turbo C(++)/Borland C++ manuals.
  8558.  
  8559.                Also, in order to make use of some of the variables in the
  8560.                OpenDoors control structure, it is important to understand the
  8561.                concepts of Boolean (TRUE/FALSE), and bit-mapped flag variables.
  8562.                If you are not familiar with these two terms, they are described
  8563.                in detail in the glossary, located towards the end of this
  8564.                manual.
  8565.  
  8566.  
  8567.  
  8568.  
  8569.  
  8570.  
  8571.  
  8572.  
  8573.  
  8574.  
  8575.  
  8576.  
  8577.  
  8578.  
  8579.  
  8580.  
  8581.  
  8582.  
  8583.  
  8584.  
  8585.  
  8586.  
  8587.  
  8588.  
  8589.  
  8590.  
  8591.  
  8592.  
  8593.  
  8594.  
  8595.  
  8596.  
  8597.  
  8598.  
  8599.  
  8600.  
  8601.  
  8602.  
  8603.  
  8604.  
  8605.  
  8606.  
  8607.  
  8608.  
  8609.  
  8610.  
  8611. ===============================================================================
  8612. OpenDoors 5.00 Manual                                           End of Page 146
  8613.  
  8614.  
  8615.  
  8616.  
  8617.  
  8618.  
  8619. CONTROL STRUCTURE - DOOR INFO FILE STATS
  8620. -------------------------------------------------------------------------------
  8621.  
  8622.                The following OpenDoors control structure variables provide your
  8623.                program with information concerning the door information file
  8624.                from which OpenDoors obtained the BBS and caller information
  8625.                that is found elsewhere in the control structure. The following
  8626.                control structure items are listed in this section:
  8627.  
  8628.                info_path                Contains the path to the door
  8629.                                         information file
  8630.  
  8631.                od_info_type             Type of door information file that was
  8632.                                         found
  8633.  
  8634.                od_node                  Node number the door is running under
  8635.  
  8636.                user_timeofcreation      The time at which the door information
  8637.                                         file was created
  8638.  
  8639.  
  8640.  
  8641.  
  8642. -------------------------------------------------------------------------------
  8643. info_path      char od_control.info_path[60];
  8644.  
  8645.                This variable stores the location of the door information file
  8646.                (such as DORINFO?.DEF, EXITINFO.BBS, CHAIN.TXT, DOOR.SYS,
  8647.                CALLINFO.BBS, SFDOORS.DAT, etc.), from which OpenDoors will read
  8648.                and write information about the BBS and the caller online. Note,
  8649.                however, that this variable only contains the path to this file,
  8650.                and not the name of the file itself. For example, if your door
  8651.                knew that the door information file resided in C:\BBS, this
  8652.                variable might contain "C:\\BBS\\". Remember that when
  8653.                programming in C, that you must place two backslash characters
  8654.                in a literal string in order to have a single backslash placed
  8655.                in the actual string, as shown in the example string above. The
  8656.                info_path variable is not case sensitive, and may or may not
  8657.                include the trailing backslash in the directory name.
  8658.  
  8659.                OpenDoors only uses this variable when it first starts up,
  8660.                during the od_init() function, and when it shuts down, during
  8661.                the od_exit() function. Thus, if you wish to alter the setting
  8662.                of the info_path variable, you must do so before calling
  8663.                od_init(), or any other OpenDoors functions. Also, you will not
  8664.                normally want to change the value of this variable after having
  8665.                called od_init() or any OpenDoors functions, as doing so would
  8666.                cause OpenDoors to re-write the caller information to another
  8667.                door information file in a different directory. This would most
  8668.                likely prevent the BBS system which your door is running under
  8669.  
  8670. ===============================================================================
  8671. OpenDoors 5.00 Manual                                           End of Page 147
  8672.  
  8673.  
  8674.                from being able to re-read the changes to the door information
  8675.                file.
  8676.  
  8677.                It is usually a good idea to design any door in such a way as to
  8678.                allow the user of the door to specify the location of the door
  8679.                information file. This will allow the sysop to place your door
  8680.                in it's own directory, and will facilitate the use of your door
  8681.                on multi-line BBS systems. If your door has a configuration
  8682.                file, you may wish to include a setting in the configuration
  8683.                file to indicate the location of the door information file.
  8684.                However, an even better design choice would be to allow the
  8685.                location of the door information file to optionally be passed to
  8686.                the door on the command line, as the example door, EZVote does.
  8687.                The following trivial door illustrates a method of reading and
  8688.                setting the location of the door information file from the
  8689.                door's command line:
  8690.  
  8691.                #include "opendoor.h"
  8692.  
  8693.                main(int argc, char *argv[])
  8694.                   {
  8695.                   if(argc>1) strncpy(od_control.info_path,argv[1],59);
  8696.  
  8697.                   od_disp_str("This is a sample OpenDoors door.\n\r");
  8698.                   od_disp_str("Press any key to continue...\n\r");
  8699.                   od_get_key(TRUE);
  8700.                   od_exit(20);
  8701.                   }
  8702.  
  8703.  
  8704.  
  8705. -------------------------------------------------------------------------------
  8706. od_info_type   char od_control.od_info_type;
  8707.  
  8708.                This variable indicates the type of information file from which
  8709.                OpenDoors has obtained the BBS and caller information that is
  8710.                found elsewhere in the OpenDoors control structure. This
  8711.                variable will have one of the following values, indicating that
  8712.                the door information file was of the corresponding type:
  8713.  
  8714.  
  8715.  
  8716.  
  8717.  
  8718.  
  8719.  
  8720.  
  8721.  
  8722.  
  8723.  
  8724.  
  8725.  
  8726.  
  8727.  
  8728.  
  8729. ===============================================================================
  8730. OpenDoors 5.00 Manual                                           End of Page 148
  8731.  
  8732.  
  8733.                      +----------------+----------------------------+
  8734.                      |  od_info_type  | Door Information File Type |
  8735.                      |      Value     |                            |
  8736.                      +----------------+----------------------------+
  8737.                      | DORINFO1       | DORINFO?.DEF               |
  8738.                      | EXITINFO       | EXITINFO.BBS (Normal)      |
  8739.                      | RA1EXITINFO    | EXITINFO.BBS (Extended)    |
  8740.                      | RA2EXITINFO    | EXITINFO.BBS (RA 2.x)      |
  8741.                      | QBBS275EXITINFO| EXITINFO.BBS (QuickBBS)    |
  8742.                      | CHAINTXT       | CHAIN.TXT                  |
  8743.                      | SFDOORSDAT     | SFDOORS.DAT                |
  8744.                      | CALLINFO       | CALLINFO.BBS               |
  8745.                      | DOORSYS_GAP    | DOOR.SYS (GAP/PC-Board)    |
  8746.                      | DOORSYS_DRWY   | DOOR.SYS (Doorway style)   |
  8747.                      | DOORSYS_WILDCAT| DOOR.SYS (WildCat standard)|
  8748.                      | CUSTOM         | Custom door information    |
  8749.                      |                | file, defined in config    |
  8750.                      |                | file.                      |
  8751.                      | NO_DOOR_FILE   | No drop file was found.    |
  8752.                      +----------------+----------------------------+
  8753.  
  8754.                The value of this variable is only valid AFTER od_init() or some
  8755.                OpenDoors function has been called.
  8756.  
  8757.                Note that this variable should be treated as a read-only
  8758.                variable, and should not normally be altered by your program.
  8759.                Altering this variable may cause OpenDoors to re-write a
  8760.                different type of door information file upon exiting, than was
  8761.                read upon startup.
  8762.  
  8763.  
  8764.  
  8765. -------------------------------------------------------------------------------
  8766. od_node        char od_control.od_node;
  8767.  
  8768.                This variable indicates the node number that the door is running
  8769.                under. If this information is supplied by the BBS in the door
  8770.                information file, the node number will be automatically by
  8771.                OpenDoors. Specifically, the node number can be determined
  8772.                automatically from systems that produce an SFDOORS.DAT, PC-
  8773.                Board/GAP style DOOR.SYS or Wildcat style DOOR.SYS door
  8774.                information file. If this information is not supplied in the
  8775.                door information file, but is provided by the sysop in the
  8776.                door's configuration file, OpenDoors will use the value found
  8777.                there. Alternatively, you can set this variable manually.
  8778.  
  8779.                On systems that produce a DORINFO?.DEF file, OpenDoors will use
  8780.                this variable to determine which DORINFO?.DEF file to search
  8781.                for. For instance, if od_control.od_node is set to 3, OpenDoors
  8782.                will first search for a DORINFO3.DEF file. If this file is not
  8783.                found, OpenDoors will then default to the DORINFO1.DEF filename.
  8784.  
  8785.  
  8786.  
  8787.  
  8788. ===============================================================================
  8789. OpenDoors 5.00 Manual                                           End of Page 149
  8790.  
  8791.  
  8792.  
  8793. -------------------------------------------------------------------------------
  8794. user           char od_control.user_timeofcreation[6];
  8795. _timeof
  8796. creation       This variable contains the time of day at which the door
  8797.                information file was created. This variable is available only
  8798.                when the door is running under a system that produces an
  8799.                EXITINFO.BBS file. To determine what type of door information
  8800.                file your door is running under, see the od_control.od_info_type
  8801.                variable, below.
  8802.  
  8803.  
  8804.  
  8805.  
  8806.  
  8807.  
  8808.  
  8809.  
  8810.  
  8811.  
  8812.  
  8813.  
  8814.  
  8815.  
  8816.  
  8817.  
  8818.  
  8819.  
  8820.  
  8821.  
  8822.  
  8823.  
  8824.  
  8825.  
  8826.  
  8827.  
  8828.  
  8829.  
  8830.  
  8831.  
  8832.  
  8833.  
  8834.  
  8835.  
  8836.  
  8837.  
  8838.  
  8839.  
  8840.  
  8841.  
  8842.  
  8843.  
  8844.  
  8845.  
  8846.  
  8847. ===============================================================================
  8848. OpenDoors 5.00 Manual                                           End of Page 150
  8849.  
  8850.  
  8851.  
  8852.  
  8853.  
  8854.  
  8855. CONTROL STRUCTURE - SERIAL PORT SETTINGS
  8856. -------------------------------------------------------------------------------
  8857.  
  8858.                The following OpenDoors control structure items store the
  8859.                communications settings that OpenDoors uses to communicate with
  8860.                the modem. These values are normally set upon the first call to
  8861.                an OpenDoors function, during the od_init() procedure. However,
  8862.                you may need to manual set this variables if:
  8863.  
  8864.                     - you wish to allow greater configurability of your door
  8865.                     - you are reading the door information file yourself
  8866.                     - you are using the OpenDoors to write a non-door
  8867.                      program
  8868.  
  8869.                Some of these variables are always used by OpenDoors, while
  8870.                others are only relevant if OpenDoor's built-in serial
  8871.                communications code is being used instead of a FOSSIL driver.
  8872.                Those that are only used when no FOSSIL driver is present are
  8873.                denoted by an [*] in the list below.
  8874.  
  8875.                The control structure variables controlling OpenDoor's serial
  8876.                port settings are as follows:
  8877.  
  8878.                od_control.baud             Serial Port BPS rate
  8879.  
  8880.                od_control.od_com_address   Serial Port address [*]
  8881.  
  8882.                 " " .od_com_fifo_trigger   16550A FIFO trigger szie
  8883.  
  8884.                od_control.od_com_irq       Serial Port IRQ number [*}
  8885.  
  8886.                od_control.od_com_method    Is FOSSIL or built-in serial I/O
  8887.                                            being used
  8888.  
  8889.                od_control.od_com_no_fifo   Disables use of 16550A FIFOs [*]
  8890.  
  8891.                od_control.od_com_rx_buf    Size of receive buffer [*]
  8892.  
  8893.                od_control.od_com_tx_buf    Size of transmit buffer [*]
  8894.  
  8895.                od_control.od_no_fossil     Prevents OpenDoors from using a
  8896.                                            FOSSIL driver, even if one is
  8897.                                            available.
  8898.  
  8899.                od_control.port             Serial port number, 0 based.
  8900.  
  8901.  
  8902.  
  8903.  
  8904.  
  8905.  
  8906. ===============================================================================
  8907. OpenDoors 5.00 Manual                                           End of Page 151
  8908.  
  8909.  
  8910. -------------------------------------------------------------------------------
  8911. baud           unsigned long od_control.baud;
  8912.  
  8913.                This variable contains the BPS rate at which the computer is
  8914.                communicating with the modem, not to be confused with the BPS
  8915.                rate at which the local modem is communicating with the remote
  8916.                modem.
  8917.  
  8918.                A value of 0 indicates that the door is operating in local mode.
  8919.  
  8920.                If a FOSSIL driver is being used for serial I/O, this value is
  8921.                ignored if it does not correspond to one of the baud rates that
  8922.                an application can directly set a FOSSIL driver to. The BPS
  8923.                rates recognized by FOSSIL drivers are: 300, 600, 1200, 2400,
  8924.                4800, 9600, 19200, 38400. If any other BPS rate is to be used,
  8925.                the FOSSIL driver must be locked at that BPS from the FOSSIL
  8926.                driver command-line. When locked, FOSSIL drivers ignore any
  8927.                attempt by an application to change the BPS rate of the locked
  8928.                port. For this reason, the od_control.baud setting has no effect
  8929.                on the FOSSIL driver if it is locked.
  8930.  
  8931.                If a FOSSIL driver is not being used for serial I/O, this value
  8932.                my be any BPS rate from 2 to 115,200 that is evenly divides
  8933.                115,200 (eg: 115200, 57600, 38400, 28800, 23040, 19200, 14400,
  8934.                12800, 9600, etc.).
  8935.  
  8936.                This variable should only be change prior to calling od_init()
  8937.                or the first OpenDoors function.
  8938.  
  8939.  
  8940.  
  8941. -------------------------------------------------------------------------------
  8942. od_com_        int od_control.od_com_address;
  8943. address
  8944.                This variable is only used when OpenDoors is NOT performing
  8945.                serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
  8946.                used, the serial port address can be set from the FOSSIL driver
  8947.                command line).
  8948.  
  8949.                This variable may optionally be set to specify the base address
  8950.                of the serial port to be used. For ports COM1: through COM4:,
  8951.                OpenDoors can normally determine the serial port address
  8952.                automatically. However, for other serial ports, the port address
  8953.                must be specified using this variable. If you are not specifying
  8954.                a serial port address with this variable, do not change it's
  8955.                default value of 0.
  8956.  
  8957.                This variable should only be changed before your first call to
  8958.                od_init() or any other OpenDoors function.
  8959.  
  8960.  
  8961.  
  8962.  
  8963.  
  8964.  
  8965. ===============================================================================
  8966. OpenDoors 5.00 Manual                                           End of Page 152
  8967.  
  8968.  
  8969. -------------------------------------------------------------------------------
  8970. od_com_        char od_control.od_com_fifo_trigger;
  8971. fifo_trigger
  8972.                This variable is only used when OpenDoors is NOT performing
  8973.                serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
  8974.                used, the IRQ line can be set from the FOSSIL driver command
  8975.                line).
  8976.  
  8977.                This variable sets the number of bytes that will be placed in
  8978.                the 16550A UART FIFO buffers before an interrupt is triggered,
  8979.                if the 16550A UART FIFOs are used. Valid values are 1, 4, 8 and
  8980.                14.
  8981.  
  8982.  
  8983.  
  8984. -------------------------------------------------------------------------------
  8985. od_com_        unsigned char od_control.od_com_irq;
  8986. irq
  8987.                This variable is only used when OpenDoors is NOT performing
  8988.                serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
  8989.                used, the IRQ line can be set from the FOSSIL driver command
  8990.                line).
  8991.  
  8992.                This variable may optionally be set to specify the IRQ line to
  8993.                be used for the serial port. By default, OpenDoors uses the
  8994.                normal IRQ 4 line for ports COM1: and COM3:, and IRQ 3 for ports
  8995.                COM2: and COM4:. To override this default, the IRQ line can be
  8996.                set using this variable. If you are not specifying an IRQ line
  8997.                with this variable, do not change it's default value of 0.
  8998.  
  8999.                This variable should only be changed before your first call to
  9000.                od_init() or any other OpenDoors function.
  9001.  
  9002.  
  9003.  
  9004. -------------------------------------------------------------------------------
  9005. od_com_        char od_control.od_com_method;
  9006. method
  9007.                This read-only variable reports the method that OpenDoors is
  9008.                using for serial I/O. This variable is set during od_init() or
  9009.                the first call to an OpenDoors function. This variable can be
  9010.                one of the following values:
  9011.  
  9012.                COM_FOSSIL     - Indicates that a FOSSIL driver is being used
  9013.                COM_INTERNAL   - Indicates that OpenDoor's internal serial I/O
  9014.                                 code is being used.
  9015.  
  9016.                OpenDoors normally automatically determines whether not a FOSSIL
  9017.                driver is available, and will attempt to use a FOSSIL driver if
  9018.                possible. You can force OpenDoors to always perform serial I/O
  9019.                using its internal communications code, bypassing a FOSSIL
  9020.                driver if present, by setting the od_control.od_no_fossil
  9021.                variable to TRUE.
  9022.  
  9023.  
  9024. ===============================================================================
  9025. OpenDoors 5.00 Manual                                           End of Page 153
  9026.  
  9027.  
  9028.  
  9029.  
  9030. -------------------------------------------------------------------------------
  9031. od_com_        char od_control.od_com_no_fifo;
  9032. no_fifo
  9033.                This variable is only used when OpenDoors is NOT performing
  9034.                serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
  9035.                used, the receive buffer size can be set from the FOSSIL driver
  9036.                command line).
  9037.  
  9038.                Normally, OpenDoors will use a 16550A FIFO buffer if a 16550A
  9039.                UART is installed. You can disable the use of the 16550A FIFO
  9040.                buffer by setting this variable to TRUE.
  9041.  
  9042.  
  9043.  
  9044. -------------------------------------------------------------------------------
  9045. od_com_        unsigned int od_control.od_com_rx_buf;
  9046. rx_buf
  9047.                This variable is only used when OpenDoors is NOT performing
  9048.                serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
  9049.                used, the receive buffer size can be set from the FOSSIL driver
  9050.                command line).
  9051.  
  9052.                This variable allows you to set the size of OpenDoor's serial
  9053.                I/O receive buffer. If you do not set this buffer size, a
  9054.                default value of 256 characters is used. Normally, this buffer
  9055.                size is more than large enough for door programs. However, if
  9056.                you find that inbound characters are lost before they can be
  9057.                processed by your program, you may wish to increase the size of
  9058.                this buffer.
  9059.  
  9060.                This variable should only be changed before your first call to
  9061.                od_init() or any other OpenDoors function.
  9062.  
  9063.  
  9064.  
  9065. -------------------------------------------------------------------------------
  9066. od_com_        unsigned int od_control.od_com_rx_buf;
  9067. rx_buf
  9068.                This variable is only used when OpenDoors is NOT performing
  9069.                serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
  9070.                used, the receive buffer size can be set from the FOSSIL driver
  9071.                command line).
  9072.  
  9073.                This variable allows you to set the size of OpenDoor's serial
  9074.                I/O receive buffer. If you do not set this buffer size, a
  9075.                default value of 256 characters is used. Normally, this buffer
  9076.                size is more than large enough for door programs. However, if
  9077.                you find that inbound characters are lost before they can be
  9078.                processed by your program, you may wish to increase the size of
  9079.                this buffer.
  9080.  
  9081.  
  9082.  
  9083. ===============================================================================
  9084. OpenDoors 5.00 Manual                                           End of Page 154
  9085.  
  9086.  
  9087.                This variable should only be changed before your first call to
  9088.                od_init() or any other OpenDoors function.
  9089.  
  9090.  
  9091.  
  9092. -------------------------------------------------------------------------------
  9093. port           char od_control.port;
  9094.  
  9095.                This variable contains the serial port number that the modem is
  9096.                connected. This number is 0 based, so that a value of 0
  9097.                corresponds to COM1:, a value of 1 corresponds to COM2:, and so
  9098.                on. This value will normally be set by the od_init() function,
  9099.                when the door information file is read, and should not be
  9100.                changed after modem initialization has been carried out by the
  9101.                od_init() function. In other words, od_control.port should
  9102.                generally be treated as a read-only variable.
  9103.  
  9104.                This variable will most often be useful in passing the port
  9105.                number to an external program, such as DSZ.
  9106.  
  9107.  
  9108.  
  9109.  
  9110.  
  9111.  
  9112.  
  9113.  
  9114.  
  9115.  
  9116.  
  9117.  
  9118.  
  9119.  
  9120.  
  9121.  
  9122.  
  9123.  
  9124.  
  9125.  
  9126.  
  9127.  
  9128.  
  9129.  
  9130.  
  9131.  
  9132.  
  9133.  
  9134.  
  9135.  
  9136.  
  9137.  
  9138.  
  9139.  
  9140.  
  9141.  
  9142. ===============================================================================
  9143. OpenDoors 5.00 Manual                                           End of Page 155
  9144.  
  9145.  
  9146.  
  9147.  
  9148.  
  9149. CONTROL STRUCTURE - BBS AND CALLER INFORMATION
  9150. -------------------------------------------------------------------------------
  9151.  
  9152.                As we have already described, there are two types of variables
  9153.                in the OpenDoors control structure. Some of the variables are
  9154.                simply used to allow you to customize OpenDoor's various
  9155.                features, such as altering colours, prompts, timeouts, etc.
  9156.                Other variables in the OpenDoors control structure serve to
  9157.                provide you with information about the user who is online and
  9158.                the BBS system your door is running under. This section deals
  9159.                with those variables that provide you with information about the
  9160.                BBS and the user.
  9161.  
  9162.                The information in these variables is read from the door
  9163.                information file, a small file created by the BBS specifically
  9164.                for the purpose of communicating with door programs. Depending
  9165.                on what BBS system your door is running under, the type of door
  9166.                information file will vary. Since different door information
  9167.                files do not all provide the same pieces of information, some
  9168.                variables in this section will only be available when your door
  9169.                is running under particular BBS systems.  Other variables will
  9170.                be available with many or all BBS systems. In the description of
  9171.                each variable in this section, we indicate under which door
  9172.                information files the particular variable will be . So, if you
  9173.                wish to access a variable that is only under certain door
  9174.                information files, your program should test whether or not the
  9175.                required information is available under the particular door
  9176.                information file that was found. In order to determine which
  9177.                door information file your door is running under, you should use
  9178.                the od_control.od_info_type variable. This variable is described
  9179.                in the section which begins on page 147. If you test the value
  9180.                of the od_control.od_info_type variable, and find that the
  9181.                required information is not available, you may wish to simply
  9182.                use some sort of default value for the variable, or
  9183.                alternatively, not allow your door to run under certain BBS
  9184.                systems. Another possibility, if the required information is not
  9185.                available, is imply to obtain this information from the user
  9186.                yourself. For example, if you wished to know the length of the
  9187.                user's screen, when this information is not available from the
  9188.                door information file, you could simply prompt the user for
  9189.                their screen length the first time they use your door. This
  9190.                information could then be stored in your door's data files for
  9191.                future reference.
  9192.  
  9193.                As an example of testing what door information file your door is
  9194.                running under, consider the case where you wanted to display the
  9195.                user's birthday. The example below will display the user's
  9196.                birthday if it is known, and otherwise, print the string
  9197.                "unknown".
  9198.  
  9199.                          if(od_control.od_info_type==RA1EXITINFO)
  9200.  
  9201. ===============================================================================
  9202. OpenDoors 5.00 Manual                                           End of Page 156
  9203.  
  9204.  
  9205.                             {
  9206.                             od_disp_str(od_control.user_birthday);
  9207.                             }
  9208.                          else
  9209.                             {
  9210.                             od_disp_str("Unknown");
  9211.                             }
  9212.  
  9213.                The chart below lists the door information file formats that
  9214.                OpenDoors recognizes, along with example BBS systems that
  9215.                produce these files and a reference letter for each type. Thus,
  9216.                an OpenDoors door can run DIRECTLY under ANY BBS SYSTEM that
  9217.                produces one of these files formats, and under ANY OTHER BBS
  9218.                system when used in conjunction with a door information file
  9219.                conversion utility.
  9220.  
  9221. +--------------------------+----------------------------------------+
  9222. | FILE FORMAT              | EXAMPLE BBS SYSTEMS                    |
  9223. +--------------------------+----------------------------------------+
  9224. | CHAIN.TXT                | WWIV                                   |
  9225. +--------------------------+----------------------------------------+
  9226. | DORINFO1.DEF             | RBBS-PC                                |
  9227. +--------------------------+----------------------------------------+
  9228. | DORINFO1.DEF             | QuickBBS                               |
  9229. |      &                   | Remote Access (versions 0.01-0.04)     |
  9230. | EXITINFO.BBS (Std. Ver.) |                                        |
  9231. +--------------------------+----------------------------------------+
  9232. | DOOR.SYS (DoorWay Style) | Remote Access                          |
  9233. +--------------------------+----------------------------------------+
  9234. | DOOR.SYS (PCB/GAP Style) | PC-Board                               |
  9235. |                          | GAP                                    |
  9236. +--------------------------+----------------------------------------+
  9237. | DOOR.SYS (WildCat Style) | Wildcat 3.00 and above                 |
  9238. |                          | Telegard                               |
  9239. +--------------------------+----------------------------------------+
  9240. | SFDOORS.DAT              | Spitfire                               |
  9241. |                          | TriTel                                 |
  9242. +--------------------------+----------------------------------------+
  9243. | CALLINFO.BBS             | WildCat 2.xx                           |
  9244. +--------------------------+----------------------------------------+
  9245. | DORINFO1.DEF             | Remote Access (versions 1.00 and later)|
  9246. |      &                   |                                        |
  9247. | EXITINFO.BBS (Ext. Ver.) |                                        |
  9248. +--------------------------+----------------------------------------+
  9249.  
  9250.  
  9251.  
  9252.  
  9253.  
  9254.  
  9255.  
  9256.  
  9257.  
  9258.  
  9259.  
  9260. ===============================================================================
  9261. OpenDoors 5.00 Manual                                           End of Page 157
  9262.  
  9263.  
  9264.  
  9265.  
  9266.  
  9267.                The following chart lists all of the OpenDoors control structure
  9268.                variables in this section, along with a brief description of
  9269.                their use. The variables are then described in detail, below.
  9270.  
  9271. +-----------------------+-----------------------------------------------+
  9272. | VARIABLE NAME         | VARIABLE CONTENTS                             |
  9273. +-----------------------+-----------------------------------------------+
  9274. | EMSI INFORMATION      | Information on current IEMSI session          |
  9275. | event_status          | The status of the next system event           |
  9276. | event_starttime       | The start time of the next system event       |
  9277. | event_errorlevel      | The errorlevel of the next system event       |
  9278. | event_days            | The days of the week to execute the event     |
  9279. | event_force           | Whether the next system event is forced       |
  9280. | event_last_run        | When the next system event was last run       |
  9281. | sysop_name            | The name of the BBS's sysop                   |
  9282. | system_calls          | Total number of calls BBS has received        |
  9283. | system_last_caller    | The name of the last caller to the BBS        |
  9284. | system_name           | The name of the BBS                           |
  9285. | TIMELOG VARIABLES     | The times at which the BBS has been most busy |
  9286. | user_ansi             | Whether the user has ANSI graphics mode on    |
  9287. | user_attribute        | User attribute bit-mapped flags               |
  9288. | user_attrib2          | Second set of user attribute bit-mapped flags |
  9289. | user_avatar           | Whether the user has AVATAR graphics mode on  |
  9290. | user_birthday         | The date the user was born                    |
  9291. | user_callsign         | The user's amateur radio call sign            |
  9292. | user_combinedrecord   | The user's combined message areas settings    |
  9293. | user_comment          | Sysop's comment about the user                |
  9294. | user_credit           | Amount of NetMail credit the user has         |
  9295. | user_dataphone        | The user's data phone number                  |
  9296. | user_date_format      | Format user wishes to have dates displayed in |
  9297. | user_deducted_time    | Total time that has been subtracted from user |
  9298. | user_downk            | Total Kilobytes downloaded by the user        |
  9299. | user_downlimit        | User's daily download limit                   |
  9300. | user_downloads        | Total number of files downloaded by the user  |
  9301. | user_echomailentered  | Whether or not the user has entered EchoMail  |
  9302. | user_error_free       | Whether or not connection is error-free       |
  9303. | user_file_area        | The user's current file area                  |
  9304. | user_firstcall        | Date of the user's first call to the BBS      |
  9305. | user_flags            | User's sysop-defined flag settings            |
  9306. | user_forward_to       | Name to forward user's mail to                |
  9307. | user_group            | User's group number                           |
  9308. | user_handle           | User's alias                                  |
  9309. | user_homephone        | User's home telephone number                  |
  9310. | user_language         | User's language setting                       |
  9311. | user_last_pwdchange   | Total calls since last password change        |
  9312. | user_lastdate         | Date of the user's last call                  |
  9313. | user_lastread         | Highest message number read by user           |
  9314. | user_lasttime         | Time of the user's last call                  |
  9315. | user_location         | Name of the city where the user lives         |
  9316. | user_logindate        | Date on which the current call began          |
  9317. +-----------------------+-----------------------------------------------+
  9318.  
  9319. ===============================================================================
  9320. OpenDoors 5.00 Manual                                           End of Page 158
  9321.  
  9322.  
  9323.  
  9324.  
  9325.  
  9326. +-----------------------+-----------------------------------------------+
  9327. | VARIABLE NAME         | VARIABLE CONTENTS                             |
  9328. +-----------------------+-----------------------------------------------+
  9329. | user_loginsec         | User's security at the beginning of this call |
  9330. | user_logintime        | Time at which the current call began          |
  9331. | user_logonpassword    | User's password at the beginning of this call |
  9332. | user_menustack        | Contents of the user's current menu stack     |
  9333. | user_menustackpointer | Pointer to the top of the menu stack          |
  9334. | user_messages         | Total number of messages written by the user  |
  9335. | user_msg_area         | The user's current message area               |
  9336. | user_name             | The user's name                               |
  9337. | user_net_credit       | The user's remaining netmail credit           |
  9338. | user_netmailentered   | Whether or not the user has entered NetMail   |
  9339. | user_num              | The user's record number in the user file     |
  9340. | user_numcalls         | Number of calls the user has made to the BBS  |
  9341. | user_numpages         | Number of times the user has paged the sysop  |
  9342. | user_password         | The user's current password                   |
  9343. | user_pending          | The value of unsent NetMail written by user   |
  9344. | user_reasonforchat    | The reason the user wishes to chat with sysop |
  9345. | user_screen_length    | The length of the user's screen               |
  9346. | user_screenwidth      | The width of the user's screen                |
  9347. | user_security         | The user's security access level              |
  9348. | user_sex              | The user's gender                             |
  9349. | user_subdate          | The date the user's subscription expires      |
  9350. | user_timelimit        | The user's daily time limit                   |
  9351. | user_todayk           | Kilobytes downloaded by the user today        |
  9352. | user_upk              | Total Kilobytes uploaded by the user          |
  9353. | user_uploads          | Total number of files uplaoded by the user    |
  9354. | user_wantchat         | Whether or not the user wishes to chat        |
  9355. | user_xi_record        | The user's record in the USERSXI.BBS file     |
  9356. +-----------------------+-----------------------------------------------+
  9357.  
  9358.  
  9359.  
  9360.  
  9361. -------------------------------------------------------------------------------
  9362. EMSI           char od_control.ra_emsi_session;
  9363. INFORMATION    char od_control.ra_emsi_crtdef[41];
  9364.                char od_control.ra_emsi_protocols[41];
  9365.                char od_control.ra_emsi_capabilities[41];
  9366.                char od_control.ra_emsi_requests[41];
  9367.                char od_control.ra_emsi_software[41];
  9368.                char od_control.ra_hold_attr1;
  9369.                char od_control.ra_hold_attr2;
  9370.                char od_control.ra_hold_len;
  9371.  
  9372.                These variables provide your door with information pertaining to
  9373.                an interactive EMSI session that has been established. Note that
  9374.                these variables are only available under systems that produce an
  9375.                RA 1.00 and later style extended EXITINFO.BBS door information
  9376.                file.
  9377.  
  9378. ===============================================================================
  9379. OpenDoors 5.00 Manual                                           End of Page 159
  9380.  
  9381.  
  9382.  
  9383.                If an IEMSI session has been established, the Boolean variable
  9384.                od_control.ra_emsi_session will be TRUE, and if no session has
  9385.                not been established, this variable will be FALSE.
  9386.  
  9387.                A full discussion of the IEMSI protocol is beyond the scope of
  9388.                this manual. Specifications for the IEMSI protocol are available
  9389.                from the OpenDoors support BBS.
  9390.  
  9391.  
  9392.  
  9393. -------------------------------------------------------------------------------
  9394. event_days     unsigned char od_control.event_days;
  9395.  
  9396.                This variable is a bit-mapped flag of the days of the week on
  9397.                which the next system event is run. The bit-map bits are as
  9398.                follows:
  9399.  
  9400.                        +-----+------+-----------+
  9401.                        | BIT | MASK | MEANING   |
  9402.                        +-----+------+-----------+
  9403.                        |  0  | 0x01 | Sunday    |
  9404.                        |  1  | 0x02 | Monday    |
  9405.                        |  2  | 0x04 | Tuesday   |
  9406.                        |  3  | 0x08 | Wednesday |
  9407.                        |  4  | 0x10 | Thursday  |
  9408.                        |  5  | 0x20 | Friday    |
  9409.                        |  6  | 0x40 | Saturday  |
  9410.                        |  7  | 0x80 | All Days  |
  9411.                        +-----+------+-----------+
  9412.  
  9413.                For more information on bit-mapped flags, see the glossary item
  9414.                entitled "BIT-MAPPED FLAGS".
  9415.  
  9416.                This variable is only available under systems that produce an
  9417.                EXITINFO.BBS door information file.
  9418.  
  9419.  
  9420.  
  9421. -------------------------------------------------------------------------------
  9422. event_         unsigned char od_control.event_errorlevel;
  9423. errorlevel
  9424.                This variable contains the ErrorLevel associated with the next
  9425.                system event. This variable is only available under systems that
  9426.                produce an EXITINFO.BBS door information file.
  9427.  
  9428.  
  9429.  
  9430. -------------------------------------------------------------------------------
  9431. event          char od_control.event_force;
  9432. _force
  9433.                This variable indicates whether the next system event should be
  9434.                forced to run at a particular time. If this variable contains a
  9435.                value of TRUE, then the user should be forced off-line in order
  9436.  
  9437. ===============================================================================
  9438. OpenDoors 5.00 Manual                                           End of Page 160
  9439.  
  9440.  
  9441.                to accommodate the event, and if this variable is false, then
  9442.                the event can wait until after the user logs off normally. This
  9443.                variable is only available under systems that produce an
  9444.                EXITINFO.BBS file.
  9445.  
  9446.  
  9447.  
  9448. -------------------------------------------------------------------------------
  9449. event          char od_control.event_last_run[9];
  9450. _last_run
  9451.                This variable contains a string representing the date on which
  9452.                the next system event was last run, and is in the same format as
  9453.                the user_lastdate variable. This variable is only available
  9454.                under systems that produce an EXITINFO.BBS file.
  9455.  
  9456.  
  9457.  
  9458. -------------------------------------------------------------------------------
  9459. event          char od_control.event_starttime[6];
  9460. _starttime
  9461.                This variable contains a string representing the time at which
  9462.                the next system event is scheduled to start, in the same format
  9463.                as the user_lasttime variable. This variable is only available
  9464.                under systems that produce an EXITINFO.BBS or Wildcat style
  9465.                DOOR.SYS door information file.
  9466.  
  9467.  
  9468.  
  9469. -------------------------------------------------------------------------------
  9470. event          unsigned char od_control.event_status;
  9471. _status
  9472.                This variable represents the status of the next system event,
  9473.                and will be equal to the value
  9474.  
  9475.                             ES_ENABLED
  9476.  
  9477.                if and only if the other event information contained in the
  9478.                control structure is valid. This variable is only available
  9479.                under systems that produce an EXITINFO.BBS file.
  9480.  
  9481.  
  9482.  
  9483. -------------------------------------------------------------------------------
  9484. sysop_name     char od_control.sysop_name[40];
  9485.  
  9486.                The od_control.sysop_name variable contains the name of the
  9487.                sysop of the BBS under which your door is running. This variable
  9488.                is available under any BBS system that produces a DORINFO?.DEF
  9489.                (including RA & QBBS which process both DORINFO1.DEF and
  9490.                EXITINFO.BBS files), or Wildcat style DOOR.SYS file.
  9491.  
  9492.  
  9493.  
  9494.  
  9495.  
  9496. ===============================================================================
  9497. OpenDoors 5.00 Manual                                           End of Page 161
  9498.  
  9499.  
  9500. -------------------------------------------------------------------------------
  9501. system_calls   long od_control.system_calls;
  9502.  
  9503.                This variable contains the total number of calls that have been
  9504.                placed to the BBS, and is available under any BBS which produces
  9505.                an EXITINFO.BBS file.
  9506.  
  9507.  
  9508.  
  9509. -------------------------------------------------------------------------------
  9510. system_last    char od_control.system_last_caller[36];
  9511. _caller
  9512.                This string contains the name of the previous caller to the BBS,
  9513.                on any line, and is available under EXITINFO.BBS.
  9514.  
  9515.  
  9516.  
  9517. -------------------------------------------------------------------------------
  9518. system_name    char od_control.system_name[40];
  9519.  
  9520.                The od_control.system_name variable contains the name of the BBS
  9521.                under which your door is running. This variable is available
  9522.                under any BBS system that produces a DORINFO?.DEF (including RA
  9523.                & QBBS which process both DORINFO1.DEF and EXITINFO.BBS files).
  9524.  
  9525.  
  9526.  
  9527. -------------------------------------------------------------------------------
  9528. TIMELOG        char od_control.timelog_start_date[9];
  9529. VARIABLES
  9530.                This string contains the date of the beginning of the time
  9531.                period for which the time log is recorded. This variable is
  9532.                available under any system that produces an EXITINFO.BBS file.
  9533.  
  9534.  
  9535.                int od_control.timelog_busyperhour[24];
  9536.  
  9537.                This variable is an array of 24 elements, with each element
  9538.                indicating the total number of times the BBS was in use during
  9539.                each of the 24 hours of the day. Element 0 corresponds to the
  9540.                time period of 0:00-1:00, element 1 corresponds to the time
  9541.                period of 1:00-2:00, and so on. In order to determine the
  9542.                frequency of system use during any hour as a percentage, simply
  9543.                calculate the total of all 24 entries in the array, and divide
  9544.                any given entry by the total, in order to come up with an
  9545.                average. This variable is available under any system that
  9546.                produces an EXITINFO.BBS file.
  9547.  
  9548.  
  9549.                int od_control.timelog_busyperday[7];
  9550.  
  9551.                This variable is an array of 7 elements, with each element
  9552.                indicating the total number of times the BBS was in use during
  9553.                each of the 7 days of the week. Here, elements 0 corresponds to
  9554.  
  9555. ===============================================================================
  9556. OpenDoors 5.00 Manual                                           End of Page 162
  9557.  
  9558.  
  9559.                Sunday, element 1 to Monday, and so on. In order to calculate
  9560.                the frequency of system use during any day of the week, use the
  9561.                same method as for calculating the frequency of calls during
  9562.                each hour, as described above. This is only available under
  9563.                systems that produces an EXITINFO.BBS file. Note that at least
  9564.                some, if not all, versions of RemoteAccess do not maintain this
  9565.                variable correctly, and thus even with the presence of an
  9566.                EXITINFO.BBS file, this array may contain all zero entries.
  9567.  
  9568.  
  9569.  
  9570. -------------------------------------------------------------------------------
  9571. user_ansi      char od_control.user_ansi;
  9572.  
  9573.                This variable contains a Boolean value, indicating whether or
  9574.                not the user has ANSI mode turned on. If ANSI graphics mode is
  9575.                enabled, this variable will contain a value of TRUE, and if ANSI
  9576.                graphics mode is disabled, this variable will contain a value of
  9577.                FALSE. Many of the OpenDoors functions test the setting of this
  9578.                variable in order to determine whether or not they should send
  9579.                ANSI-graphics control characters. Also, if this variable
  9580.                contains a TRUE value, OpenDoors will display an "[ANSI]"
  9581.                indicator on the status line.
  9582.  
  9583.                You may change the value of this variable at any time after the
  9584.                first call to od_init() or any other OpenDoors functions.
  9585.                Depending upon what BBS system your door is running under,
  9586.                changes to this variable may or may not result in changes to the
  9587.                user's ANSI setting upon return to the BBS.
  9588.  
  9589.                This variable is available under all door information file
  9590.                formats.
  9591.  
  9592.  
  9593.  
  9594. -------------------------------------------------------------------------------
  9595. user_          unsigned char od_control.user_attribute;
  9596. attribute
  9597.                This variable is a bitmap of eight flags, each of which
  9598.                represent individual pieces of information pertaining to the
  9599.                user that is currently online. These flags are as follows:
  9600.  
  9601.                        +-----+------+-----------------------+
  9602.                        | BIT | MASK | DESCRIPTION           |
  9603.                        +-----+------+-----------------------+
  9604.                        |  0  | 0x01 | Is the user deleted   |
  9605.                        |  1  | 0x02 | Is screen clearing on |
  9606.                        |  2  | 0x04 | Is "more" prompt on   |
  9607.                        |  3  | 0x08 | Is ANSI mode on       |
  9608.                        |  4  | 0x10 | User no-kill setting  |
  9609.                        |  5  | 0x20 | Transfer-priority     |
  9610.                        |  6  | 0x40 | Full screen editor    |
  9611.                        |  7  | 0x80 | Quiet mode            |
  9612.                        +-----+------+-----------------------+
  9613.  
  9614. ===============================================================================
  9615. OpenDoors 5.00 Manual                                           End of Page 163
  9616.  
  9617.  
  9618.  
  9619.                For more information on using and setting bit-mapped flags,
  9620.                please see the entry entitled "BITMAPED FLAGS" in the glossary
  9621.                of this manual.
  9622.  
  9623.                Note that this variable is only available under systems that
  9624.                produce and EXITINFO.BBS format door information file.
  9625.  
  9626.  
  9627.  
  9628. -------------------------------------------------------------------------------
  9629. user_          unsigned char od_control.user_attrib2;
  9630. attrib2
  9631.                See the user_attrib variable for more information. This variable
  9632.                is like the user_attrib variable, except that it contains
  9633.                different information. The bit-mapped flags for the
  9634.                od_control.user_attrib2 variable are as follows:
  9635.  
  9636.                        +-----+------+-----------------------+
  9637.                        | BIT | MASK | DESCRIPTION           |
  9638.                        +-----+------+-----------------------+
  9639.                        |  0  | 0x01 | User hot-keys setting |
  9640.                        |  1  | 0x02 | Is AVATAR graphics on |
  9641.                        |  2  | 0x04 | Full screen reader    |
  9642.                        |  3  | 0x08 | Hidden from userlist  |
  9643.                        +-----+------+-----------------------+
  9644.  
  9645.                Note that this variable is only available under systems that
  9646.                produce an EXITINFO.BBS door information file.
  9647.  
  9648.  
  9649.  
  9650. -------------------------------------------------------------------------------
  9651. user_avatar    char od_control.user_avatar;
  9652.  
  9653.                This variable is a Boolean value indicating whether or not
  9654.                AVATAR graphics mode is on. If AVATAR graphics is available,
  9655.                then many of the OpenDoors functions will make use of AVATAR
  9656.                graphics codes for greater display speed. If AVATAR graphics
  9657.                mode is on, a [AVT] indicator will appear on the status line. If
  9658.                your door is running under a system which produces an RA 1.00+
  9659.                style extended EXITINFO.BBS door information file, the
  9660.                user_avatar variable is set automatically. If the extended
  9661.                EXITINFO.BBS file is not available, this value will default to
  9662.                FALSE. In this case, you may wish to ask the user whether or not
  9663.                they wish to use AVATAR graphics, and thus set this variable
  9664.                yourself.
  9665.  
  9666.  
  9667.  
  9668.  
  9669.  
  9670.  
  9671.  
  9672.  
  9673. ===============================================================================
  9674. OpenDoors 5.00 Manual                                           End of Page 164
  9675.  
  9676.  
  9677. -------------------------------------------------------------------------------
  9678. user           char od_control.user_birthday[9];
  9679. _birthday
  9680.                This variable is a string, in the same format as the
  9681.                od_control.user_lastcall variable, which stores the date of the
  9682.                user's birthday, if it is available. This variable is only
  9683.                available under systems that produce an RA 1.00 and later style
  9684.                extended EXITINFO.BBS or Wildcat style DOOR.SYS file.
  9685.  
  9686.  
  9687.  
  9688. -------------------------------------------------------------------------------
  9689. user           char od_control.user_callsign[12];
  9690. _callsign
  9691.                This variable is a string which contains the user's amateur
  9692.                radio call sign, if any. This variable is only available under
  9693.                systems that produce a CHAIN.TXT file.
  9694.  
  9695.  
  9696.  
  9697. -------------------------------------------------------------------------------
  9698. user_combined  unsigned char od_control.user_combinedrecord[25];
  9699. record
  9700.                This variable is an array of bit-mapped flags, with each flag
  9701.                corresponding to an individual message area. In this case, the
  9702.                first bit of od_control.ra_combinedrecord[0] corresponds to the
  9703.                first message area, the second bit to the second message area,
  9704.                and so on. If any given bit-flag is turned on, then the user has
  9705.                corresponding message area enabled for combined access, and if
  9706.                the bit is turned off, the user does not have the area enabled
  9707.                for combined access. A detailed description of the combined
  9708.                message access is beyond the scope of this manual. This variable
  9709.                is only available under systems that produce an RA 1.00 or later
  9710.                style extended EXITINFO.BBS door information file.
  9711.  
  9712.  
  9713.  
  9714. -------------------------------------------------------------------------------
  9715. user_comment   char od_control.user_comment[81];
  9716.  
  9717.                This variable is a string which contains the sysop's comment
  9718.                about the user that is currently online. This comment may be
  9719.                displayed on the OpenDoors status line, if this variable is
  9720.                available. This variable is available under systems that produce
  9721.                an RA 1.00 and later style extended EXITINFO.BBS or Wildcat
  9722.                style DOOR.SYS file.
  9723.  
  9724.  
  9725.  
  9726. -------------------------------------------------------------------------------
  9727. user_credit    unsigned int od_control.user_credit;
  9728.  
  9729.                This variable contains the total amount of NetMail credit that
  9730.                the caller has left. Changes to this variable will be by the BBS
  9731.  
  9732. ===============================================================================
  9733. OpenDoors 5.00 Manual                                           End of Page 165
  9734.  
  9735.  
  9736.                when your door exits and control is returned to the BBS. This
  9737.                variable is only available under systems that produce an
  9738.                EXITINFO.BBS door information file.
  9739.  
  9740.  
  9741.  
  9742. -------------------------------------------------------------------------------
  9743. user_          char od_control.user_dataphone[13];
  9744. dataphone
  9745.                This string contains the user's data or business phone number,
  9746.                if available. This value is only available under system that
  9747.                produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS and WildCat
  9748.                DOOR.SYS format door information files.
  9749.  
  9750.  
  9751.  
  9752. -------------------------------------------------------------------------------
  9753. user           int od_control.user_deducted_time;
  9754. _deducted
  9755. _time          This variable contains a signed integer value, which indicates
  9756.                the total amount of time that has been deducted from the user
  9757.                during this call. This variable is only available under systems
  9758.                that produce an RA 1.00 and later style extended EXITINFO.BBS
  9759.                door information file.
  9760.  
  9761.  
  9762.  
  9763. -------------------------------------------------------------------------------
  9764. user_downk     unsigned int od_control.user_downk;
  9765.  
  9766.                This variable contains the total kilobytes of files that the
  9767.                current user has downloaded from the BBS, and is available under
  9768.                systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
  9769.                SFDOORS.DAT format door information files.
  9770.  
  9771.  
  9772.  
  9773. -------------------------------------------------------------------------------
  9774. user           unsigned int od_control.user_downlimit;
  9775. _downlimit
  9776.                This variable contains the total number of kilobytes that the
  9777.                caller is permitted to download during this call. If your door
  9778.                allows files do be downloaded, you will probably want to compare
  9779.                the value of this variable to the size of any file to be
  9780.                transferred and the total kilobytes already downloaded, as
  9781.                stored in the od_control.user_todayk variable. This variable is
  9782.                only available under systems that produce an EXITINFO.BBS file.
  9783.  
  9784.  
  9785.  
  9786.  
  9787.  
  9788.  
  9789.  
  9790.  
  9791. ===============================================================================
  9792. OpenDoors 5.00 Manual                                           End of Page 166
  9793.  
  9794.  
  9795. -------------------------------------------------------------------------------
  9796. user           unsigned int od_control.user_downloads;
  9797. _downloads
  9798.                This variable contains the total number of files that the
  9799.                current user has downloaded from the BBS, and is available under
  9800.                systems that produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS,
  9801.                WildCat style DOOR.SYS or SFDOORS.DAT format door information
  9802.                files.
  9803.  
  9804.  
  9805.  
  9806. -------------------------------------------------------------------------------
  9807. user_echo      char od_control.user_echomailentered;
  9808. mailentered
  9809.                This variable is a Boolean value, indicating whether or not the
  9810.                user has entered new EchoMail during this call. If this variable
  9811.                has a value of TRUE, then EchoMail has been entered, and if it
  9812.                has a value of FALSE, then EchoMail has not been entered. This
  9813.                variable will contain a valid value only after od_init() or some
  9814.                OpenDoors function has been called. Any changes made to this
  9815.                variable will be reflected within the BBS software when control
  9816.                is returned to the BBS. This variable is accessible only under
  9817.                systems which produce an EXITINFO.BBS door information file.
  9818.  
  9819.  
  9820.  
  9821. -------------------------------------------------------------------------------
  9822. user_error          char od_control.user_error_free;
  9823. _free
  9824.                This variable contains a Boolean value indicating whether or not
  9825.                the user is connected to the BBS via an error free connection
  9826.                (eg. a V.42/MNP or similar modem protocol). This variable is
  9827.                only available under systems that produce an SFDOORS.DAT,
  9828.                Wildcat style DOOR.SYS or RA 1.00 or later style extended
  9829.                EXITINFO.BBS door information file.
  9830.  
  9831.  
  9832.  
  9833. -------------------------------------------------------------------------------
  9834. user_first     char od_control.user_firstcall[9];
  9835. call
  9836.                This variable is a string which contains the date of the user's
  9837.                first call, in the same format as the od_control. user_lastcall
  9838.                variable. This variable is only available under systems which
  9839.                produce an RA 1.00 and later style extended EXITINFO.BBS door
  9840.                information file.
  9841.  
  9842.  
  9843.  
  9844. -------------------------------------------------------------------------------
  9845. user_          unsigned char od_control.user_flags[4];
  9846. flags
  9847.                The od_control.user_flags variable is an array of four sysop
  9848.                defined bit-mapped flags, which represent some sort of
  9849.  
  9850. ===============================================================================
  9851. OpenDoors 5.00 Manual                                           End of Page 167
  9852.  
  9853.  
  9854.                information about the user. od_control.user_flags[0] stores
  9855.                flags A1 - A8 in bits 0 through 7, respectively. Likewise,
  9856.                od_control.user_flags[1] stores flags B1 - B8, and so on. This
  9857.                variable is only available under systems that produce
  9858.                EXITINFO.BBS format door information files.
  9859.  
  9860.  
  9861.  
  9862. -------------------------------------------------------------------------------
  9863. user_handle    char od_control.user_handle[36];
  9864.  
  9865.                This variable contains the user's alias or handle name, if any.
  9866.                If the user does not have and alias or handle, this variable
  9867.                will be blank. This variable is only available under systems
  9868.                that produce a CHAIN.TXT, RA 1.00 and later extended
  9869.                EXITINFO.BBS or Wildcat style DOOR.SYS door information file.
  9870.  
  9871.  
  9872.  
  9873. -------------------------------------------------------------------------------
  9874. user_          char od_control.user_homephone[13];
  9875. homephone
  9876.                This string contains the user's home or data phone number, if
  9877.                available. This value is only available under system that
  9878.                produce one of the following door information files:
  9879.                EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat style
  9880.                DOOR.SYS or SFDOORS.DAT.
  9881.  
  9882.  
  9883.  
  9884. -------------------------------------------------------------------------------
  9885. user           unsigned char od_control.user_last_pwdchange;
  9886. _last
  9887. _pwdchange     This variable contains the number of calls that the user has
  9888.                made since they last changed their password. This variable is
  9889.                only available under EXITINFO.BBS files.
  9890.  
  9891.  
  9892.  
  9893. -------------------------------------------------------------------------------
  9894. user           char od_control.user_lastdate[9];
  9895. _lastdate
  9896.                This variable is a string containing the date of the user's last
  9897.                call to the BBS, and should always be of the format:
  9898.  
  9899.                                   "MM-DD-YY"
  9900.  
  9901.                Where MM is two digits representing the number of the month of
  9902.                the user's call, with 1 being January, 2 being February, and so
  9903.                on. DD should be two digits representing the day of the month of
  9904.                the user's last call, beginning with 1, and MM should be the
  9905.                last two digits of the year of the user's last call.
  9906.  
  9907.  
  9908.  
  9909. ===============================================================================
  9910. OpenDoors 5.00 Manual                                           End of Page 168
  9911.  
  9912.  
  9913.                This variable is only available under systems that produce one
  9914.                of the following door information files: CHAIN.TXT,
  9915.                EXITINFO.BBS, PC-Board/GAP style DOOR.SYS or WildCat style
  9916.                DOOR.SYS files.
  9917.  
  9918.  
  9919.  
  9920. -------------------------------------------------------------------------------
  9921. user_          unsigned int od_control.user_lastread;
  9922. lastread
  9923.                This variable contains the number of the highest message number
  9924.                that the user has read, and is only available under EXITINFO.BBS
  9925.                format door information files.
  9926.  
  9927.  
  9928.  
  9929. -------------------------------------------------------------------------------
  9930. user           char od_control.user_lasttime[6];
  9931. _lasttime
  9932.                This variable contains a string representing the time of the
  9933.                user's last call to the BBS, and should always be of the format:
  9934.  
  9935.                                   "HH:MM"
  9936.  
  9937.                Where HH is two digits representing the 24-hour format hour of
  9938.                the user's last call, and MM is two digits representing the
  9939.                minute of the user's last call. Thus, the following strings
  9940.                would be valid entries for this string:
  9941.  
  9942.                     "00:01"    (12:01 am)
  9943.                     "03:47"    (3:47 am)
  9944.                     "18:20"    (6:20 pm)
  9945.  
  9946.                This variable is only available under systems that produce an
  9947.                EXITINFO.BBS or Wildcat style DOOR.SYS format door information
  9948.                file.
  9949.  
  9950.  
  9951.  
  9952. -------------------------------------------------------------------------------
  9953. user           char od_control.user_location[26];
  9954. _location
  9955.                This string contains the name of the location from which the
  9956.                current user is calling from. This will usually be the name of
  9957.                the city, region (province, state, etc.) and sometimes country
  9958.                where the user lives. The contents of this variable are
  9959.                displayed on the OpenDoors status line. The value of this
  9960.                variable is valid after od_init() or any other OpenDoors
  9961.                function has been called. Also, you may change the value of this
  9962.                variable if you wish. However, not that these changes may not
  9963.                immediately be reflected in the status line, and may or may not
  9964.                cause the setting to be changed after the user returns to the
  9965.                BBS. This variable is available under systems that produce one
  9966.                of the following door information files: DORINFO?.DEF,
  9967.  
  9968. ===============================================================================
  9969. OpenDoors 5.00 Manual                                           End of Page 169
  9970.  
  9971.  
  9972.                EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat style
  9973.                DOOR.SYS SFDOORS.DAT and CALLINFO.BBS, but is not available
  9974.                under CHAIN.TXT or DoorWay style DOOR.SYS files.
  9975.  
  9976.  
  9977.  
  9978. -------------------------------------------------------------------------------
  9979. user           char od_control.caller_logindate[9];
  9980. _logindate
  9981.                This variable contains a string representing the date on which
  9982.                the current call to the BBS began. This variable is in the same
  9983.                format as the od_control.user_lastdate variable, described
  9984.                below. This variable is only available under systems which
  9985.                produce an EXITINFO.BBS file.
  9986.  
  9987.  
  9988.  
  9989. -------------------------------------------------------------------------------
  9990. user           long od_control.user_loginsec;
  9991. _loginsec
  9992.                This variable contains the user's security at login, and can be
  9993.                used to detect changes by the sysop or other programs during the
  9994.                course of the call, by comparing it's value with the
  9995.                od_control.user_security variable. This variable is only
  9996.                available under systems which produce an EXITINFO.BBS file.
  9997.  
  9998.  
  9999.  
  10000. -------------------------------------------------------------------------------
  10001. user           char od_control.user_logintime[6];
  10002. _logintime
  10003.                This variable contains a string representing the time of day at
  10004.                which the current call to the BBS began. This variable is in the
  10005.                same format as the od_control.user_lasttime variable, which is
  10006.                also described below. This variable is available under systems
  10007.                which produce an EXITINFO.BBS, a Wildcat style DOOR.SYS, or an
  10008.                SFDOORS.DAT file.
  10009.  
  10010.  
  10011.  
  10012. -------------------------------------------------------------------------------
  10013. user           char od_control.user_logonpassword[16];
  10014. _logon
  10015. password       This variable is a string which contains the user's password
  10016.                at the time at which the current call to the BBS began. This
  10017.                variable can be used to detect changes by the sysop or other
  10018.                programs to the user's password, which have taken place during
  10019.                the course of the call. In order to detect such changes, simply
  10020.                compare the contents of this string with the contents of the
  10021.                od_control.user_password variable. This variable is only
  10022.                available under systems which produce an EXITINFO.BBS format
  10023.                door information file.
  10024.  
  10025.  
  10026.  
  10027. ===============================================================================
  10028. OpenDoors 5.00 Manual                                           End of Page 170
  10029.  
  10030.  
  10031.  
  10032. -------------------------------------------------------------------------------
  10033. user           char od_control.user_menustack[50][9];
  10034. _menustack
  10035.                This variable is an array of 50 strings, containing the stack of
  10036.                BBS menus that have been executed, and is used to record the
  10037.                current position of the user within the BBS's menu system. Each
  10038.                string contains just the base portion of the filename of the
  10039.                menu, without the extension. The od_control.ra_menustackpointer
  10040.                variable points to the top of the menu stack. However, a
  10041.                complete discussion of the menu stack is beyond the scope of
  10042.                this manual. This variable is only available under systems that
  10043.                produce an RA 1.00 and later style extended EXITINFO.BBS door
  10044.                information file.
  10045.  
  10046.  
  10047.  
  10048. -------------------------------------------------------------------------------
  10049. user           unsigned char od_control.user_menustackpointer;
  10050. _menustack
  10051. pointer        This variable points to the top of the current menu stack. For
  10052.                more information on the menu stack, please refer to the
  10053.                od_control.ra_menustack variable, above. This variable is only
  10054.                available under systems that produce an RA 1.00 and later style
  10055.                extended EXITINFO.BBS door information file.
  10056.  
  10057.  
  10058.  
  10059. -------------------------------------------------------------------------------
  10060. user           unsigned int od_control.user_messages;
  10061. _messages
  10062.                This variable contains a value representing the total number of
  10063.                messages that have been written by the user, and is available
  10064.                under EXITINFO.BBS or Wildcat style DOOR.SYS format door
  10065.                information files.
  10066.  
  10067.  
  10068.  
  10069. -------------------------------------------------------------------------------
  10070. user_name      char od_control.user_name[36];
  10071.  
  10072.                This string contains the name of the user that is currently on-
  10073.                line, and is used by OpenDoors to display the current user name
  10074.                on the status line, and will most likely be used by your door
  10075.                for differentiating among different users. In most cases, you
  10076.                should probably not change the value of this variable, as a
  10077.                user's name does not usually change, and doing so could results
  10078.                in problems when returning to some BBS systems. For an example
  10079.                of using this variable, see the EZVote example program. This
  10080.                variable is available under all BBS systems.
  10081.  
  10082.  
  10083.  
  10084.  
  10085.  
  10086. ===============================================================================
  10087. OpenDoors 5.00 Manual                                           End of Page 171
  10088.  
  10089.  
  10090. -------------------------------------------------------------------------------
  10091. user_net_      unsigned int od_control.user_net_credit;
  10092. credit
  10093.                This variable contains the amount of NetMail credit that the
  10094.                current user has to his or her name. This variable is only
  10095.                available under systems that produce an EXITINFO.BBS file.
  10096.  
  10097.                Note that if you wish to change the value of the user's
  10098.                remaining NetMail credit, you should use the od_control.
  10099.                user_credit variable, instead of this variable.
  10100.  
  10101.  
  10102.  
  10103. -------------------------------------------------------------------------------
  10104. user_net       char od_control.user_netmailentered;
  10105. mailentered
  10106.                This variable is a Boolean value, indicating whether or not the
  10107.                user has entered new NetMail or GroupMail during this call. If
  10108.                this variable has a value of TRUE, then NetMail/GroupMail has
  10109.                been entered, and if it has a value of FALSE, then
  10110.                NetMail/GroupMail has not been entered. This variable will
  10111.                contain a valid value only after od_init() or some OpenDoors
  10112.                function has been called. Any changes made to this variable will
  10113.                be reflected within the BBS software when control is returned to
  10114.                the BBS. This variable is accessible only under systems which
  10115.                produce an EXITINFO.BBS door information file.
  10116.  
  10117.  
  10118.  
  10119. -------------------------------------------------------------------------------
  10120. user_num       unsigned int od_control.user_num;
  10121.  
  10122.                This variable contains the number of the user's record in the
  10123.                user database file, where 0 is the first record. This can be
  10124.                useful for changing user settings that are not re-read by the
  10125.                BBS, such as the user's phone number or security level which
  10126.                might be altered by a call back verification door. However, the
  10127.                value of this variable itself should not be altered.
  10128.  
  10129.                This variable is available under systems which produce any of
  10130.                the following door information file formats: CHAIN.TXT, PC-
  10131.                Board/GAP style DOOR.SYS, Wildcat style DOOR.SYS SFDOORS.DAT and
  10132.                EXITINFO.BBS.
  10133.  
  10134.  
  10135.  
  10136. -------------------------------------------------------------------------------
  10137. user_          unsigned int od_control.user_numcalls;
  10138. numcalls
  10139.                This variable contains the total number of calls that the
  10140.                current user has placed to the BBS, and is available under
  10141.                systems that produce EXITINFO.BBS or PC-Board/GAP and Wildcat
  10142.                style DOOR.SYS door information files.
  10143.  
  10144.  
  10145. ===============================================================================
  10146. OpenDoors 5.00 Manual                                           End of Page 172
  10147.  
  10148.  
  10149.  
  10150.  
  10151. -------------------------------------------------------------------------------
  10152. user           unsigned int od_control.user_numpages;
  10153. _numpages
  10154.                The value of this variable contains the total number of times
  10155.                that the user has paged the sysop, and can be used to limit the
  10156.                number of times that the user is permitted to page the sysop.
  10157.                OpenDoors increments this variable every time that the user
  10158.                pages the sysop, via the od_page() function. This variable is
  10159.                used with all types of door information files. However, this
  10160.                variable will only reflect the value within the BBS if an
  10161.                EXITINFO.BBS file is produced. Otherwise, the variable will only
  10162.                contain the number of times that the user has paged within the
  10163.                door, but not the total number of times the user has paged.
  10164.                Under EXITINFO.BBS systems, changes to the value of this
  10165.                variable will be reflected within the BBS upon return by the
  10166.                DOOR.
  10167.  
  10168.  
  10169.  
  10170. -------------------------------------------------------------------------------
  10171. user           char od_control.user_password[16];
  10172. _password
  10173.                This variable contains the user's password for accessing the
  10174.                BBS. OpenDoors does not use this value itself. This variable
  10175.                will contain a valid value only after od_init() or some
  10176.                OpenDoors function has been called. You may change the value of
  10177.                this variable. Note, however, that changes in this variable may
  10178.                or may not cause the setting to be changed when control returns
  10179.                to the BBS - this will depend upon the particular BBS system
  10180.                your door is running under. This variable is only available
  10181.                under systems that produce one of the following door information
  10182.                files: EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS,
  10183.                SFDOORS.DAT, and CALLINFO.BBS.
  10184.  
  10185.  
  10186.  
  10187. -------------------------------------------------------------------------------
  10188. user_pending   unsigned int od_control.user_pending;
  10189.  
  10190.                This variable represents the total value of NetMail that has
  10191.                been written by the current user, but not yet exported from the
  10192.                message base. This variable is only available under systems that
  10193.                produce an EXITINFO.BBS door information file.
  10194.  
  10195.  
  10196.  
  10197. -------------------------------------------------------------------------------
  10198. user_reason    char od_control.user_reasonforchat[78];
  10199. forchat
  10200.                This variable is a string, containing the reason for which the
  10201.                user wishes to chat with the sysop, as they entered at the time
  10202.                of paging the sysop. This variable will contain an empty string
  10203.  
  10204. ===============================================================================
  10205. OpenDoors 5.00 Manual                                           End of Page 173
  10206.  
  10207.  
  10208.                if the user has not paged the sysop, or if the reason the user
  10209.                wishes to chat is unknown. See also the od_control.user_wantchat
  10210.                variable. This variable is available under all BBS systems,
  10211.                regardless of what style of door information file they produce.
  10212.                However, this variable will not be passed between the door and
  10213.                BBS, and thus the user's reason for chat within the door will
  10214.                not necessarily correspond to their reason for chat outside the
  10215.                door.
  10216.  
  10217.  
  10218.  
  10219. -------------------------------------------------------------------------------
  10220. user_rip       char user_rip;
  10221.  
  10222.                This variable is set to TRUE if the user has RIP (Remote Imaging
  10223.                Protocol) graphics enabled, and FALSE if they do not. This
  10224.                setting can be determined from the door information (drop) file
  10225.                in many cases. In other cases, you can automatically determine
  10226.                whether or not the user's system supports RIP graphics using the
  10227.                od_autodetect() function (see page 48).
  10228.  
  10229.  
  10230.  
  10231. -------------------------------------------------------------------------------
  10232. user           unsigned int od_control.user_screen_length;
  10233. _screen
  10234. _length        This value of this variable represents the total number of
  10235.                lines that can be displayed on the user's screen at once, and is
  10236.                usually either 24 or 25. You may wish to make use of this
  10237.                variable to allow your door to pause the display of long pieces
  10238.                of text after every screen length, in order to allow the user to
  10239.                read this information before it passes off of their screen. In
  10240.                this case, you would simply maintain a counter of the total
  10241.                number of lines displayed, and when this value reaches one less
  10242.                than the length of the user screen, display a prompt asking the
  10243.                user to whether or not they wish to continue.
  10244.  
  10245.                This variable is set to the user's setting within the BBS under
  10246.                systems that produce any of the following door information file
  10247.                formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
  10248.                DOOR.SYS and CALLINFO.BBS files.
  10249.  
  10250.                This variable is used by the OpenDoors function,
  10251.                od_list_files(). If this variable contains a valid value,
  10252.                OpenDoors will pause the listing of files after every screen,
  10253.                and give the user the option of continuing, aborting, or
  10254.                disabling the "Continue?" prompt for the rest of the file
  10255.                listing. Thus, if you are using the od_list_files() under a
  10256.                system that does not produce one of the door information files
  10257.                listed above, you may wish to obtain the user's screen length
  10258.                from the user themselves. If the screen length is not available
  10259.                from the particular type of door information file that is found,
  10260.                and you do not set this value yourself, this variable will
  10261.                default to 23. If you are going to set the value of this
  10262.  
  10263. ===============================================================================
  10264. OpenDoors 5.00 Manual                                           End of Page 174
  10265.  
  10266.  
  10267.                variable yourself, you should do so after having called
  10268.                od_init() or some OpenDoors function.
  10269.  
  10270.  
  10271.  
  10272. -------------------------------------------------------------------------------
  10273. user_          unsigned char od_control.user_screenwidth;
  10274. screenwidth
  10275.                This variable contains a value representing the width of the
  10276.                user's screen, and will most often be equal to 80. This variable
  10277.                is only available under systems that produce a CHAIN.TXT or RA
  10278.                1.00 and later style extended EXITINFO.BBS door information
  10279.                file.
  10280.  
  10281.  
  10282.  
  10283. -------------------------------------------------------------------------------
  10284. user           unsigned int od_control.user_security;
  10285. _security
  10286.                This variable contains a numerical value representing the user's
  10287.                security access level on the BBS. You may wish to use this value
  10288.                to determine whether or not the current user of your door should
  10289.                have access to certain sysop-only functions. In this case, you
  10290.                may wish to have a configuration file used by your door, in
  10291.                which the sysop may define the minimum security level for sysop
  10292.                access. You would then be able to compare this configuration
  10293.                setting to the security level stored in this variable, in order
  10294.                to determine whether or not sysop function should be available.
  10295.                An alternative method, used by the EZVote sample door, of
  10296.                determining whether or not the current user is the sysop is to
  10297.                compare the user's name with the value of the
  10298.                od_control.sysop_name variable. This method has the advantage of
  10299.                not requiring a configuration program, but the disadvantage that
  10300.                the door will not function correctly under all BBS systems, as
  10301.                the od_control.sysop_name variable is not available under all
  10302.                BBS systems.
  10303.  
  10304.                The od_control.user_security variable is available under BBS
  10305.                systems that produce any of the following door information file
  10306.                formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
  10307.                DOOR.SYS, SFDOORS.DAT or CALLINFO.BBS.
  10308.  
  10309.  
  10310.  
  10311. -------------------------------------------------------------------------------
  10312. user_sex       char od_control.user_sex;
  10313.  
  10314.                This variable contains a single character representing the
  10315.                gender of the user that is currently online. This variable will
  10316.                contain an upper-case 'F' if the user is female, and an upper-
  10317.                case 'M' if the user is male. This variable is only available
  10318.                under systems that produce a CHAIN.TXT file.
  10319.  
  10320.  
  10321.  
  10322. ===============================================================================
  10323. OpenDoors 5.00 Manual                                           End of Page 175
  10324.  
  10325.  
  10326.  
  10327. -------------------------------------------------------------------------------
  10328. user_subdate   char od_control.user_subdate[9];
  10329.  
  10330.                This variable is a string, in the same format as the
  10331.                od_control.user_lastdate variable, which stores the date of
  10332.                expiry of the user's subscription to the BBS. This variable is
  10333.                only available under systems which produce a PC-Board/GAP and
  10334.                Wildcat style DOOR.SYS or RA 1.00 and later style extended
  10335.                EXITINFO.BBS door information file.
  10336.  
  10337.  
  10338.  
  10339. -------------------------------------------------------------------------------
  10340. user           int od_control.user_timelimit;
  10341. _timelimit
  10342.                This variable contains the amount of time, in minutes, that the
  10343.                user has left in the door. Note that this value may or may not
  10344.                be equal to the total amount of time that the user has left on
  10345.                the BBS, depending upon whether the BBS or a third-party door
  10346.                manager program only allows a limited amount of time in this
  10347.                door. This variable contains a valid value after od_init() or
  10348.                some OpenDoors function has been called. OpenDoors uses this
  10349.                variable to keep track of how much time the user has left in the
  10350.                door, and will automatically warn the user when nearly all of
  10351.                his or her time has been used up. OpenDoors will also force the
  10352.                user out of the door when their time in the door has expired.
  10353.                OpenDoors automatically subtracts one minute from this variable
  10354.                every minute that OpenDoors is active, unless chat mode has been
  10355.                activated (in which case the user's time will freeze), and also
  10356.                adjusts the value of this variable when the sysop uses the time
  10357.                adjustment function keys. Hence, you will not normally have any
  10358.                need to alter the value of this variable yourself. However,
  10359.                there may be some cases in which you wish to subtract a penalty
  10360.                or add a bonus to the user's time, such as in a "timebank" door
  10361.                or a door game that permits the user to "gamble time".
  10362.  
  10363.                Depending on which BBS system your door is running under, the
  10364.                value of this variable may or may not effect the user's time
  10365.                left upon return to the BBS. The BBS system will either reset
  10366.                the user's time to the value re-written to the door information
  10367.                file (this variable), or will always subtract the amount of time
  10368.                spent in the door from the user's remaining time. Other BBS
  10369.                systems, such as Apex, give the sysop an option of which means
  10370.                should be used.
  10371.  
  10372.                This variable is available under all door information file
  10373.                formats.
  10374.  
  10375.  
  10376.  
  10377.  
  10378.  
  10379.  
  10380.  
  10381. ===============================================================================
  10382. OpenDoors 5.00 Manual                                           End of Page 176
  10383.  
  10384.  
  10385. -------------------------------------------------------------------------------
  10386. user           unsigned int od_control.user_todayk;
  10387. _todayk
  10388.                This variable contains the total kilobytes of files that the
  10389.                current user has downloaded from the BBS during the current day,
  10390.                and is available under systems that produce EXITINFO.BBS, PC-
  10391.                Board/GAP and Wildcat style DOOR.SYS, or SFDOORS.DAT format door
  10392.                information files.
  10393.  
  10394.  
  10395.  
  10396. -------------------------------------------------------------------------------
  10397. user_upk       unsigned int od_control.user_upk;
  10398.  
  10399.                This variable contains the total kilobytes of files that the
  10400.                current user has uploaded to the BBS, and is available under
  10401.                systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
  10402.                SFDOORS.DAT files.
  10403.  
  10404.  
  10405.  
  10406. -------------------------------------------------------------------------------
  10407. user_uploads   unsigned int od_control.user_uploads;
  10408.  
  10409.                This variable contains the total number of files that the
  10410.                current user has uploaded to the BBS, and is available under
  10411.                systems that produce EXITINFO.BBS, PC-Board/GAP and Wildcat
  10412.                style DOOR.SYS, or SFDOORS.DAT format door information files.
  10413.  
  10414.  
  10415.  
  10416. -------------------------------------------------------------------------------
  10417. user           char od_control.user_wantchat;
  10418. _wantchat
  10419.                This variable is a Boolean value which indicates whether or not
  10420.                the user wishes to chat with the sysop (ie, the user has paged
  10421.                the sysop, but has yet to receive a chat with the sysop). This
  10422.                variable is used under all door information file formats.
  10423.                However, changes to this variable are only reflected on the BBS
  10424.                when the door is running under a system that produces an
  10425.                EXITINFO.BBS door information file.
  10426.  
  10427.                This variable is automatically turned on (ie., set to TRUE),
  10428.                when the user begins to page the sysop for chat, within the
  10429.                od_page() function, and is automatically turned off (ie., set to
  10430.                FALSE), when the sysop breaks in for chat via the chat function
  10431.                key. Also, setting this variable to TRUE will turn on the
  10432.                flashing want-chat indicator on the OpenDoors status line.
  10433.  
  10434.  
  10435.  
  10436.  
  10437.  
  10438.  
  10439.  
  10440. ===============================================================================
  10441. OpenDoors 5.00 Manual                                           End of Page 177
  10442.  
  10443.  
  10444. -------------------------------------------------------------------------------
  10445. user           unsigned int od_control.user_xi_record;
  10446. _xi_record
  10447.                This variable contains the number of the user's record in the
  10448.                USERXI.BBS file, if any. This variable is only available under
  10449.                system that produce a Remote Access 1.00 and later style
  10450.                extended door information file.
  10451.  
  10452.  
  10453.  
  10454.  
  10455.  
  10456.  
  10457.  
  10458.  
  10459.  
  10460.  
  10461.  
  10462.  
  10463.  
  10464.  
  10465.  
  10466.  
  10467.  
  10468.  
  10469.  
  10470.  
  10471.  
  10472.  
  10473.  
  10474.  
  10475.  
  10476.  
  10477.  
  10478.  
  10479.  
  10480.  
  10481.  
  10482.  
  10483.  
  10484.  
  10485.  
  10486.  
  10487.  
  10488.  
  10489.  
  10490.  
  10491.  
  10492.  
  10493.  
  10494.  
  10495.  
  10496.  
  10497.  
  10498.  
  10499. ===============================================================================
  10500. OpenDoors 5.00 Manual                                           End of Page 178
  10501.  
  10502.  
  10503.  
  10504.  
  10505.  
  10506.  
  10507. CONTROL STRUCTURE - DOOR SETTINGS
  10508. -------------------------------------------------------------------------------
  10509.  
  10510.                This section deals with those variables in the OpenDoors control
  10511.                structure which reflect the current door settings. These
  10512.                variables are as follows:
  10513.  
  10514.                od_cur_attrib            The current display attribute, or -1 if
  10515.                                         unknown.
  10516.  
  10517.                od_okaytopage            Controls whether the user is currently
  10518.                                         permitted to page the sysop.
  10519.  
  10520.                od_pageendmin            End of valid paging hours.
  10521.  
  10522.                od_pagestartmin          Start of valid paging hours.
  10523.  
  10524.                od_user_keyboard_on      Controls whether OpenDoors will
  10525.                                         currently accept input from the remote
  10526.                                         user's keyboard.
  10527.  
  10528.                od_update_stauts_now     Forces immediate update of the status
  10529.                                         line.
  10530.  
  10531.                sysop_next               Indicates whether or not the sysop has
  10532.                                         reserved use of the system after the
  10533.                                         current calls.
  10534.  
  10535.  
  10536.  
  10537. -------------------------------------------------------------------------------
  10538. od_cur         int od_control.od_cur_attrib;
  10539. _attrib
  10540.                This read-only values stores the current display colour
  10541.                attribute, or the value -1 if the current display colour is
  10542.                unknown (such as when the door first begins execution).
  10543.  
  10544.  
  10545.  
  10546. -------------------------------------------------------------------------------
  10547. od             char od_control.od_okaytopage;
  10548. _okaytopage
  10549.                This variable allows you to control whether or not the user is
  10550.                currently permitted to page the sysop via the od_page()
  10551.                function. This variable contains one of three values. A value
  10552.                equal to TRUE indicates that paging is currently permitted. A
  10553.                value equal to FALSE indicates that paging is not current
  10554.                permitted. A value of MAYBE indicates that the od_page()
  10555.                function should check the values of the od_pagestartmin and
  10556.                od_pageendmin variables in order to determine whether or not
  10557.  
  10558. ===============================================================================
  10559. OpenDoors 5.00 Manual                                           End of Page 179
  10560.  
  10561.  
  10562.                paging should be permitted. If you wish to always permit sysop
  10563.                paging, you can simply leave this variable set at its default
  10564.                value of TRUE. On the other hand, you may wish to allow the
  10565.                sysop to configure paging hours - either within your own
  10566.                configuration program, or within the BBS's configuration. In
  10567.                this case, you can either turn paging on and off manually by
  10568.                changing the value of this variable, or by setting this variable
  10569.                to MAYBE, and using the od_pagestartmin and od_pageendmin
  10570.                variables. These two variables are described below. For more
  10571.                information on the od_page() function itself, see page 101.
  10572.  
  10573.  
  10574.  
  10575. -------------------------------------------------------------------------------
  10576. od             unsigned int od_control.od_pageendmin;
  10577. _pageendmin
  10578.                This variable can be used to set the beginning of valid sysop
  10579.                paging hours within the od_page() function. If the
  10580.                od_control.od_okaytopage variable (which is described above) is
  10581.                set to MAYBE, then OpenDoors will check the value of this
  10582.                variable prior to paging the sysop via the od_page() function.
  10583.                This variable should contain the time at which the valid sysop
  10584.                paging hours end, represented as the a number of minutes since
  10585.                midnight. For more information on the od_page() function itself,
  10586.                see page 101.
  10587.  
  10588.  
  10589.  
  10590. -------------------------------------------------------------------------------
  10591. od             unsigned int od_control.od_pagestartmin;
  10592. _pagestartmin
  10593.                This variable can be used to set the beginning of valid sysop
  10594.                paging hours within the od_page() function. If the
  10595.                od_control.od_okaytopage variable (which is described above) is
  10596.                set to MAYBE, then OpenDoors will check the value of this
  10597.                variable prior to paging the sysop via the od_page() function.
  10598.                This variable should contain the time at which the valid sysop
  10599.                paging hours begin, represented as the a number of minutes since
  10600.                midnight. For more information on the od_page() function itself,
  10601.                see page 101.
  10602.  
  10603. -------------------------------------------------------------------------------
  10604. od_update      char od_control.od_update_status_now;
  10605. _status_now
  10606.                Setting this variable to TRUE forces OpenDoors to update the
  10607.                status line during the next od_kernel() execution. When the
  10608.                status line is updated, this variable is reset to its default
  10609.                value of FALSE.
  10610.  
  10611.  
  10612.  
  10613.  
  10614.  
  10615.  
  10616.  
  10617. ===============================================================================
  10618. OpenDoors 5.00 Manual                                           End of Page 180
  10619.  
  10620.  
  10621. -------------------------------------------------------------------------------
  10622. od_user        char od_control.od_user_keyboard_on;
  10623. _keyboard_on
  10624.                This variable is a Boolean value, indicating whether OpenDoors
  10625.                will currently accept input from a remote user. OpenDoors
  10626.                provides a function key (usually [ALT]-[K], unless you have
  10627.                changed the default), which will allow the sysop to temporarily
  10628.                prevent the user from having any control over the door. When the
  10629.                sysop activates this feature, a flashing [Keyboard-Off]
  10630.                indicator will appear on the status line, and this variable will
  10631.                be set to FALSE. When the sysop presses the [ALT]-[K]
  10632.                combination a second time, to toggle the user's keyboard back
  10633.                on, the flashing indicator will disappear, and this variable
  10634.                will be set back to TRUE.
  10635.  
  10636.  
  10637.  
  10638. -------------------------------------------------------------------------------
  10639. sysop_next     char od_control.sysop_next;
  10640.  
  10641.                This variable is a Boolean value, indicating whether or not the
  10642.                "sysop next" feature has been activated. The "sysop next"
  10643.                feature, which reserves the system for the sysop after the call
  10644.                has ended, can be toggled on and off within OpenDoors by use of
  10645.                a function key (Alt-N by default). Also, when the "sysop next"
  10646.                feature has been activated, an indicator will appear on the
  10647.                OpenDoors status line. This variable is only available under
  10648.                systems that produce an SFDOORS.DAT or RA 1.00 and later style
  10649.                extended EXITINFO.BBS door information file. For more
  10650.                information on testing the type of door information file
  10651.                available, please see page 156.
  10652.  
  10653.  
  10654.  
  10655.  
  10656.  
  10657.  
  10658.  
  10659.  
  10660.  
  10661.  
  10662.  
  10663.  
  10664.  
  10665.  
  10666.  
  10667.  
  10668.  
  10669.  
  10670.  
  10671.  
  10672.  
  10673.  
  10674.  
  10675.  
  10676. ===============================================================================
  10677. OpenDoors 5.00 Manual                                           End of Page 181
  10678.  
  10679.  
  10680.  
  10681.  
  10682.  
  10683.  
  10684. CONTROL STRUCTURE - DIAGNOSTICS
  10685. -------------------------------------------------------------------------------
  10686.  
  10687.                To help in diagnosing problems in your OpenDoors programs,
  10688.                OpenDoors stores information on the most recent error which
  10689.                occurred. When any of the OpenDoors functions return an "error"
  10690.                or "failure" state, the reason for this failure is recorded.
  10691.  
  10692.                The following OpenDoors control structure variable provides
  10693.                diagnostics information:
  10694.  
  10695.                od_error                 Stores a "reason code" for the last
  10696.                                         failed OpenDoors API function call.
  10697.  
  10698.  
  10699.  
  10700.  
  10701. -------------------------------------------------------------------------------
  10702. od_error       int od_control.od_error;
  10703.  
  10704.                When any of the OpenDoors API functions return an "error" or
  10705.                "failure" state (usually denoted by either of the values FALSE
  10706.                or NULL), the reason for the failure is recorded in this
  10707.                variable. Since successful function calls do not alter the value
  10708.                of the od_control.od_error variable, you must be careful not
  10709.                only to check the value of the od_control.od_error variable, but
  10710.                also to check the OpenDoors function return codes, in order to
  10711.                determine which function failed.
  10712.  
  10713.                This variable will always store the reason for the most recent
  10714.                function call failure, or ERR_NONE if no functions have failed.
  10715.                od_error may take on any of the following values:
  10716.  
  10717.                     ERR_NONE            Indicates that no error has occurred
  10718.                                         yet.
  10719.  
  10720.                     ERR_MEMORY          Function was unable to allocate
  10721.                                         required memory. This usually indicates
  10722.                                         that there is not enough available
  10723.                                         memory. This failure may also be due to
  10724.                                         memory corruption caused by your
  10725.                                         program inadvertently overwriting heap
  10726.                                         structures. If your program has been
  10727.                                         compiled in either the small or the
  10728.                                         medium memory model, try recompiling it
  10729.                                         in the compact, large, or huge memory
  10730.                                         models. If your program is already
  10731.                                         compiled in the compact, large, or huge
  10732.                                         memory models, try making more system
  10733.                                         memory available to your program.
  10734.  
  10735. ===============================================================================
  10736. OpenDoors 5.00 Manual                                           End of Page 182
  10737.  
  10738.  
  10739.  
  10740.                     ERR_NOGRAPHICS      This setting indicates that the
  10741.                                         function called requires ANSI, AVATAR
  10742.                                         or RIP graphics mode, but none of these
  10743.                                         modes are active.
  10744.  
  10745.                     ERR_PARAMETER       An invalid parameter was passed to an
  10746.                                         OpenDoors functions. Check the
  10747.                                         function's description in chapter four,
  10748.                                         to determine the required values for
  10749.                                         each function parameter.
  10750.  
  10751.                     ERR_FILEOPEN        OpenDoors was unable to open a file.
  10752.                                         This can be due to the specified
  10753.                                         filename not existing, due to the file
  10754.                                         being locked for exclusive access by
  10755.                                         another process, or due to a hardware
  10756.                                         failure.
  10757.  
  10758.                     ERR_FILEREAD        OpenDoors was able to open the
  10759.                                         specified file, but unable to read the
  10760.                                         required data from the file. This error
  10761.                                         may be due to an invalid file format,
  10762.                                         due to a portion of the file being
  10763.                                         locked by another process, or due to a
  10764.                                         hardware failure.
  10765.  
  10766.                     ERR_LIMIT           An internal function limit has been
  10767.                                         exceeded. Refer to the function's
  10768.                                         description in chapter four for
  10769.                                         information on the function's
  10770.                                         limitations.
  10771.  
  10772.                     ERR_NOREMOTE        Indicates that a function has been
  10773.                                         called which is not valid in local
  10774.                                         mode, such as od_carrier() or
  10775.                                         od_set_dtr().
  10776.  
  10777.  
  10778.  
  10779.  
  10780.  
  10781.  
  10782.  
  10783.  
  10784.  
  10785.  
  10786.  
  10787.  
  10788.  
  10789.  
  10790.  
  10791.  
  10792.  
  10793.  
  10794. ===============================================================================
  10795. OpenDoors 5.00 Manual                                           End of Page 183
  10796.  
  10797.  
  10798.  
  10799.  
  10800.  
  10801.  
  10802. CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION
  10803. -------------------------------------------------------------------------------
  10804.  
  10805.                The OpenDoors control structure provides many variables which
  10806.                allow you to customize OpenDoor's behavior and appearance. These
  10807.                customization variables fit into one of the following
  10808.                categories:
  10809.  
  10810.                          General Behavior Customization Variables
  10811.                          Sysop Function Keys Customization Variables
  10812.                          Colour Customization Variables
  10813.                          Language-Specific Prompts Customization Variables
  10814.  
  10815.                This section deals with those variables that fit into the first
  10816.                category, "General Behavior Customization Variables". The other
  10817.                categories are dealt with in the following sections of this
  10818.                chapter.
  10819.  
  10820.                Below is a brief overview of the variables grouped into this
  10821.                section of the OpenDoors control structure. Following the
  10822.                overview is a detailed description of each of these variables.
  10823.  
  10824.  
  10825.                od_box_chars             Array of characters used by the
  10826.                                         od_draw_box() function.
  10827.  
  10828.                od_before_exit           Function to call prior to exiting.
  10829.  
  10830.                od_cafter_chat           Function to call after sysop chat.
  10831.  
  10832.                od_cafter_shell          Function to call after DOS shell.
  10833.  
  10834.                od_cbefore_chat          Function to call prior to sysop chat.
  10835.  
  10836.                od_cbefore_shell         Function to call prior to DOS shell.
  10837.  
  10838.                od_cfg_lines             Sets the configuration file's custom
  10839.                                         door information file line keywords.
  10840.  
  10841.                od_cfg_text              Sets the built-in log file keywords
  10842.                                         that OpenDoors will recongize.
  10843.  
  10844.                od_chat_active           Controls whether or not sysop chat mode
  10845.                                         is active.
  10846.  
  10847.                od_clear_on_exit         Controls whether the screen is cleared
  10848.                                         upon door exit.
  10849.  
  10850.  
  10851.  
  10852.  
  10853. ===============================================================================
  10854. OpenDoors 5.00 Manual                                           End of Page 184
  10855.  
  10856.  
  10857.                od_colour_delimiter      Indicates what character should delimit
  10858.                                         imbedded colour codes for the
  10859.                                         od_printf() function.
  10860.  
  10861.                od_colour_names          Strings which OpenDoors recognizes as
  10862.                                         the names of various text colours.
  10863.  
  10864.                od_config_file           Used to enable or disable the OpenDoors
  10865.                                         configuration file system.
  10866.  
  10867.                od_config_filename       Sets the filename that will be read by
  10868.                                         the configuration file system.
  10869.  
  10870.                od_config_function       The callback function that OpenDoors
  10871.                                         will call to allow your program to
  10872.                                         process custom configuration file
  10873.                                         entries.
  10874.  
  10875.                od_default_personality   Sets the default personality to be used
  10876.                                         with the OpenDoors Multiple Personality
  10877.                                         System, and also sets the personality
  10878.                                         to use when the MPS is not active.
  10879.  
  10880.                od_default_rip_win       Whether OpenDoors should use the
  10881.                                         default 43-line RIP window for ANSI
  10882.                                         text (TRUE), or a 23-line window
  10883.                                         (FALSE).
  10884.  
  10885.                od_disable               Disable OpenDoors activities such as
  10886.                                         reading door information file and
  10887.                                         monitoring carrier detect / remaining
  10888.                                         time.
  10889.  
  10890.                od_errorlevel            Sets the errorlevel OpenDoors exits
  10891.                                         with under various conditions.
  10892.  
  10893.                od_force_local           Forces door to operate in local mode,
  10894.                                         ignoring any door information file and
  10895.                                         using default user settings.
  10896.  
  10897.                od_in_buf_size           Sets size of OpenDoor's internal
  10898.                                         local/remote inbound buffer.
  10899.  
  10900.                od_inactive_warning      Number of seconds before hanging up
  10901.                                         that OpenDoors displays the inactivity
  10902.                                         timeout warning.
  10903.  
  10904.                od_inactivity            Controls user inactivity timeout.
  10905.  
  10906.                od_ker_exec              Is called whenever od_kernel()
  10907.                                         executes.
  10908.  
  10909.  
  10910.  
  10911.  
  10912. ===============================================================================
  10913. OpenDoors 5.00 Manual                                           End of Page 185
  10914.  
  10915.  
  10916.                od_last_input            Indicates whether the last input came
  10917.                                         from the remote user (==0) or the local
  10918.                                         sysop (==1).
  10919.  
  10920.                od_list_pause            Controls whether or not the user may
  10921.                                         pause display within the
  10922.                                         od_list_files() and od_send_file()
  10923.                                         functions by using the [P] key.
  10924.  
  10925.                od_list_stop             Controls whether or not the user may
  10926.                                         terminate display within the
  10927.                                         od_list_files() and od_send_file()
  10928.                                         functions using [S], [CTRL]-[K], etc.
  10929.  
  10930.                od_logfile               Enables or disables the OpenDoors log
  10931.                                         file system.
  10932.  
  10933.                od_logfile_disable       Prevents the logfile from being opened,
  10934.                                         even if the logfile is enabled by
  10935.                                         od_logfile.
  10936.  
  10937.                od_logfile_messages      Array of message strings that OpenDoors
  10938.                                         will use when writing log file entries.
  10939.  
  10940.                od_logfile_name          Contains the filename and possibly path
  10941.                                         of the logfile.
  10942.  
  10943.                od_maxtime               Indicates the maximum length of time
  10944.                                         any user is permitted to use the door.
  10945.  
  10946.                od_maxtime_deduction     Indicates the amount of time that has
  10947.                                         temporarily been taken away from the
  10948.                                         user's remaining time, as a result of
  10949.                                         the maximum door time settting.
  10950.  
  10951.                od_mps                   Enables or disables the OpenDoors
  10952.                                         Multiple Personality System.
  10953.  
  10954.                od_no_file_func          Called when no door information file
  10955.                                         can be read.
  10956.  
  10957.                od_no_ra_codes           Disables translation of RA/QBBS control
  10958.                                         codes.
  10959.  
  10960.                od_nocopyright           Prevents OpenDoors from displaying it's
  10961.                                         name and version number when a door
  10962.                                         program begins execution.
  10963.  
  10964.                od_noexit                Prevents OpenDoors from exiting when
  10965.                                         the od_exit() function is called.
  10966.  
  10967.                od_page_len              Controls length of the sysop page beep.
  10968.  
  10969.  
  10970.  
  10971. ===============================================================================
  10972. OpenDoors 5.00 Manual                                           End of Page 186
  10973.  
  10974.  
  10975.                od_page_pausing          Enables or disables page pausing in
  10976.                                         od_send_file(), od_hotkey_menu() and
  10977.                                         od_list_files() functions.
  10978.  
  10979.                od_page_startmin         Indicates the time of day at which
  10980.                                         sysop paging is first enabled.
  10981.  
  10982.                od_page_statusline       Which status line (if any) is activated
  10983.                                         when the user pages the sysop.
  10984.  
  10985.                od_page_endmin           Indicates the time of day at which
  10986.                                         sysop paging is disabled.
  10987.  
  10988.                od_prog_name             Stores the name of your program, which
  10989.                                         will be written to the log file.
  10990.  
  10991.                od_reg_key               Stores the registration key that you
  10992.                                         receive when purchasing OpenDoors.
  10993.  
  10994.                od_reg_name              Stores your name or your companies name
  10995.                                         when you have purchased an OpenDoors
  10996.                                         licence (registration).
  10997.  
  10998.                od_spawn_freeze_time     Indicates whether the user's time
  10999.                                         remaining continues to be decreased
  11000.                                         during the execution of the
  11001.                                         od_spawn...() functions (FALSE), or if
  11002.                                         the timer should be "frozen" (TRUE).
  11003.  
  11004.                od_swapping_disable      Disables swapping during DOS shell and
  11005.                                         od_spawn...() functions.
  11006.  
  11007.                od_swapping_noems        Prevents swapping form being done to
  11008.                                         EMS expanded memory.
  11009.  
  11010.                od_swapping_path         Location where disk swap file should be
  11011.                                         created.
  11012.  
  11013.                od_status_on             Controls whether the status line sub-
  11014.                                         system is active.
  11015.  
  11016.                od_time_msg_func         Called instead of displaying time limit
  11017.                                         warning messages.
  11018.  
  11019.  
  11020.  
  11021.  
  11022. -------------------------------------------------------------------------------
  11023. od_box         char od_control.od_box_chars[8];
  11024. _chars
  11025.                This variable allows you to specify which character the
  11026.                od_draw_box() function uses in drawing the boarder of a window.
  11027.                The elements of this array are as follows:
  11028.  
  11029.  
  11030. ===============================================================================
  11031. OpenDoors 5.00 Manual                                           End of Page 187
  11032.  
  11033.  
  11034.                od_box_chars[BOX_UPPERLEFT]  - Upper left corner of box
  11035.                od_box_chars[BOX_TOP]        - Top horizontal line
  11036.                od_box_chars[BOX_UPPERRIGHT] - Upper right corner of box
  11037.                od_box_chars[BOX_LEFT]       - Left Vertical line
  11038.                od_box_chars[BOX_LOWERLEFT]  - Lower left corner of box
  11039.                od_box_chars[BOX_LOWERRIGHT] - Lower right corner of box
  11040.                od_box_chars[BOX_BOTTOM]     - Bottom horizontal line
  11041.                od_box_chars[BOX_RIGHT]      - Right horizontal line
  11042.  
  11043.  
  11044.  
  11045. -------------------------------------------------------------------------------
  11046. od_before      void (*od_control.od_before_exit)();
  11047. _exit
  11048.                This variable contains a pointer to a function which OpenDoors
  11049.                should call prior to exiting, or NULL if you do not wish to have
  11050.                any function called at exit time. For an example of the use of
  11051.                this variable, see the description of the EZVote demo door,
  11052.                which begins on page 38.
  11053.  
  11054.  
  11055.  
  11056. -------------------------------------------------------------------------------
  11057. od_cafter      void (*od_control.od_cafter_chat)();
  11058. _chat
  11059.                The function pointed to by this variable will be called after
  11060.                sysop chat mode has ended. This may be useful for allowing you
  11061.                to save the user's screen contents prior to chat, and restoring
  11062.                the afterwards. If this variable contains its default value of
  11063.                NULL, no function will be called. To alter the string of text
  11064.                which is displayed after sysop chat, see the
  11065.                od_control.od_after_chat variable, which is described in the
  11066.                section on the prompts customization portion of the control
  11067.                structure.
  11068.  
  11069.  
  11070.  
  11071. -------------------------------------------------------------------------------
  11072. od_cafter      void (*od_control.od_cafter_shell)();
  11073. _shell
  11074.                The function pointed to by this variable will be called after
  11075.                the sysop has returned from a DOS shell. If this variable
  11076.                contains its default value of NULL, no function will be called.
  11077.                To alter the string of text which is displayed after a DOS
  11078.                shell, see the od_control.od_after_shell variable, which is
  11079.                described in the section on the prompts customization portion of
  11080.                the control structure.
  11081.  
  11082.  
  11083.  
  11084.  
  11085.  
  11086.  
  11087.  
  11088.  
  11089. ===============================================================================
  11090. OpenDoors 5.00 Manual                                           End of Page 188
  11091.  
  11092.  
  11093. -------------------------------------------------------------------------------
  11094. od_cbefore     void (*od_control.od_cbefore_chat)();
  11095. _chat
  11096.                The function pointed to by this variable will be called prior to
  11097.                entering sysop chat mode. This may be useful for allowing you to
  11098.                save the user's screen contents prior to chat, and restoring the
  11099.                afterwards. If this variable contains its default value of NULL,
  11100.                no function will be called. To alter the string of text which is
  11101.                displayed prior to sysop chat, see the od_control.od_before_chat
  11102.                variable, which is described in the section on the prompts
  11103.                customization portion of the control structure. To replace the
  11104.                OpenDoors sysop chat facility with your own, simply activate
  11105.                your chat mode when this function is called. Your chat mode
  11106.                facility should remain active until OpenDoors sets the
  11107.                od_control.od_chat_active variable to FALSE. If you wish to
  11108.                terminate chat mode prior to this variable being set to FALSE,
  11109.                you should set this variable to FALSE yourself if you do not
  11110.                wish OpenDoors to activate its own chat mode.
  11111.  
  11112.  
  11113.  
  11114. -------------------------------------------------------------------------------
  11115. od_cbefore     void (*od_control.od_cbefore_shell)();
  11116. _shell
  11117.                The function pointed to by this variable will be called prior to
  11118.                executing a sysop DOS shell. If this variable contains its
  11119.                default value of NULL, no function will be called. To alter the
  11120.                string of text which is displayed before a DOS shell, see the
  11121.                od_control.od_before_shell variable, which is described in the
  11122.                section on the prompts customization portion of the control
  11123.                structure.
  11124.  
  11125.  
  11126.  
  11127. -------------------------------------------------------------------------------
  11128. od_cfg_lines   char od_control.cfg_lines[25][33];
  11129.  
  11130.                This array contains the strings for the keywords that represent
  11131.                various lines in the definition of a custom door information
  11132.                file. Each keyword must be 32 character or less in length. These
  11133.                keywords are not case sensitive. See page 220 for more
  11134.                information on defining custom door information (drop) file
  11135.                formats. The default values for this array are as follows:
  11136.  
  11137.                     [0]  "Ignore"
  11138.                     [1]  "ComPort"
  11139.                     [2]  "FossilPort"
  11140.                     [3]  "ModemBPS"
  11141.                     [4]  "LocalMode"
  11142.                     [5]  "UserName"
  11143.                     [6]  "UserFirstName"
  11144.                     [7]  "UserLastName"
  11145.                     [8]  "Alias"
  11146.                     [9]  "HoursLeft"
  11147.  
  11148. ===============================================================================
  11149. OpenDoors 5.00 Manual                                           End of Page 189
  11150.  
  11151.  
  11152.                     [10] "MinutesLeft"
  11153.                     [11] "SecondsLeft"
  11154.                     [12] "ANSI"
  11155.                     [13] "AVATAR"
  11156.                     [14] "PagePausing"
  11157.                     [15] "ScreenLength"
  11158.                     [16] "ScreenClearing"
  11159.                     [17] "Security"
  11160.                     [18] "City"
  11161.                     [19] "Node"
  11162.                     [20] "SysopName"
  11163.                     [21] "SysopFirstName"
  11164.                     [22] "SysopLastName"
  11165.                     [23] "SystemName"
  11166.                          "RIP"                      [24] 
  11167.  
  11168.                If you wish to change any of these variable, you must do so
  11169.                before calling any OpenDoors functions.
  11170.  
  11171.  
  11172.  
  11173. -------------------------------------------------------------------------------
  11174. od_cfg_text    char od_control.od_cfg_text[47][33];
  11175.  
  11176.                This array of strings contains the built-in configuration file
  11177.                keywords that are recognized by OpenDoors. These keywords may be
  11178.                up to 32 characters in size, and are not case sensitive. If you
  11179.                wish to change any of these settings, you must do so before
  11180.                calling any OpenDoors functions. The default values for this
  11181.                array are as follows:
  11182.  
  11183.                     [0]  "Node"
  11184.                     [1]  "BBSDir"
  11185.                     [2]  "DoorDir"
  11186.                     [3]  "LogFileName"
  11187.                     [4]  "DisableLogging"
  11188.                     [5]  "SundayPagingHours"
  11189.                     [6]  "MondayPagingHours"
  11190.                     [7]  "TuesdayPagingHours"
  11191.                     [8]  "WednesdayPagingHours"
  11192.                     [9]  "ThursdayPagingHours"
  11193.                     [10] "FridayPagingHours"
  11194.                     [11] "SaturdayPagingHours"
  11195.                     [12] "MaximumDoorTime"
  11196.                     [13] "SysopName"
  11197.                     [14] "SystemName"
  11198.                     [15] "SwappingDisable"
  11199.                     [16] "SwappingDir"
  11200.                     [17] "SwappingNoEMS"
  11201.                     [18] "LockedBPS"
  11202.                     [19] "SerialPort"
  11203.                     [20] "CustomFileName"
  11204.                     [21] "CustomFileLine"
  11205.                     [22] "InactivityTimeout"
  11206.  
  11207. ===============================================================================
  11208. OpenDoors 5.00 Manual                                           End of Page 190
  11209.  
  11210.  
  11211.                     [23] "PageDuration"
  11212.                     [24] "ChatUserColour"
  11213.                     [25] "ChatSysopColour"
  11214.                     [26] "FileListTitleColour"
  11215.                     [27] "FileListNameColour"
  11216.                     [28] "FileListSizeColour"
  11217.                     [29] "FileListDescriptionColour"
  11218.                     [30] "FileListOfflineColour"
  11219.                     [31] "Personality"
  11220.                     [32] "NoFossil"
  11221.                     [33] "PortAddress"
  11222.                     [34] "PortIRQ"
  11223.                     [35] "ReceiveBuffer"
  11224.                     [36] "TransmitBuffer"
  11225.                     [37] "PagePromptColour"
  11226.                     [38] "LocalMode"
  11227.                     [39] "PopupMenuTitleColour"
  11228.                     [40] "PopupMenuBorderColour"
  11229.                     [41] "PopupMenuTextColour"
  11230.                     [42] "PopupMenuKeyColour"
  11231.                     [43] "PopupMenuHighlightColour"
  11232.                     [44] "PopupMenuHighKeyColour"
  11233.                     [45] "NoFIFO"
  11234.                     [46] "FIFOTriggerSize"
  11235.  
  11236.  
  11237.  
  11238. -------------------------------------------------------------------------------
  11239. od_chat        char od_control.od_chat_active;
  11240. _active
  11241.                This variable is set to TRUE when sysop chat mode is active, and
  11242.                is set to FALSE when sysop chat mode is not active. This
  11243.                variable can be used to determine whether or not chat mode is
  11244.                active, and to force chat mode to end. When the sysop presses
  11245.                the chat mode key ([ALT]-[C] if the default personality is being
  11246.                used) while chat mode is active, this variable is set to FALSE.
  11247.  
  11248.  
  11249.  
  11250. -------------------------------------------------------------------------------
  11251. od_clear       char od_control.od_clear_on_exit;
  11252. _on_exit
  11253.                This variable contains a Boolean value, which indicates whether
  11254.                or not you wish OpenDoors to clear the screen prior to exiting.
  11255.                This variable defaults to a value of TRUE, which causes the
  11256.                screen to be cleared when a door program exits. However, you may
  11257.                wish to set this variable to a value of FALSE, which will cause
  11258.                the contents of the screen to remain unchanged when the door
  11259.                exits. While setting this variable to FALSE will probably result
  11260.                in a messy display if the door is to return control to a batch
  11261.                file, if the door returns directly to the BBS, it will result in
  11262.                a smoother transition from the door back to the BBS (as the
  11263.                sysop is not left with a blank screen). If your door has a
  11264.                configuration file or configuration program, you may wish to
  11265.  
  11266. ===============================================================================
  11267. OpenDoors 5.00 Manual                                           End of Page 191
  11268.  
  11269.  
  11270.                have an option which will allow the individual sysop to
  11271.                determine whether or not the screen should be cleared when the
  11272.                door exits.
  11273.  
  11274.  
  11275.  
  11276. -------------------------------------------------------------------------------
  11277. od_colour      char od_control.od_colour_delimiter;
  11278. _delimiter
  11279.                This variable sets the character that is used to delimit colour
  11280.                codes in the od_printf() function, and defaults to the back-
  11281.                quote (`) character. If you wish to be able to display the back-
  11282.                quote (`) character using the od_printf() function, and thus
  11283.                wish to use a different character to delimit colour codes in the
  11284.                od_printf() function, simply set this variable to the
  11285.                alternative character you wish to use. If you wish to disable
  11286.                the imbedded colour codes feature of the od_printf() function,
  11287.                simply set this variable to a value of zero. For more
  11288.                information on od_printf() imbedded colour codes, see the
  11289.                description of the od_printf() function, which begins on page
  11290.                105.
  11291.  
  11292.  
  11293.  
  11294. -------------------------------------------------------------------------------
  11295. od_colour      char od_control.od_colour_names[12][33];
  11296. _names
  11297.                This array sets the strings that OpenDoors will recognize as
  11298.                colour description keywords. These are the keywords that can be
  11299.                imbedded in od_printf() format strings, and are also the
  11300.                keywords that can be used to change colour settings in the
  11301.                OpenDoors configuration file. If you wish to change these
  11302.                keywords, you will normally do so before calling any OpenDoors
  11303.                functions. These keywords should always be supplied in upper-
  11304.                case characters. The defaults values for this array are as
  11305.                follows:
  11306.  
  11307.                     [0]  "BLACK"
  11308.                     [1]  "BLUE"
  11309.                     [2]  "GREEN"
  11310.                     [3]  "CYAN"
  11311.                     [4]  "RED"
  11312.                     [5]  "MAGENTA"
  11313.                     [6]  "YELLOW"
  11314.                     [7]  "WHITE"
  11315.                     [8]  "BROWN"
  11316.                     [9]  "GREY"
  11317.                     [10] "BRIGHT"
  11318.                     [11] "FLASHING"
  11319.  
  11320.  
  11321.  
  11322.  
  11323.  
  11324.  
  11325. ===============================================================================
  11326. OpenDoors 5.00 Manual                                           End of Page 192
  11327.  
  11328.  
  11329. -------------------------------------------------------------------------------
  11330. od_config      void (*od_control.od_config_file)(void);
  11331. _file
  11332.                Set this variable to INCLUDE_CONFIG_FILE to enable the OpenDoors
  11333.                configuration file system, or set it to NO_CONFIG_FILE to
  11334.                disable the configuration file system. This variable should only
  11335.                be set prior to your first call to an OpenDoors function. For
  11336.                more information on the OpenDoors configuration file system, see
  11337.                page 215.
  11338.  
  11339.  
  11340.  
  11341. -------------------------------------------------------------------------------
  11342. od_config      char *od_control.od_config_filename;
  11343. _filename
  11344.                If set, this variable should point to a string containing the
  11345.                filename that you wish the OpenDoors configuration file system
  11346.                to read. If this variable has its default value of NULL, the
  11347.                filename DOOR.CFG will be used by default.
  11348.  
  11349.  
  11350.  
  11351. -------------------------------------------------------------------------------
  11352. od_config      void (*od_control.od_config_function)(char *keyword, char
  11353. _function      *options);
  11354.  
  11355.                If set, this variable should point to the function that
  11356.                OpenDoors should call when lines with unrecognized keywords are
  11357.                encountered in the configuration file. This allows you to add
  11358.                your own configuration file keywords. The first parameter to
  11359.                this function will be a pointer to a string containing the
  11360.                unrecognized keywords, and the second parameter will be a
  11361.                pointer to a string containing any options that were specified
  11362.                after the keyword. If no options were specified after the
  11363.                keyword, this string will have a length of 0.
  11364.  
  11365.  
  11366.  
  11367. -------------------------------------------------------------------------------
  11368. od_default     void (*od_control.od_default_personality)(unsigned char
  11369. _personality   operation);
  11370.  
  11371.                This variable sets the default personality that OpenDoors will
  11372.                use if the multiple personality system is active. If the
  11373.                multiple personality system is not active, the personality set
  11374.                by this variable will be the only personality available. This
  11375.                variable should only be set prior to calling an OpenDoors
  11376.                function. This variable can be set to point to your own
  11377.                personality function, or it can be set to one of the manifest
  11378.                constants that represent one of the built-in personalities:
  11379.  
  11380.                     PER_OPENDOORS
  11381.                     PER_PCBOARD
  11382.                     PER_RA
  11383.  
  11384. ===============================================================================
  11385. OpenDoors 5.00 Manual                                           End of Page 193
  11386.  
  11387.  
  11388.                     PER_WILDCAT
  11389.  
  11390.                For more information on the OpenDoors Multiple Personality
  11391.                System, see page 220.
  11392.  
  11393.  
  11394.  
  11395. -------------------------------------------------------------------------------
  11396. od_default     char od_control.od_default_rip_win;
  11397. _rip_win
  11398.                This variable defaults to FALSE. When set to FALSE, OpenDoors
  11399.                resets the RIP text window to a 23-line window that is most
  11400.                appropriate for doors that support both RIP-graphics and non-RIP
  11401.                mode. When this variable is set to TRUE, OpenDoors will use the
  11402.                default sized text output window, 43 lines in size.
  11403.  
  11404.  
  11405.  
  11406. -------------------------------------------------------------------------------
  11407. od_disable     unsigned int od_control.od_disable;
  11408.  
  11409.                This variable is a bit-mapped flag which can be used to disable
  11410.                certain OpenDoors features which are normally active, in order
  11411.                to allow for maximum customization of OpenDoors. Each bit of
  11412.                this variable represents a different feature that can be
  11413.                disabled. To DISABLE a feature, you set the bit that corresponds
  11414.                to the particular feature. To ENABLE the feature, the bit is
  11415.                reset. Each bit is represented by a keyword, as follows:
  11416.  
  11417.                DIS_INFOFILE - Setting the DIS_INFOFILE bit of the
  11418.                     od_control.od_disable variable allows you to prevent
  11419.                     OpenDoors from reading or re-writing a door information
  11420.                     file. If you wish to disable OpenDoors' reading of the door
  11421.                     information file, you must  do so prior to calling
  11422.                     od_init() or any other OpenDoors door-driver functions. At
  11423.                     the same time, you must also manually set any required
  11424.                     variables that are normally set by the information obtained
  11425.                     from the door information file, such as the comm port
  11426.                     number, baud rate, user name, and so on. You may wish to
  11427.                     disable reading of the door information file in a number of
  11428.                     cases. For example, you may wish to manually read another
  11429.                     format of door information file not supported by OpenDoors,
  11430.                     or to obtain the necessary door information from your
  11431.                     program's command line. Also, if you are using OpenDoors to
  11432.                     write a non-door communications program, such as a terminal
  11433.                     program, you want to prevent OpenDoors from attempting to
  11434.                     read a door information file on startup.
  11435.  
  11436.                DIS_CARRIERDETECT - Setting this bit allows you to prevent
  11437.                     OpenDoors from exiting when it the carrier detect signal
  11438.                     from the modem disappears. This bit may be set or rest at
  11439.                     any time. If you use this bit to disable OpenDoors' carrier
  11440.                     detection, you will probably want to monitor the state of
  11441.  
  11442.  
  11443. ===============================================================================
  11444. OpenDoors 5.00 Manual                                           End of Page 194
  11445.  
  11446.  
  11447.                     the carrier detect signal yourself, using the od_carrier()
  11448.                     function, which is described on page 51.
  11449.  
  11450.                DIS_TIMEOUT - This flag allows you to prevent OpenDoors from
  11451.                     exiting when the user runs out of time. As with the
  11452.                     DIS_CARRIERDETECT flag, you may set or reset this bit at
  11453.                     any time. You will most often want to use this setting when
  11454.                     writing a non-door program, which you would not want to
  11455.                     have exit after a particular amount of time has elapsed. Be
  11456.                     sure that you do not confuse this flag with the user's
  11457.                     inactivity timeout. To disable the inactivity timeout, set
  11458.                     the do_control.od_inactivity variable to 0.
  11459.  
  11460.                DIS_LOCAL_OVERRIDE - This setting affects OpenDoors' behavior
  11461.                     when a locked BPS rate is specified in the configuration
  11462.                     file, and another BPS rate is specified in the door
  11463.                     information file. By default, OpenDoors will initialize the
  11464.                     modem at the BPS rate specified in the configuration file,
  11465.                     unless the BPS rate specified in the door information file
  11466.                     is 0. In this case, the 0 BPS rate is used to indicate that
  11467.                     the door is operating in local mode, and will override the
  11468.                     BPS rate specified in the configuration file. Setting this
  11469.                     flag disables the local mode override, causing the modem to
  11470.                     always be initialized at the locked BPS rate, even when the
  11471.                     door information file specifies that local mode should be
  11472.                     used.
  11473.  
  11474.                DIS_BPS_SETTING - When used with a FOSSIL driver, OpenDoors
  11475.                     normally changes the BPS rate to that passed from the BBS
  11476.                     (if the BBS passes a valid FOSSIL BPS rate). Setting the
  11477.                     DIS_BPS_SETTING flag disables this BPS rate setting.
  11478.  
  11479.                DIS_LOCAL_INPUT -  The local keyboard may be disabled by setting
  11480.                     this bit. This only affects the sysop's input in
  11481.                     circumstances that input is also accepted from the remote
  11482.                     user; this setting has no effect on the sysop function
  11483.                     keys.
  11484.  
  11485.                Note that in order to disable the OpenDoors status line, the
  11486.                od_control.od_status_on variable is used, instead of the
  11487.                od_disable variable. You may also disable the user's inactivity
  11488.                timeout by setting the od_control.od_inactivity variable to 0.
  11489.                The od_control.od_status_on variable is described later in this
  11490.                section.
  11491.  
  11492.  
  11493.  
  11494. -------------------------------------------------------------------------------
  11495. od             unsigned char od_control.od_errorlevel[8];
  11496. _errorlevel
  11497.                Allows you to configure the errorlevel (program exit code) which
  11498.                OpenDoors exits with under various circumstances. The elements
  11499.                of this array are as follows:
  11500.  
  11501.  
  11502. ===============================================================================
  11503. OpenDoors 5.00 Manual                                           End of Page 195
  11504.  
  11505.  
  11506.                [ERRORLEVEL_ENABLE]     Enables or disables custom errorlevels
  11507.                [ERRORLEVEL_CRITICAL]   Critical error errorlevel
  11508.                [ERRORLEVEL_NOCARRIER]  Carrier lost errorlevel
  11509.                [ERRORLEVEL_HANGUP]     Sysop manually terminated call
  11510.                [ERRORLEVEL_TIMEOUT]    User time expired errorlevel
  11511.                [ERRORLEVEL_INACTIVITY] Keyboard inactivity timeout errorlevel
  11512.                [ERRORLEVEL_DROPTOBBS]  Sysop returned user to BBS errorlevel
  11513.                [ERRORLEVEL_NORMAL]     Door has exited normally
  11514.  
  11515.                If you wish to override the default errorlevels used by
  11516.                OpenDoors, you should set element [ERRORLEVEL_ENABLE] of this
  11517.                array to TRUE, and set the remaining array elements to the
  11518.                appropriate errorlevels. Note that the settings in this array
  11519.                only affect the errorlevels which OpenDoors uses when it causes
  11520.                the door to exit for one of the reasons listed above. This
  11521.                setting has no effect on the errorlevel returned when your
  11522.                program explicitly exits by calling the od_exit() function, or
  11523.                your program returns by calling exit() or returning from the
  11524.                main() function. For a list of the default errorlevels used by
  11525.                OpenDoors, see page 33.
  11526.  
  11527.  
  11528.  
  11529. -------------------------------------------------------------------------------
  11530. od             char od_control.od_force_local;
  11531. _force_local
  11532.                This variable defaults to FALSE, which causes OpenDoors to
  11533.                behave normally. When this variable is set to TRUE prior to
  11534.                calling od_init() or any other OpenDoors functions, OpenDoors
  11535.                will operate in local mode. In this case, no door information
  11536.                file will be read. Also, the user name will be used if
  11537.                od_control.user_name has not been set prior to calling od_init()
  11538.                or the first OpenDoors function.
  11539.  
  11540.                The default OpenDoors settings when od_control.od_force_local is
  11541.                set are as follows:
  11542.  
  11543.                - ANSI mode is on
  11544.                - Time limit is 60 minutes
  11545.                - User's location is the name of the BBS, or "Unknown Location"
  11546.                otherwise if BBS name is not known.
  11547.                - User name is set to sysop's name ("Sysop" if no sysop name is
  11548.                specified in the configuration file).
  11549.  
  11550.                You may wish to add a "-local" type parameter to your program's
  11551.                command line, which will permit the sysop to easily operate the
  11552.                door in local mode, as an interface to the
  11553.                od_control.od_force_local setting.
  11554.  
  11555.  
  11556.  
  11557.  
  11558.  
  11559.  
  11560.  
  11561. ===============================================================================
  11562. OpenDoors 5.00 Manual                                           End of Page 196
  11563.  
  11564.  
  11565. -------------------------------------------------------------------------------
  11566. od_in_buf      unsigned int od_control.od_in_buf_size;
  11567. _size
  11568.                Specifies the size, in characters, of the OpenDoor's internal
  11569.                local/remote inbound buffer size. Two bytes of storage are
  11570.                required for each character in this buffer. This variable should
  11571.                only be changed prior to calling od_init() or the first
  11572.                OpenDoors function. If not set, this variable defaults to a
  11573.                value of 256.
  11574.  
  11575.                The buffer corresponding to this variable should not be confused
  11576.                with the FOSSIL or internal communications receive buffer (which
  11577.                is set by od_control.od_com_rx_buf). Unlike the serial I/O
  11578.                receive buffer, which is used only for characters received from
  11579.                the remote system, this buffer serves as a queue for input from
  11580.                both the remote system and the local keyboard. If you find that
  11581.                characters are lost when information is being set to your door
  11582.                from the user, you may wish to increase the size of this buffer.
  11583.  
  11584.  
  11585.  
  11586. -------------------------------------------------------------------------------
  11587. od             unsigned int od_control.od_inactivity;
  11588. _inactivity
  11589.                OpenDoors has a built in user-inactivity timeout facility, which
  11590.                will automatically disconnect a user who appears .to be sleeping
  11591.                at the keyboard. If the user has not pressed any keys on their
  11592.                keyboard for to great a length of time, they will be warned that
  11593.                they are about to be disconnected due to inactivity. If they
  11594.                still do not respond after another few seconds, OpenDoors will
  11595.                automatically disconnect the user and return control to the BBS
  11596.                software. The od_control.od_inactivity variable allows you to
  11597.                set the maximum length of time, in seconds, after which the user
  11598.                will be disconnected for inactivity. This variable defaults to a
  11599.                value of 200 seconds. You may disable OpenDoors' inactivity
  11600.                timeout altogether, by setting the od_control.od_inactivity
  11601.                variable to a value of 0.
  11602.  
  11603.  
  11604.  
  11605. -------------------------------------------------------------------------------
  11606. od_inactive    int od_control.od_inactive_warning.
  11607. _warning
  11608.                This variable sets the number of seconds prior to hanging up
  11609.                that OpenDoors displays the inactivity timeout warning. This
  11610.                variable should only be changed after your first call to an
  11611.                OpenDoors API function. If not explicitly set by your program,
  11612.                this setting defaults to 10 seconds.
  11613.  
  11614.  
  11615.  
  11616.  
  11617.  
  11618.  
  11619.  
  11620. ===============================================================================
  11621. OpenDoors 5.00 Manual                                           End of Page 197
  11622.  
  11623.  
  11624. -------------------------------------------------------------------------------
  11625. od_ker_exec    void (*od_control.od_ker_exec)(void);
  11626.  
  11627.                When od_control.od_ker_exec is set to point to a function,
  11628.                OpenDoors will call this function whenever od_kernel() executes.
  11629.                This provides any easy way for you to perform your own
  11630.                processing on a regular basis during door execution. The
  11631.                od_control.od_ker_exec variable defaults to NULL.
  11632.  
  11633.  
  11634.  
  11635. -------------------------------------------------------------------------------
  11636. od_last        char od_control.od_last_input;
  11637. _input
  11638.                Indicates whether the last key retrieved using the od_get_key()
  11639.                function originated from the remote user, or the local sysop. If
  11640.                the input originated from the remote, this variable is set to 0.
  11641.                If the input originated from the local keyboard, this variables
  11642.                is set to 1.
  11643.  
  11644.  
  11645.  
  11646. -------------------------------------------------------------------------------
  11647. od_list        char od_control.od_list_pause;
  11648. _pause
  11649.                This variable contains a Boolean value, which allows you to
  11650.                control whether or not the user may pause displaying within the
  11651.                od_list_files() and od_send_file() function. When this variable
  11652.                is set to its default value of TRUE, the user will be able to
  11653.                pause the display by pressing the [P] key, and resume display by
  11654.                pressing any other key. However, the pause feature may be
  11655.                disabled by setting this variable to FALSE.
  11656.  
  11657.  
  11658.  
  11659. -------------------------------------------------------------------------------
  11660. od_list        char od_control.od_list_stop;
  11661. _stop
  11662.                This variable contains a Boolean value, which allows you to
  11663.                control whether or not the user may abort displaying within the
  11664.                od_list_files() and od_send_file() function. When this variable
  11665.                is set to its default value of TRUE, the user will be able to
  11666.                pause the display by pressing the [S], [CTRL]-[K] or [CTRL]-[C]
  11667.                keys. However, the stop feature may be disabled by setting this
  11668.                variable to FALSE.
  11669.  
  11670.  
  11671.  
  11672. -------------------------------------------------------------------------------
  11673. od_local       void (*od_control.od_local_input)(int);
  11674. _input
  11675.                If set, this function is called whenever the sysop presses a
  11676.                non-sysop-function key on the local keyboard. The key pressed is
  11677.  
  11678.  
  11679. ===============================================================================
  11680. OpenDoors 5.00 Manual                                           End of Page 198
  11681.  
  11682.  
  11683.                passed to the function in the single int parameter that it
  11684.                accepts.
  11685.  
  11686.  
  11687.  
  11688. -------------------------------------------------------------------------------
  11689. od_logfile     void *(od_control.od_logfile)(void);
  11690.  
  11691.                To make the OpenDoors log file system available in your program,
  11692.                set this variable to INCLUDE_LOGFILE, prior to calling any
  11693.                OpenDoors functions. If not set, or if set to NO_LOGFILE, the
  11694.                OpenDoors log file system will not automatically be enabled.
  11695.  
  11696.  
  11697.  
  11698. -------------------------------------------------------------------------------
  11699. od_logfile     char od_control.od_logfile_disable;
  11700. _disable
  11701.                This variable defaults to the value of FALSE, unless the
  11702.                "LogfileDisable" option is specified in the configuration file,
  11703.                in which case the variable will be set to TRUE. If this variable
  11704.                is set to TRUE, OpenDoors will not write to a logfile, even if
  11705.                the logfile system is enabled using od_control.od_logfile.
  11706.  
  11707.  
  11708.  
  11709. -------------------------------------------------------------------------------
  11710. od_logfile     char *od_control.od_logfile_messages[14];
  11711. _messages
  11712.                This array of pointers to strings contains the messages that
  11713.                OpenDoors will automatically write to the log file, if the log
  11714.                file system is enabled. If you wish to change the settings of
  11715.                this array, you should do so before calling any OpenDoors
  11716.                functions. The default strings for this array are as follows:
  11717.  
  11718.                [0] "Carrier lost, exiting door"
  11719.                [1] "System operator terminating call, exiting door"
  11720.                [2] "User's time limit expired, exiting door"
  11721.                [3] "User keyboard inactivity time limit exceeded, exiting door"
  11722.                [4] "System operator returning user to BBS, exiting door"
  11723.                [5] "Exiting door with errorlevel %d,
  11724.                [6] "Invoking operating system shell"
  11725.                [7] "Returning from operating system shell"
  11726.                [8] "User paging system operator"
  11727.                [9] "Entering sysop chat mode"
  11728.                [10] "Terminating sysop chat mode"
  11729.                [11] "%s entering door"
  11730.                [12] "Reason for chat: %s"
  11731.                [13] "Exiting door"
  11732.  
  11733.  
  11734.  
  11735.  
  11736.  
  11737.  
  11738. ===============================================================================
  11739. OpenDoors 5.00 Manual                                           End of Page 199
  11740.  
  11741.  
  11742. -------------------------------------------------------------------------------
  11743. od_logfile     char od_control.od_logfile_name[80];
  11744. _name
  11745.                This variable specifies the filename, and optionally the full
  11746.                path of the logfile where OpenDoors should perform logging. This
  11747.                variable only has an effect when set prior to calling any
  11748.                OpenDoors functions. If the log file name is specified in the
  11749.                configuration file, that name will be stored in this variable.
  11750.                If you do not set this variable, and the log file name is not
  11751.                specified in the configuration file, the default name "DOOR.LOG"
  11752.                will be used. If you wish to set this variable, you should do so
  11753.                prior to calling od_init() or any OpenDoors function.
  11754.  
  11755.  
  11756.  
  11757. -------------------------------------------------------------------------------
  11758. od_            unsigned int od_control.od_maxtime;
  11759. maxtime
  11760.                This variable specifies the maximum length of time that any user
  11761.                is permitted to use the door, and is normally set from a
  11762.                configuration file option. If upon entering the door, the user's
  11763.                time remaining online is greater than the od_maxtime setting,
  11764.                their time remaining is temporarily decreased to the maximum
  11765.                value. Then upon exit of the door, the number of subtracted
  11766.                minutes is added back onto the user's remaining time. If the
  11767.                user's remaining time is less than this value, then the setting
  11768.                has no effect. A value of 0 disables the maximum time setting
  11769.                altogether.
  11770.  
  11771.  
  11772.  
  11773. -------------------------------------------------------------------------------
  11774. od_maxtime     int od_control.od_maxtime_deduction;
  11775. _deduction
  11776.                This variable store the amount of time that should be added to
  11777.                the user's time upon exit of the door, as a result of the
  11778.                maximum time deduction, described above. If the maximum time
  11779.                feature is not used, this variable will be given a value of 0.
  11780.  
  11781.  
  11782.  
  11783. -------------------------------------------------------------------------------
  11784. od_mps         void (*od_control.od_mps)(void);
  11785.  
  11786.                To make the OpenDoors Multiple Personality system available in
  11787.                your program, set this variable to INCLUDE_MPS before calling
  11788.                any OpenDoors functions. If this variable is not set, or is set
  11789.                to NO_MPS, the Multiple Personality System will be disabled. For
  11790.                more information on the OpenDoors Multiple Personality System,
  11791.                see page 223.
  11792.  
  11793.  
  11794.  
  11795.  
  11796.  
  11797. ===============================================================================
  11798. OpenDoors 5.00 Manual                                           End of Page 200
  11799.  
  11800.  
  11801. -------------------------------------------------------------------------------
  11802. od_no_         void (*od_control.od_no_file_func)();
  11803. file_func
  11804.                If od_no_file_func is set to point to a function, that function
  11805.                will be called whenever a door information (drop) file cannot be
  11806.                located or read. This provides an easy mechanism to add your own
  11807.                door information file reader, or to provide a local login prompt
  11808.                when no drop file is present. If you wish the door to operate in
  11809.                local mode, you should set od_control.od_force_local to TRUE
  11810.                prior to returning from your function. If you have successfully
  11811.                read your own door information file format, you should set
  11812.                od_control.od_info_type to CUSTOM. If neither of these variables
  11813.                are set by the od_no_file_function, OpenDoors will report that
  11814.                it is unable to find or read a door information file and will
  11815.                exit immediately.
  11816.  
  11817.  
  11818.  
  11819. -------------------------------------------------------------------------------
  11820. od_no_ra       char od_control.od_no_ra_codes;
  11821. _codes
  11822.                This variable defaults to FALSE. When set to TRUE, the
  11823.                translation of the RemoteAccess/QuickBBS control codes by the
  11824.                functions od_sen_file(), od_hotkey_menu() and od_disp_emu() is
  11825.                disabled.
  11826.  
  11827.  
  11828.  
  11829. -------------------------------------------------------------------------------
  11830. od_            char od_control.od_nocopyright;
  11831. nocopyright
  11832.                This variable is a Boolean value that allows you to prevent
  11833.                OpenDoors from displaying its name, version number, copyright
  11834.                notice and registration information when the program begins
  11835.                execution. Set this variable to TRUE to disable the display of
  11836.                copyright and associated information. When this variable is set
  11837.                to TRUE, OpenDoors also does not change the initial display
  11838.                colour on startup. For obvious reasons, this variable does not
  11839.                take effect when OpenDoors is operating in unregistered mode.
  11840.  
  11841.  
  11842.  
  11843. -------------------------------------------------------------------------------
  11844. od_noexit      char od_control.od_noexit;
  11845.  
  11846.                This variable contains a Boolean value, which allows you to
  11847.                prevent OpenDoors from exiting when shutting down. This may be
  11848.                useful when you want to have your program to do more processing
  11849.                after you have called the od_exit() function, or if you do not
  11850.                wish to have your program exit automatically when the user drops
  11851.                carrier. Normally, this variable will default to a value of
  11852.                FALSE, indicating that OpenDoors will exit normally when the
  11853.                od_exit() function is called. However, you may optionally set
  11854.                this variable to TRUE after od_init() or some OpenDoors function
  11855.  
  11856. ===============================================================================
  11857. OpenDoors 5.00 Manual                                           End of Page 201
  11858.  
  11859.  
  11860.                has been called. In this case, when the od_exit() function is
  11861.                called, either by your program manually, or automatically by
  11862.                OpenDoors in response to the user dropping carrier, etc.,
  11863.                OpenDoors will not exit. However, the normal operations of
  11864.                closing the serial port and re-writing the door information file
  11865.                will be carried out. If you set the od_noexit variable to TRUE,
  11866.                you will probably have to provide some mechanism to allow your
  11867.                program to detect when OpenDoors shutdowns due to the loss of
  11868.                carrier, etc. The best way of doing this is to provide a
  11869.                function which is to be called at the beginning of the od_exit()
  11870.                function, by setting the od_control.od_before_exit pointer,
  11871.                described above.
  11872.  
  11873.  
  11874.  
  11875. -------------------------------------------------------------------------------
  11876. od_page        char od_control.od_page_len;
  11877. _len
  11878.                This variable allows you to control the length, in seconds, of
  11879.                the sysop page beep produced when the user pages the sysop via
  11880.                the od_page() function.
  11881.  
  11882.  
  11883.  
  11884. -------------------------------------------------------------------------------
  11885. od_page        char od_control.od_page_pausing;
  11886. _pausing
  11887.                This variable contains a Boolean value that indicates whether or
  11888.                not page pausing is enabled in the od_send_file(),
  11889.                od_hotkey_menu() and od_list_files() functions. The default
  11890.                value of TRUE indicates that page pausing is enabled. A value of
  11891.                FALSE indicates that page pausing is disabled.
  11892.  
  11893.  
  11894.  
  11895. -------------------------------------------------------------------------------
  11896. od_page        int od_control.od_pagestartmin;
  11897. startmin       int od_control.od_pageendmin;
  11898.  
  11899. od_page        These variables indicate the start and end times for sysop
  11900. endmin         paging, expressed as the number of minutes past midnight.
  11901.                Sysop paging will be available through the od_page() function
  11902.                from the start time, up to but not including the end time.
  11903.  
  11904.  
  11905.  
  11906. -------------------------------------------------------------------------------
  11907. od_page        char od_control.od_page_statusline;
  11908. _statusline
  11909.                This variable controls which status line, if any, is activated
  11910.                when the user pages the system operator (via the od_page()
  11911.                function). A value between 0 and 9 causes the corresponding
  11912.                status line to be activated. A value of -1 prevents any change
  11913.                from being made to the current status line setting. This
  11914.  
  11915. ===============================================================================
  11916. OpenDoors 5.00 Manual                                           End of Page 202
  11917.  
  11918.  
  11919.                variable will normally be set by personality functions (see page
  11920.                223).
  11921.  
  11922.  
  11923.  
  11924. -------------------------------------------------------------------------------
  11925. od_prog_name   char od_control.od_prog_name[40];
  11926.  
  11927.                This variable should contain the full name of your program, up
  11928.                to 39 characters. Currently, this variable is only used when
  11929.                writing to the OpenDoors log file. However, this variable may
  11930.                also be used for other purposes in future versions. If not set,
  11931.                OpenDoors will use its name and version information in place of
  11932.                this variable. If used, this variable should be set prior to
  11933.                calling any OpenDoors functions.
  11934.  
  11935.  
  11936.  
  11937. -------------------------------------------------------------------------------
  11938. od_reg_key     unsigned log od_control.od_reg_key;
  11939.  
  11940.                When you purchase an OpenDoors licence (registration), this
  11941.                variable should be set to your registration key, prior to
  11942.                calling any OpenDoors functions.
  11943.  
  11944.  
  11945.  
  11946. -------------------------------------------------------------------------------
  11947. od_reg_name    char od_control.od_reg_name[36];
  11948.  
  11949.                When you purchase an OpenDoors licence (registration), this
  11950.                variable should be set to your name, or your company's name, as
  11951.                is listed in your OpenDoors registration record.
  11952.  
  11953.  
  11954.  
  11955. -------------------------------------------------------------------------------
  11956. od_spawn       char od_control.od_spawn_freeze_time;
  11957. _freeze_time
  11958.                This variable is a Boolean value which indicates whether or not
  11959.                the user's time remaining is frozen during the execution of one
  11960.                of the od_spawn...() functions. If this variable is set to TRUE,
  11961.                the user's time remaining will not decrease during the time that
  11962.                the od_spawn...() function is executing. However, if this
  11963.                variable is set to FALSE, the user's time remaining will
  11964.                continue to be subtracted during the execution of the
  11965.                od_spawn...() function. The default value of this variable is
  11966.                FALSE.
  11967.  
  11968.  
  11969.  
  11970.  
  11971.  
  11972.  
  11973.  
  11974. ===============================================================================
  11975. OpenDoors 5.00 Manual                                           End of Page 203
  11976.  
  11977.  
  11978. -------------------------------------------------------------------------------
  11979. od_swapping    char od_control.od_swapping_disable;
  11980. _disable
  11981.                This variable is a Boolean value which specifies whether or not
  11982.                OpenDoors will attempt to swap itself and your entire door upon
  11983.                DOS shell or a call to one of the od_spawn...() functions. This
  11984.                variable defaults to FALSE. If set to TRUE, OpenDoors will not
  11985.                attempt to perform swapping activities.
  11986.  
  11987.  
  11988.  
  11989. -------------------------------------------------------------------------------
  11990. od_swapping    char od_control.od_swapping_noems;
  11991. _noems
  11992.                This variable is a Boolean value which can be used to prevent
  11993.                OpenDoors from swapping to EMS memory. This variable defaults to
  11994.                the value FALSE. If set to TRUE, OpenDoors will not attempt to
  11995.                use EMS memory for swapping, and will only swap to disk.
  11996.  
  11997.  
  11998.  
  11999. -------------------------------------------------------------------------------
  12000. od_swapping    char od_control.od_swapping_path;
  12001. _path
  12002.                This variable specifies the drive and directory where OpenDoors
  12003.                should create its disk swapping file, if applicable. More than
  12004.                one path can be specified, by separating the paths with a semi-
  12005.                colon (;) character.
  12006.  
  12007.  
  12008.  
  12009. -------------------------------------------------------------------------------
  12010. od_status      char od_control.od_status_on;
  12011. _on
  12012.                This variable is a Boolean value which allows your program to
  12013.                completely disable the OpenDoors status line. The variable
  12014.                defaults to a value of TRUE, which causes the OpenDoors status
  12015.                line to be controllable by function keys, displayed and updated
  12016.                as it would normally be. However, if this variable is set to
  12017.                FALSE, then OpenDoors will not update the status line, nor will
  12018.                it allow the status line to be re-displayed as a result of one
  12019.                of the status line ([F1] through [F10]) keys being pressed. When
  12020.                you change the value of this variable from FALSE to TRUE,
  12021.                OpenDoors will automatically redisplay the status line. Note,
  12022.                however, that the status line isn't automatically removed when
  12023.                the value of this variable is changed from TRUE to FALSE. In
  12024.                order to erase the status line after resetting the value of this
  12025.                variable, you should reset the output window to the full screen,
  12026.                by calling the function window(1,1,25,80). Then manually erase
  12027.                the old status line either by clearing the bottom two lines of
  12028.                the screen, or by clearing the entire screen.
  12029.  
  12030.                It is important that you do not confuse the use of this variable
  12031.                with the od_set_statusline() function, which is described on
  12032.  
  12033. ===============================================================================
  12034. OpenDoors 5.00 Manual                                           End of Page 204
  12035.  
  12036.  
  12037.                page 136. When the status line is enabled, the sysop can change
  12038.                which status line, if any, is being displayed, using the
  12039.                function keys [F1] through [F10]. The od_set_statusline()
  12040.                function allows your program to make the same changes to the
  12041.                status line setting which the sysop can make by pressing one of
  12042.                the function keys. The status line can be removed from the
  12043.                screen, allowing a full 25 lines of text to be displayed, by
  12044.                pressing the [F10] key, or by making the appropriate call to the
  12045.                od_set_statusline() function. Note, however, than when this is
  12046.                done, the status line is still enabled, and can be turned on by
  12047.                pressing any of the other function keys. On the other hand, if
  12048.                the status line is turned off using this variable
  12049.                (od_control.od_status_on), the status line sub-system will be
  12050.                disabled, and pressing function keys will not "bring it back".
  12051.                So, if you were writing a program where a status line would be
  12052.                undesirable - such as a non-door communications program, you
  12053.                would use the od_control.od_status_on variable. On the other
  12054.                hand, if you only wanted to temporarily remove the status line -
  12055.                say in order that all 25 lines of a door program's output could
  12056.                be viewed - while still allowing the status line to be turned on
  12057.                with the sysop function keys, you would use the
  12058.                od_set_statusline() function. For more information on the
  12059.                od_set_statusline() function, see page 136.
  12060.  
  12061.  
  12062.  
  12063. -------------------------------------------------------------------------------
  12064. od_time        void (*od_control.od_time_msg_func)(char *string)
  12065. _msg_func
  12066.                This variable defaults to a value of NULL. If set to point to a
  12067.                function, OpenDoors will call this function INSTEAD OF
  12068.                displaying time limit warning messages to the user. The messages
  12069.                redirected to this function are:
  12070.  
  12071.                     - Inactivity timeout warning
  12072.                     - Inactivity timeout expired
  12073.                     - Less than 4 minutes left today
  12074.                     - Daily time limit expired
  12075.  
  12076.                Providing your own od_time_msg_func allows you to display these
  12077.                messages at a specific screen location, within a popup window,
  12078.                etc.
  12079.  
  12080.                The function pointed to by od_time_msg_func must accept a single
  12081.                parameter of type char *. OpenDoors will pass a pointer to the
  12082.                string containing the time limit message in this parameter.
  12083.  
  12084.  
  12085.  
  12086.  
  12087.  
  12088.  
  12089.  
  12090.  
  12091.  
  12092. ===============================================================================
  12093. OpenDoors 5.00 Manual                                           End of Page 205
  12094.  
  12095.  
  12096.  
  12097.  
  12098.  
  12099.  
  12100.  
  12101. CONTROL STRUCTURE - FUNCTION KEYS
  12102. -------------------------------------------------------------------------------
  12103.  
  12104.                Within OpenDoors, as with most BBS software and doors, the sysop
  12105.                has access to a number of function keys, which permits the sysop
  12106.                to carry out various functions such as entering chat mode,
  12107.                hanging up on the user, shelling to DOS, and so on. (For more
  12108.                information on these function key, see page 32.) The variables
  12109.                in this section allow you to customize which keys carry out the
  12110.                standard sysop functions, allowing you to customize your door's
  12111.                interface to mimic any BBS package. By default, OpenDoors
  12112.                emulates the function keys used by the Remote Access BBS
  12113.                package, but you may choose, for example, to have your door use
  12114.                the key combinations used by PC-Board. In addition, OpenDoors
  12115.                provides an interface which allows you to add your own function
  12116.                keys which will be accepted by the door. This could allow you to
  12117.                add additional features, such as giving the sysop access to a
  12118.                status screen which displays information about your door.
  12119.  
  12120.                Many of the variables in this section are unsigned ints, which
  12121.                represent a sysop key combination such as [ALT]-[H], [F8], or
  12122.                [CTRL]-[P]. These values are in the same format as is returned
  12123.                by the Turbo C(++) / Borland C++ bioskey() function. The high-
  12124.                order byte represents the scan code of the key, and the low-
  12125.                order byte represents the ASCII value, if any, of the key
  12126.                combination. Note that a complete tutorial on these key codes is
  12127.                beyond the scope of this manual. For more information on these
  12128.                key codes, you should see the documentation on the bioskey()
  12129.                function, which accompanies your compiler. If you wish to
  12130.                determine the key code which corresponds to a particular
  12131.                keystroke, there is a simple program, listed below, which you
  12132.                can compile and use. This program will simply display the key
  12133.                code for any key pressed, until you press the [ESCape] key. So,
  12134.                in order to determine the code for [SHIFT]-[F8], you would
  12135.                simply run this program, press the [SHIFT]-[F8] key combination
  12136.                on your keyboard, and record the value displayed on your screen.
  12137.  
  12138.                          #include <bios.h>
  12139.  
  12140.                          int main(int argc, char *agv[])
  12141.                             {
  12142.                             register unsigned int keystroke=0;
  12143.  
  12144.                             while((keystroke&0xff)!=27)
  12145.                                {
  12146.                                keystroke=bioskey(0);
  12147.                                if(keystroke!=0)
  12148.                                   {
  12149.                                   printf("You pressed %u\n",keystroke);
  12150.  
  12151. ===============================================================================
  12152. OpenDoors 5.00 Manual                                           End of Page 206
  12153.  
  12154.  
  12155.                                   }
  12156.                                }
  12157.                             }
  12158.  
  12159.  
  12160. -------------------------------------------------------------------------------
  12161. BUILT IN       These variable allow you to customize the sysop function keys
  12162. FUNCTION       which control functions such as hanging up on the user, shelling
  12163. KEYS           to DOS, and so on. All of these variable will be assigned
  12164.                default values, which correspond to the same function keys used
  12165.                by the RemoteAccess BBS package. However, you may change the
  12166.                values of these variables in order to customize the key
  12167.                combinations which carry out these functions in your own door
  12168.                program. Remember that if you wish to change the value of any of
  12169.                these variables, you must do so after having called od_init() or
  12170.                some OpenDoors function. Each of these variables contain a scan-
  12171.                code / ASCII-code combination representing a keystroke, as is
  12172.                described above. These variables are as follows:
  12173.  
  12174.                +---------------------+----------------------------------------+
  12175.                | VARIABLE            | CORRESPONDING FUNCTION                 |
  12176.                +---------------------+----------------------------------------+
  12177.                | od_control.         | Enter sysop chat mode                  |
  12178.                | key_chat            | (Normally [ALT]-[C]                    |
  12179.                |                     |                                        |
  12180.                | od_control.         | Invoke sysop DOS shell                 |
  12181.                | key_dosshell        | (Normally [ALT]-[J]                    |
  12182.                |                     |                                        |
  12183.                | od_control.         | Return to the BBS without hanging up   |
  12184.                | key_drop2bbs        | (Normally [ALT]-[D])                   |
  12185.                |                     |                                        |
  12186.                | od_control.         | Hangup on the user                     |
  12187.                | key_hangup          | (Normally [ALT]-[H])                   |
  12188.                |                     |                                        |
  12189.                | od_control.         | Turn off the user's keyboard           |
  12190.                | key_keyboardoff     | (Normally [ALT]-[K])                   |
  12191.                |                     |                                        |
  12192.                | od_control.         | Decreases the user's remaining time    |
  12193.                | key_lesstime        | (Normally [DOWN-ARROW])                |
  12194.                |                     |                                        |
  12195.                | od_control.         | Lock the user out of the BBS system    |
  12196.                | key_lockout         | (Normally [ALT]-[L])                   |
  12197.                |                     |                                        |
  12198.                | od_control.         | Increases the user's remaining time    |
  12199.                | key_moretime        | (Normally [UP-ARROW])                  |
  12200.                |                     |                                        |
  12201.                | od_control.         | Array of eight function keys to set the|
  12202.                | key_status[8]       | current status line.                   |
  12203.                |                     | (Normally [F1], [F2], [F3], [F4], [F5],|
  12204.                |                     |  [F6], [F9], [F10])                    |
  12205.                |                     |                                        |
  12206.                | od_control.         | "Sysop next" toggle key                |
  12207.                | key_sysopnext       | (Normally [ALT]-[N])                   |
  12208.                +---------------------+----------------------------------------+
  12209.  
  12210. ===============================================================================
  12211. OpenDoors 5.00 Manual                                           End of Page 207
  12212.  
  12213.  
  12214.  
  12215.  
  12216.  
  12217. -------------------------------------------------------------------------------
  12218. CUSTOM         In addition to the sysop function keys built into OpenDoors, you
  12219. FUNCTION       may wish to add your own function keys to your door. For
  12220. KEYS           example, you might wish to have the [ALT]-[Z] combination
  12221.                display a window of information about your door, or you may wish
  12222.                to add your own user editor to your door, accessible through the
  12223.                [ALT]-[E] combination. The four variables:
  12224.  
  12225.                          unsigned char od_control.od_num_keys;
  12226.                          unsigned int od_control.od_hot_key[16];
  12227.                          unsigned int od_control.od_last_hot;
  12228.                          void (*od_control.od_hot_function[16])(void);
  12229.  
  12230.                provide your program with an interface to add your own sysop
  12231.                function keys (not accessible by the remote user) to the door
  12232.                you have written.
  12233.  
  12234.                OpenDoors allows you to define up to sixteen custom sysop
  12235.                function keys. The key codes (as described at the beginning of
  12236.                this section) are stored in the od_control.od_hot_key[] array,
  12237.                and the od_control.od_num_keys variable records the number of
  12238.                keys which have been defined. The od_control.od_num_keys
  12239.                variable defaults to a value of 0. So, in order to add your own
  12240.                function keys, simply place the key codes for these keys in the
  12241.                first n elements of the od_control.od_hot_key[] array, and set
  12242.                the od_control.od_num_keys variable to the number of keys you
  12243.                have defined. OpenDoors will then watch the keyboard for any of
  12244.                your predefined sysop function keys being pressed. If one of
  12245.                these keys is pressed, OpenDoors will place the key code of the
  12246.                pressed key in the od_control.od_last_hot variable. Your program
  12247.                will then be able to respond to one of your custom function keys
  12248.                being pressed by checking the value of the
  12249.                od_control.od_last_hot variable. At any time this variable
  12250.                contains a non-zero value. If this is the case, you will then be
  12251.                able to determine which of your function keys has been pressed
  12252.                by checking the key code contained in this variable. After
  12253.                taking the appropriate action for the key pressed, you should be
  12254.                sure to reset the value of the od_control.od_last_hot variable
  12255.                back to zero, which will indicate to OpenDoors that your program
  12256.                has received and responded to the function key which was
  12257.                pressed.
  12258.  
  12259.                As an alternative to testing the contents of the
  12260.                od_control.od_last_hot variable, you  can also have your program
  12261.                respond to custom sysop function keys by providing a callback
  12262.                function in the array:
  12263.  
  12264.                          void (*od_control.od_hot_function[16])(void);
  12265.  
  12266.                The Nth element in this array corresponds to the Nth element in
  12267.                the od_control.od_hot_key array. To use this mechanism, simply
  12268.  
  12269. ===============================================================================
  12270. OpenDoors 5.00 Manual                                           End of Page 208
  12271.  
  12272.  
  12273.                set the appropriate element of this array to point to the
  12274.                function that you wish to have OpenDoors call when the sysop
  12275.                presses the corresponding function key. For instance, assume
  12276.                that the following function is included in your program's source
  12277.                code:
  12278.  
  12279.                     void addPoints(void)
  12280.                        {
  12281.                        /* add ten points to the user's score */
  12282.                        currentUser->points += 10;
  12283.                        }
  12284.  
  12285.                If you wanted to have this function called when the sysop
  12286.                presses the [Page Up] key, you could do the following:
  12287.  
  12288.                     /* get number of new sysop function key, and increment */
  12289.                     /* total number of keys */
  12290.                     int new_key = od_control.od_num_keys++;
  12291.  
  12292.                     /* Set next sysop hotkey to Page Up */
  12293.                     od_control.od_hot_key[new_key] = 0x4900;
  12294.  
  12295.                     /* Set corresponding function to addPoints() */
  12296.                     od_control.od_hot_function[new_key] = addPoints;
  12297.  
  12298.  
  12299.  
  12300.  
  12301.  
  12302.  
  12303.  
  12304.  
  12305.  
  12306.  
  12307.  
  12308.  
  12309.  
  12310.  
  12311.  
  12312.  
  12313.  
  12314.  
  12315.  
  12316.  
  12317.  
  12318.  
  12319.  
  12320.  
  12321.  
  12322.  
  12323.  
  12324.  
  12325.  
  12326.  
  12327.  
  12328. ===============================================================================
  12329. OpenDoors 5.00 Manual                                           End of Page 209
  12330.  
  12331.  
  12332.  
  12333.  
  12334.  
  12335.  
  12336. CONTROL STRUCTURE - COLOUR CUSTOMIZATION
  12337. -------------------------------------------------------------------------------
  12338.  
  12339.                The OpenDoors control structure variables listed in this section
  12340.                allow you to customize the colour of text displayed by several
  12341.                of the OpenDoors functions. Each of the variables in this
  12342.                section are unsigned chars, which contain the IBM-PC colour
  12343.                attribute of the colour to be displayed. For more information on
  12344.                these colour attributes, see the description of the
  12345.                od_set_attrib() function on page 125. These colour variables are
  12346.                listed below, along with a description of where each colour is
  12347.                used:
  12348.  
  12349.                +---------------------+----------------------------------------+
  12350.                | VARIABLE            | WHERE COLOUR IS USED                   |
  12351.                +---------------------+----------------------------------------+
  12352.                | od_control.         | Text typed by the sysop in chat mode   |
  12353.                | od_chat_colour1     |                                        |
  12354.                |                     |                                        |
  12355.                | od_control.         | Text typed by the user in chat mode    |
  12356.                | od_chat_colour2     |                                        |
  12357.                |                     |                                        |
  12358.                | od_control.         | File description fields in FILES.BBS   |
  12359.                | od_list_comment_col | listings                               |
  12360.                |                     |                                        |
  12361.                | od_control.         | Color of page pausing prompt that is   |
  12362.                | od_continue_col     | displayed at the end of each page      |
  12363.                |                     |                                        |
  12364.                | od_control.         | Filename fields in FILES.BBS listings  |
  12365.                | od_list_name_col    |                                        |
  12366.                |                     |                                        |
  12367.                | od_control.         | "Missing" string in FILES.BBS listings |
  12368.                | od_list_offline_col |                                        |
  12369.                |                     |                                        |
  12370.                | od_control.         | File size fields in FILES.BBS listings |
  12371.                | od_list_size_col    |                                        |
  12372.                |                     |                                        |
  12373.                | od_control.         | Title fields in FILES.BBS listings     |
  12374.                | od_list_title_col   |                                        |
  12375.                |                     |                                        |
  12376.                | od_control.         | Color of the window title as displayed |
  12377.                | od_menu_title_col   | by od_popup_menu()                     |
  12378.                |                     |                                        |
  12379.                | od_control.         | Color of the window border as          |
  12380.                | od_menu_border_col  | displayed by od_popup_menu()           |
  12381.                |                     |                                        |
  12382.                | od_control.         | Color of the normal text displayed     |
  12383.                | od_menu_text_col    | by od_popup_menu()                     |
  12384.                |                     |                                        |
  12385.                | od_control.         | Color of the shortcut keys displayed   |
  12386.  
  12387. ===============================================================================
  12388. OpenDoors 5.00 Manual                                           End of Page 210
  12389.  
  12390.  
  12391.                | od_menu_key_col     | by od_popup_menu()                     |
  12392.                |                     |                                        |
  12393.                | od_control.         | Color of the selection bar as          |
  12394.                | od_menu_highlight_  | displayed by od_popup_menu()           |
  12395.                | col                 |                                        |
  12396.                |                     |                                        |
  12397.                | od_control.         | Color of the shortcut keys displayed   |
  12398.                | od_menu_highkey_col | on the selected line by od_popup_menu()|
  12399.                +---------------------+----------------------------------------+
  12400.  
  12401.  
  12402.  
  12403.  
  12404.  
  12405.  
  12406.  
  12407.  
  12408.  
  12409.  
  12410.  
  12411.  
  12412.  
  12413.  
  12414.  
  12415.  
  12416.  
  12417.  
  12418.  
  12419.  
  12420.  
  12421.  
  12422.  
  12423.  
  12424.  
  12425.  
  12426.  
  12427.  
  12428.  
  12429.  
  12430.  
  12431.  
  12432.  
  12433.  
  12434.  
  12435.  
  12436.  
  12437.  
  12438.  
  12439.  
  12440.  
  12441.  
  12442.  
  12443.  
  12444.  
  12445.  
  12446. ===============================================================================
  12447. OpenDoors 5.00 Manual                                           End of Page 211
  12448.  
  12449.  
  12450.  
  12451.  
  12452.  
  12453.  
  12454. CONTROL STRUCTURE - TEXT CUSTOMIZATION
  12455. -------------------------------------------------------------------------------
  12456.  
  12457.                In addition to the other aspects of OpenDoors which may be
  12458.                customized by use of the OpenDoors control structure, all of the
  12459.                text displayed by OpenDoors may also be customized. This may be
  12460.                done either to create doors with OpenDoors that use languages
  12461.                other than English, or to simply give your doors a "personal
  12462.                touch". The variables described in this section allow you to
  12463.                define what text you want to have displayed by OpenDoors at any
  12464.                time. All of these variables are pointers to strings, and are
  12465.                set to default values in the od_init() function. Thus, if you
  12466.                wish to change the string pointed to by any of these variables,
  12467.                you must do so after od_init() or some OpenDoors API function
  12468.                has been called. To set any of these variables, you can simply
  12469.                set them to point to a string-constant in your program. For
  12470.                example, to set the text displayed by OpenDoors prior to a DOS
  12471.                shell, you could:
  12472.  
  12473.                od_control.od_before_shell=(char *)"\n\rJust a moment...\n\r";
  12474.  
  12475.                The chart below lists each of the text customization variables
  12476.                (without the "od_control." prefix, for the sake of brevity),
  12477.                along with their default strings.
  12478.  
  12479.                Note that some of these strings MUST always be the same length
  12480.                as their default string. You may not display longer text within
  12481.                these strings, and if you wish to display shorter text, you must
  12482.                pad the remaining space in the string with spaces, in order to
  12483.                preserve its length. Those string which must be of fixed length
  12484.                also have their length listed in the chart below. Any strings
  12485.                which have an asterisk (*) in their length column may be any
  12486.                length.
  12487.  
  12488.                Also keep in mind that any string with "printf-style" formatting
  12489.                sequences, such as "%s", must retain the same sequences in the
  12490.                same order.
  12491.  
  12492.                In addition, four of these pointers - od_after_chat,
  12493.                od_after_shell, od_before_chat and od_before_shell - can be set
  12494.                to a value of NULL. In this case, OpenDoors will not display any
  12495.                string where this variable's string is normally displayed.
  12496.  
  12497. +-----------------------+-----+----------------------------------------------+
  12498. | VARIABLE NAME         | LEN | DEFAULT VALUE                                |
  12499. +-----------------------+-----+----------------------------------------------+
  12500. | od_after_chat         |  *  | "\n\rChat mode ended...\n\r\n\r"             |
  12501. |                       |     |                                              |
  12502. | od_after_shell        |  *  | "\n\r...Thanks for waiting\n\r\n\r"          |
  12503. |                       |     |                                              |
  12504.  
  12505. ===============================================================================
  12506. OpenDoors 5.00 Manual                                           End of Page 212
  12507.  
  12508.  
  12509. | od_before_chat        |  *  | "\n\rSysop breaking in for chat...\n\r\n\r"  |
  12510. |                       |     |                                              |
  12511. | od_before_shell       |  *  | "\n\rPlease wait a moment...\n\r"            |
  12512. |                       |     |                                              |
  12513. | od_chat_reason        |  *  | "                          Why would you "   |
  12514. |                       |     | "like to chat?\n\r"                          |
  12515. |                       |     |                                              |
  12516. | od_continue           |  *  | "Continue? [Y/n/=]"                          |
  12517. |                       |     |                                              |
  12518. | od_continue_no        | char| 'N'                                          |
  12519. |                       |     |                                              |
  12520. | od_continue_nonstop   | char| '='                                          |
  12521. |                       |     |                                              |
  12522. | od_continue_yes       | char| 'Y'                                          |
  12523. |                       |     |                                              |
  12524. | od_day[0]             |  3  | "Sun"                                        |
  12525. |                       |     |                                              |
  12526. | od_day[1]             |  3  | "Mon"                                        |
  12527. |                       |     |                                              |
  12528. | od_day[2]             |  3  | "Tue"                                        |
  12529. |                       |     |                                              |
  12530. | od_day[3]             |  3  | "Wed"                                        |
  12531. |                       |     |                                              |
  12532. | od_day[4]             |  3  | "Thu"                                        |
  12533. |                       |     |                                              |
  12534. | od_day[5]             |  3  | "Fri"                                        |
  12535. |                       |     |                                              |
  12536. | od_day[6]             |  3  | "Sat"                                        |
  12537. |                       |     |                                              |
  12538. | od_hanging_up         |  *  | "Terminating Call"                           |
  12539. |                       |     |                                              |
  12540. | od_help_text          |  80 | "  Alt: [C]hat [H]angup [L]ockout [J]Dos "   |
  12541. |                       |     | "[K]eyboard-Off [D]rop to BBS            "   |
  12542. |                       |     |                                              |
  12543. | od_help_text2         |  79 | "  OpenDoors 5.00 - (C)Copyright 1992, "     |
  12544. |                       |     | "Brian Pirie - Registered Version         "  |
  12545. |                       |     |                                              |
  12546. | od_inactivity_timeout |  *  | "User sleeping at keyboard, inactivity "     |
  12547. |                       |     | "timeout...\n\r\n\r"                         |
  12548. |                       |     |                                              |
  12549. | od_inactivity_warning |  *  | "Warning, only %d minute(s) remaining "      |
  12550. |                       |     | "today...\n\r\n\r"                           |
  12551. |                       |     |                                              |
  12552. | od_month[0]           |  3  | "Jan"                                        |
  12553. |                       |     |                                              |
  12554. | od_month[1]           |  3  | "Feb"                                        |
  12555. |                       |     |                                              |
  12556. | od_month[2]           |  3  | "Mar"                                        |
  12557. |                       |     |                                              |
  12558. | od_month[3]           |  3  | "Apr"                                        |
  12559. |                       |     |                                              |
  12560. | od_month[4]           |  3  | "May"                                        |
  12561. |                       |     |                                              |
  12562. | od_month[5]           |  3  | "Jun"                                        |
  12563.  
  12564. ===============================================================================
  12565. OpenDoors 5.00 Manual                                           End of Page 213
  12566.  
  12567.  
  12568. |                       |     |                                              |
  12569. | od_month[6]           |  3  | "Jul"                                        |
  12570. |                       |     |                                              |
  12571. | od_month[7]           |  3  | "Aug"                                        |
  12572. |                       |     |                                              |
  12573. | od_month[8]           |  3  | "Sep"                                        |
  12574. |                       |     |                                              |
  12575. | od_month[9]           |  3  | "Oct"                                        |
  12576. |                       |     |                                              |
  12577. | od_month[10]          |  3  | "Nov"                                        |
  12578. |                       |     |                                              |
  12579. | od_month[11]          |  3  | "Dec"                                        |
  12580. |                       |     |                                              |
  12581. | od_no_keyboard        |  10 | "[Keyboard]"                                 |
  12582. |                       |     |                                              |
  12583. | od_no_sysop           |  *  | "\n\rI'm afraid the sysop is not available " |
  12584. |                       |     | "at this time.\n\r"                          |
  12585. |                       |     |                                              |
  12586. | od_no_response        |  *  | " No response.\n\r\n\r"                      |
  12587. |                       |     |                                              |
  12588. | od_no_time            |  *  | "Sorry, you have used up your time for "     |
  12589. |                       |     | "today...\n\r\n\r"                           |
  12590. |                       |     |                                              |
  12591. | od_offline            |  10 | "[OFFLINE] "                                 |
  12592. |                       |     |                                              |
  12593. | od_paging             |  *  | "\n\rPaging Sysop for Chat"                  |
  12594. |                       |     |                                              |
  12595. | od_press_key          |  *  | "Press [Enter] to continue..."               |
  12596. |                       |     |                                              |
  12597. | od_sending_rip        |  *  | "\xb4 Sending RIP File \xc3"                 |
  12598. |                       |     |                                              |
  12599. | od_status_line[0]     |  80 | "                                        "   |
  12600. |                       |     | "                             [Node:     "   |
  12601. |                       |     |                                              |
  12602. | od_status_line[1]     |  *  | "%s of %s at %u BPS"                         |
  12603. |                       |     |                                              |
  12604. | od_status_line[2]     |  79 | "Security:        Time:                  "   |
  12605. |                       |     | "                             [F9]=Help "    |
  12606. |                       |     |                                              |
  12607. | od_sysop_next         |  5  | "[SN] "                                      |
  12608. |                       |     |                                              |
  12609. | od_time_left          |  10 | "%d mins   "                                 |
  12610. |                       |     |                                              |
  12611. | od_time_warning       |  *  | "Warning, only %d minute(s) remaining tod"   |
  12612. |                       |     | "ay...\n\r\n\r"                              |
  12613. |                       |     |                                              |
  12614. | od_want_chat          |  11 | "[Want-Chat]"                                |
  12615. +-----------------------+-----+----------------------------------------------+
  12616.  
  12617.  
  12618.  
  12619.  
  12620.  
  12621.  
  12622.  
  12623. ===============================================================================
  12624. OpenDoors 5.00 Manual                                           End of Page 214
  12625.  
  12626.  
  12627.  
  12628. -------------------------------------------------------------------------------
  12629. CHAPTER 6 - SPECIAL TOPICS
  12630. -------------------------------------------------------------------------------
  12631.  
  12632.  
  12633.  
  12634.  
  12635. CONFIGURATION FILE SYSTEM
  12636. -------------------------------------------------------------------------------
  12637.  
  12638.                One of the most useful OpenDoors features that you can
  12639.                optionally choose to include in your programs is the OpenDoors
  12640.                configuration file system. All that is required to enable the
  12641.                configuration file system is to include the following line
  12642.                before your first call to any OpenDoors function:
  12643.  
  12644.                     od_control.od_config_file = INCLUDE_CONFIG_FILE;
  12645.  
  12646.                OpenDoors will now search for and read an OpenDoors
  12647.                configuration file. If you do not specify the name of this file,
  12648.                the default name of DOOR.CFG will be used. Using this
  12649.                configuration file, the sysop can set a wide variety of options,
  12650.                such as modem and system configuration information, maximum time
  12651.                limits for the door, and even define custom door information
  12652.                (drop) file formats. The example DOOR.CFG file included in your
  12653.                OpenDoors package shows the format and all options that are
  12654.                automatically supported by the configuration file system. This
  12655.                configuration file format is designed to be easy to use, and the
  12656.                example configuration file contains comments which provide a
  12657.                complete description of each option. Feel free to redistribute
  12658.                DOOR.CFG or a modified version of this file with your door
  12659.                programs. In addition to the many configuration file settings
  12660.                already supported, you can add your own settings that are
  12661.                specific to your particular program.
  12662.  
  12663.                To specify your own filename for the configuration file, use the
  12664.                od_config_filename control structure variable. For example, the
  12665.                following line:
  12666.  
  12667.                     od_control.od_config_filename = "MYDOOR.CFG"
  12668.  
  12669.                causes OpenDoors to look for the configuration file MYDOOR.CFG
  12670.                instead of the default DOOR.CFG.
  12671.  
  12672.                OpenDoors fill first search for the configuration file in the
  12673.                directory specified in the od_config_filename variable, if a
  12674.                specific directory name was supplied. If not found, it will then
  12675.                search the current directory. If the configuration file system
  12676.                is unable to locate a configuration file, or if any settings are
  12677.                omitted from the file, the default values for these settings
  12678.                will be used automatically. This means that the configuration
  12679.                file is always optional, unless your program has custom settings
  12680.                that it requires in order to run.
  12681.  
  12682. ===============================================================================
  12683. OpenDoors 5.00 Manual                                           End of Page 215
  12684.  
  12685.  
  12686.  
  12687.                The format for the configuration file is as follows. Blank lines
  12688.                and any text following the semi-colon (;) character are ignored.
  12689.                Configuration options are specified using a keyword, possibly
  12690.                followed by one or more options. The keywords are not case
  12691.                sensitive, but some of the options are. The order of options in
  12692.                the configuration file is not significant, with the exception of
  12693.                the "CustomFileLine" option. For more information on the
  12694.                "CustomFileLine" setting, see the section that begins on page
  12695.                220. The built-in configuration options are as follow:
  12696.  
  12697.                BBSDir - BBS System directory. Indicates where the door
  12698.                     information file (drop file) can be found.
  12699.  
  12700.                DoorDir - The door's working directory. This is where the door's
  12701.                     system files are located. OpenDoors will automatically
  12702.                     perform a chdir into this directory at initialization, and
  12703.                     will return to the original directory on exit.
  12704.  
  12705.                LogFileName - Specifies the filename (path optional) where the
  12706.                     door should record log information.
  12707.  
  12708.                DisableLogging - Prevents door from writing to a log file.
  12709.  
  12710.                Node - BBS node number that the door is running on. Only used if
  12711.                     OpenDoors is unable to determine the node number by some
  12712.                     other means.
  12713.  
  12714.                ???dayPagingHours - Specifies sysop paging hours. Sysop paging
  12715.                     will be permitted beginning at the start time, up until,
  12716.                     but not including, the end time. Times should be in the 24-
  12717.                     hour format. To disable paging on a particular day, set the
  12718.                     paging start and end times to the same time. ???day can be
  12719.                     one of Sunday, Monday, Tuesday, Wednesday, Thursday, Friday
  12720.                     or Saturday.
  12721.  
  12722.                PagDuration - Duration of sysop page. Value indicates the number
  12723.                     of beeps that compose the sysop page alarm.
  12724.  
  12725.                MaximumDoorTime - Maximum length of time a user is permitted to
  12726.                     access the door. If the user's total remaining time on the
  12727.                     BBS is less than this value, the user will only be
  12728.                     permitted to access the door for this shorter length of
  12729.                     time. This option is disabled by commenting out the line.
  12730.  
  12731.                InactivityTimeout - Specifies the maximum number of seconds that
  12732.                     may elapse without the user pressing a key, before the user
  12733.                     will automatically be disconnected. A value of 0 disables
  12734.                     inactivity timeouts.
  12735.  
  12736.                SysopName - Name of the sysop. OpenDoors can usually determine
  12737.                     the sysop's name from the door information (drop) file.
  12738.                     How3ever, some BBS packages do not supply this information.
  12739.  
  12740.  
  12741. ===============================================================================
  12742. OpenDoors 5.00 Manual                                           End of Page 216
  12743.  
  12744.  
  12745.                     In such cases, if the sysop's name is required by the door,
  12746.                     it may be supplied here.
  12747.  
  12748.                SystemName - Like the sysop's name, this option can usually be
  12749.                     determined from the door information file. If it is not
  12750.                     available, the sysop my supply the information here.
  12751.  
  12752.                ChatUserColour - Specifies the colour of text typed by the user
  12753.                     in sysop chat mode. The format of the colour name is
  12754.                     included in the description of the od_colour_config()
  12755.                     function.
  12756.  
  12757.                ChatSysopColour - Specifies the colour of test typed by the
  12758.                     sysop in chat mode.
  12759.  
  12760.                FileListTitleColour - Files.BBS listing colours.
  12761.                FileListNameColour
  12762.                FileListSizeColour
  12763.                FileListDescriptionColour
  12764.                FileListOfflineColour
  12765.  
  12766.                SwappingDir - Directory where disk swapping will be done.
  12767.  
  12768.                SwappingNoEMS - Disables swapping to EMS memory.
  12769.  
  12770.                SwappingDisable - Disables swapping entirely.
  12771.  
  12772.                LockedBPS -  BPS rate at which door should communicate with the
  12773.                     modem.  Valid rates are 300, 600, 1200, 2400, 4800, 9600,
  12774.                     19200 and 38400. A value of 0 forces the door to always
  12775.                     operate in local mode. This option is not normally needed,
  12776.                     as the information is usually available from the door
  12777.                     information file.
  12778.  
  12779.                FossilPort - Specifies the FOSSIL driver port number that the
  12780.                     modem is connected to. FOSSIL port 0 usually corresponds to
  12781.                     COM1, port 1 to COM2, and so on. This option is not
  12782.                     normally needed, as the information is usually available
  12783.                     from the door information file.
  12784.  
  12785.                CustomFileName - Specifies the filename used by the custom door
  12786.                     information file format. Described in more detail below.
  12787.  
  12788.                CustomFileLine - Specifies the contents of a particular line in
  12789.                     the custom door information file format.
  12790.  
  12791.                The last two configuration file options, "CustomFileName" and
  12792.                "CustomFileLine" allow you or the system operator using your
  12793.                program to define your own door information (drop) file formats.
  12794.                For more information on this topic, see the section which begins
  12795.                on page 220.
  12796.  
  12797.                You can also extend OpenDoor's configuration file format to add
  12798.                your own options, by supplying a callback function that will be
  12799.  
  12800. ===============================================================================
  12801. OpenDoors 5.00 Manual                                           End of Page 217
  12802.  
  12803.  
  12804.                called whenever OpenDoors encounters an unrecognized
  12805.                configuration file keyword. The prototype of this function
  12806.                should be as follows:
  12807.  
  12808.                     custom_line_function(char *keyword, char *options)
  12809.  
  12810.                To cause OpenDoors to use your function, you would include the
  12811.                following line before your first call to any OpenDoors function:
  12812.  
  12813.                     od_control.od_config_function = custom_line_function;
  12814.  
  12815.                (You can use a different function name if you wish.) When
  12816.                OpenDoors encounters unrecognized keyword, it will now call your
  12817.                function, passing a pointer to an upper case version the keyword
  12818.                string in the first parameter, and a pointer to any options that
  12819.                follow the keyword in the second parameter. For instance, if the
  12820.                following line were encountered in the configuration file:
  12821.  
  12822.                     RegisteredTo    John Smith      ; Sysop's name
  12823.  
  12824.                The parameters passed to your function would be:
  12825.  
  12826.                     char *keyword = "REGISTEREDTO"
  12827.                     char *options = "John Smith"
  12828.  
  12829.                Your custom line function should be written in such a way that
  12830.                if OpenDoors passes a configuration option to your function that
  12831.                your function does not recognize, that option would simply be
  12832.                ignored.
  12833.  
  12834.                The example program below demonstrates how to use the custom
  12835.                line function to add your own configuration file options. This
  12836.                program looks for three custom configuration file options,
  12837.                "RegistrationKey", "DefaultColour" and "DisplayWinners". If the
  12838.                "RegistrationKey" option is present, the numerical value
  12839.                following this option is stored in the global variable "key". If
  12840.                the "DefaultColour" option is present, the color description
  12841.                (such as "Bright Red on Black") is translated to an
  12842.                od_set_attr() colour code using od_colour_config(). This color
  12843.                setting is stored in the global variable default_colour. Since
  12844.                this variable is initialized to 0x07 (the value for dark white
  12845.                on black), if this option is omitted, that colour is used by
  12846.                default. If the "DisplayWinners" option is included in the
  12847.                configuration file, the global variable display_winners is set
  12848.                to TRUE, regardless of any options that may follow this keyword.
  12849.  
  12850.  
  12851.                #include "opendoor.h"                  /* Include opendooor.h */
  12852.                                        /* Prototype for custom line function */
  12853.                void custom_line_function(char *keyword, char *options);
  12854.  
  12855.                unsigned long key=0L; /* Variables for our own config option */
  12856.                unsigned char default_colour=0x07;
  12857.                char display_winners=FALSE;
  12858.  
  12859. ===============================================================================
  12860. OpenDoors 5.00 Manual                                           End of Page 218
  12861.  
  12862.  
  12863.  
  12864.                main()                     /* Program's execution begins here */
  12865.                   {            /* Begin door operations, reading config file */
  12866.                   od_config_file = INCLUDE_CONFIG_FILE;
  12867.                   od_init();
  12868.  
  12869.                                         /* Main program's operations go here */
  12870.  
  12871.                   od_exit(FALSE,10);                            /* Exit door */
  12872.                   }
  12873.  
  12874.                                             /* Code for custom line function */
  12875.                void custom_line_function(char *keyword, char *options)
  12876.                   {                         /* If option is registration key */
  12877.                   if(stricmp(keyword,"REGISTRATIONKEY")==0)
  12878.                      {
  12879.                      key=atol(options);             /* Store key in variable */
  12880.                      }                           /* If option is text colour */
  12881.                   else if(stricmp(keyword,"DEFAULTCOLOUR")==0)
  12882.                      {          /* Get colour value using od_colour_config() */
  12883.                      default_colour=od_colour_config(options);
  12884.                      }      /* Example of option enabled by just the keyword */
  12885.                   else if(stricmp(keyword,"DISPLAYWINNERS")==0)
  12886.                      {              /* If keyword is present, turn on option */
  12887.                      display_winners=TRUE;
  12888.                      }
  12889.                   }
  12890.  
  12891.  
  12892.  
  12893.  
  12894.  
  12895.  
  12896.  
  12897.  
  12898.  
  12899.  
  12900.  
  12901.  
  12902.  
  12903.  
  12904.  
  12905.  
  12906.  
  12907.  
  12908.  
  12909.  
  12910.  
  12911.  
  12912.  
  12913.  
  12914.  
  12915.  
  12916.  
  12917.  
  12918. ===============================================================================
  12919. OpenDoors 5.00 Manual                                           End of Page 219
  12920.  
  12921.  
  12922.  
  12923.  
  12924.  
  12925.  
  12926. DEFINING CUSTOM DOOR INFORMATION FILE FORMATS
  12927. -------------------------------------------------------------------------------
  12928.  
  12929.                As is mentioned in the previous section, the OpenDoors
  12930.                configuration file system provides two settings which allow the
  12931.                sysop to define a custom door information file format. This
  12932.                permits OpenDoors doors to operate directly on any BBS system
  12933.                that produces a door information file format not directly
  12934.                supported by OpenDoors. A custom door information file format is
  12935.                defined using the "CustomFileName" option, followed by one or
  12936.                more lines beginning with the "CustomFileLine" option.
  12937.  
  12938.                The "CustomFileName" option specifies the filename used to
  12939.                distinguish this file format from other file formats. This
  12940.                filename should not include a path. To specify the path where
  12941.                the door information file is located, the sysop should use the
  12942.                BBSDir configuration file setting. If the filename of the custom
  12943.                format is the same as that of one of the built-in formats, the
  12944.                custom format will override the built-in format.
  12945.  
  12946.                The actual format of the custom file is specified using a number
  12947.                of lines that begin with the keyword "CustomFileLine". Each of
  12948.                these lines will correspond to a single line in the door
  12949.                information file, with the option following the "CustomFileLine"
  12950.                keyword specifying the information that can be found on that
  12951.                line. This can be one of the following keywords:
  12952.  
  12953.                     Ignore - Causes the next line in the door information file
  12954.                          to be ignored. Use on lines for which none of the
  12955.                          options below apply.
  12956.  
  12957.                     COMPORT - COM? port the modem is connected to (0 indicates
  12958.                          local mode)
  12959.  
  12960.                     FOSSILPORT - Fossil port number the modem is connected to
  12961.  
  12962.                     MODEMBPS - BPS rate at which to communicate with modem (0
  12963.                          or non-numerical value indicates local mode)
  12964.  
  12965.                     LOCALMODE - 1, T or Y if door is operating in local mode
  12966.  
  12967.                     USERNAME - Full name of the user
  12968.  
  12969.                     USERFIRSTNAME - First name(s) of the user
  12970.  
  12971.                     USERLASTNAME - Last name of the user
  12972.  
  12973.                     ALIAS - The user's pseudonym / handle
  12974.  
  12975.                     HOURSLEFT - Hours user has left online
  12976.  
  12977. ===============================================================================
  12978. OpenDoors 5.00 Manual                                           End of Page 220
  12979.  
  12980.  
  12981.  
  12982.                     MINUTESLEFT - Minutes user has left online, or time left
  12983.                          online in format hh:mm
  12984.  
  12985.                     SECONDSLEFT - Seconds user has left online, or time left
  12986.                          online in format hh:mm:ss or format mm:ss (If more
  12987.                          than one of the above time options are used, the user
  12988.                          time left is taken to be the total of all of these
  12989.                          values.)
  12990.  
  12991.                     ANSI - 1, T, Y or G for ANSI graphics mode
  12992.  
  12993.                     AVATAR - 1, T or Y for AVATAR graphics mode
  12994.  
  12995.                     PAGEPAUSING - 1, T or Y if user wishes a pause at end of
  12996.                          screen
  12997.  
  12998.                     SCREENLENGTH - Number of lines on user's screen
  12999.  
  13000.                     SCREENCLEARING - 1, T or Y if screen clearing mode is on
  13001.  
  13002.                     SECURITY - The user's security level / access level
  13003.  
  13004.                     CITY - City the user is calling from
  13005.  
  13006.                     NODE - Node number user is connected to
  13007.  
  13008.                     SYSOPNAME - Full name of the sysop
  13009.  
  13010.                     SYSOPFIRSTNAME - The sysop's first name(s)
  13011.  
  13012.                     SYSOPLASTNAME - The sysop's last name
  13013.  
  13014.                     SYSTEMNAME - Name of the BBS
  13015.  
  13016.                As an example of how to define custom door information file
  13017.                formats, consider the following imaginary file format, which we
  13018.                will name DROPINFO.TXT:
  13019.  
  13020.                     Brian Pirie         <-- User name
  13021.                     0                   <-- Local mode
  13022.                     COM1:               <-- Serial port to use
  13023.                     9600                <-- BPS rate
  13024.                     22:30:15 05-08-95   <-- File creation time
  13025.                     35                  <-- Time remaining (in minutes)
  13026.                     1                   <-- ANSI mode
  13027.                     Ottawa, Canada      <-- Location
  13028.  
  13029.                This format would be defined in an OpenDoors configuration file
  13030.                as follows:
  13031.  
  13032.  
  13033.  
  13034.  
  13035.  
  13036. ===============================================================================
  13037. OpenDoors 5.00 Manual                                           End of Page 221
  13038.  
  13039.  
  13040.                     CustomFileName DROPINFO.TXT
  13041.                     CustomFileLine USERNAME
  13042.                     CustomFileLine LOCALMODE
  13043.                     CustomFileLine COMPORT
  13044.                     CustomFileLine MODEMBPS
  13045.                     CustomFileLine IGNORE
  13046.                     CustomFileLine MINUTESLEFT
  13047.                     CustomFileLine ANSI
  13048.                     CustomFileLine CITY
  13049.  
  13050.                Notice that the first "CustomFileLine" keyword in the
  13051.                configuration file corresponds to the first line in our
  13052.                DROPINFO.TXT file, the second "CustomFileLine" to the second
  13053.                line, and so on. Also notice that the keyword "IGNORE" is used
  13054.                for the line that contains the file creation time, since there
  13055.                is no CustomFileLine keyword that allows you to read this
  13056.                information.
  13057.  
  13058.  
  13059.  
  13060.  
  13061.  
  13062.  
  13063.  
  13064.  
  13065.  
  13066.  
  13067.  
  13068.  
  13069.  
  13070.  
  13071.  
  13072.  
  13073.  
  13074.  
  13075.  
  13076.  
  13077.  
  13078.  
  13079.  
  13080.  
  13081.  
  13082.  
  13083.  
  13084.  
  13085.  
  13086.  
  13087.  
  13088.  
  13089.  
  13090.  
  13091.  
  13092.  
  13093.  
  13094.  
  13095. ===============================================================================
  13096. OpenDoors 5.00 Manual                                           End of Page 222
  13097.  
  13098.  
  13099.  
  13100.  
  13101.  
  13102.  
  13103. MULTIPLE PERSONALITY SYSTEM
  13104. -------------------------------------------------------------------------------
  13105.  
  13106.                The OpenDoors Multiple Personality System allows OpenDoors to
  13107.                support multiple sysop function key / status line
  13108.                "personalities". Most commonly, you will use this feature in
  13109.                conjunction with the "Personality" setting in the OpenDoors
  13110.                configuration file, to allow the sysop to choose one of the
  13111.                built-in personalities that most closely mimics the BBS software
  13112.                they are using. OpenDoors includes the following personalities:
  13113.  
  13114.                     Configuration Keyword         Manifest constant
  13115.                     -----------------------------------------------------------
  13116.                     Standard                      PER_OPENDOORS
  13117.                     PCBoard                       PER_PCBOARD
  13118.                     RemoteAccess                  PER_RA
  13119.                     Wildcat                       PER_WILDCAT
  13120.  
  13121.                The PCBoard, RemoteAccess and Wildcat personalities mimic the
  13122.                status lines and function keys used by the BBS packages with
  13123.                those names. The Standard personality, which is the personality
  13124.                used by default, is a trimmed down version of the status lines
  13125.                provided by OpenDoors 4.10 and earlier.
  13126.  
  13127.                In addition to using the personalities supplied with OpenDoors,
  13128.                you can create your own personalities. This simply involves
  13129.                writing a function which OpenDoors will call to setup the sysop
  13130.                function keys and to display the status line.
  13131.  
  13132.                Include the following line before your first call to any
  13133.                OpenDoors function:
  13134.  
  13135.                     od_control.od_mps = INCLUDE_MPS;
  13136.  
  13137.                to include the multiple personality system in your program. This
  13138.                also enables the Personality setting in the configuration file,
  13139.                if you are using the configuration file system.
  13140.  
  13141.                You can set the default personality to be used by OpenDoors by
  13142.                setting od_control.od_default_personality to one of the manifest
  13143.                constants listed in the table above. If you have included the
  13144.                multiple personality system in your program, this setting will
  13145.                determine the personality to use if the "Personality" option is
  13146.                not set in the configuration file, and your program does not
  13147.                later change the personality using the od_set_personality()
  13148.                function. If you do not include the multiple personality system
  13149.                in your program, this setting will determine the personality
  13150.                that will always be used.
  13151.  
  13152.  
  13153.  
  13154. ===============================================================================
  13155. OpenDoors 5.00 Manual                                           End of Page 223
  13156.  
  13157.  
  13158.                Creating your own personality involves writing a single
  13159.                function.. Whenever OpenDoors needs to perform an operation that
  13160.                involves the personality, it will call this function, passing
  13161.                one of the following message values:
  13162.  
  13163.                PEROP_INITIALIZE    Initialize the personality, installing any
  13164.                                    custom function keys.
  13165.                PEROP_DEINITIALIZE  Deinitialize the personality, returning any
  13166.                                    changed settings to their original values.
  13167.                PEROP_CUSTOMKEY     Indicates that a custom function key has
  13168.                                    been pressed.
  13169.                PEROP_DISPLAYx      Where x is a number from 1 to 10. Indicates
  13170.                                    that the specified status line should be
  13171.                                    drawn from scratch.
  13172.                PEROP_UPDATEx       Where x is a number from 1 to 10. Indicates
  13173.                                    that the specified status line should be
  13174.                                    updated to reflect any changes.
  13175.  
  13176.                If you have enabled the multiple personality system by setting
  13177.                od_control.od_mps to INCLUDE_MPS, you can install your
  13178.                personality function into OpenDoors by calling
  13179.                od_add_personality(). When you call od_add_personality(), you
  13180.                supply a string containing the name of the personality, along
  13181.                with the top and bottom output line numbers to use. These line
  13182.                numbers specify the portion of the screen to use for door
  13183.                output, leaving the remainder of the screen available for
  13184.                displaying the personality's status line. Once the personality
  13185.                has been installed into OpenDoors, it can be selected by the
  13186.                sysop using the "Personality" configuration file option, or
  13187.                manually activated using the od_set_personality() function. For
  13188.                more information on the od_add_personality() function, see page
  13189.                46.
  13190.  
  13191.                You can make your personality function the default personality
  13192.                by setting od_control.od_default_personality to point to your
  13193.                personality function. As is the case with the built-in
  13194.                personalities, this setting will be used as the default
  13195.                personality if you have enabled the multiple personality system
  13196.                by setting od_control.od_mps to INCLUDE_MPS. If you have not
  13197.                enabled the multiple personality system in this manner, your
  13198.                personality function will become the one and only personality
  13199.                used within your program. When creating your own personality,
  13200.                you can use the od_control.od_page_statusline variable to set
  13201.                which status line (if any) will be activated when the user pages
  13202.                the system operator.
  13203.  
  13204.  
  13205.  
  13206.  
  13207.  
  13208.  
  13209.  
  13210.  
  13211.  
  13212.  
  13213. ===============================================================================
  13214. OpenDoors 5.00 Manual                                           End of Page 224
  13215.  
  13216.  
  13217.  
  13218.  
  13219.  
  13220.  
  13221. LOG FILE SYSTEM
  13222. -------------------------------------------------------------------------------
  13223.  
  13224.                In order for the system operator to monitor system activity and
  13225.                diagnose problems that have ocurred while the system was
  13226.                unattended, it is common for BBS software and door programs to
  13227.                record major events in a log file. This log file typically
  13228.                records the date and time of evens such as a user logging on or
  13229.                off, transferring files, sending messages, paging the system
  13230.                operator, and similar activities. Sometimes the system operator
  13231.                will configure all of the pieces of software running on a
  13232.                paticular node to write to a single log file. In other cases,
  13233.                the system operator will prefer to have each program write to
  13234.                its own log file. However, software serving one line of a multi-
  13235.                node BBS system should never attempt to write to the same log
  13236.                file that is used by anothe rnode.
  13237.  
  13238.                OpenDoors uses the "FrontDoor format" log file standard. This
  13239.                was chosen as it is a clearly documented format that is quickly
  13240.                becoming the standard for bulletin board software log files. A
  13241.                segment from a log file produced by OpenDoors is listed below.
  13242.  
  13243.                          ----------  Thu 25 Feb 93, EZVote 5.00
  13244.                          > 19:42:23  Brian Pirie entering door
  13245.                          > 19:50:55  User paging system operator
  13246.                          > 19:51:02  Entering sysop chat mode
  13247.                          > 20:05:41  Terminating sysop chat mode
  13248.                          > 20:18:32  User time expired, exiting door
  13249.  
  13250.                To enable the OpenDoors log file system, simply include the
  13251.                following line before your first call to any OpenDoors function:
  13252.  
  13253.                     od_control.od_log_file = INCLUDE_LOGFILE;
  13254.  
  13255.                When OpenDoors is initialized, it will open the log file and
  13256.                begin logging activities, unless logging has been disabled with
  13257.                the od_control.od_logfile_disable variable. The log file name
  13258.                will be taken from the od_control.od_logfile_name variable,
  13259.                which is usually set by the configuration file. If no logfile
  13260.                name has been set, OpenDoors will use the logfile named
  13261.                DOOR.LOG. Upon opening the log file, OpenDoors will write an
  13262.                entry indicating the time at which the use entered the door.
  13263.  
  13264.                The od_control.od_prog_name variable sets the program name that
  13265.                is written to the log file immediately after the current date
  13266.                information. If this variable is not set, OpenDoors will write
  13267.                its own name and version information in this place.
  13268.  
  13269.                When the OpenDoors log file system is enabled, OpenDoors will
  13270.                automatically produce logfile entries for the following events:
  13271.  
  13272. ===============================================================================
  13273. OpenDoors 5.00 Manual                                           End of Page 225
  13274.  
  13275.  
  13276.  
  13277.                          - User paging sysop
  13278.                          - Beginning of sysop chat
  13279.                          - Ending of sysop chat
  13280.                          - Sysop entering DOS shell
  13281.                          - Sysop returning from DOS shell
  13282.                          - User inactivity timeout
  13283.                          - User time expired
  13284.                          - Sysop dropping user back to BBS
  13285.                          - Sysop hanging up on user
  13286.                          - User hanging up on BBS
  13287.                          - Sysop locking out user
  13288.                          - Your door calling the od_exit()
  13289.                            function
  13290.  
  13291.                These built in log file entries can be customized by altering
  13292.                the value of the array od_control.od_logfile_messages.
  13293.  
  13294.                The logfile is automatically closed when your program exits.
  13295.  
  13296.  
  13297.  
  13298.  
  13299.  
  13300.  
  13301.  
  13302.  
  13303.  
  13304.  
  13305.  
  13306.  
  13307.  
  13308.  
  13309.  
  13310.  
  13311.  
  13312.  
  13313.  
  13314.  
  13315.  
  13316.  
  13317.  
  13318.  
  13319.  
  13320.  
  13321.  
  13322.  
  13323.  
  13324.  
  13325.  
  13326.  
  13327.  
  13328.  
  13329.  
  13330.  
  13331. ===============================================================================
  13332. OpenDoors 5.00 Manual                                           End of Page 226
  13333.  
  13334.  
  13335.  
  13336.  
  13337.  
  13338.  
  13339. MAKING DOORS MULTI-NODE-AWARE
  13340. -------------------------------------------------------------------------------
  13341.  
  13342.                Today, it is common for BBS systems to have multiple nodes
  13343.                (phone lines) that can be in use by different users
  13344.                simultaneously. As such, it is often possible for door programs
  13345.                to be in use concurrently by more than one person, each on a
  13346.                different node of the BBS. Some doors are designed to behave on
  13347.                multi-node systems just as they would on single-line BBSes
  13348.                (except for the fact that more than one person may be using the
  13349.                door at once). Other doors take special advantage of multi-node
  13350.                environments to permit users to interact or communicate with one
  13351.                another in "real time". In either case, there are a number of
  13352.                issues that the door programmer must be aware of when writing
  13353.                doors for multiple node BBSes that are not of concern in single
  13354.                node situations.
  13355.  
  13356.                If you expect your door program to be used on a multi-line BBS
  13357.                system, the best time to begin planning for multi-node
  13358.                capabilities is when you first start to write your door. Writing
  13359.                multi-node-aware doors is not usually much more complicated than
  13360.                writing doors that are not multi-node-aware. However, the job is
  13361.                usually much easier if you plan multi-node capabilities from the
  13362.                beginning.
  13363.  
  13364.                OpenDoors is designed for use with both single-node and
  13365.                multiple-node BBS systems, and many simple doors may not require
  13366.                any special attention to multi-node capabilities. However, if
  13367.                your door must access any data files or other resources that are
  13368.                to be shared among doors, it is your responsibility to
  13369.                coordinate access to these resources. While this section deals
  13370.                primarily with sharing access to files, similar principles apply
  13371.                to coordinating access to other resources such as CD-ROM drives
  13372.                or packet network connections.
  13373.  
  13374.                When sharing access to files between multiple nodes, there are
  13375.                generally two issues that you have to deal with:
  13376.  
  13377.                     1. Coordinating write access to files or records within a
  13378.                        file in order that only one node is attempting to write
  13379.                        to a file at any instant. If you do not do this, the
  13380.                        information being written by one node may be overwritten
  13381.                        by another node.
  13382.  
  13383.                     2. Keeping information read into memory from files up to
  13384.                        date.
  13385.  
  13386.                Often, these two requirements go hand in hand. For instance,
  13387.  
  13388.  
  13389.  
  13390. ===============================================================================
  13391. OpenDoors 5.00 Manual                                           End of Page 227
  13392.  
  13393.  
  13394.  
  13395. -------------------------------------------------------------------------------
  13396. CHAPTER 7 - DEBUGGING AND GETTING ASSISTANCE WITH OPENDOORS
  13397. -------------------------------------------------------------------------------
  13398.  
  13399.  
  13400.  
  13401.  
  13402. ABOUT THIS CHAPTER
  13403. -------------------------------------------------------------------------------
  13404.  
  13405.                This chapter is perhaps the most important section of this
  13406.                entire manual. Here, we provide detailed instructions to help
  13407.                you in tracing the source of problems in programs written with
  13408.                OpenDoors. Included in this chapter is a step-by-step OpenDoors
  13409.                troubleshooting guide and a chart listing common problems and
  13410.                their solutions. Also included in this chapter is information on
  13411.                the many means available to you for getting more help with
  13412.                OpenDoors, including the OpenDoors support BBS, the OpenDoors
  13413.                EchoMail conference, and how to get in touch with me. It is
  13414.                strongly encouraged that you take the time to read through this
  13415.                chapter.
  13416.  
  13417.  
  13418.  
  13419. TROUBLESHOOTING PROBLEMS
  13420. -------------------------------------------------------------------------------
  13421.  
  13422.                If you are experiencing difficulty with a program that you are
  13423.                writing using OpenDoors, it is suggested that you follow the
  13424.                steps listed below in order to quickly solve your problem. Also,
  13425.                be sure to check to "solutions to common problems" section of
  13426.                this manual. There are many common difficulties which people
  13427.                have with OpenDoors, that can easily be fixed using the
  13428.                instructions in the "common solutions" section. Also, if you are
  13429.                having difficulty solving a problem yourself, do not hesitate to
  13430.                get in touch with me, as I am always happy to help with any
  13431.                problems. In addition, you may find the other means of OpenDoors
  13432.                support (described latter in this chapter), invaluable in
  13433.                solving difficulties with OpenDoors.
  13434.  
  13435.                Keep in mind that most programs you write will have some "bugs"
  13436.                to begin with, and you should expect to spend at least 50% of
  13437.                any programming project tracing down and solving errors and
  13438.                bugs. While it would be nice if every program written worked
  13439.                correctly the first time, it is a fact of life that debugging is
  13440.                and always has been an important part of the software life-
  13441.                cycle. In fact, what most often separates the good programs from
  13442.                the bad is the amount of time their programmer's spend debugging
  13443.                and improving them. Unfortunately, it is difficult, if not
  13444.                impossible, to come up with a "magic formula" for debugging
  13445.                software. Debugging software is really more of an art than a
  13446.                science. However, there are some basic guidelines, which if
  13447.                followed, can greatly ease the task of software debugging.
  13448.  
  13449. ===============================================================================
  13450. OpenDoors 5.00 Manual                                           End of Page 228
  13451.  
  13452.  
  13453.  
  13454.                As with all problem solving, the secret to software debugging
  13455.                lies in obtaining as much information about the problem as
  13456.                possible. While it is sometimes possible to solve a bug by
  13457.                making intuitive changes in your program, or in re-writing a
  13458.                piece of code to solve the problem by a different means,
  13459.                debugging most often requires more of a "planned attack". This
  13460.                planned attack generally involves little more than learning as
  13461.                much about what is going wrong as possible. The first step in
  13462.                solving a bug usually lies in locating the source of the
  13463.                problem. Once you have located the problem, solving it is often
  13464.                a relatively simple procedure. In locating the source of your
  13465.                bug, the use of a software debugger, such as the one built into
  13466.                the Turbo C(++) / Borland C++ integrated development
  13467.                environment, can be invaluable.
  13468.  
  13469.                When debugging programs written with OpenDoors, you should also
  13470.                follow the steps listed below, in order to obtain more
  13471.                information related to the problem you are trying to solve:
  13472.  
  13473.                1.)  Re-read the section(s) of this manual, your Turbo C(++) /
  13474.                     Borland C++ manuals and your program's source code, which
  13475.                     apply to the problem you are experiencing.
  13476.  
  13477.                2.)  Check the solutions to common problems section below. The
  13478.                     most common problems with OpenDoors can be solved using
  13479.                     this simple chart.
  13480.  
  13481.                3.)  Check the value in the od_errno variable, which will often
  13482.                     provide vital clues as to the source of the problem. Use of
  13483.                     the od_errno variable is described in the section below.
  13484.  
  13485.                4.)  If you are still stuck, please feel more than free to get
  13486.                     in touch with me! (see the end of this chapter for
  13487.                     information on reaching me) I am always more than happy to
  13488.                     help with any OpenDoors or general programming problems!
  13489.  
  13490.  
  13491.  
  13492.  
  13493.  
  13494.  
  13495.  
  13496.  
  13497.  
  13498.  
  13499.  
  13500.  
  13501.  
  13502.  
  13503.  
  13504.  
  13505.  
  13506.  
  13507.  
  13508. ===============================================================================
  13509. OpenDoors 5.00 Manual                                           End of Page 229
  13510.  
  13511.  
  13512.  
  13513.  
  13514.  
  13515.  
  13516. SOLUTIONS TO COMMON PROBLEMS
  13517. -------------------------------------------------------------------------------
  13518.  
  13519.                Below, several common difficulties with OpenDoors are listed,
  13520.                along with suggested solutions to these problems. If you are
  13521.                experiencing any difficulty with a program that you have written
  13522.                with OpenDoors, we would suggest that you read this section
  13523.                thoroughly. Here, the common problem is listed in the left
  13524.                margin, and the solutions listed on the right portion of the
  13525.                page.
  13526.  
  13527.  
  13528. -------------------------------------------------------------------------------
  13529. PROGRAM        1.) Check that the compiler is able to locate the OpenDoors
  13530. WON'T          header file, "OPENDOOR.H". This can be accomplished either by
  13531. COMPILE        placing this header file in the same directory as your other
  13532.                header files (such as STDIO.H, etc.), or by placing the header
  13533.                file in the current directory.
  13534.  
  13535.                2.) Be sure that you are linking your program with the correct
  13536.                library for the memory model you are using. (See the section on
  13537.                compiling with OpenDoors). Also be sure that both the source
  13538.                code file for your program (such as EZVOTE.C) and the library
  13539.                file are listed in your project file, and that the project file
  13540.                is loaded. For more information on compiling programs written
  13541.                with OpenDoors, see page 25.
  13542.  
  13543.                3.) If you have tried the above solutions, and your program
  13544.                still won't compile, then the problem is most likely an error in
  13545.                your source code file. If you are unable to resolve your
  13546.                problem, feel free to get in touch with me.
  13547.  
  13548.  
  13549. -------------------------------------------------------------------------------
  13550. SCREEN         If you are using the od_clr_scr() function to clear the screen,
  13551. WILL NOT       but are not getting any results, this is likely because the user
  13552. CLEAR          online has screen clearing turned off. If you wish to force
  13553.                screen clearing regardless of the user's screen clearing
  13554.                settings (this is probably not a good idea), use the function
  13555.                call od_disp_emu("\xc", TRUE);
  13556.  
  13557.  
  13558. -------------------------------------------------------------------------------
  13559. ALT-J KEY      If you press the Alt-J function key, but do not get any results,
  13560. DOES NOT       your problem is likely as a result of lack of memory. If enough
  13561. WORK           memory is not available to load the command processor (usually
  13562.                COMMAND.COM) when the Alt-J function key is pressed, OpenDoors
  13563.                will automatically return to the door.
  13564.  
  13565.  
  13566.  
  13567. ===============================================================================
  13568. OpenDoors 5.00 Manual                                           End of Page 230
  13569.  
  13570.  
  13571. -------------------------------------------------------------------------------
  13572. FIXUP          This problem was probably caused by a mismatch between your
  13573. OVERFLOW       memory model selection in your compiler, and the memory model
  13574. ERROR          library you are using. See the section on compiling programs
  13575.                with OpenDoors for more information on the correct library you
  13576.                should be using for your memory model selection.
  13577.  
  13578.  
  13579.  
  13580.  
  13581.  
  13582.  
  13583.  
  13584.  
  13585.  
  13586.  
  13587.  
  13588.  
  13589.  
  13590.  
  13591.  
  13592.  
  13593.  
  13594.  
  13595.  
  13596.  
  13597.  
  13598.  
  13599.  
  13600.  
  13601.  
  13602.  
  13603.  
  13604.  
  13605.  
  13606.  
  13607.  
  13608.  
  13609.  
  13610.  
  13611.  
  13612.  
  13613.  
  13614.  
  13615.  
  13616.  
  13617.  
  13618.  
  13619.  
  13620.  
  13621.  
  13622.  
  13623.  
  13624.  
  13625.  
  13626. ===============================================================================
  13627. OpenDoors 5.00 Manual                                           End of Page 231
  13628.  
  13629.  
  13630.  
  13631.  
  13632.  
  13633.  
  13634. OPENDOORS SUPPORT
  13635. -------------------------------------------------------------------------------
  13636.  
  13637.                The powerful and easy to use door toolkit and this comprehensive
  13638.                manual are only two portions of how OpenDoors helps you to write
  13639.                BBS door and similar programs. The third element of OpenDoors is
  13640.                the extensive OpenDoors support mechanisms. The OpenDoors
  13641.                EchoMail conference and support BBS each give you a chance to
  13642.                share ideas and source code with other OpenDoors programmers.
  13643.                You can also receive help learning OpenDoors or solving
  13644.                difficulties from the OpenDoors echo and BBS. In addition to
  13645.                these sources, I am also more than happy to answer any of your
  13646.                questions, or hear any suggestions for future versions of
  13647.                OpenDoors. The remainder of this chapter provides more
  13648.                information on the various sources of OpenDoors support.  Also
  13649.                keep your eyes open for the "OpenDoors Tech Journal", which will
  13650.                soon be available. Included in this newsletter will be
  13651.                information on OpenDoors and future versions, questions and
  13652.                answers about OpenDoors and BBS door / utility programming in
  13653.                general, sample source code, and much more.
  13654.  
  13655.  
  13656.  
  13657.  
  13658. THE OPENDOORS SUPPORT BBS
  13659. -------------------------------------------------------------------------------
  13660.  
  13661.                One of the many means of receiving OpenDoors support is via the
  13662.                OpenDoors BBS. Below is an outline of some of what is available
  13663.                from the OpenDoors BBS:
  13664.  
  13665.                     -   The newest version of this package is always available
  13666.                         for download.
  13667.  
  13668.                     -   Also available for download is example source code and
  13669.                         other files which you may find helpful when writing
  13670.                         programs with OpenDoors.
  13671.  
  13672.                     -   Access to the OpenDoors support conference where
  13673.                         OpenDoors programmers can share ideas, source code, and
  13674.                         receive help with difficulties or with learning
  13675.                         OpenDoors.
  13676.  
  13677.                     -   Get in touch with me with any questions, comments,
  13678.                         suggestions or bug reports.
  13679.  
  13680.                     -   Other files by yours truly, which may be of use in you
  13681.                         programming, such as a registration key system, and so
  13682.                         on.
  13683.  
  13684.  
  13685. ===============================================================================
  13686. OpenDoors 5.00 Manual                                           End of Page 232
  13687.  
  13688.  
  13689.                All users receive full access upon their first call to the
  13690.                OpenDoors BBS. The North American phone number for the support
  13691.                BBS is:
  13692.  
  13693.                                    +1 613 526 4466
  13694.  
  13695.                Note that if you are calling from outside of North America, you
  13696.                may have to add the appropriate long distance routing codes to
  13697.                the phone number. If you are having difficulty getting through
  13698.                to the BBS (ie, you get a BUSY signal), it may be best to try
  13699.                again in ten to twelve hours time. Since the BBS system is
  13700.                sometimes used for beta test purposes, it may be unavailable for
  13701.                several hours at a time. The OpenDoors support BBS also has a
  13702.                FidoNet address, 1:243/8. If you are interested in a list of
  13703.                files available from the support BBS, simply file-request
  13704.                "FILES". To receive the newest version of OpenDoors, you can
  13705.                file-request "ODOORS".
  13706.  
  13707.  
  13708.  
  13709. THE OPENDOORS SUPPORT CONFERENCE
  13710. -------------------------------------------------------------------------------
  13711.  
  13712.                Also available to OpenDoors users who are a member of FidoNet or
  13713.                other EMail networks is the OpenDoors EchoMail support
  13714.                conference (tag-name "OPENDOORS"). The OpenDoors support
  13715.                conference is devoted to OpenDoors and BBS door and utility
  13716.                programming in general. As with the OpenDoors support BBS, this
  13717.                conference gives people programming with OpenDoors a chance to
  13718.                share ideas and source code. It also is a forum for receiving
  13719.                help either learning OpenDoors, or with a specific difficulty.
  13720.                Bug reports, suggestions and information on future versions of
  13721.                OpenDoors is also available in the OpenDoors conference. For
  13722.                more information on the OPENDOORS echo, please feel more than
  13723.                free to get in touch
  13724.                with me.
  13725.  
  13726.  
  13727. GETTING IN TOUCH WITH ME
  13728. -------------------------------------------------------------------------------
  13729.  
  13730.                If you have any questions about OpenDoors, would like help with
  13731.                any programs that your are writing, or have any suggestions for
  13732.                future versions of OpenDoors, please feel free to get in touch
  13733.                with me. You can get in touch with me by any of the following
  13734.                means:
  13735.  
  13736.                -  By calling the OpenDoors support BBS. Information on the
  13737.                   support BBS is provided earlier on in this chapter.
  13738.  
  13739.  
  13740.                -  By electronic mail. My FidoNet NetMail address is:
  13741.  
  13742.                               1:243/8   ***SEE NOTE BELOW***
  13743.  
  13744. ===============================================================================
  13745. OpenDoors 5.00 Manual                                           End of Page 233
  13746.  
  13747.  
  13748.  
  13749.                   My Internet address is:
  13750.  
  13751.                               brian@bpecomm.ocunix.on.ca
  13752.  
  13753.                   My CompuServe ID is:
  13754.  
  13755.                               75122,2303
  13756.  
  13757.                   While I would like to be able to reply to all NetMail
  13758.                   messages by CrashMail, I am afraid I simply can not afford to
  13759.                   do this. So, if you choose to send NetMail, please indicate
  13760.                   whether you would like me to reply by routed NetMail (this
  13761.                   may not work, if routed NetMail is not available in your
  13762.                   area), or to place the message on hold for you to poll and
  13763.                   pick up.
  13764.  
  13765.  
  13766.                -  By writing a message to me in the OpenDoors support EchoMail
  13767.                   conference. For more information on the OPENDOORS echo, see
  13768.                   the previous section of this chapter.
  13769.  
  13770.  
  13771.                -  By conventional mail. My postal address is:
  13772.  
  13773.                               Brian Pirie
  13774.                               Apt. 1416 - 2201 Riverside Dr.
  13775.                               Ottawa, Ontario
  13776.                               Canada
  13777.                               K1H 8K9
  13778.  
  13779.  
  13780.                I try to respond to all correspondences as soon as possible.
  13781.                However, it is possible that it may take slightly longer to
  13782.                reply to your message, if you are asking a question that
  13783.                requires time for me to get an answer, or if I happen to be away
  13784.                for a few days.
  13785.  
  13786.                If you are having some sort of difficulty with OpenDoors, the
  13787.                more detailed information you supply (such as source code to the
  13788.                program that is causing the problem, how to duplicate the
  13789.                problem, and so on), the more quickly I will be able to
  13790.                determine the source of your problem. Also, before you write
  13791.                about a problem with OpenDoors, you may wish to be sure that you
  13792.                have read and followed the instructions in the section on
  13793.                troubleshooting, found on page 228. While I do not mind taking
  13794.                the time to answer any questions related to OpenDoors, you may
  13795.                be able to save yourself the time of writing and waiting for a
  13796.                response - simply by following the instructions in the
  13797.                troubleshooting section. More often than not, the answer to
  13798.                questions I receive is already in this manual.
  13799.  
  13800.                If you have suggestions for enhancements or additions for future
  13801.                versions of OpenDoors, and are sending your suggestions by
  13802.  
  13803. ===============================================================================
  13804. OpenDoors 5.00 Manual                                           End of Page 234
  13805.  
  13806.  
  13807.                conventional mail, it would be easiest for me if you sent your
  13808.                suggestions on the suggestion form, located on page 21. If you
  13809.                have a BBS system, for which you would like to see support
  13810.                added, and either have the technical information on that BBSes
  13811.                structures, or know where I could get this information, please
  13812.                let me know.
  13813.  
  13814.  
  13815.  
  13816.  
  13817.  
  13818.  
  13819.  
  13820.  
  13821.  
  13822.  
  13823.  
  13824.  
  13825.  
  13826.  
  13827.  
  13828.  
  13829.  
  13830.  
  13831.  
  13832.  
  13833.  
  13834.  
  13835.  
  13836.  
  13837.  
  13838.  
  13839.  
  13840.  
  13841.  
  13842.  
  13843.  
  13844.  
  13845.  
  13846.  
  13847.  
  13848.  
  13849.  
  13850.  
  13851.  
  13852.  
  13853.  
  13854.  
  13855.  
  13856.  
  13857.  
  13858.  
  13859.  
  13860.  
  13861.  
  13862. ===============================================================================
  13863. OpenDoors 5.00 Manual                                           End of Page 235
  13864.  
  13865.  
  13866. -------------------------------------------------------------------------------
  13867. APPENDIX A - CONTENTS OF PACKAGE
  13868. -------------------------------------------------------------------------------
  13869.  
  13870.  
  13871.  
  13872.  
  13873.                OpenDoors is usually distributed in the form of a single,
  13874.                compressed archive file. Thus, you should have received this
  13875.                version of OpenDoors in a file whose name began with ODOORS40.
  13876.                The files listed below should be included in your OpenDoors
  13877.                package. If any of these files are missing, you will probably
  13878.                want to look for the most recent version of OpenDoors from
  13879.                another source.
  13880.  
  13881.                Each file contains the same date and time. The time listed in a
  13882.                file's directory entry represents the version number it belongs
  13883.                to, and it's date is the date of that version's release. Hence,
  13884.                a file with a time of 4:00 is part of OpenDoors 4.00. This is
  13885.                intended to help in distinguishing between a file that is part
  13886.                of the current version of OpenDoors, and one that is part of an
  13887.                older version.
  13888.  
  13889.                MISCALENEOUS FILES
  13890.                     FILE_ID.DIZ    Description of the OpenDoors package
  13891.                     DORINFO1.DEF   Sample door info file for testing doors
  13892.                     DOOR.CFG       Sample OpenDoors configuration file
  13893.  
  13894.                EXAMPLE PROGRAMS
  13895.                     EX_HELLO.C     Demonstrates how simple a door can be
  13896.                     EX_CHAT.C      Split-screen sysop chat program
  13897.                     EX_MUSIC.C     Example of ANSI music in OpenDoors
  13898.                     EX_SKI.C       Simple slalom skiing action game
  13899.                     EX_VOTE1.C     Steps in building EZVote polling program
  13900.                     EX_VOTE2.C               "                 "
  13901.                     EX_VOTE3.C               "                 "
  13902.                     EX_VOTE4.C               "                 "
  13903.                     EX_VOTE5.C               "                 "
  13904.                     EZVOTE.EXE     Compiled version of EX_VOTE5.C
  13905.  
  13906.                THE LIBRARY FILES
  13907.                     ODOORS.LIB     Small memory model library
  13908.                     ODOORM.LIB     Medium memory model library
  13909.                     ODOORL.LIB     Large memory model library
  13910.                     ODOORH.LIB     Huge memory model library
  13911.  
  13912.                THE HEADER FILE
  13913.                     OPENDOOR.H     OpenDoors #include .Header file
  13914.  
  13915.                OPENDOORS DOCUMENATION
  13916.                     ORDER.FRM      Easy-to-print order form
  13917.                     OPENDOOR.TXT   OpenDoors programmer's manual; this file
  13918.  
  13919.  
  13920.  
  13921. ===============================================================================
  13922. OpenDoors 5.00 Manual                                           End of Page 236
  13923.  
  13924.  
  13925. -------------------------------------------------------------------------------
  13926. APPENDIX B - CHANGES FOR THIS VERSION
  13927. -------------------------------------------------------------------------------
  13928.  
  13929.  
  13930.  
  13931.  
  13932.                Below is a list of enhancements and changes between OpenDoors
  13933.                4.10 and OpenDoors 5.00. A File containing a complete history of
  13934.                OpenDoors is available for download from the OpenDoors support
  13935.                BBS (see page 232).
  13936.  
  13937.                Version 5.00 represents several major steps forward for
  13938.                OpenDoors. In addition to numerous bug fixes and minor
  13939.                improvements, a number of major new features have been added to
  13940.                this version. These include an optional multiple personality
  13941.                system which allow the sysop to choose the status line and
  13942.                function key style they prefer. This version also adds text-mode
  13943.                support for RIP (Remote Imaging Protocol) graphics, and adds a
  13944.                group of advanced ANSI/AVATAR/RIP functions for scrolling areas
  13945.                of the screen, saving and restoring portions of the screen and
  13946.                creating pop-up windows and menus. Also new in this version is
  13947.                support for compilers other than Borland/Turbo C(++), such as
  13948.                compilers from Microsoft. Version 5.00 also adds built-in
  13949.                communications support, making the use of a FOSSIL driver
  13950.                optional. Furthermore, direct support for additional BBS systems
  13951.                has been added. The list below provides more detail of the
  13952.                changes and new features in version 5.00:
  13953.  
  13954.                     - The nonstop key ([=]) now works correctly during
  13955.                       FILES.BBS listing.
  13956.  
  13957.                     - New door information file formats now supported include:
  13958.                       RA 2.00 EXITINFO.BBS.
  13959.  
  13960.                     - If the TASK environment variable is set, OpenDoors will
  13961.                       now use its value to determine the current node number.
  13962.  
  13963.                     - The od_control.od_spawn_freeze_time variable now works
  13964.                       correctly. Previously, the user's time would always be
  13965.                       frozen during od_spawn...() execution, regardless of the
  13966.                       value of this variable.
  13967.  
  13968.                     - A new feature known as the "Multiple Personality System"
  13969.                       has been added to this version. If you choose to include
  13970.                       the Multiple Personality System in a door, the sysop will
  13971.                       be able to specify which of a number of "personalities"
  13972.                       should be used. Each personality defines the statusline
  13973.                       appearance and function keys seen by the sysop, and has
  13974.                       no effect on the door's operation from the user's
  13975.                       standpoint. OpenDoors 5.00 includes personality
  13976.                       definitions for WildCat, RemoteAccess, PC-Board, and it's
  13977.                       own simplified RA style status lines. You can also define
  13978.                       your own personalities by writing a personality
  13979.  
  13980. ===============================================================================
  13981. OpenDoors 5.00 Manual                                           End of Page 237
  13982.  
  13983.  
  13984.                       definition function. If your choose not to include the
  13985.                       Multiple Personality System in a door, you will still be
  13986.                       able to define which single personality you wish
  13987.                       OpenDoors to use.
  13988.  
  13989.                     - This version of OpenDoors can be used with a larger
  13990.                       variety of compilers than where supported by the previous
  13991.                       version. OpenDoors 5.00 is known to work with all
  13992.                       versions of Turbo C, Turbo C++, Borland C++, Microsoft C,
  13993.                       Microsoft C++, Quick C and Visual C++. It should also
  13994.                       work with any other MS-DOS based ANSI C compiler that
  13995.                       supports the Microsoft/DOS .OBJect and .LIBrary file
  13996.                       formats.
  13997.  
  13998.                     - A new diagnostics feature has been added to OpenDoors,
  13999.                       which allows you to determine the reason for the most
  14000.                       recent OpenDoors function failure. When any OpenDoors
  14001.                       function returns a failure condition, it also sets the
  14002.                       new od_control.od_error variable to indicate the reason
  14003.                       for the failure.
  14004.  
  14005.                     - Added additional definitions to OPENDOOR.H, to map names
  14006.                       of OpenDoors functions and variables with the word
  14007.                       "colour" from the U.S. spelling "color". In other words,
  14008.                       both od_set_colour() and od_set_color() are now
  14009.                       recognized by OpenDoors.
  14010.  
  14011.                     - The od_list_files() now supports more intelligent path
  14012.                       specifications. If the parameter to od_list_files() is
  14013.                       NULL or empty, it will search for a FILES.BBS file in the
  14014.                       current directory. If a directory path is specified, it
  14015.                       will look for a FILES.BBS in that directory. If a full
  14016.                       directory and filename are specified, the specified
  14017.                       filename will be used in place of FILES.BBS.
  14018.  
  14019.                     - To save space, the compact memory model library is no
  14020.                       longer included in the normal OpenDoors package. The
  14021.                       compact memory model library is now available seperately.
  14022.  
  14023.                     - A new function, od_set_dtr(), has been added to allow the
  14024.                       DTR line to the modem to be manually controlled. This can
  14025.                       be useful in writing programs where you wish to force the
  14026.                       modem to hangup, such as a call-back verification door.
  14027.  
  14028.                     - Added additional support for various DOS multitasking
  14029.                       environments. OpenDoors is now specifically Microsoft
  14030.                       Windows aware. OpenDoors also now gives up time to other
  14031.                       waiting tasks when it is idle during chat mode.
  14032.  
  14033.                     - The od_edit_str() "M" mode now capitializes a character
  14034.                       following a dash '-' character.
  14035.  
  14036.                     - When transmitting more than one character at a time,
  14037.                       OpenDoors now uses the FOSSIL trasfer block function,
  14038.  
  14039. ===============================================================================
  14040. OpenDoors 5.00 Manual                                           End of Page 238
  14041.  
  14042.  
  14043.                       instead of multiple calls to the transfer character
  14044.                       function. This should help to improve performance over
  14045.                       high speed connections when running on slow PCs or under
  14046.                       multitasking environments.
  14047.  
  14048.                     - OpenDoors 4.10 would not correctly change the display
  14049.                       colour from high-intensity back to low-intensity. This
  14050.                       problem has been fixed.
  14051.  
  14052.                     - OpenDoors now recognizes DORINFO?.DEF filenames with
  14053.                       alphabetical identifiers (ie, DORINFOA.DEF thru
  14054.                       DORINFOZ.DEF) for nodes 10 thru 35.
  14055.  
  14056.                     - Improvements have been made to the logfile system. An
  14057.                       exit at errorlevel zero no longer causes garbage to be
  14058.                       written to the logfile. The logfile functions have been
  14059.                       made more reliable when operating under low stack
  14060.                       availability conditions. In the past, if a large number
  14061.                       of local variables where allocated on the stack, the
  14062.                       logfile functions would fail, often writing garbage to
  14063.                       the logfile. When the user pages the sysop for chat, the
  14064.                       user's reason for wishing a chat is also written to the
  14065.                       logfile.
  14066.  
  14067.                     - Support for text-mode RIP (Remote Imaging Protocol)
  14068.                       graphics has been added. Because this version of
  14069.                       OpenDoors always operates in DOS text-mode, none of the
  14070.                       graphics mode RIP features (such as drawing lines,
  14071.                       circles and displaying icons) will appear on the local
  14072.                       screen. Plans for a version of OpenDoors that will
  14073.                       operate in graphics mode and optionally display graphics
  14074.                       locally are currently under consideration. In this
  14075.                       version, RIP support includes a number of new features.
  14076.                       OpenDoors will now recognize the RIP setting passed in an
  14077.                       RA 2.00 EXITINFO.BBS file and WildCat DOOR.SYS file, and
  14078.                       also allows the RIP setting to be specified in a custom
  14079.                       door information file. The od_send_file() and
  14080.                       od_hotkey_menu() functions will now search for files with
  14081.                       .RIP, .AVT, .ANS and .ASC extensions. When displaying RIP
  14082.                       graphics to the remote user, a pop-up window appears on
  14083.                       the local screen, indicating to the sysop which file is
  14084.                       being displayed.
  14085.  
  14086.                     - A set of new functions have been added to permit advanced
  14087.                       screen manipulations. These functions include
  14088.                       od_gettext() and od_puttext() to save and restore
  14089.                       portions of the screen, and od_save_screen() and
  14090.                       od_restore_screen() to save and restore the entire
  14091.                       screen. od_scroll() can be used to scroll any portion of
  14092.                       the screen upwards or downwards. od_save_screen() and
  14093.                       od_restore_screen() will operate in any mode, but the
  14094.                       other functions require ANSI/AVATAR/RIP mode to be
  14095.                       available.
  14096.  
  14097.  
  14098. ===============================================================================
  14099. OpenDoors 5.00 Manual                                           End of Page 239
  14100.  
  14101.  
  14102.                     - Three additional functions, od_window_create(),
  14103.                       od_window_remove() and od_popup_menu(), have been added
  14104.                       to facilitate the creation of popup windows and menus.
  14105.                       When such a window or menu is removed from the screen,
  14106.                       the are of the screen "under" the window is returned to
  14107.                       it's original state. This allows you to create multiple
  14108.                       overlapping windows within a door program. The
  14109.                       od_popup_menu() function creates a popup window with a
  14110.                       menu from a simple menu definition string. The user can
  14111.                       select an option from this menu by pressing the key
  14112.                       associated with an option, or by moving a menu selection
  14113.                       bar using their arrow keys. These three functions require
  14114.                       an ANSI/AVATAR/RIP mode to be available.
  14115.  
  14116.                     - A new function, od_chat() has been added, to allow you to
  14117.                       explicitly invoke the OpenDoors chat mode from within
  14118.                       your program.
  14119.  
  14120.                     - A new setting variable, od_control.od_always_clear has
  14121.                       been added. When set to TRUE, od_clr_scr() will always
  14122.                       clear the screen, regardless of the user's screen
  14123.                       clearing setting. When set to FALE, od_clr_scr() will
  14124.                       only clear the screen if the user has screen clearing
  14125.                       enabled.
  14126.  
  14127.                     - It is now possible to configure the errorlevels OpenDoors
  14128.                       exits with under various circumstances, such as when the
  14129.                       user runs out of time remaining online. See the
  14130.                       od_control.od_errorlevel variable
  14131.  
  14132.                     - A new setting variable, od_control.od_force_local, can be
  14133.                       used to easily force OpenDoors to operate in local mode.
  14134.                       Using this variable you can easily add a command line
  14135.                       parameter such as "-local" to allow the sysop to force
  14136.                       your door to operate in local mode. When OpenDoors is
  14137.                       forced into local mode using this variable, it does not
  14138.                       look for a door information file, and uses default
  14139.                       settings for the user's name, etc.
  14140.  
  14141.                     - OPENDOOR.H now sets structure packing to single byte
  14142.                       alignment for the od_control structure when Borland and
  14143.                       Microsoft compilers are being used. In the past,
  14144.                       programmers using OpenDoors have experienced difficulties
  14145.                       the od_control structure when the compiler has been set
  14146.                       to use word packing.
  14147.  
  14148.                     - OpenDoors now closes the FOSSIL driver prior to
  14149.                       performing a spawn or sysop DOS shell. This allows doors
  14150.                       or other communications programs which use the FOSSIL
  14151.                       driver to be executed while the door's execution is
  14152.                       suspended.
  14153.  
  14154.                     - When used with a FOSSIL driver, OpenDoors normally
  14155.                       changes the BPS rate to that passed from the BBS (if the
  14156.  
  14157. ===============================================================================
  14158. OpenDoors 5.00 Manual                                           End of Page 240
  14159.  
  14160.  
  14161.                       BBS passes a valid FOSSIL BPS rate). This BPS rate
  14162.                       setting may now be disabled by setting the
  14163.                       DIS_BPS_SETTING bit of the od_control.od_disable
  14164.                       variable.
  14165.  
  14166.                     - A function hook has been added to allow you to install a
  14167.                       function to be called whenever od_kernel() executes
  14168.                       (od_control.od_ker_exec). Another function hook,
  14169.                       od_control.od_time_msg_func, can be installed to override
  14170.                       OpenDoor's time limit warning messages.
  14171.  
  14172.                     - A new array, od_control.od_hot_function, allows the you
  14173.                       to define functions to be called when any of the
  14174.                       programmer-defined sysop hotkeys have been pressed.
  14175.  
  14176.                     - A function hook, od_control.od_no_file_func, has been
  14177.                       added. This function will be called whenever OpenDoors is
  14178.                       unable to find or read a door information file. This
  14179.                       allows you to add your own door information file reader,
  14180.                       or to provide a local login prompt when no door
  14181.                       information file is present.
  14182.  
  14183.                     - Previously, OpenDoors would stop correctly updating the
  14184.                       user's remaining time at midnight when running under
  14185.                       certain BIOSes. This problem has been fixed.
  14186.  
  14187.                     - The current display colour attribute can now be accessed
  14188.                       through an control structure member,
  14189.                       od_control.od_cur_attrib.
  14190.  
  14191.                     - od_send_file() and od_hotkey_menu() no longer pause with
  14192.                       a "Continue?" prompt prematurely in files that have line
  14193.                       lengths greater than 254 characters.
  14194.  
  14195.                     - The local keyboard may now be disabled by setting the
  14196.                       DIS_LOCAL_INPUT bit of od_control.od_disable. This only
  14197.                       affects the sysop's input in circumstances that input is
  14198.                       also accepted from the remote user; this setting has no
  14199.                       effect on the sysop function keys.
  14200.  
  14201.                       A new function hook:                      -
  14202.  
  14203.                          void (*od_control.od_local_input)(int);
  14204.  
  14205.                       has been added. If set, this function will be called
  14206.                       whenever the sysop presses a non-sysop-function key on
  14207.                       the local keyboard.
  14208.  
  14209.                     - od_control.od_clear_on_exit now controls whether the
  14210.                       screen is cleared before shelling or executing
  14211.                       od_spawn...(), in addition to before OpenDoors shuts
  14212.                       down.
  14213.  
  14214.  
  14215.  
  14216. ===============================================================================
  14217. OpenDoors 5.00 Manual                                           End of Page 241
  14218.  
  14219.  
  14220.                     - od_page() now restores the original display colour before
  14221.                       returning.
  14222.  
  14223.                     - It is now possible to display an entire string of
  14224.                       characters with terminal emulation, using the new
  14225.                       function od_disp_emu().
  14226.  
  14227.                     - OpenDoors will now display a small popup window when
  14228.                       disconnecting the current connection.
  14229.  
  14230.                     - A new variable, od_control.od_in_buf_size, can now be set
  14231.                       prior to calling any OpenDoors function to set the size
  14232.                       of OpenDoors combined local/remote keyboard input buffer.
  14233.                       By default, this buffer is 256 bytes in size.
  14234.  
  14235.                     - Previously, there were a number of OpenDoors API
  14236.                       functions that would not correctly initialize OpenDoors
  14237.                       if they were the first function called in the program.
  14238.                       This has been fixed.
  14239.  
  14240.                     - To facilitate setting of bps rates up to 115,200,
  14241.                       od_control.baud is now an unsigned long.
  14242.  
  14243.                     - A new setting, od_control.od_no_ra_codes, has been added
  14244.                       to disable the use of RemoteAccess/QuickBBS control codes
  14245.                       by od_send_file()/od_hotkey_menu()/od_disp_emu(). The
  14246.                       RemoteAccess/QuickBBS ASCII 1 "pause for key" is also now
  14247.                       recognized.
  14248.  
  14249.  
  14250.  
  14251.  
  14252.  
  14253.  
  14254.  
  14255.  
  14256.  
  14257.  
  14258.  
  14259.  
  14260.  
  14261.  
  14262.  
  14263.  
  14264.  
  14265.  
  14266.  
  14267.  
  14268.  
  14269.  
  14270.  
  14271.  
  14272.  
  14273.  
  14274.  
  14275. ===============================================================================
  14276. OpenDoors 5.00 Manual                                           End of Page 242
  14277.  
  14278.  
  14279. -------------------------------------------------------------------------------
  14280. APPENDIX C - FUTURE VERSIONS
  14281. -------------------------------------------------------------------------------
  14282.  
  14283.  
  14284.  
  14285.  
  14286.                While I cannot make any promises about what features and changes
  14287.                will be seen in future versions of OpenDoors, I would like to
  14288.                take a moment to tell you a bit about some of the features you
  14289.                can expect to see in future versions of OpenDoors
  14290.  
  14291.                As you are probably already aware, OpenDoors is a constantly
  14292.                evolving package. To help meet the needs of programmers working
  14293.                with OpenDoors, nearly every idea and change that is made to the
  14294.                package results from the suggestions and comments I receive from
  14295.                the people using OpenDoors. For this reason, I will most likely
  14296.                continue to produce new versions of OpenDoors for as long as
  14297.                there is a demand and ideas for upgrades. There certainly is no
  14298.                shortage of either of this right now.
  14299.  
  14300.                Some of the features that are currently in the works for
  14301.                upcoming versions of OpenDoors include:
  14302.  
  14303.                     - Support for additional programming
  14304.                       operating systems.
  14305.  
  14306.                     - Additional RIP graphics support, including display of RIP
  14307.                       images on local screen.
  14308.  
  14309.                     - A built-in automatic ANSI/high-ASCII to plain-ASCII
  14310.                       conversion system.
  14311.  
  14312.                     - More advanced ANSI/AVATAR terminal routines, such as
  14313.                       screen save and restore, window scrolling, and more.
  14314.  
  14315.                     - Direct interfacing with more BBS systems, including
  14316.                       Maximus direct interfacing.
  14317.  
  14318.                     - AVATAR compression.
  14319.  
  14320.                     - Built-in ANSI music support, including optional local
  14321.                       sound.
  14322.  
  14323.                     - Improvements to existing OpenDoors features, such as more
  14324.                       configuration file options, multiple log file formats,
  14325.                       and many smaller changes.
  14326.  
  14327.                     - Since the user's time remaining field is not consistently
  14328.                       written to the EXITINFO.BBS file (some packages write the
  14329.                       actual time remaining, while others write the users total
  14330.                       time limit for the connection, to this field), OpenDoors
  14331.                       now reads this information from the DORINFOx.DEF file
  14332.  
  14333.  
  14334. ===============================================================================
  14335. OpenDoors 5.00 Manual                                           End of Page 243
  14336.  
  14337.  
  14338.                       that must also always be present when an EXITINFO.BBS is
  14339.                       used.
  14340.  
  14341.  
  14342.  
  14343.  
  14344.  
  14345.  
  14346.  
  14347.  
  14348.  
  14349.  
  14350.  
  14351.  
  14352.  
  14353.  
  14354.  
  14355.  
  14356.  
  14357.  
  14358.  
  14359.  
  14360.  
  14361.  
  14362.  
  14363.  
  14364.  
  14365.  
  14366.  
  14367.  
  14368.  
  14369.  
  14370.  
  14371.  
  14372.  
  14373.  
  14374.  
  14375.  
  14376.  
  14377.  
  14378.  
  14379.  
  14380.  
  14381.  
  14382.  
  14383.  
  14384.  
  14385.  
  14386.  
  14387.  
  14388.  
  14389.  
  14390.  
  14391.  
  14392.  
  14393. ===============================================================================
  14394. OpenDoors 5.00 Manual                                           End of Page 244
  14395.  
  14396.  
  14397. -------------------------------------------------------------------------------
  14398. APPENDIX D - SPECIAL THANKS
  14399. -------------------------------------------------------------------------------
  14400.  
  14401.  
  14402.  
  14403.  
  14404.                There are a great many people who I would like to thank, for
  14405.                their suggestions, ideas and assistance in making OpenDoors what
  14406.                it is today. In a way, I feel somewhat reluctant to list people
  14407.                names, as I will no doubt forget someone important. Among those
  14408.                I would like to thank are:
  14409.  
  14410.                     - Everyone who has taken the time to register OpenDoors
  14411.  
  14412.                     - All those who participate in the OpenDoors conference,
  14413.                       who provide many suggestions, bug reports and words of
  14414.                       encouragement.
  14415.  
  14416.                     - In particular I would like to thank the following people
  14417.                       for their devotion of time, in the form of suggestions,
  14418.                       bug reports, sending information, etc.:
  14419.  
  14420.                               Ron Bergeron
  14421.                               Scott Burkett
  14422.                               Joel Downer
  14423.                               Mike Hartmann
  14424.                               Winfried Hirsch
  14425.                               Robert La Ferte
  14426.                               Ron Le Blanc
  14427.                               Bill Meck
  14428.                               Bill Pavich
  14429.                               Mark Williamson
  14430.  
  14431.  
  14432.  
  14433.  
  14434.  
  14435.  
  14436.  
  14437.  
  14438.  
  14439.  
  14440.  
  14441.  
  14442.  
  14443.  
  14444.  
  14445.  
  14446.  
  14447.  
  14448.  
  14449.  
  14450.  
  14451.  
  14452. ===============================================================================
  14453. OpenDoors 5.00 Manual                                           End of Page 245
  14454.  
  14455.  
  14456. -------------------------------------------------------------------------------
  14457. GLOSSARY
  14458. -------------------------------------------------------------------------------
  14459.  
  14460. ANSI           "ANSI", often referred to as "ANSI Graphics", is a display
  14461.                protocol which allows (in this case), BBS software to perform
  14462.                certain display functions such as changing the colour of
  14463.                displayed text, or moving the location of the cursor on the
  14464.                screen. The majority, though not all, BBS users use terminal
  14465.                software with ANSI graphics capabilities. Any users that do not
  14466.                have graphics display capabilities, will be using ASCII mode,
  14467.                instead. Compare ASCII and AVATAR.
  14468.  
  14469.  
  14470. ASCII          ASCII (pronounced "ass-key") is an acronym for "American
  14471.                Standard Code for Information Interchange", and is a definition
  14472.                of a set of 128 letters, number and symbols, which can be
  14473.                displayed by computer systems. Also, when used within the domain
  14474.                of BBS software, ASCII mode is often used to refer to the lack
  14475.                of any graphics display capabilities, such as ANSI or AVATAR.
  14476.                When ASCII mode is used, characters can only be displayed in
  14477.                standard Teletype fashion, one after another. Also, colour and
  14478.                cursor positioning functions are not available in ASCII mode.
  14479.                Compare ANSI and AVATAR.
  14480.  
  14481.  
  14482. AVATAR         AVATAR is an acronym for "Advanced Video Attribute Terminal
  14483.                Assembler and Recreator". AVATAR is a graphics display protocol,
  14484.                similar to ANSI. Like ANSI-graphics, AVATAR graphics allow
  14485.                functions such as cursor positioning, and colour changing.
  14486.                However, AVATAR also offers many capabilities not available from
  14487.                ANSI, and performs the same functions as ANSI much more quickly.
  14488.                AVATAR graphics is less common than both ANSI or ASCII, but is
  14489.                becoming more popular as time goes by. Compare ASCII and ANSI.
  14490.  
  14491.  
  14492. BAUD           For our purposes, the term "baud" or "baud rate" refers to the
  14493.                speed at which data is being sent from one computer to another
  14494.                over a modem. Sometimes referred to as "BPS".
  14495.  
  14496.  
  14497. BIT-MAPPED     As with Boolean values, described below, bit mapped flags
  14498. FLAGS          are used to indicate whether or not various conditions exist.
  14499.                (For example, whether or not a certain setting is enabled, or
  14500.                whether or not a particular event has occurred.) However, unlike
  14501.                Boolean variables, a single bit-mapped flag represents more than
  14502.                one of these TRUE/FALSE values. In fact, each bit (BInary
  14503.                Digit), which makes of the variable can be used to represent a
  14504.                separate TRUE/FALSE state. (ie, each bit maps to a particular
  14505.                piece of information, and hence the term "Bit Map").
  14506.  
  14507.                For an example of using bit-mapped flags, let us take a case of
  14508.                a single "unsigned char" which contains three independent
  14509.                TRUE/FALSE values. We will call this variable user_info, and it
  14510.  
  14511. ===============================================================================
  14512. OpenDoors 5.00 Manual                                           End of Page 246
  14513.  
  14514.  
  14515.                will indicate whether or not a user has ANSI graphics, whether
  14516.                or not the user has screen clearing turned on, and whether or
  14517.                not the user has end-of-page "more" prompts enabled. Internally,
  14518.                the bits of the user_info variable will be as follows:
  14519.  
  14520.                      Bit:  7 6 5 4 3 2 1 0
  14521.                                      | | |
  14522.                                      | | +--- ANSI Graphics
  14523.                                      | +----- Screen Clearing
  14524.                                      +------- More prompts
  14525.  
  14526.                In this case, we will have three constants which we define in
  14527.                order to simplify access to these bit-mapped flags, as follows:
  14528.  
  14529.                      #define ANSI_GRAPHICS        0x01
  14530.                      #define SCREEN_CLEARING      0x02
  14531.                      #define MORE_PROMPTS         0x04
  14532.  
  14533.                Note that normally within OpenDoors, these constants will be
  14534.                defined for you, and you will have no need to know what their
  14535.                values are, nor in which bit which piece of information is
  14536.                stored.
  14537.  
  14538.                Using bit-mapped flags, you are able to set or clear any of the
  14539.                individual flags, and check whether any of the flags are set,
  14540.                using these simple methods: (Not that a set flag is the
  14541.                equivalent of a Boolean value of "True", and a cleared flag is
  14542.                the equivalent of a Boolean value of "False".)
  14543.  
  14544.                     Set Flag:      variable |= FLAG_CONSTANT;
  14545.                     Clear Flag:    variable &=~ FLAG_CONSTANT;
  14546.                     Test Flag:     variable & FLAG_CONSTANT
  14547.  
  14548.                Where "variable" is the name of the bit-mapped flag variable,
  14549.                and "FLAG_CONSTANT" is the pre-defined constant for the
  14550.                individual setting. To return to our example, you could turn on
  14551.                the user's ANSI graphics setting by using the line:
  14552.  
  14553.                     user_info |= ANSI_GRAPHICS;
  14554.  
  14555.                and to turn off screen clearing you would:
  14556.  
  14557.                     user_info &=~ ANSI_GRAPHICS;
  14558.  
  14559.                To perform an action (such as waiting for the user to press
  14560.                [Return]/[Enter]) only if "More" prompts are enabled, you would:
  14561.  
  14562.                     if(user_info & MORE_PROMPTS)
  14563.                          {
  14564.                          ...            /* Whatever you want */
  14565.                          }
  14566.  
  14567.  
  14568.  
  14569.  
  14570. ===============================================================================
  14571. OpenDoors 5.00 Manual                                           End of Page 247
  14572.  
  14573.  
  14574. BOOLEAN        Many of the variables used within OpenDoors contain a
  14575. VALUES         "Boolean Value". A Boolean value is a two-state variable, who's
  14576.                states are referred to as "True" and "False'. If the variable
  14577.                contains a value of "True", it indicates that a certain
  14578.                condition is so, and if it contains a value of "False", it
  14579.                indicates that the condition is not so. For example, a Boolean
  14580.                variable "wait" might be used to indicate whether or not
  14581.                OpenDoors should wait for the user to press a key, or continue
  14582.                without waiting. In this case, a value of "True" would indicate
  14583.                that OpenDoors should wait, and a value of "False" would
  14584.                indicate that it should not wait.
  14585.  
  14586.                Note that in the C programming language, there is no actual
  14587.                Boolean variable type - usually a char or an int are used to
  14588.                store Boolean values.
  14589.  
  14590.                The constants TRUE and FALSE, as defined in the OPENDOOR.H file,
  14591.                are used to represent the two states of a Boolean value. Thus,
  14592.                to set a Boolean variable "wait" to the value of "True", you
  14593.                would use this line:
  14594.  
  14595.                          wait=TRUE;
  14596.  
  14597.                and to set the variable "wait" to "False", you would:
  14598.  
  14599.                          wait=FALSE;
  14600.  
  14601.                However, you SHOULD NOT test whether a Boolean variable is
  14602.                "True" or "False" by using the C compare (==) operator, as the
  14603.                value "True" will not always be the same numerical value.
  14604.                (Actually, the TRUE constant represents just one of many
  14605.                possible numerical values for "True"). Instead, to perform an
  14606.                action of the "wait" Boolean variable is "True", you would:
  14607.  
  14608.                          if(wait)
  14609.                               {
  14610.                               ...        /* Whatever you want */
  14611.                               }
  14612.  
  14613.                and to perform an action if the "wait" Boolean variable is
  14614.                "False', you would:
  14615.  
  14616.                          if(!wait)
  14617.                               {
  14618.                               ...       /* Whatever you want */
  14619.                               }
  14620.  
  14621.                For interest sake, Boolean values are named after the 19th
  14622.                century English mathematician, who studied formal logic, and
  14623.                created Boolean algebra - an algebra which deals with TRUE and
  14624.                FALSE values.
  14625.  
  14626.  
  14627.  
  14628.  
  14629. ===============================================================================
  14630. OpenDoors 5.00 Manual                                           End of Page 248
  14631.  
  14632.  
  14633. BPS            BPS is an acronym for "Bits Per Second". For our purposes here,
  14634.                the terms BPS and BAUD refer to the same thing.
  14635.  
  14636.  
  14637. CARRIER        The term "Carrier" or "Carrier Detect" refers to a signal which
  14638. DETECT         most modems send to the computer, which indicates whether or not
  14639.                the modem is currently connected to (communicating with) another
  14640.                modem. The door driver module of OpenDoors, as with most other
  14641.                BBS software, uses the status of this carrier detect signal in
  14642.                order to know whether the user is still connected to the BBS
  14643.                computer. Thus, if the user hangs up, or if something goes wrong
  14644.                and the connection is lost, OpenDoors is able to detect this
  14645.                state, and exit to the BBS. The BBS will then also detect that
  14646.                the carrier signal has been "lost", and will reset itself, and
  14647.                then again be ready to accept calls.
  14648.  
  14649.  
  14650. CHAT MODE      The term "chat mode" refers to a means by which the sysop can
  14651.                communicate with a user of the BBS / door. During sysop chat,
  14652.                anything typed by the sysop will appear on the user's screen,
  14653.                and likewise, anything typed by the user will appear on the
  14654.                sysop's screen. Sysop chatting is available on both single and
  14655.                multi-line systems. Sysop chatting is initiated by the sysop,
  14656.                either at any time a user is online, or specifically in response
  14657.                to a sysop page.
  14658.  
  14659.  
  14660. DOOR           A "door" is a program that runs as part of a BBS system, but
  14661.                which is separate from the central BBS software (RemoteAccess,
  14662.                Maximus, QuickBBS, PC-Board, etc.) itself. A door provides
  14663.                additional features not built into the BBS software, such as on-
  14664.                line games, on-line shopping services, voting booths, match
  14665.                making systems, access to special files or messages, and much
  14666.                much more. Since the user also communicates with the door
  14667.                online, as they do with the BBS, it may not necessarily be
  14668.                obvious to the user that the door is even a separate entity from
  14669.                the central BBS software itself.
  14670.  
  14671.  
  14672. DOOR           Also referred to as a "drop file", "exit file", or "chain
  14673. INFORMATION    file". The door information file is a file passed from the
  14674. FILE           central BBS software to a door program, providing it with
  14675.                information about the user who is online, the BBS the door is
  14676.                running under, and the current modem connection. The door
  14677.                information file may also be used to pass changed information
  14678.                back to the BBS, such as the amount of time that the user has
  14679.                used in the door. OpenDoors takes care of all of the work
  14680.                involved in reading and writing the door information file for
  14681.                you, as described in the "Basics of Door Programming" section,
  14682.                in chapter 4. Examples of door information files supported by
  14683.                OpenDoors include: DOOR.SYS, EXITINFO.BBS, DORINFO?.DAT,
  14684.                SFDOORS.DAT, CALLINFO.BBS and CHAIN.TXT.
  14685.  
  14686.  
  14687.  
  14688. ===============================================================================
  14689. OpenDoors 5.00 Manual                                           End of Page 249
  14690.  
  14691.  
  14692. ECHO           See "Local Echo".
  14693.  
  14694.  
  14695. FOSSIL         The FOSSIL driver, or simply FOSSIL, is a TSR program or
  14696. DRIVER         device driver which OpenDoors can optionally make use of in
  14697.                order to communicate with the modem. The FOSSIL driver is loaded
  14698.                prior to starting up the BBS or your door, usually from the
  14699.                AUTOEXEC.BAT or CONFIG.SYS files. The two most commonly used
  14700.                FOSSIL drivers are X00 and BNU. (FOSSIL is an acronym for
  14701.                "Fido/Opus/SEAdog Standard Interface Layer", although it has now
  14702.                become the standard for nearly all BBS software.) FOSSIL drivers
  14703.                are also available for other specialized serial port hardware,
  14704.                such as the popular "DigiBoard" multi-port serial card.
  14705.  
  14706.  
  14707. LIBRARY        The term "library" or "library file" is a collection of
  14708.                precompiled functions and variables that can be used in other
  14709.                programs. All of the features, capabilities and functions of
  14710.                OpenDoors that you can make use of are contained within the
  14711.                OpenDoors library files. (Likewise, the C runtime library,
  14712.                consisting of the familiar functions such as fopen(), printf()
  14713.                and atoi(), is also contained within a library file.) For more
  14714.                information on the different OpenDoors library files, see the
  14715.                section that begins on page 25.
  14716.  
  14717.                Library files are actually a collection of individual object
  14718.                files. When you compile a program that makes use of a library
  14719.                file, only those portions of the library file that your program
  14720.                actually uses are linked into your program's .EXE file.
  14721.  
  14722.                Library files can be identified by a .LIB extension.
  14723.  
  14724.  
  14725. LOCAL MODE     The term "local mode" refers to a mode in which a BBS system or
  14726.                door program may operate. In local mode, the BBS/door behave as
  14727.                they would if a user were connected via modem to the BBS, except
  14728.                that all display and input is done simply on the BBS software,
  14729.                but not through the modem. Local mode allows the sysop or
  14730.                another person with direct access to the BBS computer to use the
  14731.                BBS/door software, either for their own user, or for testing
  14732.                that the software is running correctly. When programming door
  14733.                software, local mode can be very useful in testing and debugging
  14734.                the door, without requiring the door to be connected to a remote
  14735.                system. All doors written with OpenDoors automatically support
  14736.                local mode operation. Compare "Remote".
  14737.  
  14738.  
  14739. LOCAL ECHO     The term "Local Echo" refers to a door displaying the same
  14740.                characters which are sent to the modem on the local screen
  14741.                ("Output Window"). This allows the sysop to view the same
  14742.                information that is sent to the user's system, in the same
  14743.                manner that it will appear on the user's screen.
  14744.  
  14745.  
  14746.  
  14747. ===============================================================================
  14748. OpenDoors 5.00 Manual                                           End of Page 250
  14749.  
  14750.  
  14751. LOCKED         (eg. "Locked Baud Rate", "Locked BPS Rate", "Locked Commport
  14752.                Speed", etc.) Usually, the communication port to which a modem
  14753.                is connected is set to transfer data at the same BPS rate as the
  14754.                rate at which the modem is communicating. However, many high
  14755.                speed modems allow very high speed data transfer by using built-
  14756.                in data compression methods. In this case, the actual rate of
  14757.                data transfer can easily exceed the true BPS rate of the
  14758.                connection. As a result, the BPS rate of the port is kept a
  14759.                single speed, faster than any of the true modem connections, in
  14760.                order to increase modem speed performance. This is referred to
  14761.                as locking the commport BPS rate. OpenDoors has full support for
  14762.                the use of locked BPS rates.
  14763.  
  14764.  
  14765. LOG FILE       A log file is a normal text file in which BBS software records
  14766.                all major activities that have taken place. As such, the log
  14767.                file permits the sysop, to review what activities have taken
  14768.                place on the BBS during the time which they have been away from
  14769.                the computer. A log file can be helpful in identifying system
  14770.                errors or crashes that have occurred, in alerting the sysop in
  14771.                the case that any users have been causing problems on the BBS,
  14772.                or in simply letting the sysop know who has called recently, and
  14773.                what when they did when they called.
  14774.  
  14775.  
  14776. MODEM          A device connected to a computer which permits it to communicate
  14777.                with other computers, usually over standard telephone lines.
  14778.  
  14779.  
  14780. OBJECT FILE    An object file contains the compiled version of a source code
  14781.                file of a program. The source code file may be a .C file, .CPP
  14782.                file, .ASM file, .PAS file, .BAS file, or any number of other
  14783.                extensions associated with other programming languages. When any
  14784.                of these language's source code files are compiled, a .OBJ file
  14785.                is created containing information such as the executable code,
  14786.                and names of symbols (variables and functions) that are to be
  14787.                shared with other .OBJ files. In order to produce a .EXE file
  14788.                that may be executed, a process known as linking must be
  14789.                performed. During the link process, one or more object files
  14790.                composing your program are combined, along with the necessary
  14791.                code from any library files being used, in order to produce the
  14792.                final .EXE file.
  14793.  
  14794.  
  14795. ONLINE         In the case of BBS software and BBS door programs, the term
  14796.                online refers to the state of a user using the BBS. Usually, the
  14797.                user will be connected to the BBS from a remote location, using
  14798.                a modem. However, it is also possible that the user will be
  14799.                using the actual BBS computer, with the software operating in
  14800.                "local mode".
  14801.  
  14802.  
  14803. OUTPUT WINDOW  The local screen of the BBS on which BBS software is running is
  14804.                usually divided into two sections. At the bottom of the screen,
  14805.  
  14806. ===============================================================================
  14807. OpenDoors 5.00 Manual                                           End of Page 251
  14808.  
  14809.  
  14810.                there is often a one or two line status line, which displays
  14811.                information to the sysop about the BBS and the user who is
  14812.                currently online. The rest of the screen is usually an "output
  14813.                window", in which the information which is being displayed to
  14814.                the user, is also displayed on the local screen. In some cases,
  14815.                there will be no status line, in which case the entire screen
  14816.                will be the output window. Usually, the upper 23 lines of the
  14817.                screen in an OpenDoors door will be the output window, with the
  14818.                bottom two lines being the status line. However, it is possible
  14819.                to disable the OpenDoors status line, in which case the entire
  14820.                screen will be the output window. See also "Status Line"
  14821.  
  14822.  
  14823. PAGE           See "SYSOP PAGE"
  14824.  
  14825.  
  14826. PARAMETER      In the C programming language, many tasks are accomplished by
  14827.                calling functions. When a function is called, one or more pieces
  14828.                of information may be passed to a function, in the form of
  14829.                parameters. For example, a function used to set the foreground
  14830.                and background colour of displayed text might accept two
  14831.                parameters, one for each of the two colour settings. In this
  14832.                example, a function such as od_set_colour(), would be called as
  14833.                follows:
  14834.  
  14835.                               od_set_colour(D_GREEN,D_RED);
  14836.  
  14837.                In this case, D_GREEN, the foreground colour, is the first
  14838.                parameter, and D_RED, the background colour, is the second
  14839.                parameter.
  14840.  
  14841.                In C, parameters are enclosed in parentheses, ( and ), which are
  14842.                located after the name of the function to be called. Each
  14843.                parameter is then separated by a comma character. If a function
  14844.                does not accept any parameters, the parentheses will have
  14845.                nothing between them. (ie. od_clr_scr() ).
  14846.  
  14847.  
  14848. REGISTRATION   This is a demonstration version of OpenDoors, which may only be
  14849.                used under limited circumstances, for a limited period of time.
  14850.                If you wish to continue using OpenDoors after this "evaluation
  14851.                period", you must "register" it. For more information on
  14852.                registering OpenDoors, please see chapter 2 of this manual.
  14853.  
  14854.  
  14855. REMOTE         When used in reference to BBS software or door programs, the
  14856.                term remote is used to refer to a user or computer that is
  14857.                communicating with the BBS, for a distant location, by use of a
  14858.                modem. Compare "Local Mode"
  14859.  
  14860.  
  14861. RIP            "RIP", "RIPScrip" or "Remote Imaging Protocol" is a popular
  14862.                graphical terminal standard that is used with BBS systems.
  14863.                Unlike other terminal emulation standards, such as the ANSI and
  14864.  
  14865. ===============================================================================
  14866. OpenDoors 5.00 Manual                                           End of Page 252
  14867.  
  14868.  
  14869.                AVATAR modes supported by OpenDoors, RIP operates in bit mapped
  14870.                graphics mode, allowing features such as lines, circles and
  14871.                icons to be drawn on the remote screen. OpenDoors provides
  14872.                support for RIP graphics, although OpenDoors operates in text
  14873.                mode itself.
  14874.  
  14875.  
  14876. STATUS LINE    Usually, the bottom two lines of the screen, as displayed by an
  14877.                OpenDoors door, is devoted to a status line (although this
  14878.                status line may be turned off). This status line will display
  14879.                information about the user who is online, along with information
  14880.                about the current state of the BBS system, and a reference to
  14881.                the sysop function keys. See also "Local Window".
  14882.  
  14883.  
  14884. SYSOP          The term sysop is a short-form for "SYStem OPerator", and refers
  14885.                to the individual who is responsible for running and maintaining
  14886.                the BBS system. The sysop is usually the only person who has
  14887.                direct access to the local keyboard and computer on which the
  14888.                BBS, BBS utilities and BBS doors are running.
  14889.  
  14890.  
  14891. SYSOP CHAT     See "CHAT MODE".
  14892.  
  14893.  
  14894. SOURCE CODE    The term "source code" refers to the original file or files that
  14895.                where used to produce a library or executable program. The
  14896.                source code files contain the language statements or commands
  14897.                that are directly written by the programmer. These source code
  14898.                files are then compiled to produce an executable file that may
  14899.                be "run".
  14900.  
  14901.  
  14902. SYSOP PAGE     Sysop paging refers to the process whereby a user of the BBS
  14903.                system may call or page for the sysop's attention, when they
  14904.                wish to "chat" with the sysop, and can be thought of as being
  14905.                similar to the ringing of a telephone. When a user pages the
  14906.                sysop, the BBS system will produce some sort of sound, which the
  14907.                sysop may elect to respond to if they are within hearing range
  14908.                of the computer. The most common reasons for a user to page a
  14909.                sysop include the case that they are having difficulty with some
  14910.                aspect of the BBS, that they have a question, or if they are
  14911.                simply interested in having a friendly conversation with the
  14912.                sysop. Obviously, since the sysop may not wish to be disturbed
  14913.                by users paging at certain times (such as when they are in bed),
  14914.                most BBS software provides controls to allow you to control
  14915.                paging. These features might include the ability to set hours
  14916.                for each day of the week during which paging will be permitted,
  14917.                and the ability to temporarily override the ability of some or
  14918.                all callers to page the sysop.
  14919.  
  14920.  
  14921. USER           When applied to computers in general, the term user simply
  14922.                refers to any person using the computer hardware and software.
  14923.  
  14924. ===============================================================================
  14925. OpenDoors 5.00 Manual                                           End of Page 253
  14926.  
  14927.  
  14928.                However, when applied particularly to BBSes, the term user
  14929.                refers specifically to a person who calls the BBS, to carry out
  14930.                activities such as communicating via messages or chatting,
  14931.                uploading and downloading files, or using doors. Often, the term
  14932.                user is used in contrast with the term sysop. In this case,
  14933.                users are all of the people who call and user the BBS, other
  14934.                than the sysop themselves.
  14935.  
  14936.  
  14937. WINDOWS        Windows, or Microsoft Windows, is a computer operating
  14938.                environment which runs on IBM PC and compatible computers, and
  14939.                such runs in conjunction with the MS-DOS or PC-DOS operating
  14940.                systems. This version of OpenDoors can only be used to produce
  14941.                DOS-mode programs, which will run under DOS, DESQview, Windows
  14942.                and OS/2.
  14943.  
  14944.  
  14945.  
  14946.  
  14947.  
  14948.  
  14949.  
  14950.  
  14951.  
  14952.  
  14953.  
  14954.  
  14955.  
  14956.  
  14957.  
  14958.  
  14959.  
  14960.  
  14961.  
  14962.  
  14963.  
  14964.  
  14965.  
  14966.  
  14967.  
  14968.  
  14969.  
  14970.  
  14971.  
  14972.  
  14973.  
  14974.  
  14975.  
  14976.  
  14977.  
  14978.  
  14979.  
  14980.  
  14981.  
  14982.  
  14983. ===============================================================================
  14984. OpenDoors 5.00 Manual                                           End of Page 254
  14985.  
  14986.  
  14987. -------------------------------------------------------------------------------
  14988. INDEX
  14989. -------------------------------------------------------------------------------
  14990.  
  14991. About This Manual, 24
  14992. Access Level, 175
  14993. Alias, 168
  14994. ANSI Graphics, 131, 163, 246
  14995. Archive Contents, 236
  14996. ASCII Chart, 86
  14997. ASCII Mode, 246
  14998. AVATAR Graphics, 114, 131, 164, 246
  14999. Baud Rate, 152
  15000. BBS Information, 156
  15001. BBS Name, 162
  15002. BBS Systems, 29
  15003. Before Exit Function, 188
  15004. Box Characters, 182, 187
  15005. BPS Rate, 152
  15006. Built-In Function Keys, 207
  15007. Caller Information, 156
  15008. Carrier Detect, 51, 96
  15009. Chat, 38, 101
  15010. Chat Mode, 32, 101, 249
  15011. Colour Attribute Codes, 125
  15012. Colour Constants, 129
  15013. Colour Customization, 210, 220, 223, 227
  15014. Colour Functions, 42
  15015. Colours, 105, 125, 128
  15016. Common Problems, 230
  15017. Compiler Errors, 230, 231
  15018. Compiling With OpenDoors, 25
  15019. Custom Function Keys, 208
  15020. Debugging, 24, 228
  15021. Demo Version, 9
  15022. Display Functions, 42, 64
  15023. Displaying Text, 28, 41, 42, 60, 62, 64, 89, 105, 110, 114, 121
  15024. Door Driver Functions, 40
  15025. Door Driver Module, 5, 28, 40
  15026. Door Functions, 45
  15027. Door Information File, 29, 31, 147, 156
  15028. Door Settings, 179
  15029. DORINFOx.DEF File, 31
  15030. DOS Shell, 32, 188, 230
  15031. Download Limit, 166
  15032. Drop To BBS Key, 33
  15033. Error Free Connection, 167
  15034. ErrorLevels, 33
  15035. Example Program - Changing Only Foreground/Background Colour, 129
  15036. Example Program - Choosing Text Colour, 126
  15037. Example Program - Clearing A Line, 56
  15038. Example Program - Dialog Box, 67
  15039. Example Program - Door And Utility In One Program, 91
  15040. Example Program - Drawing A Window, 114
  15041.  
  15042. ===============================================================================
  15043. OpenDoors 5.00 Manual                                           End of Page 255
  15044.  
  15045.  
  15046. Example Program - Exiting A Door, 81
  15047. Example Program - EZVote, 31
  15048. Example Program - First Door, 28
  15049. Example Program - Hanging Up In CBV Door, 51
  15050. Example Program - Hotkeyed Menu, 90
  15051. Example Program - Input Key With Echo, 110
  15052. Example Program - Pausing In A Door, 96
  15053. Example Program - Setting Door Info File Location, 148
  15054. Example Program - Shelling To DOS, 138
  15055. Example Program - Terminal Emulation, 63
  15056. Example Program - Testing Available Door Information, 156
  15057. Example Program - Testing Screen Clearing Capabilities, 57
  15058. Example Program - Transferring A File Using DSZ, 139
  15059. Example Program - User Statistics Door, 108
  15060. Example Program - Waiting For CR, 54
  15061. Exiting A Door Program, 81
  15062. Features, 5
  15063. Feedback Form, 21
  15064. File Display Functions, 43
  15065. FILES.BBS File, 98
  15066. Fossil Driver, 250
  15067. FOSSIL port, 155
  15068. Function Keys, 32, 96, 206
  15069. Future Versions, 243
  15070. Getting In Touch With Us, 233
  15071. Graphics Mode, 163, 164, 246
  15072. Hangup, 33
  15073. History, 237
  15074. Hotkeys, 89
  15075. IBM Colour Attribute Codes, 125
  15076. IEMSI Session Information, 159
  15077. Inactivity Timeout, 195, 196, 197
  15078. Input Functions, 44, 83, 84
  15079. Keyboard Buffer, 53, 96, 110
  15080. Keys, 96
  15081. Language Customization, 212
  15082. Learning OpenDoors, 28
  15083. Library, 250
  15084. LIBrary Files, 27
  15085. Line Number, 149
  15086. Linking, 25
  15087. Local Mode, 31, 196, 250
  15088. Locked, 251
  15089. Lockout, 33
  15090. Memory Models, 26, 27
  15091. Memory Swapping, 204
  15092. Modem Port, 155
  15093. Modem Settings, 151
  15094. New Version, 237
  15095. Node Number, 149
  15096. Object File, 251
  15097. od_autodetect() Function, 48
  15098. od_carrier() Function, 51
  15099. od_chat() Function, 50
  15100.  
  15101. ===============================================================================
  15102. OpenDoors 5.00 Manual                                           End of Page 256
  15103.  
  15104.  
  15105. od_clear_keybuffer() Function, 53
  15106. od_clr_line() Function, 55
  15107. od_clr_scr() Function, 57, 230
  15108. od_colour_config() Function, 59
  15109. od_control Structure, 29, 145
  15110. od_disable Variable, 194
  15111. od_disp() Function, 60
  15112. od_disp_emu() Function, 62
  15113. od_disp_str() Function, 64
  15114. od_draw_box() Function, 66
  15115. od_edit_str() Function, 70
  15116. od_exit() Function, 30, 81, 188, 191
  15117. od_get_answer() Function, 83
  15118. od_get_key() Function, 28, 53, 84
  15119. od_gettext() Function, 88
  15120. od_hotkey_menu() Function, 89
  15121. od_init() Function, 29, 91, 147
  15122. od_input_str() Function, 53, 94
  15123. od_kernal() Function, 30, 96
  15124. od_list_files() Function, 98
  15125. od_log_write() Function, 100
  15126. od_page() Function, 101, 202
  15127. od_popup_menu() Function, 102
  15128. od_printf() Function, 28, 105, 192
  15129. od_putch() Function, 110
  15130. od_puttext() Function, 112
  15131. od_repeat() Function, 114
  15132. od_restore_screen() Function, 116
  15133. od_save_screen() Function, 117
  15134. od_scroll() Function, 119
  15135. od_send_file() Function, 121
  15136. od_set_attrib() Function, 125
  15137. od_set_color() Function, 128
  15138. od_set_cursor() Function, 131
  15139. od_set_dtr() Function, 133
  15140. od_set_personality() Function, 135
  15141. od_set_statusline() Function, 136
  15142. od_spawn Function, 203
  15143. od_spawn() Function, 138
  15144. od_spawnvpe() Function, 140
  15145. od_window_create() Function, 142
  15146. od_window_remove() Function, 144
  15147. OPENDOOR.H File, 25, 28, 34
  15148. OpenDoors BBS, 232
  15149. OpenDoors Customization, 184
  15150. OPENDOORS Echo, 233
  15151. OpenDoors History, 237
  15152. Our Address, 233
  15153. Output Functions, 42
  15154. Output Window, 32, 251
  15155. Paging Hours, 179, 180
  15156. Paging The Sysop, 101
  15157. Pause Key, 198
  15158. Phone Number, 168
  15159.  
  15160. ===============================================================================
  15161. OpenDoors 5.00 Manual                                           End of Page 257
  15162.  
  15163.  
  15164. Printing, 28, 41, 42, 60, 62, 64, 89, 105, 110, 114, 121
  15165. Printing Manual, 25
  15166. Problems, 24
  15167. Product Support, 232
  15168. Project Files, 25
  15169. Registration, 9, 11, 15, 19, 20, 233, 252
  15170. Registration Form, 13, 20
  15171. RIP, 252
  15172. RIPScrip, 252
  15173. Running Doors, 29
  15174. Screen Functions, 42
  15175. Screen Length, 174
  15176. Screen Width, 175
  15177. Security Level, 175
  15178. Setting Colours, 105, 125, 128
  15179. Solutions To Problems, 230
  15180. Source Code, 9, 17, 22
  15181. Special Thanks, 245
  15182. Status Line, 32, 101, 136, 204, 205, 253
  15183. Stop Key, 198
  15184. Support, 232
  15185. Support BBS, 232, 233
  15186. Swapping, 204
  15187. Sysop Chat, 38, 101, 188
  15188. Sysop Function Keys, 206
  15189. Sysop Keys, 32, 96
  15190. Sysop Name, 161
  15191. Sysop Next Key, 33
  15192. Sysop Next Setting, 181
  15193. Sysop Page, 202
  15194. Sysop Paging, 101, 253
  15195. System Events, 160
  15196. System Name, 162
  15197. Terminal Emulator, 62, 121, 122
  15198. Terminal Emulator Control Codes, 122
  15199. Text Customization, 212
  15200. Thank-yous, 245
  15201. Time Left, 176
  15202. Timeout, 96
  15203. Troubleshooting, 24
  15204. User Handle (Alias), 168
  15205. User Information, 156
  15206. User Keyboard Off Key, 33, 53
  15207. User Keyboard Setting, 180, 181
  15208. User Name, 171
  15209. User Password, 173
  15210. User Timeout, 96
  15211. Version History, 237
  15212. Want-Chat Setting, 177
  15213.  
  15214.  
  15215.  
  15216.  
  15217.  
  15218.  
  15219. ===============================================================================
  15220. OpenDoors 5.00 Manual                                           End of Page 258
  15221.  
  15222.  
  15223.  
  15224.  
  15225.  
  15226.  
  15227.  
  15228.  
  15229.  
  15230.  
  15231.  
  15232.  
  15233.  
  15234.  
  15235.  
  15236.  
  15237.  
  15238.