bbs/magicka
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
This repository has been archived on 2024-04-08. You can view files and clone it, but cannot push or open issues or pull requests.
26f1e850e2
magicka/deps/odoors/OPENDOOR.TXT

14806 lines
699 KiB
Plaintext
Raw Normal View History

Basic Experimental Full Screen Editor
2016-12-03 05:08:50 +00:00
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
<20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
<20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
<20><><EFBFBD>
<20><><EFBFBD>
<20><><EFBFBD> Online Software Programming Toolkit
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
Programmer's Manual
Version 6.00
DOS and Win32 Editions
NOTE: Since you will likely want to refer to this manual while
working with OpenDoors, it is highly recommended that you take
the time to print it out. Simply type COPY OPENDOOR.TXT PRN
from your DOS prompt. With the exception of this title page,
this document contains only 7-bit ASCII characters.
(C) Copyright 1991 - 1996 by Brian Pirie. All Rights Reserved.
TABLE OF CONTENTS
CHAPTER 1 - INTRODUCTION TO OPENDOORS.......................................5
WELCOME! ...............................................................5
FEATURES OF THE OPENDOORS TOOLKIT ......................................6
CHAPTER 2 - ABOUT THIS EVALUATION COPY AND ORDERING.........................9
THE EVALUATION COPY & BENEFITS OF REGISTERING ..........................9
HOW TO ORDER ...........................................................10
HOW TO ORDER BY MAIL ...................................................11
SENDING YOUR ORDER FEE IN THE MAIL .....................................12
ORDERING BY CREDIT CARD ................................................14
HOW YOU CAN RECEIVE YOUR ORDER .........................................15
ORDERING THE SOURCE CODE ...............................................17
OPENDOORS 6.00 ORDER FORM ..............................................18
OPENDOORS 6.00 FEEDBACK FORM ...........................................19
TERMS OF REGISTRATION AND SOURCE CODE USE ..............................20
CHAPTER 3 - OPENDOORS TUTORIAL..............................................21
ABOUT THIS MANUAL ......................................................21
COMPILING A PROGRAM WITH OPENDOORS .....................................22
LINKING WITH OPENDOORS USING A DOS COMPILER ............................23
LINKING WITH OPENDOORS USING A WINDOWS COMPILER ........................24
RUNNING A DOOR PROGRAM WRITTEN WITH OPENDOORS ..........................26
RUNNING DOS-BASED DOOR PROGRAMS ........................................26
RUNNING WINDOWS 95/NT DOOR PROGRAMS ....................................26
BASICS OF DOOR PROGRAMMING WITH OPENDOORS ..............................29
TOUR OF A SAMPLE DOOR PROGRAM: "EX_VOTE" ...............................33
OTHER EXAMPLE PROGRAMS INCLUDED WITH OPENDOORS .........................38
CHAPTER 4 - THE OPENDOORS API FUNCTIONS.....................................40
OVERVIEW ...............................................................40
TABLE OF MOST COMMONLY USED FUNCTIONS ..................................41
TABLE OF ALL FUNCTIONS .................................................42
OD_ADD_PERSONALITY() ...................................................47
OD_AUTODETECT() ........................................................48
OD_CHAT() ..............................................................50
OD_CARRIER() ...........................................................51
OD_CLEAR_KEYBUFFER() ...................................................53
OD_CLR_LINE() ..........................................................55
OD_CLR_SCR() ...........................................................57
OD_COLOR_CONFIG() ......................................................59
OD_DISP() ..............................................................60
OD_DISP_EMU() ..........................................................62
OD_DISP_STR() ..........................................................63
OD_DRAW_BOX() ..........................................................65
OD_EDIT_STR() ..........................................................68
OD_EXIT() ..............................................................79
OD_GET_ANSWER() ........................................................81
OD_GET_INPUT() .........................................................82
OD_GET_KEY() ...........................................................85
===============================================================================
OpenDoors 6.00 Manual End of Page 2
OD_GETTEXT() ...........................................................89
OD_HOTKEY_MENU() .......................................................90
OD_INIT() ..............................................................92
OD_INPUT_STR() .........................................................95
OD_KERNEL() ............................................................97
OD_LIST_FILES() ........................................................98
OD_LOG_WRITE() .........................................................100
OD_MULTILINE_EDIT() ....................................................101
OD_PAGE() ..............................................................104
OD_PARSE_CMD_LINE() ....................................................105
OD_POPUP_MENU() ........................................................107
OD_PRINTF() ............................................................110
OD_PUTCH() .............................................................115
OD_PUTTEXT() ...........................................................116
OD_REPEAT() ............................................................118
OD_RESTORE_SCREEN() ....................................................120
OD_SAVE_SCREEN() .......................................................121
OD_SCROLL() ............................................................123
OD_SEND_FILE() .........................................................124
OD_SET_ATTRIB() ........................................................128
OD_SET_COLOR() .........................................................131
OD_SET_CURSOR() ........................................................134
OD_SET_DTR() ...........................................................135
OD_SET_PERSONALITY() ...................................................136
OD_SET_STATUSLINE() ....................................................137
OD_SLEEP() .............................................................139
OD_SPAWN() .............................................................141
OD_SPAWNVPE() ..........................................................143
OD_WINDOW_CREATE() .....................................................145
OD_WINDOW_REMOVE() .....................................................147
CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE.................................148
INTRODUCTION TO THE CONTROL STRUCTURE ..................................148
CONTROL STRUCTURE - DOOR INFO FILE STATS ...............................150
CONTROL STRUCTURE - SERIAL PORT SETTINGS ...............................153
CONTROL STRUCTURE - BBS AND CALLER INFORMATION .........................158
CONTROL STRUCTURE - DOOR SETTINGS ......................................182
CONTROL STRUCTURE - DIAGNOSTICS ........................................185
CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION ............................187
CONTROL STRUCTURE - FUNCTION KEYS ......................................212
CONTROL STRUCTURE - COLOR CUSTOMIZATION ................................216
CONTROL STRUCTURE - TEXT CUSTOMIZATION .................................217
CHAPTER 6 - SPECIAL TOPICS..................................................220
ADDITIONAL INFORMATION ON THE WIN32 VERSION ............................220
CONFIGURATION FILE SYSTEM ..............................................225
DEFINING CUSTOM DOOR INFORMATION FILE FORMATS ..........................230
MULTIPLE PERSONALITY SYSTEM ............................................233
LOG FILE SYSTEM ........................................................235
MAKING DOORS MULTI-NODE-AWARE ..........................................237
CHAPTER 7 - TROUBLESHOOTING AND GETTING ASSISTANCE WITH OPENDOORS...........242
===============================================================================
OpenDoors 6.00 Manual End of Page 3
ABOUT THIS CHAPTER .....................................................242
TROUBLESHOOTING PROBLEMS ...............................................242
SOLUTIONS TO COMMON PROBLEMS ...........................................244
OPENDOORS SUPPORT ......................................................245
THE OPENDOORS SUPPORT BBS ..............................................245
THE OPENDOORS WORD WIDE WEB SITE .......................................246
THE OPENDOORS CONFERENCE ...............................................246
GETTING IN TOUCH WITH ME ...............................................247
APPENDIX A - CONTENTS OF PACKAGE............................................249
APPENDIX B - CHANGES FOR THIS VERSION.......................................250
APPENDIX C - FUTURE VERSIONS................................................254
APPENDIX D - SPECIAL THANKS.................................................255
GLOSSARY....................................................................256
INDEX.......................................................................267
===============================================================================
OpenDoors 6.00 Manual End of Page 4
11
111
11
11
11
11
1111
-------------------------------------------------------------------------------
CHAPTER 1 - INTRODUCTION TO OPENDOORS
WELCOME!
-------------------------------------------------------------------------------
Welcome to OpenDoors! OpenDoors is a POWERFUL and EASY TO USE
online software programming toolkit for C and C++. While
OpenDoors is most often used to create add-on "door" programs
that run under BBS systems, it can also be used for many other
online software applications. By using OpenDoors, you are
joining over 500 other programmers from around the world who
have used it since it was first released to the public in 1991.
Over the years, OpenDoors has grown from a simple BBS door
programming library to what is perhaps the most sophisticated,
widely used and supported package of its type.
What exactly is OpenDoors? OpenDoors provides a complete system
that allows you to quickly and easily write spectacular,
professional quality interactive online software. With
OpenDoors, you can write software such as BBS door programs just
as you would write any other program - without having to worry
about the many of the internal details of door programming.
OpenDoors looks after communicating through the modem, providing
ANSI/AVATAR/RIP terminal support and interfacing with a wide
variety of BBS packages through door information files (such as
DOOR.SYS, DORINFO1.DEF, etc.). OpenDoors also looks after status
lines and sysop function keys for DOS shells, chatting, hanging
up, and so on. In addition, OpenDoors carries out all the work
involved in keeping track of carrier detection, user timeouts
and much, much more. OpenDoors is also highly flexible, allowing
you to take as little or as much control of your program's
behavior as you wish.
This package includes both DOS and Win32 versions of OpenDoors.
This allows you to build a plain-DOS version of your program to
run under a variety of platforms (DOS, DesqView, Windows 3.x,
NT, 95 and OS/2), to build a Win32 version that takes special
advantage of Windows 95 / NT, or build both versions of your
program - the choice is yours. The DOS version of OpenDoors
performs its serial I/O using either a FOSSIL driver, or built-
in serial I/O capabilities, making the use of a FOSSIL driver
===============================================================================
OpenDoors 6.00 Manual End of Page 5
optional. The Win32 version takes special advantage of 32-bit
programming, multithreading and the Windows GUI, and allows you
to access many services that are provided by Windows, such as
ODBC (for database access) and MAPI (for email and messaging).
Both the DOS and Win32 versions of OpenDoors can be run under
both DOS and Windows-based BBS packages. The DOS version of
OpenDoors can also be run under OS/2-based BBS packages.
The following section provides more detailed information on the
features and capabilities that OpenDoors provides.
FEATURES OF THE OPENDOORS TOOLKIT
-------------------------------------------------------------------------------
You will find that OpenDoors provides a solid platform to build
BBS door programs and other online software on top of. You may
want to write simple utility door programs, on-line games or
sophisticated applications. Perhaps you are interested in
getting into the market of selling online software, or perhaps
you just wish to write some custom door programs for a
particular BBS system. With OpenDoors, you can accomplish all of
these things - and do it much more easily than ever before. Some
of the features that OpenDoors provides to :
- OpenDoors handles all the "dirty" work involved in writing
BBS door programs. Since OpenDoors looks after all the door-
related operations for you, you need do next to nothing
different when writing door programs than you would when
writing any other program. You simply call OpenDoor's simple
functions to input, output and control door operation. In
fact, many people have converted non-door programs to door
programs in only a matter of minutes using OpenDoors. One of
the most common comments I receive about OpenDoors is how
easy it is to use.
- OpenDoors allows you to write software that DIRECTLY support
a wide variety of BBS systems, including RemoteAccess,
QuickBBS, PC-Board, Maximus, Opus, Wildcat!, WWIV, Spitfire,
SuperBBS, Telegard, TriBBS, GAP, and others.
- As you would expect, OpenDoors flawlessly monitors the
modem's carrier detect signal, to automatically recover when
a user hangs up - without your having to do anything extra in
your program. OpenDoors also monitors how much time the user
has left in the door, and provides a fully adjustable
inactivity timeout monitor.
- OpenDoors takes care of all the work involved in reading and
writing BBS door information files, such as DORINFO1.DEF,
===============================================================================
OpenDoors 6.00 Manual End of Page 6
EXITINFO.BBS, CHAIN.TXT, DOOR.SYS, etc. If the particular
information is available to OpenDoors, it will provide you
with just about everything you could ever want to know about
the user on-line, the system your door is running under, and
so on. In addition to the many door information file formats
supported by OpenDoors, you are also able to define your own
custom formats.
- OpenDoors also does all the work involved in displaying and
automatically updating the door's status line, with
information available to the sysop such as user name,
location, baud rate, time left, function keys,
ANSI/AVATAR/RIP settings, and so on. Using OpenDoors, you can
choose from a number of different "personalities". These
personalities allows OpenDoors to mimic the status lines and
sysop function keys used in various BBS packages. OpenDoors
includes personalities that mimic RemoteAccess, PC-Board and
Wildcat! OpenDoors also allows you to create your own
personalities to mimic any other BBS system.
- OpenDoors automatically provides the sysop with all the
standard function keys for adjusting user time, hanging up on
or even locking out the user, and so on. OpenDoors also
provides you with a chat mode, which is available to the
sysop by pressing Alt-C. In addition, OpenDoors has full
support for sysop shell to DOS, activated by the Alt-J key.
- What's more, OpenDoors is designed to be very easy to use.
Even the most novice 'C' programmers are able to write
professional-quality doors with OpenDoors. It takes care of
just about every detail for you, yet still gives you the
ability to completely control and customize every detail of
your door's behavior. There are even people who begin door
programming with OpenDoors, having never programmed in C in
the past.
- OpenDoors supports both FOSSIL-based and built-in serial I/O
capabilities. FOSSIL-based serial I/O can be used for maximum
compatibility with various systems and serial ports,
including multiple-port serial cards such as DigiBoard.
OpenDoors can also operate without a FOSSIL driver, using
it's own serial I/O capabilities. OpenDoor's built-in
asynchronous communications supports baud rates of up to
115,200 and non-standard serial port configurations.
OpenDoors also has the ability to automatically detect which
of the two serial I/O methods should be used on a particular
system.
- OpenDoors also automatically detects when the BBS system is
operating in local mode, and supports full local mode
operations itself.
===============================================================================
OpenDoors 6.00 Manual End of Page 7
- Other OpenDoors functions include a built in sysop-page
function that will ask the user why they wish to chat, and
then proceed to page the sysop, just as any BBS package
would. OpenDoors also provides screen clearing functions
(which will detect whether the user has screen clearing
turned on), and various ANSI/AVATAR/RIP control functions
(which again detect if the user has graphics mode turned on).
- In addition to the basic display features of OpenDoors there
are also a number of advanced screen control functions. These
include functions to save and restore the entire screen,
along with functions to save, restore or scroll portions of
the screen. Other functions allow you to provide overlapping
windows and pop-up menus with highlighted selection bars.
- OpenDoors provides a multi-line text editor that you can use
to allow the user to enter or edit text files, email
messages, or any other text that spans multiple lines. You
can customize many of the editor's settings to suit your
needs.
- OpenDoors has a number of special sub-systems that you may
elect to include in your doors. Among these, is a log-file
system that allows you to add log file support to your doors
with only a single line of programming.
- Another valuable OpenDoors sub-system is the configuration
file system. Again using only a single line of code, you can
add configuration file support to your doors. OpenDoors
configuration files permit the sysop using the door to
customize the door's behavior to their own preferences.
- OpenDoors can also be fully customized in order that you may
write door programs that use languages other than English.
- Among the ANSI/AVATAR/RIP features found in OpenDoors is the
ability to send ANSI/AVATAR/RIP files from disk. This allows
you to easily design program screens, and incorporate them
into your doors.
- OpenDoors also comes with the source code for a number of
example doors, which you can modify, or simply extract bits
and pieces for use in your own doors. Plus, this manual
contains many examples of C source code, to help you in
writing nearly any door program you might wish to build.
- You may also elect to purchase the source code for OpenDoors,
which will permit you to make modifications to any portion of
OpenDoors, use any portions of the OpenDoors source code in
other programs you write, or merely learn how communications-
type programs are written.
===============================================================================
OpenDoors 6.00 Manual End of Page 8
2222
22 22
22
22
22
22
222222
-------------------------------------------------------------------------------
CHAPTER 2 - ABOUT THIS EVALUATION COPY AND ORDERING
THE EVALUATION COPY & BENEFITS OF REGISTERING
-------------------------------------------------------------------------------
OpenDoors is distributed and sold using the conventional
"shareware" approach. This complete package can be freely
distributed, both online (through BBS systems and the Internet)
and on CD-ROMs or other media. This gives you the chance to try
OpenDoors before you buy it. Unlike traditional commercial
software, you have the opportunity to see OpenDoors first-hand,
and determine whether it meets your needs without first paying
for it. However, before registering you are only permitted to
use it under the following conditions:
1.)You may only use this package for a one month period, and
for evaluation purposes only.
2.) Programs written with this package may not be distributed.
Also, before registering, any program written with OpenDoors
will display a message to the user indicating that OpenDoors is
not registered. Of course, this message is removed once you have
registered.
If you decided to register OpenDoors, you will become the
licensed owner of a powerful tool for creating BBS door programs
and other online software. Registered (licensed) owners of
OpenDoors are entitled to:
1.)Virtually unlimited use of OpenDoors. You may write as many
programs as you wish using OpenDoors, and do what you please
with these programs. They may be freely distributed, or even
sold. What's more, there are no additional royalty fees.
Your one time purchase of OpenDoors entitles you to use it
as you please.
2.)Your registration entitles you to use both the DOS and Win32
versions of OpenDoors.
===============================================================================
OpenDoors 6.00 Manual End of Page 9
3.)You will also be entitled to free upgrades to newer versions
of OpenDoors. In addition to the great many features and the
quality that this version of OpenDoors has to offer, I am
currently working on a great many additions and enhancements
for the next version. (See the end of this document for an
outline of features currently "in the works".) Any programs
you write using this version will also automatically take on
many of these new features when you upgrade to the new
version.
Perhaps the best news of all is the price of OpenDoors. Similar
packages sell for $50, $75, or even more. However, this version
of OpenDoors will only cost you $28 US Dollars, $34 Canadian
Dollars, or the equivalent in your country's currency! (Note
that this price will increase in future versions. By registering
now, you will save by being able to upgrade to all future
versions at no additional charge.)
Also, the source code for OpenDoors is now available to licensed
users for an additional $28US / $34CDN / equivalent. Ordering a
copy of the source code will allow you to customize OpenDoors
for your own use, making any changes or additions that you wish.
It also gives you the opportunity to see how OpenDoors works,
and to use any portions of the OpenDoors code in any other
programs you wish to write. If you think you might be interested
in ordering the OpenDoors source code, please be sure to read
the section entitled "Ordering The Source Code", located on page
20.
HOW TO ORDER
-------------------------------------------------------------------------------
There are to ways of ordering and OpenDoors license
(registration):
-The most common way to order is by mailing the OpenDoors order
form along with a cheque, money order or cash to the address
on this order form.
- You may order using a major credit card. OpenDoors credit card
orders are handled by a third-party credit card order service,
named PsL.
The following sections provide more information on how to order
using each of these options.
===============================================================================
OpenDoors 6.00 Manual End of Page 10
HOW TO ORDER BY MAIL
-------------------------------------------------------------------------------
To order OpenDoors by mailing a cheque, money order or cash,
simply follow these three steps:
1.) Fill out the registration form. Information on filling out
the form is located on page 15.
2.) Send the appropriate payment, $28US/$34CDN/equivalent for
the registration or $56US/$68CDN/equivalent for both the
registration and source code. If you wish more detailed
instructions on sending the registration fee, see the
section that begins page on 12. Included in that section is
a list of equivalent prices for a number of other
countries.
3.) Send the above two items to me at:
Brian Pirie
117 Cedarock Drive
Kanata ON K2M 2H5
Canada
Many people who register OpenDoors also order the source code
package. You may wish to consider the benefits of having the
OpenDoors source code - it allows you to learn how OpenDoors and
communications software is written, it allows you to modify and
customize OpenDoors to suit your own preferences, and it also
allows you to use portions of OpenDoors for other non-door
programming projects. If you think you might also be interested
in the OpenDoors source code, be sure to read the section on the
source code, which begins on page 20.
Also, you may wish to send the OpenDoors feedback form (located
on page 19), along with your registration. The feedback form
gives you a chance to tell me what you think of OpenDoors, and
what changes you would like to see in future versions. In fact,
the majority of suggestions made on these forms in the past have
already been implemented in the current version of OpenDoors.
If you have printed the OpenDoors manual, you can simply remove
and mail the forms on pages 18 and 19. If you have not already
printed a copy of the manual, and you have a printer, you can
quickly print these forms by printing the ORDER.FRM file
included in the OpenDoors distribution archive. (Type COPY
ORDER.FRM PRN from your DOS prompt.)
NO PRINTER? Alternatively, if you do not have a printer, simply send a hand-
written version of the order form.
===============================================================================
OpenDoors 6.00 Manual End of Page 11
If you have any special instructions for me, or anything that
you would like to say when you register, feel free to write this
on the back of the registration form, or on a separate piece of
paper.
When filling out the OpenDoors registration form, be sure to
indicate how you would prefer to receive your OpenDoors
registration key and/or source code. The following options are
available:
- Having me send the registration and/or source code
by conventional mail
- Internet E-Mail (the fastest option)
- By Fax
- Having me call to your BBS
- You calling the OpenDoors support BBS
- FidoNet "CrashMail"
Once you have decided which means you would prefer to receive
your order by, please read the detailed instructions on your
order method, below. Also, if you are ordering the source code,
please be sure to read the section on ordering the source code,
which begins on page 20.
SENDING YOUR ORDER FEE IN THE MAIL
-------------------------------------------------------------------------------
The price of OpenDoors is 34 Canadian Dollars, 28 U.S. Dollars,
or equivalent for the registration. The source code costs an
additional 34 Canadian Dollars, 28 U.S. Dollars, or equivalent.
For your convenience, the equivalent value in a number of other
country's currencies, at the time of this writing, is as
follows:
-----------------------------------------------
REGISTRATION
REGISTRATION ONLY AND SOURCE CODE
-----------------------------------------------
34 Canadian Dollars 68 Canadian Dollars
28 US Dollars 56 US Dollars
18 British Pounds 36 British Pounds
150 French Francs 300 French Francs
44 German Marks 88 German Marks
50 Netherland Gilders 100 Netherland Gilders
39 Australian Dollars 78 Australian Dollars
-----------------------------------------------
If you are ordering by mail, this order fee may be paid using
any of the following methods:
===============================================================================
OpenDoors 6.00 Manual End of Page 12
-Cheque or Money Order in Canadian currency, drawn upon a
Canadian bank. In this case, your order fee will be either
$34CDN for just the registration, or $68CDN for both the
registration and source code.
-Cheque or Money Order in U.S. currency, drawn upon a U.S. bank.
In this case, your order fee will be either $28US for just the
registration, or $56US for both the registration and source
code.
-An International Money Order or International Bank Draft
(available from your bank, post office or companies such as
American Express), in Canadian currency. Depending on the
particular case, your order fee MAY be sent to me by the postal
service, and you will mail your order form by itself. You
should have the money order drawn in either $34CDN for just the
registration, or $68CDN for both the registration and source
code.
-A cheque drawn on any bank in the world, IN THAT COUNTRY'S
CURRENCY, equivalent to 34 Canadian dollars. For instance, a
cheque for the appropriate number of British Pounds, drawn on a
British bank, is perfectly acceptable. However, I am unable to
accept a cheque for $34 Canadian dollars, drawn on a British
Bank. UNFORTUNATELY, THE BANKS IN CANADA ARE CURRENTLY
UNWILLING TO ACCEPT EUROCHEQUES.
-Cash. Please note that it is not usually recommended that cash
be sent in the mail, and that I cannot be responsible for any
cash lost in the mail. Simply put, if you wish to order by
cash, it is your responsibility to get the cash to me. However,
if I do receive your order in the form of cash, it will be
perfectly acceptable to me. I would like to mention that many
people have already ordered OpenDoors by sending cash, and I
have yet to run across any case of cash being lost in the mail.
Nonetheless, if you wish to send cash, you may wish to consider
doing so by registered mail, for your added security.
If you are ordering OpenDoors from within Canada, you will most
likely choose the first option (a Canadian cheque or money
order). If you are ordering OpenDoors from within the United
States, you will most likely choose the second option (an
American cheque or money order). If you are ordering from
outside Canada and the U.S., it would be ideal if you could send
your fee by an international money order. However, it should be
noted that any of the above order methods will be acceptable
from any location. Also, it is quite possible that I may be able
to accept other means of sending your order fee. If you are
unsure about sending your order fee, please feel free to get in
touch with me by any of the means listed on page 247.
===============================================================================
OpenDoors 6.00 Manual End of Page 13
ORDERING BY CREDIT CARD
-------------------------------------------------------------------------------
This information applies to CREDIT CARD ORDERS ONLY. Please read
this entire section before ordering OpenDoors by credit card.
In order to cover the additional costs of processing credit card
orders, an $8 shipping and handling fee applies to all OpenDoors
orders made through PsL. As such, the total prices you will pay
are:
- Just registration ($28 + $8 Handling) = $36 U.S.
- Registration and Source Code ($56 + $8 Handling) = $64 U.S.
(All prices will be charged to your credit card in U.S.
Dollars.)
You can order OpenDoors with MC, Visa, Amex, or Discover from
Public (software) Library by calling 800-2424-PsL or 713-524-6394
or by FAX to 713-524-6398 or by CIS Email to 71355,470. You can
also order online through the World Wide Web. For more
information on how to do this, visit the OpenDoors Web site.
(Information on the OpenDoors web site is provided on page 246.)
You can also mail credit card orders to PsL at P.O.Box 35705,
Houston, TX 77235-5705. When ordering by phone, you must call
between 6:00am and 6:00pm CST on Monday to Thursday, or between
6:00am and 12:30pm on Fridays.
THE ABOVE NUMBERS ARE FOR CREDIT CARD ORDERS ONLY.
THE AUTHOR OF THIS PROGRAM CANNOT BE REACHED AT THESE NUMBERS.
Any questions about the status of the shipment of the order,
refunds, registration options, product details, technical
support, volume discounts, dealer pricing, site licenses, non-
credit card orders, etc., must be directed to:
Brian Pirie
117 Cedarock Drive
Kanata ON K2M 2H5
Canada
To insure that you get the latest version, PsL will notify me the
day of your order and I will ship OpenDoors directly to you. I
will send OpenDoors by conventional mail unless I have previously
heard from you, asking me to send your order by some other means.
When ordering by credit card through PsL, please be sure to
indicate whether you wish to order just the OpenDoors
registration, or both the registration and source code. Also,
please be sure to include your credit card billing address.
Without this information, PsL will be unable to process your
order.
===============================================================================
OpenDoors 6.00 Manual End of Page 14
HOW YOU CAN RECEIVE YOUR ORDER
-------------------------------------------------------------------------------
For your convenience, I can send your OpenDoors registration key
and/or source code by any of the following methods. If you are
ordering OpenDoors by mail, simply check one of these options on
your order form. If you are ordering through the third-party
credit card service, I will automatically send your order by
Internet email or conventional mail unless I receive a message
from you before you order, asking me to send it by some other
means.
-------------------------------------------------------------------------------
RECEIVING If you wish to receive your OpenDoors registration key by
ORDER BY Internet E-Mail (including Internet E-Mail to a CompuServe
INTERNET account), fill out the order form and mail it along with your
E-MAIL payment as described below. Be sure to include your e-mail
address on your order form. Note that the source code cannot be
sent via Internet e-mail.
-------------------------------------------------------------------------------
RECEIVING In order to receive your OpenDoors registration key and/or
ORDER source code by conventional mail, simply fill out the order
BY MAIL form and mail it along with your payment as described below. I
will cover the cost of postage. If your address contains non-
Roman characters, also enclose a self-addressed envelope or
mailing label.
-------------------------------------------------------------------------------
RECEIVING If you wish to receive your OpenDoors registration key by
ORDER BY FAX, fill out the order form and mail it along with your payment
FAX as described below. Be sure to include your fax number on your
order form. Do to choose this method if you are ordering the
source code.
-------------------------------------------------------------------------------
RECEIVING You may choose to receive your OpenDoors registration and/or
ORDER BY source code by calling the OpenDoors BBS after your registration
CALLING form and order fee have been received here. If you are unable to
OPENDOORS receive your order by any other electronic means (such as a call
BBS to your BBS, or by electronic mail), this may be the quickest
way for you to receive your registration information and/or
source code. The obvious disadvantage with to option is the fact
that you will have to estimate when your order will arrive here
in order to receive it as quickly as possible. You may end up
calling the OpenDoors BBS more than once before your order has
arrived. After your order form has arrived, your registration
key and/or source code will be placed on hold for you, and you
===============================================================================
OpenDoors 6.00 Manual End of Page 15
will be able to receive it on your first call to the BBS. The
phone number of the BBS is:
+1 (613) 599-5554
-------------------------------------------------------------------------------
RECEIVING In order to receive your OpenDoors registration key and/or
ORDER BY source code by a message and/or upload to your BBS, fill out
CALL TO the order form and mail it along with your payment as described
YOUR BBS below. Be sure to include the phone number, baud rate, and my
login and password for the BBS to which you would like me to
call. As always, I will cover any long distance costs. If, for
some reason, I am unable to connect to your BBS (not because it
is busy, but, for example, if your BBS is no longer online), I
will send your order by conventional mail instead.
-------------------------------------------------------------------------------
RECEIVING In order to receive your OpenDoors registration key and/or
ORDER BY source code by FidoNet CrashMail, simply fill out the order
FIDONET form and mail it along with your payment as described below.
CRASHMAIL Be sure to include the FidoNet node address to which you wish to
have your registration key and/or source code sent to (via
CrashMail). Again I will cover any long distance costs. If, for
some reason, I am unable to connect to your FidoNet system, I
will send your order by conventional mail instead.
===============================================================================
OpenDoors 6.00 Manual End of Page 16
ORDERING THE SOURCE CODE
-----------------------------------------------------------------------------
Many people also choose to order the source code along with
their OpenDoors registration. Ordering the source code will
allow you to customize OpenDoors for your own use, use parts of
the OpenDoors source code in other programs, and learn more
about how OpenDoors works. If you have any ideas for changes
that you would like to see in OpenDoors, either large or small,
ordering the source code will allow you to makes these changes
yourself, creating your own customized version of OpenDoors. You
will be able to remove copyright notices, change the way certain
OpenDoors functions work, or add new capabilities to OpenDoors
in surprisingly little time. You will also be able to use any of
the OpenDoors source code, be it the DesqView-aware code,
EMS/disk swapping routines, configuration file system,
communications routines, or anything else, in any other programs
that you write. Also, ordering the OpenDoors source code will
allow you to learn more about how OpenDoors works, and how to
program communications software and BBS door programs.
When you order the OpenDoors source code, you will receive the
source code package. The source code package also includes a
short "Source Code Manual", with a description of how the
OpenDoors source code is organized, instructions on how to
recompile the source code, and more. If you choose to receive
the source code package electronically, you will receive it in
the form of a single .ZIP file. If you choose to receive the
source code package by mail, you will receive it on a 3-1/2"
diskette.
REQUIREMENTS Due to the wide variety of compilers that are available, and the
differences between them, I have been unable to test the
OpenDoors source code with every compiler. This means that you
may need to make some changes to the source code in order to
compile it with certain compilers.
In order to compile the DOS version of OpenDoors, you must be
using a compiler that supports inline assembly language
keywords. This includes all Borland compilers released since
1991, and many other compilers. The one notable exception is
Watcom's compiler, which does not support inline assembly
language at the time of this writing.
For your information, the DOS OpenDoors libraries included with
this package were compiled using Turbo C++ 1.0 Professional. The
Win32 libraries included with this package were compiled using
Microsoft Visual C++ 2.0. This means that you can be reasonably
certain that OpenDoors will compile with these compilers and any
more recent compilers by these companies without any changes.
===============================================================================
OpenDoors 6.00 Manual End of Page 17
--------------------------------------------------------------------------
OPENDOORS 6.00 ORDER FORM
--------------------------------------------------------------------------
REGISTRATION NAME : _______________________________ (AS SHOULD APPEAR IN
REGISTRATION)
YOUR NAME : _______________________________ (IF DIFFERENT)
POSTAL ADDRESS : ______________________________________________________
______________________________________________________
______________________________________________________
E-MAIL ADDRESSES : ____________________________________ (IF APPLICABLE)
ADDITIONAL INFO : ______________________________________________________
(EG FAX/BBS PHONE NUMBER & BRIAN'S PASSWORD, IF NEEDED)
I WISH TO RECEIVE MY ORDER BY:
___ ___
| | - INTERNET E-MAIL (FASTEST) | | - I WILL CALL BRIAN'S BBS
|___| |___|
___ ___
| | - CONVENTIONAL MAIL | | - CALL TO MY BBS
|___| |___| (INCLUDE LOGIN INFO)
___ ___
| | - FAX (INCLUDE FAX #) | | - FIDONET "CRASHMAIL"
|___| |___|
___
I WOULD LIKE TO ORDER: | | - BOTH REGISTRATION KEY AND SOURCE CODE
|___| ($56 US, $68 CANADIAN, OR EQUIVALENT FUNDS)
___
| | - JUST MY REGISTRATION KEY
|___| ($28 US, $34 CANADIAN, OR EQUIVALENT FUNDS)
___
| | - UPGRADE TO SOURCE CODE (ONLY IF ALREADY
|___| REGISTERED) ($28 US, $34 CANADIAN OR EQUIV.)
I AGREE TO THE REGISTRATION TERMS, ____________________________
SET FORTH ON PAGE 20 OF THE MANUAL (SIGNATURE)
MAKE CHEQUES PAYABLE TO: BRIAN PIRIE
117 CEDAROCK DRIVE
KANATA ON K2M 2H5
CANADA
+-- OFFICIAL USE ONLY ----------------------------------------------------+
| |
| S.N. : _____________ SENT : _________________________________________ |
+-------------------------------------------------------------------------+
===============================================================================
OpenDoors 6.00 Manual End of Page 18
--------------------------------------------------------------------------
OPENDOORS 6.00 FEEDBACK FORM
--------------------------------------------------------------------------
YOUR NAME : _______________________________
WHICH OPENDOORS LIBRARY(S) DO YOU EXPECT TO USE:
___
| | - DOS VERSION, MEMORY MODELS: _________________________
|___|
___
| | - WINDOWS (WIN32) VERSION
|___|
HOW DID YOU FIRST LEARN OF OPENDOORS?
____________________________________________________________
WHICH COMPILER(S) AND VERSION(S) ARE YOU USING?
____________________________________________________________
WHAT DO YOU LIKE MOST ABOUT OPENDOORS?
____________________________________________________________
____________________________________________________________
WHAT CHANGES OR ADDITIONS WOULD YOU LIKE TO SEE IN FUTURE VERSIONS?
____________________________________________________________
____________________________________________________________
DO YOU HAVE ANY ADDITIONAL COMMENTS?
____________________________________________________________
____________________________________________________________
____________________________________________________________
-----------------------------------------------------------------------------
===============================================================================
OpenDoors 6.00 Manual End of Page 19
TERMS OF REGISTRATION AND SOURCE CODE USE
-----------------------------------------------------------------------------
When you purchase an OpenDoors registration and/or source code
license, you are entitled to almost unlimited use of all
versions of OpenDoors. However, in order to protect my
investment of time and effort in developing OpenDoors, you must
also agree to the terms outlined below when licensing OpenDoors
and/or the source code. These terms are intended to be very
reasonable, and are in no way intended to limit your use of
OpenDoors. The primary intent of these terms is that you are not
permitted to disclose your OpenDoors registration information,
or the OpenDoors source code, to other individuals. The terms of
registration and source code use are as follows:
For the purpose of these terms, "OpenDoors" is defined to be the
library files, header files, example programs and programmer's
manual of all versions, past and present, for all languages and
platforms of the OpenDoors online software programming toolkit.
In the case of a source code license, OpenDoors also refers to
the source code that is used to build OpenDoors. Upon licensing
OpenDoors, the individual or organization named on the order
form (the licensee) is entitled to use of all versions of
OpenDoors, within the terms set forth below. Violation of these
terms will be considered copyright infringement, and grounds for
the termination of the registration agreement. The licensee is
entitled, at no additional cost, to use, distribute or sell the
executable (.EXE or .COM) files that are built from OpenDoors.
The licensee is also entitled to use, distribute or sell the
example programs, example configuration files and portions of
the manual. If licensing the source code, the licensee is also
entitled to distribute or sell any executable files that result
from using altered versions of the source code, or portions
thereof, provided that it is not possible for other programmers
to access the OpenDoors API functions through this executable
file. The licensee is NOT entitled to distribute the
registration key number that is provided by Brian Pirie, nor any
portions of the OpenDoors source code. For the purposes of these
terms, an organization is considered to be a company or non-
profit organization. If the licensee is an organization, the
registration key and source code may be shared among members of
the organization, under the condition that these individuals are
using the registration and/or source code only for official
activities of that organization. These terms in no way suggest
an agreement on the part of Brian Pirie to develop any future
versions of OpenDoors, or fix any bugs in current versions of
OpenDoors. OpenDoors is offered "as is", and no warrantees are
expressed or implied. In no event shall Brian Pirie be liable
for any loss of profit or any other damage, including but not
limited to special, incidental, consequential or other damages.
===============================================================================
OpenDoors 6.00 Manual End of Page 20
3333
33 33
33
333
33
33 33
3333
-------------------------------------------------------------------------------
CHAPTER 3 - OPENDOORS TUTORIAL
ABOUT THIS MANUAL
-------------------------------------------------------------------------------
The OpenDoors programmer's manual is intended to serve as a
complete tutorial, guide and reference to writing programs with
OpenDoors. Chapter 1 of this manual, beginning on page 5,
provides an introduction and overview of the features of
OpenDoors. If you are unsure of what OpenDoors will do for you,
begin with Chapter 1. Chapter 2, beginning on page 9, provides
important information related to this evaluation copy of
OpenDoors, and how to register your copy. Chapter 3 serves as a
tutorial on OpenDoors and BBS door programming in general.
Chapter 4 provides a reference to the OpenDoors API functions
which you can use in your programs. Chapter 5 provides a
reference to the "OpenDoors control structure", which gives you
access to a wide array of information, and allows you to
customize OpenDoor's appearance and behavior. Chapter 6 provides
information on special OpenDoors features and advanced door
programming topics. Among the subjects discussed in chapter 6
are the Win32 version of OpenDoors, configuration files, multi-
node operation, RIP graphics, logfile support, defining custom
door information file formats, and more.
Chapter 7 (which begins on page 242) gives instructions on
troubleshooting programs written with OpenDoors, lists solutions
to common difficulties, and has information about the many
sources for OpenDoors support. If at any time you are having
difficulty with OpenDoors, be sure to refer to this chapter for
complete step-by-step instruction on tracing the source of your
problem, and for solutions to common difficulties with
OpenDoors. This chapter also directs you to some of the major
sources of support, including information on the OpenDoors email
conference, the OpenDoors support BBS, and how to get in touch
with me.
You will also find many useful tools in this manual, which will
no doubt come in useful while working with OpenDoors. Beginning
on page 2 is a basic table of contents, showing you how the
manual is organized, and helping you to locate general topics.
===============================================================================
OpenDoors 6.00 Manual End of Page 21
At the end of the manual, beginning on page 267, is an index to
help you locate more information on specific topics. The manual
also includes a glossary, on page 256, which will help you in
understanding new terms that you may come across while reading
the manual. At the end of the manual, you will also find several
useful sections, such as information on what is new in this
version, information on how to contact me, and information about
new OpenDoors features currently in the works.
You will likely want to print this manual, to make reading and
reference while programming easier. To print this manual, simply
type the following line from your DOS prompt. If you are worried
about the size of this manual, you might consider using a
utility that can print multiple pages of a text file on a single
sheet of paper. Printing two manual pages per side of paper
should certainly be legible, and even four-up would give you
text about the size of average newspaper text. Printing on both
sides, you should be able to fit the manual on about 34 sheets
of paper (269/8 < 34).
COMPILING A PROGRAM WITH OPENDOORS
-------------------------------------------------------------------------------
The process of compiling a program written with OpenDoors is
very similar to that of compiling any other program. However,
there are two additional steps which you must be sure to
remember:
1.) You must include the OPENDOOR.H header file.
2.) You must link your program with the appropriate OpenDoors
library file.
All programs written with OpenDoors, must "include" the
OPENDOOR.H header file. If you have placed the OPENDOOR.H header
file in the same directory as your program's source code, place
the following line at the beginning of your .C or .CPP file(s):
#include "opendoor.h"
If you have placed the OPENDOOR.H header file in the same
directory as other standard header files (such as stdio.h),
place the following line at the beginning of your .C or .CPP
file(s):
#include <opendoor.h>
===============================================================================
OpenDoors 6.00 Manual End of Page 22
In addition to including the OpenDoors header file in your
source code modules, you must also "link" the appropriate
OpenDoors library file with your program. The procedure for
doing this depends upon which compiler you are using. The
following sections describe how to link with the OpenDoors
libraries using various compilers.
LINKING WITH OPENDOORS USING A DOS COMPILER
-------------------------------------------------------------------------------
This section describes how to link with the provided OpenDoors
library files under a variety of DOS compilers. If you are using
a compiler other than those described here, refer to your
compiler's manual for information on how to link with third-
party libraries.
If you are using Borland Turbo C 2.00 or earlier, you can cause
your compiler to link your program with the OpenDoors library by
creating a text file with a .PRJ extension. In this text file,
you should list the names of your program's .C modules, along
with the name of the appropriate OpenDoors library file, as
listed in the table at the end of this section. You should then
select this Project file from within the Turbo C IDE prior to
compiling your program.
If you are using Turbo C++ or Borland C++, you can set your
compiler to link your program with the OpenDoors library by
creating a project file from within the IDE. To do this, choose
the Open Project command from the Project menu, and enter the
name for your new project file in the Load Project dialog box.
Then add the names of your program's .C/.CPP modules, along with
the name of the appropriate OpenDoors library file, by pressing
[Insert] in the project window. When you return to Turbo C++ or
Borland C++ again, you can work with the same project file by
using the Open command from the Project menu.
If you are using any Microsoft C compiler, such as Quick C,
Microsoft C or Visual C++, you can set your compiler to link
your program with the OpenDoors library by creating a makefile.
You can create a new project file from within Quick C by using
the Set Program List option from the Make menu. You can do this
from within Visual C++ by using the New command from the Project
menu. You should add the names of your program's .C/.CPP source
files, along with the name of the appropriate OpenDoors library
file, to the newly create makefile.
There are several different DOS library files included with
OpenDoors, each one for use with a different memory model. The
following chart lists the library file names, along with their
corresponding memory model. It is important that you use the
===============================================================================
OpenDoors 6.00 Manual End of Page 23
library file which corresponds to the memory model you are
using. Whenever you change your compiler to use a different
memory model, it is important to rebuild all of your source
files (using the "Build All" or "Rebuild All" command) in
addition to changing the library that your program is being
linked with. If you are unfamiliar with the concept of memory
models, you should refer to your compiler's manuals. If you are
unsure as to what memory model your compiler is currently using,
check this setting in the compile options dialog box or command
line reference information.
+------------------------------------------------+
| Library | Memory |
| Filename | Model |
|-------------|----------------------------------|
| ODOORS.LIB | DOS small memory model library |
| | |
| ODOORM.LIB | DOS medium memory model library |
| | (Available separately) |
| | |
| ODOORC.LIB | DOS compact memory model library |
| | (Available separately) |
| | |
| ODOORL.LIB | DOS large memory model library |
| | |
| ODOORH.LIB | DOS huge memory model library |
+------------------------------------------------+
To understand how to compile a program written with OpenDoors,
it is a good idea to try compiling one of the example programs,
such as ex_hello.c, that are included in the OpenDoors package.
LINKING WITH OPENDOORS USING A WINDOWS COMPILER
-------------------------------------------------------------------------------
The Win32 version of OpenDoors resides in a DLL, ODOORS60.DLL.
In order to use OpenDoors from a Win32 program, you will
typically link to an import library (although it is also
possible to use load-time dynamic linking through the use of
LoadLibrary() and GetProcAddress()). The OpenDoors package
includes a COFF-format import library for use Microsoft
compilers, named ODOORW.LIB. If you are using a compiler that
uses OMF-format object files, such as a Borland compiler, you
will need to create your own version of the odoorw.lib import
library, by using the implib utility provided with your
compiler.
When compiling an OpenDoors program with a Windows compiler, be
sure that either the WIN32 or __WIN32__ constant is defined.
===============================================================================
OpenDoors 6.00 Manual End of Page 24
Microsoft and Borland compilers define one of these constants by
default. However, if you are using a compiler from another
company, you may need to explicitly configure your compiler to
define one of these preprocessor constants.
If you are using Microsoft Visual C++ 2.0 or later, you can
setup your compiler to link with the OpenDoors import library by
creating a makefile (choose File|New|Project) and adding both
your program's .C/.CPP source file(s) and the odoorw.lib import
library to the project. When prompted for the Project type,
choose "Application", not a "MFC AppWizard". If you are using
Visual C++ 2.0, then you must manually edit the .mak file using
a text editor. In this file, replace all occurrences of
"/SUBSYSTEM:windows" with "/SUBSYSTEM:windows,4.0". This
instructs the linker to create an executable file that is
targeted for Windows 95. If you do not do this, some of the
OpenDoors visual elements will not appear correctly. Later
versions of Microsoft's compiler default to using
"/SUBSYSTEM:windows,4.0", and so this step is no longer
necessary with those compilers.
If you are using Borland C++ 4.50 or later, you must create an
OpenDoors import library for ODOORS60.DLL before you can compile
your first OpenDoors program. To do this, go to the directory
where ODOORS60.DLL is located, move the original odoorw.lib to a
backup location, and issue the command:
IMPLIB ODOORW.LIB ODOORS60.DLL
This will create a new import library (ODOORW.LIB) which you can
then use with your compiler. To compile an OpenDoors program
from the command line, issue the command:
BCC32 -tW your_program.c ODOORW.LIB
To compile an OpenDoors program from within the IDE, create a
new project file, and add both your program's source file(s) and
the OpenDoors import library to that project. If you are
compiling from within the IDE, check the TargetExpert and be
sure that you are using the multithreaded version of the the
runtime libraries. By default, the Borland IDE compiles single-
threaded, which will not work with OpenDoors.
Additional information on the Win32 version of OpenDoors is
provided in chapter 6.
===============================================================================
OpenDoors 6.00 Manual End of Page 25
RUNNING A DOOR PROGRAM WRITTEN WITH OPENDOORS
-------------------------------------------------------------------------------
This section provides information on how to run a BBS door
program that has been written with OpenDoors. If you are using
OpenDoors to write some other form of online software, the
information provided here will apply to different degrees,
depending on the nature of your program.
OpenDoors supports both local and remote modes. In the normal
mode of operation, remote mode, your program's output will be
displayed to both the local screen and the remote user's screen.
To run your program in remote mode, you will usually set it up
to run under some BBS package. However, for testing purposes, it
is often convenient to run your program in local mode.
There are several ways to start your program in local mode. The
first method is to place the example DORINFO1.DEF file in the
same directory as your program. If your program uses the
OpenDoors command line processing function, od_parse_cmd_line(),
then you can start your program in local mode by simply
specifying -local on your program's command line. For example,
you can try the example program include with OpenDoors by
issuing the command VOTEDOS -LOCAL (for the DOS version) or
VOTEWIN -LOCAL (for the Windows 95/NT version). OpenDoors will
also run in local mode if you set it up to run under a BBS
package, and log into the BBS in local mode. When the BBS runs
your door program, OpenDoors will automatically run in local
mode.
To run your program in remote mode, you will probably want to
run it under a BBS system. If you don't have a BBS package for
testing purposes, you might want to obtain a popular BBS package
such as Wildcat!, Maximus (which is free) or RemoteAccess.
RUNNING DOS-BASED DOOR PROGRAMS
-------------------------------------------------------------------------------
DOS BBS packages typically run door programs using one of two
methods. Either the BBS package directly loads and executes the
program, or it exits to a DOS batch file, which in turn executes
the door program. In either case, the BBS package produces a
door information file, common called a "drop file", which
provides information to the door program such as the name of the
current user. OpenDoors automatically supports the common drop
file formats, including DORINFOx.DEF and DOOR.SYS.
RUNNING WINDOWS 95/NT DOOR PROGRAMS
===============================================================================
OpenDoors 6.00 Manual End of Page 26
-------------------------------------------------------------------------------
This section provides information specific to running door
programs that are compiled with the Win32 version of OpenDoors.
Please feel free to include this information in your program's
manual.
Since the Win32 version of OpenDoors resides in a DLL,
ODOORS60.DLL, this file must be present on any system where your
program will be run. Although Windows 95/NT will find this file
if it is located in the same directory as your program's
executable file, it is a good idea to install this DLL into the
Windows system directory. This way, all programs using the Win32
version of OpenDoors can share the same copy of the DLL,
reducing the amount of disk space that is used.
The required setup for a Windows 95/NT door will depend upon
what BBS system it is being run under. If you the program is
being run under a native Windows 95/NT BBS system, then ideally
that BBS system will provide the ability to pass a live serial
port handle to the door program, on the program's command line.
Otherwise, you should run the door from a batch file, following
the instructions provided below for running the program under a
DOS-based BBS system. If the BBS system is able to pass a live
Window communications handle on the door's command line, and you
are using the OpenDoors standard command-line processing
function (od_parse_cmd_line()), then you can just setup the BBS
to run the program directly, using the command line:
YourProgramName.exe -handle xxxxxxxxxx
where xxxxxxxxx is the serial port handle, in decimal format.
You do not need to use the start command, nor the DTRON utility,
and you do not have to change the COM<n>AutoAssign setting in
the system.ini file.
If you are running the Win32 door program under a DOS-based BBS
system, or a Windows-based BBS system that is unable to pass a
live serial port handle to the door program, then follow these
steps:
1.Add a line of the form "COM<n>AutoAssign=<x>" to the [386Enh]
section of your system.ini file. Here, <n> specifies the
serial port number that the BBS's modem is connected to, and
<x> will usually be 0. For example, if your modem is
connected to COM1, you would add a line such as
"COM1AutoAssign=0" (sans quotes). You will then have to re-
start your computer for this change to take effect. If you do
not do this, the Windows-based door program will not be able
to access the modem.
===============================================================================
OpenDoors 6.00 Manual End of Page 27
2.Setup the BBS software to run the Windows-based door program
just as you would any other door program. You will probably
want to do this from a batch file. The command line that runs
the Windows program should be of the form:
start /w /m YourProgramName.exe [any command line
parameters]
This will cause the Windows-based door program to start in
minimized mode, and cause the calling MS-DOS session to wait
until the Windows program exits before continuing. If you do
not wish the program to be started in minimized mode, remove
the /m from the command line. If you attempt to start the
door program by calling it directly, rather than using the
"start /w" command, the BBS software will immediately start
again, cause it to attempt to run simultaneously with the
door program.
3.After running the start command, use DTRON.EXE or a similar
utility to re-enable DTR detection by the modem. Normally,
this command line will be of the form:
dtron /port x /bps y
Where x is the serial port number (0 for COM1, 1 for COM2,
etc.) and y is the locked bps rate. For example, if your
serial port is locked at 38400 bps and is connected to COM2,
you would use:
dtron /port 1 /bps 38400
For full information on the DTRON utility, simply type the
command line:
dtron /help
You may freely redistribute the DTRON utility that is
included in this package with your program.
Additional information on the Win32 version of OpenDoors, and
further explanation of some of these steps, is provided in
chapter 6.
===============================================================================
OpenDoors 6.00 Manual End of Page 28
BASICS OF DOOR PROGRAMMING WITH OPENDOORS
-------------------------------------------------------------------------------
This section provides a complete tutorial to the basics of
writing BBS door programs using OpenDoors. If you are using
OpenDoors to write other online software, much of this
information will still be relevant.
In addition to reading this section, I would encourage you to
look at the example programs included int the OpenDoors
packages. These programs, which are described beginning on page
38, will give you a much better idea of what an OpenDoors
program will look like. These programs can also serve as a great
starting point for writing your own programs using OpenDoors.
Probably the best means of introduction to door programming with
OpenDoors is by doing it yourself. As such, I strongly encourage
you to try compiling and running the simple introduction program
below. For instructions on compiling programs written with
OpenDoors, see page 22.
DOS version:
#include "opendoor.h"
main()
{
od_printf("Welcome to my first door program!\n\r");
od_printf("Press a key to return to BBS!\n\r");
od_get_key(TRUE);
od_exit(0, FALSE);
}
Win32 version:
#include "opendoor.h"
int WINAPI WinMain(HINSTANCE hInstance,
HINSTANCE hPrevInstance,LPSTR lpszCmdLine,int nCmdShow)
{
od_printf("Welcome to my first door program!\n\r");
od_printf("Press a key to return to BBS!\n\r");
od_get_key(TRUE);
od_exit(0, FALSE);
}
Keep in mind that even this simple program will automatically
have all of the door capabilities we have already mentioned.
Notice the line that reads #include "opendoor.h". All programs
written with OpenDoors must include the OPENDOOR.H header file
in order to compile correctly. The first two lines in the
main/WinMain function simply call the OpenDoors od_printf()
===============================================================================
OpenDoors 6.00 Manual End of Page 29
function. od_printf() is similar to the printf() function that C
programmers will already be familiar with. However, unlike
printf(), the od_printf() function sends the output to both the
modem and the local screen. Notice that the lines of text
displayed by the od_printf() function end with a "\n\r"
sequence, instead of the normal "\n". This is because the
terminal emulation software that is running on the remote user's
system usually requires both a carriage return and a line feed
to correctly begin a new line. The next line in our example
program is the OpenDoors single-key input function,
od_get_key(). The TRUE value causes OpenDoors to wait for a key
to be pressed (again, either from remote or local keyboard)
before returning. The last line of the main/WinMain function is
a call to od_exit(). Any program using OpenDoors should call
this function. For the time being, you can always use the (0,
FALSE) parameters.
Once again, you are encouraged to try compiling and running this
program, as described above. Congratulations, you have written
your first door program! Feel free to make any changes to this
program, and see what effects your changes have.
To simplify this example, separate versions of this program are
shown for the DOS and Win32 versions of OpenDoors. However, you
would typically write your program so that it could be compiled
using either the DOS or Win32 versions of OpenDoors, by
beginning the mainline function as follows:
#ifdef ODPLAT_WIN32
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE
hPrevInstance,
LPSTR lpszCmdLine, int nCmdShow)
#else
int main(int argc, char *argv[])
#endif
In case you are not entirely familiar with the operation of door
programs, we will now provide an introduction to the internals
of a door's operation. Keep in mind that OpenDoors automatically
carries out most of these tasks for you. When any door program
starts up, one of the first things it must do is to read the
door information file(s) (sometimes called a "drop file") passed
to it by the BBS. When a user is on-line, and wishes to run a
door, they will most likely select a command from a menu. At
this point, the BBS system (such as RemoteAccess, Maximus, PC-
Board or whatever), will create a file of information about the
system, who is currently on-line, and so on. Various BBS
packages produce various styles of door information files.
OpenDoors automatically recognizes and reads a wide variety of
door information file formats. As a result, your doors will be
able to run on a almost any BBS system.
===============================================================================
OpenDoors 6.00 Manual End of Page 30
Fortunately, OpenDoors takes care of all the work involved in
detecting and reading the door information file, and then
initializing and communicating with the serial port for you. In
order to carry out these tasks, along with setting up the status
line, and so on, OpenDoors provides a function called od_init().
If you do not explicitly call this function, the first call to
any other OpenDoors function (such as the first time your door
program outputs anything) will automatically cause the od_init()
function to be called. As a result, upon the first call to an
OpenDoors function, all of the initialization tasks for the door
will automatically be carried out. However, there may be times
when you will want your program to have access information about
the user who is on-line, or carry out other actions which
require od_init() to have been executed - prior to the point
where you call any other OpenDoors functions. In this case, you
will have to call od_init() yourself before you do any of these
things.
OpenDoors provides you with a C/C++ structure, by the name of
od_control, which allows you to access all the available
information about the user who is on-line, the system your door
is running on, and also allows you to adjust various OpenDoors
parameters. Depending on what BBS system your door is running
under, the actual information available from the od_control
structure will vary. For more information on the od_control
structure, see the section on the control structure, beginning
on page 148.
Once the door has initialized itself, it will then begin
communications with the user who is online. OpenDoors takes care
of all communications, through its various input and display
functions. When the door has finished, it will then write any
information that has changed back to the door information file
(if applicable), finish communicating with the modem, and return
to the BBS. In OpenDoors, these shut-down operations are
automatically performed you call the od_exit() function. This
function will terminate the door's activity, OPTIONALLY hang up
on the user (allowing you to provide either return to BBS or
logoff options for exiting), and then exit with the specified
errorlevel.
One other important OpenDoors function that you should be aware
of is the od_kernel() function. od_kernel() is the central
OpenDoors control function, and is responsible for much of
OpenDoor's updating of the status line, monitoring the carrier
detect and user timeout status, responding to sysop function
keys, and so on. The od_kernel() function is called
automatically by OpenDoors, within the other OpenDoors
functions. As a result, since most door programs will call some
OpenDoors function on a regular basis, you will most often have
no need to call the od_kernel() function yourself. However, if
your door is going to perform some action, such as updating data
===============================================================================
OpenDoors 6.00 Manual End of Page 31
files, during which it will not call any OpenDoors function for
more than a few seconds, you should then call the od_kernel()
function yourself. For more information on the od_kernel()
function, see page 97.
For more information on the functions available from OpenDoors,
or the control structure, see the corresponding sections in this
manual.
===============================================================================
OpenDoors 6.00 Manual End of Page 32
TOUR OF A SAMPLE DOOR PROGRAM: "EX_VOTE"
------------------------------------------------------------------------------
One of the best ways to see how OpenDoors works, and the
potential that it has, is to look at the example programs
included in the OpenDoors package. A brief description of each
of these programs can be found on page 38. This section takes a
closer look at one of the example programs, EX_VOTE.C. Unlike
our simple example in the previous section, EX_VOTE.C is a much
more complicated program, taking advantage of many of the
advanced features of OpenDoors. Even if you do not understand
everything that EX_VOTE.C does, you should be able to make use
of various elements demonstrated here, in your own programs.
The OpenDoors package includes a two compiled versions of
EX_VOTE. VOTEDOS.EXE is a plain-DOS program which can run under
DOS, Windows or OS/2. VOTEWIN.EXE was compiled using the Win32
version of OpenDoors, and so it runs only on Windows 95/NT. The
OpenDoors package also contains a sample door information file,
DORINFO1.DEF. You can use this file to test any doors in local
mode. If you wish to manually create your own DORINFO1.DEF file,
you can do so very easily. The DORINFO1.DEF door information
file is a simple text file which lists a different piece of
information on each line, in the following format:
+----------------------------------------------------------+
| LINE NUMBER | DESCRIPTION | EXAMPLE |
+-------------+------------------------+-------------------|
| 1 | Name of the BBS | MY OWN BBS |
| 2 | Sysop's first name | BRIAN |
| 3 | Sysop's last name | PIRIE |
| 4 | Com Port modem is on | COM0 |
| 5 | Baud rate, etc. | 0 BAUD,N,8,1 |
| 6 | Unused | 0 |
| 7 | User's first name | JOHN |
| 8 | User's last name | PUBLIC |
| 9 | Caller's location | OTTAWA, ON |
| 10 | ANSI mode (0=off, 1=on)| 1 |
| 11 | User's security level | 32000 |
| 12 | User's time left | 60 |
+----------------------------------------------------------+
Feel free to make any changes you wish to EX_VOTE.C, and
recompile it. One of the most effective and enjoyable ways to
learn OpenDoors is by experimenting. If you are a registered
owner of OpenDoors, you may even distribute your own versions of
this door. Also, you may find that EX_VOTE.C serves as a good
framework for building your own door programs.
The EX_VOTE.C door behaves similarly to most other door
programs, and will have a fair bit in common with any other door
===============================================================================
OpenDoors 6.00 Manual End of Page 33
you write in OpenDoors. What you see in the output window is
identical to what a remote user will be seeing. If the user has
ANSI, AVATAR or RIP mode turned on, you will see the same colors
as they do, and if they have screen clearing turned on, your
screen will be cleared when theirs is. The status line at the
bottom of the window will list the name of the user currently
on-line (if you are using the sample DORINFO1.DEF file, the
user's name will be "The Sysop"), the user's location, and the
user's baud rate (0 if the door is operating in local mode). The
local display also shows how much time the user has left,
whether the user has paged the system operator for a chat, and
other information.
There are a number of special commands that are only available
to the system operator on the local keyboard. These commands
allow the system operator to hang up on the user, adjust the
amount of time the user may remain online, enter chat mode with
the user, enter a DOS shell (in the DOS version), and so on. In
the DOS version, help on these commands is available on the
status line by pressing the [F9] key. In the Windows version,
these commands are listed on the menu that appears at the top of
the window.
Now, let us take a closer look at the actual source code for the
EX_VOTE.C door. If you have not already printed out a copy of
this manual, and possibly the EX_VOTE.C file as well, it would
probably be a good idea to do so now.
Notice that near the top of the program, along with all the
standard header files, the OPENDOOR.H file is included. This
file must be included in all programs written under OpenDoors.
If you are placing the OPENDOOR.H file in the same directory as
the door you are compiling, simply include the line:
#include "opendoor.h"
in your program.
The main()/WinMain() function of the EX_VOTE.C program has a
for(;;) loop that repeatedly displays the main menu, obtains a
choice from the user and responds to the command, until the user
chooses to exit the program. Before the main menu is displayed,
the screen is cleared by calling od_clr_scr(). The od_clr_scr()
function will clear both the local and remote screens, but only
if the user has screen clearing enabled. Refer to page 57 for
information on how to force the screen to be cleared, regardless
of the user's screen clearing setting. The main menu is
displayed using the od_printf() function, one of the most common
OpenDoors functions you will use. Next, od_get_answer() is used
to obtain a menu choice from the user from the specified set of
keys. Next, a switch() statement is used to respond to the
user's command appropriately. If the user presses the P key to
===============================================================================
OpenDoors 6.00 Manual End of Page 34
page the system operator, od_page() is called. If the user
chooses to return to the BBS, od_exit() is called to terminate
OpenDoor's activities and return control to the BBS. The FALSE
parameter passed to od_exit() indicates that OpenDoors should
not disconnect (hangup) before exiting. If the user chooses to
log off, EX_VOTE.C first confirms this action with the user, and
then calls od_exit() with the TRUE parameter. The numerical
parameter passed to od_exit() sets the errorlevel that OpenDoors
will exit with.
In its ChooseQuestion() function, EX_VOTE.C uses the OpenDoors
function od_get_key(). This function is similar to the
od_get_answer() function that we have already seen. However,
unlike od_get_answer() which will wait until the user presses
some key from the list of possibilities you provide,
od_get_key() will allow the user to press any key. od_get_key()
accepts a single parameter. If this parameter is TRUE,
od_get_key() will wait for the user to press a key before
returning. If this parameter is FALSE, od_get_key() will return
immediately with a value of 0 if there are no keys waiting in
the inbound buffer, and returning the next key if there are
characters waiting.
In a number of places, EX_VOTE.C also uses the od_input_str()
function. Unlike od_get_key() and od_get_answer() which return a
single character, od_input_str() allows the user to input and
edit a string of many characters. You will only receive the
string entered by the user after they press the enter key.
od_input_str() accepts four parameters: the string where the
user's input should be stored, the maximum number of characters
to input, the minimum character value to accept and the maximum
character value to accept.
Another new feature of OpenDoors that is used by EX_VOTE.C is
the OpenDoors control structure, od_control. This global
structure is documented in chapter 5 of this manual. The
OpenDoors control structure allows you to access a wide variety
of information about the user who is currently online, the BBS
system your program is running on, and also allows you to
control various OpenDoors settings. For example, EX_VOTE.C
compares the current user name (od_control.od_user_name) with
the name of the system operator (od_control.od_sysop_name) to
determine whether it is the system operator who using the
program.
EX_VOTE.C uses two data files, the first of which contains a
record for every user, and the second of which contains a record
for every question. EX_VOTE.C accesses these data files in a
controlled manner in order to permit the program to be running
simultaneously on multiple lines on a multi-node BBS system.
When EX_VOTE.C needs to update a data file, it opens it for
exclusive access, so that only one node can access the file at
===============================================================================
OpenDoors 6.00 Manual End of Page 35
any given time. Since the data file could have been changed by
another node since the time that EX_VOTE.C last read the file,
it always reads a record, makes changes to it and then re-writes
the record while it has the file open for exclusive access. It
then closes the file as soon as possible after opening the file,
in order to permit other nodes to once again access the file.
Because EX_VOTE.C keeps track of which questions each user has
voted on, along with the questions and results of voting on each
question, its data file format is more complex than many door
programs (although not as complex as others).
EX_VOTE.C also uses color. One of the easiest ways to use
different colors in an OpenDoors program is to use the
OpenDoor's print color-setting extensions. You can change the
color of text display at any point in an od_printf() format
string using by enclosing the name of new display color in back
quote characters (`, not '). For example:
od_printf("`red`This is in red `green`This is green\n\r");
Would cause the words "This is in red" to be displayed in red,
and the words "This is in green" to be displayed in green.
EX_VOTE.C also takes advantage of a number of OpenDoors
capabilities that you can optionally choose to include in your
door programs. You will notice that there are a number of new
lines at the beginning of the main() function, all of which
change settings in the OpenDoors control structure. The line:
od_control.od_config_file = INCLUDE_CONFIG_FILE;
causes the OpenDoors configuration file system to be included in
your program. Using this system, OpenDoors automatically reads a
configuration file that can be used by the system operator to
change various program settings. Refer to the included door.cfg
file for an example OpenDoors configuration file. In addition to
the configuration file settings automatically supported by the
configuration file system, you can also add your own
configuration file settings. To do this, you simply supply
OpenDoors with a callback function that it will call whenever it
encounters an unrecognized keyword in the configuration file.
The line:
od_control.od_config_function = CustomConfigFunction;
Causes OpenDoors to call the function CustomConfigFunction() in
EX_VOTE.C for this purpose. You will notice that the
CustomConfigFunction() receives two parameters - the first is
the unrecognized keyword, and the second is any parameters that
follow the keyword in the configuration file. EX_VOTE.C checks
for two special configuration file lines - one to set whether or
===============================================================================
OpenDoors 6.00 Manual End of Page 36
not users can add questions, and one to set whether or not users
can view the results of a question before voting on it.
The next line in the main() function,
od_control.od_mps = INCLUDE_MPS;
causes the OpenDoors "Multiple Personality System" to be
included in program. This allows the sysop to choose from a
number of status line / sysop function key "personalities" that
mimic a number of different BBS systems, using the Personality
setting in the configuration file.
The line:
od_control.od_logfile = INCLUDE_LOGFILE;
causes the OpenDoors log file system to be included in the
program. The OpenDoors log file system automatically records the
date and time of program startup, exit and other major actions
in the specified file. EX_VOTE.C also writes its own log file
entries by calling the od_log_write() function.
EX_VOTE.C also provides the ability for the sysop to provide
their own ASCII/ANSI/AVATAR/RIP files to be displayed in place
of the normal main menu. EX_VOTE.C uses the od_hotkey_menu()
function to display a VOTE.ASC/.ANS/.AVT/.RIP file for the main
menu, if such a file exists. If the file is not available, the
normal EX_VOTE.C menu is used instead. The od_hotkey_menu()
function will automatically select the appropriate file
(.ASC/.ANS/.AVT/.RIP) for the current display mode, and the user
is able to make a menu choice at any time. If a menu choice is
made before the menu is entirely displayed, the function will
stop displaying the menu and return immediately.
===============================================================================
OpenDoors 6.00 Manual End of Page 37
OTHER EXAMPLE PROGRAMS INCLUDED WITH OPENDOORS
------------------------------------------------------------------------------
In addition to the EX_VOTE.C program, which is discussed in
detail in the previous section, a number of other example
programs are included with OpenDoors. These programs help to
demonstrate what is possible with OpenDoors. They can also serve
as excellent tools to help you learn OpenDoors. In addition, you
are free to include any portions of any of these example
programs in your own programs. Below is a summary of each of
these example programs:
-------------------------------------------------------------------------------
EX_HELLO.C This an example of a very simple door program that displays a
short message and prompts for the user to press a key. After the
user presses a key, the door exits and control is returned to
the main BBS software. Despite the fact that it only consists of
a few lines of code, EX_HELLO remains a fully functional door
program. For information on compiling an OpenDoors door program,
see the section that begins on page 22.
-------------------------------------------------------------------------------
EX_CHAT.C This program is an example of a multi-window full-screen chat
door written with OpenDoors. EX_CHAT demonstrates the ease of
using sophisticated ANSI / AVATAR / RIP terminal features within
OpenDoors programs. For instructions on how to compile this
program, see the section that begins on page 22.
This program create two windows on the screen, separated by a
bar with user name / sysop name information. This program
permits communication between the local sysop and remote user by
displaying the text typed by the user in one window, and the
text typed by the sysop in the other window. When either
person's typing reaches the bottom of the window, the contents
of the window is scrolled up to provide more room for typing.
Words are also wrapped when either typist reaches the end of a
line. The advantage of a split-screen chat program is that it
permits both sysop and user to type at the same time without
difficulty. The chat function automatically invokes OpenDoor's
internal chat mode if ANSI, AVATAR or RIP modes are not
available. The display colors, window sizes and locations, and
distance to scroll a window's contents are configurable by
setting the appropriate variables, below. When the Sysop invokes
a DOS shell, a pop-up window is displayed to indicate to the
user that the door program has been suspended.
The chat feature of this program can also be easily integrated
into other doors you write, and may be used to replace the
existing OpenDoors line-oriented chat system.
===============================================================================
OpenDoors 6.00 Manual End of Page 38
-------------------------------------------------------------------------------
EX_MUSIC.C This example door demonstrates how to play "ANSI" music and
sound effects in an OpenDoors door. Included in this program is
a function to send "ANSI" music to the remote system, and a
function to text the remote system's ability to play "ANSI"
music. You may use both of these functions in your own doors, if
you wish to add music or sound effect capabilities. This program
can be compiled by following the instructions that begin on page
22.
-------------------------------------------------------------------------------
EX_SKI.C This is a simple but addictive online game that is written using
OpenDoors. In this action game, the player must control a skier
through a downhill slalom course. The user may turn the skier
left or right, and the game ends as soon as the player skis
outside the marked course. The game begins at an easy level, but
quickly becomes more and more difficult as the course to be
navigated becomes more and more narrow. The game maintains a
list of players with high scores, and this list may be viewed
from the main menu.
-------------------------------------------------------------------------------
EX_VOTE.C The EX_VOTE.C file contain the source code for the Vote example
door, as is described beginning on page 38. The Vote example
door allows users to vote on up to 200 different "polls", view
the results of voting on each question, and optionally add their
own questions for other users to answer.
===============================================================================
OpenDoors 6.00 Manual End of Page 39
444
4444
44 44
44444444
44
44
44
-------------------------------------------------------------------------------
CHAPTER 4 - THE OPENDOORS API FUNCTIONS
OVERVIEW
------------------------------------------------------------------------------
OpenDoors provides a wide set of features that you can take
advantage of in your program. You control these features and
access OpenDoors from your program using two facilities - the
OpenDoors API functions, and the OpenDoors control structure. In
general, the API functions are used to actually accomplish a
task, such as displaying something to the user, or retrieving
input from the user. The OpenDoors control structure, on the
other hand, is used to alter OpenDoors settings or retrieve
specific information.
Any program written with OpenDoors makes use of the OpenDoors
API functions for all of its door-related input and output. In
addition to the common input and output tasks, the OpenDoors API
functions provide access to many special capabilities, such as
displaying ASCII/ANSI/AVATAR/RIP files, providing pop-up windows
and menus, and much more. Much of the information about the user
who is online, information about the system your door is running
on, and settings which customize OpenDoor's behavior are
controlled through the OpenDoors control structure. The control
structure is described in the section beginning on page 148.
This chapter is divided into the following sections:
i.) TABLE OF MOST COMMONLY USED FUNCTIONS (Page 41)
ii.) TABLE OF ALL OPENDOORS FUNCTIONS (Page 42)
iii.) DETAILED INFORMATION ON EACH FUNCTION (Pages 47 - 147)
The two tables list the names of the OpenDoors functions, along
with a brief description of the task performed by each function,
and the page number on which the detailed description of that
function can be found. The first table lists only the most
commonly used OpenDoors functions, to allow you to quickly find
the function you are most likely looking for. The second table
lists all of the OpenDoors functions, grouped according to
general categories of functionality.
===============================================================================
OpenDoors 6.00 Manual End of Page 40
The section containing detailed information lists all of the
functions in alphabetical order, with the information about each
function beginning on a new page. This section includes a brief
description of each function's purpose, a detailed description
of how to use the function, the function call format, a list of
related functions, and in many cases example source code showing
you a typical use of the function.
TABLE OF MOST COMMONLY USED FUNCTIONS
------------------------------------------------------------------------------
od_printf() Displays text, with the ability to change
display color. (page 110)
od_clr_scr() Clears the screen. (Page 57)
od_input_str() Inputs a string of one or more characters
from the user. (Page 95)
od_get_answer() Inputs a single key from a list of possible
choices ignoring upper/lower case. (Page 81)
od_get_key() Inputs any single key from the user.
(Page 82)
od_set_cursor() Positions the cursor in ANSI/AVATAR/RIP
modes. (Page 134)
od_hotkey_menu() Displays an ASCII/ANSI/AVATAR/RIP file, with
the option of watching for a keypress from
the user. (Page 90)
od_popup_menu() Displays a popup menu in ANSI/AVATAR/RIP
modes. (Page 105)
od_window_create() Creates a popup window in ANSI/AVATAR/RIP
modes. (Page 145)
od_window_remove() Removes a popup window in, restoring screen
contents "underneath" window. (Page 147)
===============================================================================
OpenDoors 6.00 Manual End of Page 41
TABLE OF ALL FUNCTIONS
-------------------------------------------------------------------------------
OUTPUT TEXT DISPLAY FUNCTIONS
FUNCTIONS ----------------------
od_disp_str() Displays a normal, NULL-terminated
string. (page 63)
od_disp() Sends the specified number of
characters to the modem, with or
without local echo. (page 60)
od_printf() Performs formatted output, as the
printf() function does. Also allows
imbedded codes to change display color.
(page 110)
od_putch() Displays a single character. (page 115)
od_disp_emu() Displays a string, interpreting
imbedded ANSI/AVATAR terminal emulation
codes. (page 62)
od_repeat() Displays the same character any number
of times, using AVATAR optimization, if
possible. (page 118)
COLOR AND CURSOR CONTROL
------------------------
od_set_color() Sets current color to specified
foreground and background settings.
(page 131)
od_set_attrib() Sets current color to specified IBM-PC
display attribute. (page 128)
od_set_cursor() Sets the position of the cursor, if
ANSI/AVATAR/RIP mode is enabled. (page
134)
SCREEN MANIPULATION
-------------------
od_clr_scr() Clears the screen, if user has screen
clearing enabled. (page 57)
od_save_screen() Stores the current contents of the
screen, to be later redisplayed using
od_restore_screen(). Works in all
display modes. (page 121)
od_restore_screen() Restores the contents of the screen, as
previously stored using
===============================================================================
OpenDoors 6.00 Manual End of Page 42
od_save_screen(). Works in all display
modes. (page 120)
BLOCK MANIPULATION
------------------
od_clr_line() Clears the remainder of current line.
(page 55)
od_gettext() Stores any area of the screen, to later
be displayed by od_puttext(). Requires
ANSI/AVATAR/RIP graphics mode. (page
89)
od_puttext() Displays text with color information,
as previously stored using
od_gettext(). Requires ANSI/AVATAR/RIP
graphics mode. (page 116)
od_scroll() Scrolls a portion of the screen in
ANSI/AVATAR/RIP graphics modes. (page
123)
POPUP WINDOWS AND MENUS
-----------------------
od_draw_box() Draws a box on the screen in
ANSI/AVATAR/RIP graphics mode. (page
65)
od_window_create() Displays a popup window, storing the
screen contents "under" the window.
Requires ANSI/AVATAR/RIP graphics mode.
(page 145)
od_window_remove() Removes a popup window displayed with
od_window_create(), restoring the
original screen contents "under" the
window. Requires ANSI/AVATAR/RIP
graphics mode. (page 147)
od_popup_menu() Displays a menu in a popup window,
allowing the user to choose menu items
either by pressing a "hot" key, or
moving a highlighted selection bar.
After menu selection, the menu may be
removed, restoring the original screen
contents "under" the window. Requires
ANSI/AVATAR/RIP graphics mode. (page
105)
===============================================================================
OpenDoors 6.00 Manual End of Page 43
FILE DISPLAY FUNCTIONS
----------------------
od_send_file() Displays an ASCII/ANSI/AVATAR/RIP file
(for instance, an .ANS file created by
a program such as "TheDraw" (page 124)
od_hotkey_menu() Displays an ASCII/ANSI/AVATAR/RIP menu
file, with hotkeys active. (page 90)
od_list_files() Lists the files available for download
in an area, using a FILES.BBS file.
(page 98)
-------------------------------------------------------------------------------
INPUT od_get_answer() Inputs a single key from the keyboard,
FUNCTIONS allowing only particular responses.
(page 81)
od_get_input() A more flexible version of
od_get_key(), that also supports
extended keys such as arrow keys,
insert, etc. (page 82)
od_get_key() Inputs a single key from the keyboard,
optionally waiting if a key is not
available. (page 82)
od_input_str() Inputs a string of specified length,
from the keyboard. (page 95)
od_edit_str() Formatted string editing function,
requiring ANSI/AVATAR/RIP graphics.
(page 68)
od_multiline_edit() Provides a text editor that allows the
user to enter or edit text that spans
multiple lines, such as email messages
or text files. (page 101)
od_clear_keybuffer() Removes any waiting keys from the
keyboard input queue. (page 53)
-------------------------------------------------------------------------------
COMMON od_page() Allows the user to page the sysop.
DOOR (page 101)
ACTIVITY
FUNCTIONS od_spawn() OpenDoors "quick" spawn function.
Executes an external program (eg. file
compressor, external protocol, etc.) on
===============================================================================
OpenDoors 6.00 Manual End of Page 44
a separate screen, restoring the
OpenDoors screen afterwards. (page 139)
od_spawnvpe() OpenDoors full-featured spawn function.
Executes an external program on a
separate screen, searching the path for
the program, allowing you to specify an
environment to pass to the child
process, and returning the errorlevel
returned by the child process. (page
143)
od_log_write() Adds an entry to the end of the log
file. (page 100)
od_parse_cmd_line() Handle standard command line options.
(page 105)
-------------------------------------------------------------------------------
SPECIAL od_init() Begins door operation by setting up
CONTROL the OpenDoors control structure,
FUNCTIONS setting up the local screen,
initializing the serial port (if
applicable), and reading the door
information file. (page 92)
od_color_config() Transfers a color configuration line to
a color attribute value. (page 59)
od_add_personality() Adds a custom status line/control key
personality to OpenDoors. (page 47)
od_set_statusline() Temporarily alters the setting of the
current OpenDoors status line. (page
137)
od_autodetect() Automatically determines the remote
terminal software's graphical
capabilities. (page 48)
od_kernel() The central OpenDoors control function,
which should be executed every few
seconds. (page 97)
od_exit() Ends door operations, closing the
serial port driver, re-writing the door
information file, and optionally
returning control to the BBS. (page 79)
===============================================================================
OpenDoors 6.00 Manual End of Page 45
od_carrier() Allows detection of carrier signal in
programs that have disabled OpenDoors
internal checking. (page 51)
od_set_dtr() Controls the DTR signal to the modem.
Can be used to manually disconnect a
remote user, in order to perform
activities such as call back
verification. (page 135)
od_chat() Forces OpenDoors to enter chat mode,
even if sysop did not press the "chat"
key. (page 50)
od_sleep() Suspends program execution, yielding
control to other tasks in a
multitasking environment. (page 139)
===============================================================================
OpenDoors 6.00 Manual End of Page 46
OD_ADD_PERSONALITY()
-------------------------------------------------------------------------------
PURPOSE Installs a custom status line / sysop function key personality
into OpenDoors.
FORMAT BOOL od_add_personality(char *pszName, BYTE btOutputTop,
BYTE btOutputBottom, OD_PERSONALITY_PROC *pfPerFunc);
RETURNS TRUE on success
FALSE on failure
DESCRIPTION If used, this function should be called before any other
OpenDoors API functions. This function installs a new
personality into OpenDoors. The first parameter specifies the
string that will be used to identify the personality. This is
the string that the user will be able to supply in the
configuration file to select this personality, and is also the
string that can be passed to od_set_personality() to manually
switch to this personality. The second and third parameters
specify the 1-based to and bottom line numbers of the output
window to be used with this personality. For instance, a top
value of 1 and bottom value of 23 would cause all door output to
be displayed on the first 23 lines of the screen, leaving the
bottom two lines for use by the personality's status line. The
last parameter is a pointer to the personality function, which
OpenDoors will call to perform various operations with that
involve the personality. For more information on personalities
and the OpenDoors Multiple Personality System, see the section
which begins on page 233.
This function only has an effect under the DOS version of
OpenDoors.
SEE ALSO od_set_personality(), od_set_statusline()
===============================================================================
OpenDoors 6.00 Manual End of Page 47
OD_AUTODETECT()
-------------------------------------------------------------------------------
PURPOSE Attempts to automatically determine the terminal capabilities of
the remote system.
FORMAT void od_autodetect(int nFlags);
RETURNS N/A
DESCRIPTION This function can be used to determine whether or not the remote
terminal supports ANSI and/or RIP (Remote Imaging Protocol)
graphics modes. This information is usually supplied to the door
by the BBS software, through the door information file. For this
reason, most door programs do not need to make used of this
function. However, if your door will be running under any BBS
software that does not report the ANSI or RIP capabilities of
the remote system, you may wish to use this function.
od_autodetect() will set either of the following OpenDoors
control structure variables to TRUE if the corresponding
graphics mode is detected:
od_control.user_ansi - TRUE if ANSI mode is available
od_control.user_rip - TRUE if RIP mode is available
However, if either of these variables have previously been set
to TRUE (either explicitly by your program, or due to the
corresponding modes being enabled in the door information file),
and od_autodetect() does not detect the corresponding graphics
mode, they will not be set to FALSE. Not all terminal software
that supports ANSI or RIP graphics mode will necessarily have
the ability to report their graphics mode capabilities to the
door. For this reason, failure to detect either of these modes
does not necessarily indicate that they are not available.
However, if these modes are detected by od_autodetect(), it is
safe to assume that the remote system does support the detected
mode.
The nFlags parameter is reserved for future use, and should
always be set to DETECT_NORMAL.
This function cannot auto-detect AVATAR mode, because there is
no standard means of determining whether a remote system
supports AVATAR mode.
EXAMPLE Below is an example of using od_autodetect() in determining the
remote terminal's graphics capabilities. Since not all terminal
software supports auto-detection, this example will also prompt
===============================================================================
OpenDoors 6.00 Manual End of Page 48
the user to determine their software's capabilities if
od_autodetect() fails to detect ANSI mode. This code assumes
that if the terminal software supports the autodetection of ANSI
mode, that it will also support the autodetection of RIP mode.
OpenDoors assumes that ANSI mode is always available in
conjunction with RIP mode.
/* Call the automatic terminal detection function */
od_autodetect();
/* If ANSI mode was not detected, ask the user about
if(!od_control.user_ansi)
{
/* Prompt the user for ANSI capabilities */
od_clr_scr();
od_printf("Does your system support ANSI graphics?");
od_printf(" (Y/N)");
/* If the user chooses [Y]es */
if(od_get_answer("YN") == 'Y')
{
/* Turn on ANSI mode */
od_control.user_ansi = TRUE;
/* Since ANSI mode is present, RIP mode may also */
/* be available. Prompt the user for RIP. */
od_printf("\r\n\n");
od_printf("Does your system support RIP graphics?");
od_printf(" (Y/N)");
/* If the user chooses [Y]es */
if(od_get_answer("YN") == 'Y')
/* Turn on RIP mode */
od_control.user_rip = TRUE;
/* Since ANSI mode is present, AVATAR mode may */
/* also be available. Prompt the user for AVATAR. */
od_printf("\r\n\n");
od_printf("Does your system support AVATAR ");
od_printf("graphics? (Y/N)");
/* If the user chooses [Y]es */
if(od_get_answer("YN") == 'Y')
/* Turn on AVATAR mode */
od_control.user_avatar = TRUE;
}
od_printf("\r\n\n");
}
===============================================================================
OpenDoors 6.00 Manual End of Page 49
OD_CHAT()
-------------------------------------------------------------------------------
PURPOSE Manually invokes sysop chat mode.
FORMAT void od_chat(void);
RETURNS N/A
DESCRIPTION Normally, the OpenDoors sysop chat mode will only be invoked
when the sysop explicitly requests it using the sysop chat key.
However, there may be some cases where you wish to manually
invoke the sysop chat mode. One example is when you are
replacing the OpenDoors built-in chat mode with your own, but
still wish to use the OpenDoors chat mode under some
circumstances. For instance, you may wish to use your own split-
screen chat routine if ANSI, AVATAR or RIP graphics mode is
available, and use the OpenDoors line-oriented chat mode if only
ASCII mode is available.
SEE ALSO od_page()
EXAMPLE For an example of using the od_chat() function, see the
ex_chat.c example door, which is described on page 38.
===============================================================================
OpenDoors 6.00 Manual End of Page 50
OD_CARRIER()
-------------------------------------------------------------------------------
PURPOSE To determine the status of the carrier detect signal, in
programs where OpenDoors' internal carrier detection has been
disabled.
FORMAT BOOL od_carrier(void);
RETURNS TRUE if a carrier is present, or
FALSE if no carrier is present, or in local mode.
DESCRIPTION Usually, you will not have any use for the od_carrier()
function, as OpenDoors automatically monitor's the carrier
detect signal, and will correctly recover if the carrier detect
signal is lost while the door is operating in remote mode.
However, in some programs, you may wish to disable OpenDoors'
internal carrier detection routines, using the
od_control.od_disable variable. Two such cases in which you
might want to do this, are a call-back verification door, which
disconnects the user and attempts to call them back, or in a
terminal program, which is in fact not a door at all (and as
such you would not want to have OpenDoors exit when the carrier
detect signal is lost). In cases like these, you will then be
able to use the od_carrier() function in order to determine the
state of the carrier detect signal.
This function will return a Boolean value (for more information
on Boolean values, see the Glossary which begins on page 256),
of either TRUE or FALSE. If a carrier detect signal is present
when the function is called, it will return TRUE, and if no
carrier detect signal is detected, it will return FALSE. Since
there is no remote connection, and thus no carrier when
OpenDoors is operating in local mode, this function will always
return a value of FALSE in local mode.
SEE ALSO od_set_dtr()
EXAMPLE As an example of the use of this function, let us consider a
call back verification door, which hangs up on the user, and
then calls the user back at their entered phone number, in order
to verify the correctness of that number. This program would
probably contain a function that is responsible for
disconnecting the user, waiting for the connection to be broken,
and then phoning the user. At some point in this function,
likely just prior to the point where the function hangs up on
===============================================================================
OpenDoors 6.00 Manual End of Page 51
the user, you would disable OpenDoors' internal carrier
detection, using the line:
od_control.od_disable |= DIS_CARRIERDETECT;
You would then want to have a piece of code which would simply
wait up to a given amount of time for the carrier signal to
drop. If this occurs, you would continue to place the call, and
if it does not occur, you would probably try your hangup
procedure one or two more times. In this example, the function
will return with a value of FALSE if the carrier signal does not
drop, and will return a value of TRUE if it does.
char hangup(void)
{
clock_t timer;
char to_return = FALSE;
od_set_dtr(FALSE); /* Hangup modem */
/* Wait up to 30secs */
timer = clock() + CLOCKS_PER_SEC * 30;
while(timer >= clock())
{ /* If carrier has been lost, return with success */
if(!od_carrier())
{
to_return = TRUE;
break;
}
}
od_set_dtr(TRUE); /* Re-enable DTR signal */
return(to_return);
}
===============================================================================
OpenDoors 6.00 Manual End of Page 52
OD_CLEAR_KEYBUFFER()
-------------------------------------------------------------------------------
PURPOSE Function to clear the input keyboard buffer
FORMAT void od_clear_keybuffer(void);
RETURNS N/A
DESCRIPTION OpenDoors maintains its own keyboard input buffer, in order to
permit the user to "type ahead" - to send input to the door
prior to the time when it is ready to process those key presses.
For example, the user could begin to type a command while a menu
is still being displayed, and when your door reaches the point
of inputting the menu command, the characters already typed by
the user will already be waiting for the OpenDoors input
functions. Note that the keyboard input buffer will include both
the keys hit by the user on-line, and the non-function keys (ie,
Alt-C will not appear in the OpenDoors keyboard buffer), hit by
the sysop. This allows both the user on-line and the sysop to
control the door at any time. If the sysop wishes to temporarily
prevent the user from having any control over the door, the
sysop may use the Alt-K (user-keyboard off) key. The key strokes
placed in the OpenDoors type-ahead buffer will be retrieved by
the od_get_key() and od_input_str() functions. The keyboard
buffer can contain a maximum of 64 user keystrokes in this
version of OpenDoors, after which any additional keystrokes will
simply be discarded by OpenDoors.
There are times, however, when you will want to erase any keys
that have been hit by the user, to prevent them from typing
ahead. For example, if your door has been busy doing some
processing for a few moments, they user may have been pressing
keys on their keyboard - perhaps in the hope that doing so will
speed things up. These keys will be waiting in the type-ahead
buffer, and if one of the keys the user entered was a valid
response to the next prompt in your door, the user may find that
they have accidentally made a choice they did not wish to. A
well designed door will simply erase the contents of the type-
ahead buffer after any long period of internal processing, etc.
Keep in mind that too much use of the od_clear_keybuffer()
function can be just as undesirable as not using it all, as
there are times when the presence of the keyboard buffer can
prove to be very useful for the user of a door.
To erase the contents of the type-ahead buffer, you simply call
the od_clear_keybuffer() function. This function takes no
parameters, and does not return any value.
===============================================================================
OpenDoors 6.00 Manual End of Page 53
SEE ALSO od_get_key(), od_input_str(), od_edit_str()
EXAMPLE For one example of the use of the od_clear_keybuffer() function,
see the example program EX_VOTE.C, which is described beginning
on page 38. Below is another example of using this function. In
this case, we present a simple function, wait_for_return(),
which simply pauses for the user to press their [Enter]/[Return]
key. The function begins by displaying a prompt asking for the
[Enter] or [Return] key to be pressed. The function then clears
the keyboard input buffer, and waits until the user presses the
carriage return key, using the od_get_key() function. Note also
that this function will only continue if the user has pressed
the correct key. This is a good idea in all door programs, as it
allows your door to distinguish between a character pressed by
the user, and a "line noise" character.
void wait_for_return(void)
{ /* Display prompt */
od_disp_str("Please Press [Enter] to continue...\n\r");
od_clear_keybuffer(); /* Clear keyboard buffer */
while(od_get_key(TRUE) != 13); /* Wait for Enter key */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 54
OD_CLR_LINE()
-------------------------------------------------------------------------------
PURPOSE Clears the rest of the current display line
FORMAT void od_clr_line(void);
RETURNS N/A
DESCRIPTION This function clears the line that the cursor is on, from the
cursor position to the end of the line. After the rest of the
line is cleared, the cursor is automatically returned to the
position it was at prior to issuing the command. Hence, if the
display line the cursor was located on looked as follows, with
the underscore (_) character representing the cursor position:
This is a_line of text!
With the cursor between the words "a" and "line", after the
od_clr_line command is issued, the line would appear as follows:
This is a_
With the cursor directly following the word "a". Note that this
function places a space character at the cursor location, and
every location up to the end of the line.
When the door is running in plain ASCII mode, this command will
simply clear the rest of the line by manually sending a series
of space and backspace characters. When ANSI, AVATAR or RIP
modes are active, the corresponding ANSI/AVATAR control sequence
will be sent in order to accomplish the line clear. Since the
graphics mode sequences are much shorter than the sequence that
would be required to clear the line manually, the use of this
function will cause your door's graphics to display much more
quickly when ANSI, AVATAR or RIP modes are active. Also note
that in ANSI, AVATAR or RIP graphics modes, the line will be
cleared with the currently selected color attribute. Thus, if
you wanted to place a blue background on a particular line, you
would use the od_set_color() (or od_set_attrib()) function, then
use the od_set_cursor() function to locate the cursor at the
beginning of the desired line, followed by the od_clr_line()
function. Just such a procedure is demonstrated in the example,
below.
SEE ALSO od_clr_scr(), od_set_cursor()
===============================================================================
OpenDoors 6.00 Manual End of Page 55
EXAMPLE Below, is an example of a function that clears an entire line
with a specified color. Since this function performs operations
that require ANSI, AVATAR or RIP graphics mode, it should only
be used in a case where these modes are known to be available.
For example, this function would be useful in a full-screen
editor or viewer, or when performing ANSI animations. The
function accepts three parameters: the line to be cleared (where
1 is the first line, 2 the second, and so on), the foreground
color of this line, and the background color of this line.
This function differs from the od_clr_line() function itself in
several important manners. First of all, this function clears
the entire line, whereas the od_clr_line() function can be used
to clear only the remaining characters of the line, after any
particular location. Also, as mentioned before, this function
selects a color to clear the line to, and moves the cursor to
the line which is to be cleared - neither of which is done by
the od_clr_line() function.
void clear_line(char line_number,char foreground,char
background)
{
od_set_cursor(line_number,1); /* move to correct line */
od_set_color(foreground,background); /* set color */
od_clr_line(); /* clear entire line */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 56
OD_CLR_SCR()
------------------------------------------------------------------------------
PURPOSE The OpenDoors clear screen function
FORMAT void od_clr_scr(void);
RETURNS N/A
DESCRIPTION The od_clr_scr() function can be used to clear the output
screen. (ie, the user's screen and local screen with the
exception of the status line are cleared.) This function will
only clear the screen if screen clearing is enabled. If your
program will be running under BBS systems that do not pass the
user's screen clearing setting to the door, you may wish to
determine yourself whether or not the user's system supports
screen clearing codes, during the first time the user uses the
door. You will then be able to store this setting in a data
file. The example below demonstrates how to detect whether or
not the user's system supports screen clearing.
You should note that the ability for the user's terminal to
support screen clearing codes is independent of the user's ANSI
/ AVATAR / RIP graphics mode settings.
For more information on the user's screen clearing setting,
please refer to the user_attrib variable in the OpenDoors
Control Structure chapter of this manual. If you wish to force a
screen clear, regardless of the user's screen clearing setting,
simply use the function call:
od_disp_emu("\xc", TRUE);
SEE ALSO od_clr_line()
EXAMPLE Below is an example of a function which determines whether or
not the user's system supports screen clearing. This function
will return a value of TRUE if screen clearing is supported, and
will return a value of FALSE if screen clearing is not
supported:
int user_supports_screen_clearing(void)
{
char answer;
/* display instructions to user */
od_disp_str("In order for this door to function\n\r");
od_disp_str("correctly, we must know whether or not\n\r");
===============================================================================
OpenDoors 6.00 Manual End of Page 57
od_disp_str("your system supports screen clearing.\n\r");
od_disp_str("In a moment, we will attempt to clear\n\r");
od_disp_str(
"your screen in order to test your system's\n\r");
od_disp_str("capabilities.\n\r\n\r");
od_disp_str("Please press [Enter]/[Return] when you\n\r");
od_disp_str("are ready to perform this test.\n\r");
while(od_get_key(TRUE)!=13); /* wait for [Return] key */
od_clr_scr(); /* attempt to clear screen */
/* ask user if their screen cleared */
od_disp_str("Did your screen just clear? (Y/N)\n\r");
for(;;) /* loop until user chooses [Y]es or [N]o */
{
answer=od_get_key(TRUE); /* Get user's answer */
if(answer=='y' || answer=='Y') return(TRUE);
if(answer=='n' || answer=='N') return(FALSE);
}
}
===============================================================================
OpenDoors 6.00 Manual End of Page 58
OD_COLOR_CONFIG()
-------------------------------------------------------------------------------
PURPOSE Parses a color configuration line from the configuration file,
generating a color attribute value.
FORMAT BYTE od_color_config(char *pszColorDesc);
RETURNS Color attribute value
DESCRIPTION This function will be of use if you are using the configuration
file system of OpenDoors, and wish to allow the sysop to specify
text colors to be used in your door. While OpenDoors
automatically recognizes color configuration settings for things
such as sysop chat mode and FILES.BBS listings, you may wish to
add additional color configuration options. In this case, you
could call the od_color_config() function from your custom line
function. For more information on the custom line function, see
the section on the OpenDoors configuration file system, which
begins on page 224.
To use this function, simply pass the configuration file line
you wish to have parsed to the function in it's single
parameter. The function will then return a color attribute value
in the same format that is used but the od_set_attrib()
function. Colors are specified using a string of the format:
{Flashing} {Bright} [foreground] on [background]
Where "Flashing" is an optional keyword indicating that the text
should be flashing. "Bright" is an optional keyword indicating
that the foreground color should be bright. Foreground is the
name of a foreground color, and background is the name of a
background color. Case (upper or lower) is not significant.
The color keywords are language configurable, using the array
od_control.od_color_names.
EXAMPLE See the example accompanying in the section on the OpenDoors
configuration file system, which begins on page 224.
===============================================================================
OpenDoors 6.00 Manual End of Page 59
OD_DISP()
------------------------------------------------------------------------------
PURPOSE Sends a buffer of text with optional local echo
FORMAT void od_disp(char *pachBuffer, INT nSize, BOOL bLocalEcho);
RETURNS N/A
DESCRIPTION This function allows you to send a buffer of text of any
specified length, with the option of enabling or disabling local
echo. You will probably have little use for this function -
instead you will most likely display strings using either the
od_disp_str() or od_printf() functions, depending on whether or
not you wish to use printf()'s formatting options. For a
breakdown of the uses of the various OpenDoors display
functions, see the description of the od_disp_str() function, on
page 63.
There are two cases when this function will come in useful:
1.)If you wish to display a buffer of characters of known
length, which may contain null (ASCII 0) characters.
Since this character is used by the C language to
indicate the end of a string, the other two string
display functions (od_disp_str() and od_printf()) will
not send this character to the remote system.
2.)If you wish to send text to the remote system without
having it displayed on the local screen, or if you wish
to send strings to the modem when it is in command
mode, without having these characters displayed on the
local screen.
The od_disp() function is called with three parameters. The
first parameter, pachBuffer, is a pointer to a buffer of
characters you wish to have displayed. The second parameter,
nSize, is simply the number of characters in the buffer to be
displayed. If the third parameter, bLocalEcho, is set to TRUE,
then all characters sent to the modem will also be displayed on
the local screen. If the third parameter is set to FALSE, then
the buffer will be sent to the modem without being echoed to the
sysop's screen.
SEE ALSO od_disp_str(), od_printf(), od_putch(), od_repeat(),
od_disp_emu()
===============================================================================
OpenDoors 6.00 Manual End of Page 60
EXAMPLES The following are a few examples of the use of the od_disp()
function:
In order to display a single character, contained in the
variable "character", without echo to the local screen:
od_disp(&character,1,FALSE);
In order to send a command to the modem (only if you know that
the modem is in command mode), with the command contained in the
null-terminated string "string":
od_disp(string,strlen(string),FALSE);
In order to send exactly 5 characters from the buffer "buffer",
WITH echo to the local screen:
od_disp(buffer,5,TRUE);
===============================================================================
OpenDoors 6.00 Manual End of Page 61
OD_DISP_EMU()
-------------------------------------------------------------------------------
PURPOSE Displays a string with ANSI/AVATAR terminal emulation
FORMAT void od_disp_emu(char *pszToDisplay, BOOL bRemoteEcho);
RETURNS N/A
DESCRIPTION The od_disp_emu() function allows you to display your own ANSI /
AVATAR graphics sequences. This function passes the characters
you wish to display to the OpenDoors terminal emulator, which is
fully documented in the description of the od_send_file()
function, on page 124. This function can be used to send these
control sequences to the user's terminal, and also have them
displayed on the local screen as they will appear to the user.
The string passed to od_disp_emu() contains any stream of text
to display, and may include both normal text and terminal
emulation control sequences. If the bRemoteEcho parameter is set
to TRUE, the string passed to od_disp_emu() will be sent to the
remote terminal in addition to being displayed locally. If this
parameter is set to FALSE, the string will only be displayed
locally.
Note that if you wish to display an entire file containing
ANSI/AVATAR/RIP graphics sequences (perhaps as your program's
menu or title screen), you can use the od_send_file() function.
SEE ALSO od_send_file(), od_disp(), od_disp_str() od_printf().
For a breakdown of the uses of the various OpenDoors display
functions, see the od_disp_str() function, on page 63.
EXAMPLE For an example of the use of the od_disp_emu() function, see the
SpaceRight() and MoveLeft() functions included in the example
program ex_ski.c.
===============================================================================
OpenDoors 6.00 Manual End of Page 62
OD_DISP_STR()
-------------------------------------------------------------------------------
PURPOSE Displays a string to the screen (remote and local)
FORMAT od_disp_str(char *pszToDisplay);
RETURNS N/A
DESCRIPTION The two functions most often used for displaying strings within
a door are the od_disp_str() and od_printf() functions. The
od_printf() function allows for formatted output, whereas the
od_disp_str function simply displays the actual contents of the
string passed to it. If you wish to display a single character,
use the od_putch() function. If you wish to send a string or
buffer to the modem without local echo, use the od_disp()
function. If you wish to send a sequence of the same character
to the modem, the od_repeat() function will use graphics control
codes, if available to display the sequence much faster than
simply sending the same character in repetition. Also, if you
wish to send ANSI, AVATAR or RIP graphics control codes, and
have them emulated on the local screen, use the od_disp_emu()
function.
The od_disp_str() function displays the contents of the null-
terminated string pointed to by *string. Display is sent to both
the local screen and modem (presuming the door is not running in
local mode).
An important thing to keep in mind when using the od_disp_str()
function, is that you should use "/n/r" instead of simply "/n"
for a new line. This is due to the fact that terminal programs
usually require a carriage-return line-feed sequence (/n/r),
instead of just a line-feed (/n). For example, instead of using:
od_disp_str("Hello world!\n");
You should use:
od_disp_str("Hello world!\n\r");
To change the cursor color or location of output with the
od_disp_str() function, refer to the od_set_cursor() and the
od_set_attrib() functions.
SEE ALSO od_disp(), od_printf(), od_putch(), od_repeat(), od_disp_emu()
===============================================================================
OpenDoors 6.00 Manual End of Page 63
EXAMPLES Below are a few examples of various uses of the od_disp_str()
function:
Displaying three string constants on separate lines:
od_disp_str("This is an example\n\r");
od_disp_str("of the OpenDoors\n\r");
od_disp_str("od_disp_str() function\n\r");
Displaying three string constants on the same line:
od_disp_str("Another ");
od_disp_str("od_disp_str() ");
od_disp_str("example\n\r");
Displaying a string variable:
char string[80];
strcpy(string,"This is a string!\n\r");
od_disp_str(string);
===============================================================================
OpenDoors 6.00 Manual End of Page 64
OD_DRAW_BOX()
-------------------------------------------------------------------------------
PURPOSE Draws a box on the screen in ANSI, AVATAR or RIP graphics modes.
FORMAT BOOL od_draw_box(BYTE btLeft, BYTE btTop, BYTE btRight, BYTE
btBottom);
RETURNS TRUE on success, FALSE on failure
DESCRIPTION This function is for use in ANSI, AVATAR or RIP graphics modes.
This function will draw a box in the current display attribute,
at the specified location on the screen. The boarder of the box
is made up of the characters specified in the od_control.
od_box_chars[] array. If AVATAR graphics mode is available, this
function uses AVATAR control codes to display the box in less
than 1/10 the length of time required to display the box in ANSI
mode.
The first two parameters of this function, btLeft and btTop,
specify the coordinates of the top, left-hand corner of the box
to be draw. The third and fourth parameters, btRight and
btBottom, specify the coordinates of the bottom, left-hand
corner of the box. Like the values passed to the od_set_cursor()
function, these coordinates are relative to the upper left-hand
corner of the screen, with the position (1,1) being this corner.
As mentioned above, this function will display the window in the
current text color. Thus, before calling this function, you
should use either the od_set_color() or the od_set_attrib()
function to specify the color in which you would like to have
the window displayed.
Normally, the boarder of the window will be displayed using the
IBM extended ASCII characters which produce a single line
boarder. However, you may wish to have the boarder displayed
using different characters. In this case, the characters used to
display the boarder can be specified by the od_control.
od_box_chars variable, described in the OpenDoors control
structure section of this manual.
SEE ALSO od_set_color(), od_set_attrib(), od_clr_scr(), od_edit_str(),
od_set_cursor()
EXAMPLE As an example of the use of the od_draw_box() function in
conjunction with the od_edit_str() function, we show a portion
of a program which displays a window, and allows the user to
input the name of a file they would like to upload, a
===============================================================================
OpenDoors 6.00 Manual End of Page 65
description of the file, and whether they want it to be a
private upload. The user is able to move among fields using the
tab key, and select a "continue" button when they are finished.
The function returns TRUE if the user selects continue, and
FALSE if the user presses [ESCape].
// Main "dialog box" function
int get_information(char *filename, char *description,
char *private)
{
char current_field=1; // Currently selected field
int choice; // User's choice
od_set_color(L_WHITE,D_BLUE); // Display window
od_draw_box(10,5,70,13);
od_set_cursor(5,25); // Display window title
od_set_color(L_GREEN,D_BLUE);
od_disp_str(" ENTER FILENAME INFORMATION ");
od_set_color(L_CYAN,D_BLUE); // Display fields and titles
od_set_cursor(6,15);
od_disp_str("FILENAME : ");
od_repeat(176,13);
od_set_cursor(7,12);
od_disp_str("DESCRIPTION : ");
od_repeat(176,43);
od_set_cursor(8,16);
od_disp_str("PRIVATE : ");
od_repeat(176,2);
draw_button();
filename[0]='\0'; // Blank out contents of input variables
description[0]='\0';
private[0]='\0';
for(;;) // Main dialog box loop
{
if(current_field==4) // If field is the button
{
od_set_color(L_GREEN,D_BLUE); // Highlight button
draw_button();
do // Loop until user presses [TAB], [ENTER], or [ESC]
{
choice=od_get_key(TRUE);
} while(choice!=9 && choice!=13 && choice!=27);
od_set_color(L_CYAN,D_BLUE); // Un-highlight button
draw_button();
if(choice==13) return(TRUE); // If [ENTER] was pressed
===============================================================================
OpenDoors 6.00 Manual End of Page 66
if(choice==27) return(FALSE); // If [ESC] was pressed
current_field=1; // Otherwise, [TAB] was pressed
}
switch(current_field) // According to selected field
{ // Input from the appropriate line
case 1:
choice=od_edit_str(filename,"FFFFFFFFFFFF",6,26,
0x1b,0x1a,176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_FIELD_MODE|
EDIT_FLAG_KEEP_BLANK);
break;
case 2:
choice=od_edit_str(description,
"*******************",
7,26,0x1b,0x1a,176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_FIELD_MODE|
EDIT_FLAG_KEEP_BLANK);
break;
case 3:
choice=od_edit_str(private,"Y",8,26,
0x1b,0x1a,176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_FIELD_MODE);
}
// If user pressed [ESCape]
if(choice==EDIT_RETURN_CANCEL) return(FALSE);
// If user choice to go to previous field
if(choice==EDIT_RETURN_PREVIOUS)
{
if(current_field==1) // If at first field
current_field=4; // Go to last field
else // If not at first field
--current_field; // Go to previous field
}
else // If user chose next field
++current_field; // Go to next field
}
}
void draw_button(void) // Function to display the button
{
od_draw_box(12,10,23,12); // Draw box for button
od_set_cursor(11,14);
od_disp_str("Continue"); // Display text in button
}
===============================================================================
OpenDoors 6.00 Manual End of Page 67
OD_EDIT_STR()
-------------------------------------------------------------------------------
PURPOSE Allows you to perform formatted input with full line editing
features, etc., in ANSI/AVATAR/RIP graphics mode.
FORMAT WORD od_edit_str(char *pszInput, char *pszFormat, INT nRow,
INT nColumn, BYTE btNormalColor, BYTE btHighlightColor,
char chBlank, WORD nFlags);
RETURNS This function will return one of the following values:
EDIT_RETURN_ERROR Indicates that an error has occurred,
and the edit function was unable to
run. This will occur if there is an
error in one of the parameters, or if
ANSI/AVATAR/RIP graphics is not
available
EDIT_RETURN_CANCEL Indicates that the user pressed the
cancel key [ESC], and that the string
was left unaltered.
EDIT_RETURN_ACCEPT Indicates that the user pressed the
accept key [Enter], or that the auto-
enter feature was activated.
EDIT_RETURN_PREVIOUS Indicates that the user wishes to move
to the previous field, by pressing [UP
ARROW], [SHIFT]-[TAB], etc.
EDIT_RETURN_NEXT Indicates that the user wishes to move
to the next field, by pressing [DOWN
ARROW], [TAB], etc.
DESCRIPTION To perform string input within OpenDoors, one of two functions
can be used, od_input_str() and od_edit_str(). The first
function, od_input_str(), allows simple line input and editing,
and can be used in ASCII, ANSI, AVATAR and RIP modes. The second
function, od_edit_str(), allows many formatted input options,
advanced line editing, and other features, but requires the use
of ANSI, AVATAR or RIP terminal modes.
As mentioned above, the od_edit_str() function allows for
advanced line editing, such as inputting and deleting text from
the middle of the string (whereas the od_input_str() function
only allows editing from the end of the string, such as
backspacing to erase a mistake). The edit functions available
from the od_edit_str() are listed below. Note that some of these
===============================================================================
OpenDoors 6.00 Manual End of Page 68
functions may or may not be available, depending upon the
capabilities of the user's terminal program. While there is no
single standard used for the transmission of special edit keys
such as the arrow keys, the od_edit_str() function makes as much
effort as possible to make all of the edit features available to
most terminal programs. Many of the edit functions can be
accesses using either [CONTROL]-key combinations or special keys
such as the arrow keys, delete key, and so on. OpenDoors will
recognize most of these special control keys when sent as either
an ANSI control sequence (which is sent by most terminal
programs), or as a DoorWay style scan code / ASCII code sequence
(which is also available from many terminal programs, but is not
usually required). The od_edit_str() edit functions are as
follows. Note that all edit functions are always available from
the local keyboard.
HOME - Moves the cursor to the beginning of the line being
edited. Press the [HOME] key, either in DoorWay mode
or from the local keyboard.
END - Moves the cursor to the end of the line being edited.
Press the [END] key, either in DoorWay mode or from
the local keyboard.
DELETE CHARACTER - Deletes the character under the cursor. Press
[DELete] on the local keyboard, in DoorWay mode, and
under many terminal programs without DoorWay mode.
Alternatively, press [CONTROL]-[G].
BACKSPACE - Deletes the character left of the cursor. Press
[BACKSPACE] or [CONTROL]-[H].
TOGGLE INSERT MODE - Switches the od_edit_str() function between
insert mode and overwrite mode. Press [INSert], either
in DoorWay mode, or from the local keyboard.
Alternatively, press [CONTROL]-[V].
CURSOR LEFT - Moves the cursor left one character. Press [LEFT
ARROW] on the local keyboard, in DoorWay mode, and
under many terminal programs without DoorWay mode.
Alternatively, press [CONTROL]-[S].
CURSOR RIGHT - Moves the cursor right one character. Press
[RIGHT ARROW] on the local keyboard, in DoorWay mode,
and under many terminal programs without DoorWay mode.
Alternatively, press [CONTROL]-[D].
ERASE ENTIRE LINE - Press [CONTROL]-[Y].
ACCEPT INPUT - Press the [ENTER] / [RETURN] line to accept the
input. Alternatively, press [CONTROL]-[Z]. Note that
this key will only work when the current input is
===============================================================================
OpenDoors 6.00 Manual End of Page 69
"valid" (ie, it conforms to the format string, which
is described below)
CANCEL INPUT - Only available if specifically enabled on the
od_edit_str() command line. Press [ESCape].
NEXT FIELD - If enabled, allows the user to move to the next
field in a dialog box / form. Press [DOWN ARROW] in
DoorWay mode and under many terminal programs without
DoorWay mode. Alternatively, press [TAB]. Note that
the [DOWN ARROW] key is NOT usually available from the
local keyboard, as it is usually used to adjust the
user's remaining time.
PREVIOUS FIELD - If enabled, allows the user to move to the
previous field in a dialog box / form. Press [UP
ARROW] in DoorWay mode and under many terminal
programs without DoorWay mode. Alternatively, press
[SHIFT]-[TAB] on the local keyboard or in DoorWay
mode. Again, note that the [UP ARROW] key is NOT
usually available from the local keyboard, as it is
usually used to adjust the user's remaining time.
Let us now look at the parameters which the od_edit_str()
function accepts. The first parameter, pszInput, is a pointer to
the string where the user's input should be stored. It is
important that this string be long enough to accommodate the
longest input your format string will permit, including the '\0'
C string terminator (ie, the string should be one character
greater than the length of the format string, not including the
format string's ' and " characters).
The second parameter, pszFormat, is a pointer to a string which
specifies the format and maximum length of the input the
od_edit_str() function should accept. Using the format string,
not only do you specify the length of the input field, but you
can also force the user's input into certain formats. For
example, if you wished to input a North American style phone
number, you could use a format string of "###-###-####". Then
regardless of whether the user typed any dash character or not,
their input would be converted, as they type, to the format of
the phone number 613-599-5554. You could also specify a format
string such of "MMMMMMMMMMMMMMMMMMMMMMMMMMMMMM", which would
permit the user to enter a name of up to 30 characters. Note
that since the cursor can be moved to the position immediately
following the last character, a the input field for a 30
character string will occupy 31 columns on the screen. The
od_edit_str() function would then automatically capitalize the
name, so that the first character of each word is capitalized,
and the remain characters of the word is in lower case. Even if
the user were to move the cursor to the middle of the string
===============================================================================
OpenDoors 6.00 Manual End of Page 70
they had entered, and add or delete a space (and thus either
make one work two or two words one), od_edit_str() would re-
format the string to reflect the change. The valid characters
for the format sting, along with their meanings, are listed
below. Note that the format string is NOT case sensitive (except
for literal strings delimited by the '' or "" characters), and
space characters can be added at any point to increase
legibility.
# Indicates that numeric characters from '0' to '9' are valid
for this position
% Indicates that numeric characters from '0' to '9', and the
space character (' ') are valid for this position.
9 Indicates that numeric characters from '0' to '9', along
with '.', '-' and '+' are valid for this position. This
format style is intended for floating-point numeric input.
? Indicates that any character is valid for this position.
* Indicates that any printable character, from ASCII 32 to
ASCII 127, is valid for this position.
A Indicates that alphabetical characters 'A' to 'Z', 'a' to
'z' and space (' ') are valid for this position.
C Indicates that city name characters are valid for this
position. As with the 'M' format character, words are
automatically capitalized so that the first letter is in
upper case, and all subsequent letters are in lower case.
In addition to permitting alphabetical characters and the
space (' ') character, the ',' and '.' characters are also
accepted in this position.
D Indicates that date characters '0' to '9', '-' and '/' are
valid for this position.
F Indicates that MS-DOS filename characters are valid for
this position.
H Indicates that hexidecimal character '0' to '9', 'A' to 'F'
and 'a' to 'f' are valid for this position.
L Indicates that only lower case alphabetical characters 'a'
to 'z', and the space (' ') character is valid for this
position. However, if the user attempts to enter an upper
case alphabetical character in this position, it will
automatically be converted to the lower case equivalent.
M Indicates that name characters are valid for this position.
These characters are the alphabetical characters 'A' to
===============================================================================
OpenDoors 6.00 Manual End of Page 71
'Z', 'a' to 'z', and the space character (' '). A
character's case is converted such that the first character
of a word is in upper case, and all other letters are in
lower case.
T Indicates that telephone number character '0' to '9', '(',
')', '-' and ' ' are valid for this position.
U Indicates that only upper case alphabetical characters 'A'
to 'Z', and the space (' ') character is valid for this
position. However, if the user attempts to enter a lower
case alphabetical character in this position, it will
automatically be converted to the upper case equivalent.
W Indicates that MS-DOS filename characters are permitted in
this position, including the '*' and '?' wildcard
characters.
X Indicates that alphanumeric characters 'A' to 'Z', 'a' to
'z', '0' to '9' and ' ' are valid for this position.
Y Indicates that yes/no characters 'Y', 'N', 'y', 'n' are
valid for this position. The characters are automatically
converted to upper case.
'/" Single or double quotes can be used to specify sequences of
characters that should appear at the same location in the
input string (referred to elsewhere as "literal strings").
When the user is entering the string, these characters are
automatically supplied, and the user is not required to
type them. Literal strings must begin and end with the same
quote character. Remember that the double quote (")
character must be imbedded in C strings by preceding the
quote character with a \ (backslash) character.
The third and fourth parameters, nRow and nColumn specify the
location on the screen where the first (left most) character of
the input field should be located. These parameters are
identical to the nRow and nColumn parameters passed to the
od_set_cursor() function. In other words, nRow specifies the
line number on the screen, where 1 is the first line, and
nColumn specifies the column across the screen, where 1 is the
first column.
The fifth and sixth parameters, btNormalColor and
btHighlightColor, allow you to specify the color of the input
field. The fifth parameter, btNormalColor, specifies the color
of the input field when input is not taking place and the sixth
parameter, btHighlightColor, specifies the color of the field
while input is taking place. Thus, if you had several input
fields on the screen at one time, you would be able to make is
easier for the user to identify the currently active field by
===============================================================================
OpenDoors 6.00 Manual End of Page 72
having the field currently accepting input highlighted in a
color distinct from the other fields. When the od_edit_str()
function begins, it will change the current color of the field
from the normal color to the highlighted color. Then, when the
od_edit_str() function exits, it will change the current color
of the field back to its normal color. If you do not wish to
have the field highlighted, you can set both of these parameters
to the same value, and disable field re-drawing by using the
eighth parameter, flags.
The seventh parameter accepted by the od_edit_str() function,
chBlank, will serve one of two purposes. Normally, this
parameter will specify a background character to display in the
unfilled portion at the end of the input field. This can be set
to a character, such as the ASCII 177 grey block character, to
produce a visual background to the field. Doing this will show
the user visually how long the field is, and how many character
they will be permitted to type into the field. Normally, this
field will be displayed during input, and removed when the
od_edit_str() function exits. However, you may cause the
background to remain in place using the eighth parameter, flags.
If you do not wish to have this "background" visual field
effect, simply set the character parameter to a space (ASCII
32). In password input mode, this parameter will instead specify
the character to display in place of characters typed by the
user. In this case, the background display character defaults to
the space (ASCII 32) character.
The eighth, and last, parameter accepted by the od_edit_str()
function is the nFlags parameter. This parameter is a bit-mapped
flags variable which allows you to control special features of
the od_edit_str() function. More than one of these settings may
be specified by listing a chain of the values, separated by the
bitwise-or (|) operator. If you do not wish to turn on any of
these modes, simply pass the EDIT_FLAG_NORMAL value as the flags
parameter.
EDIT_FLAG_NORMAL - Default setting, use this value of none of
the other flags below are active.
EDIT_FLAG_NO_REDRAW - When set, prevents the od_edit_str()
function from re-drawing the input string and field
when it starts up and exits. If you set this flag, the
normal color and highlight color should contain the
same value. If background character (the character
parameter) is not a space (ASCII 32) character, you
must draw the field background prior to calling
od_edit_str(). Also, if you are calling od_edit_str()
with the EDIT_FLAG_EDIT_STRING flag set, you must
display the existing string in the field prior to
calling od_edit_str().
===============================================================================
OpenDoors 6.00 Manual End of Page 73
EDIT_FLAG_FIELD_MODE - Setting this flag specifies that
od_edit_str() should operate in field input mode. In
field input mode, the user may finish entering their
input by pressing the previous field or next field
button (arrow keys, tab keys, etc.), as described
above. If the user chooses to finish and accept their
input by pressing one of these keys, the od_edit_str()
return value will reflect which choice they made. This
will allow you to make it possible for the user to
move between a number of input fields in a form /
dialog box, as demonstrated in the example
accompanying the od_draw_box() function.
EDIT_FLAG_EDIT_STRING - Setting this flag specifies that
od_edit_str() should edit a pre-existing string,
instead of starting with a blank string. In this case,
the input_string parameter MUST point to an
initialized string. This string may either contain
some text, or be empty, but od_edit_str() will expect
to find a string terminator ('\0') character, and will
begin editing the contents of the string prior to that
character. If you do not set the EDIT_FLAG_EDIT_STRING
flag, the previous contents of the input_string
parameter is not significant, as od_edit_str() will
automatically start with a blank string.
EDIT_FLAG_STRICT_INPUT - Setting this flag causes the
od_edit_str() function to operate in "strict" input
mode, which may be desirable if your input format
contains more than one type of input. Normally, if you
were inputting such a string, the user would be able
to move to the middle of the string, and insert any
text. Doing so would cause the rest of the input line
to shift right. However, in cases where your format
string specifies different types of character to be
permitted in different positions, this can cause the
input to be changed so that it no longer conforms to
the format string. In this case, the user's input will
no longer be valid, and the user will not be able to
exit the function by pressing [ENTER] (although
[ESCAPE] will still be available, if you activated it)
until they change their input. However, when strict
input mode is turned on, od_edit_str() will restrict
the ways in which the user is permitted to edit the
string, to prevent just such a case from occurring.
EDIT_FLAG_PASSWORD_MODE - Setting this flag causes the
od_edit_str() function to operate in "password" mode.
In password mode, the characters typed by the user
will be hidden, displayed instead as the blank
character specified in the "character" parameter.
===============================================================================
OpenDoors 6.00 Manual End of Page 74
EDIT_FLAG_ALLOW_CANCEL - When this flag is set, the user will be
able to cancel their current input and abort the
editing process by pressing their [ESCAPE] key. When
they do so, any changes they have made to the input
field will be canceled, and replaced by the original
contents of the string. The od_edit_str() function
will then exit, indicating that the user has canceled
their input.
EDIT_FLAG_FILL_STRING - When set, this flag will force the user
to enter a string that fills the entire length of the
format string. Normally, the user will be able to
enter a string of any length up to the maximum length
specified by the format string. However in some cases,
such as when inputting a date, you will want to have
the input field filled. (Otherwise, the user would be
able to enter only the first part of the date.)
EDIT_FLAG_AUTO_ENTER - When set, this flag will cause the
od_edit_str() function to automatically simulate
pressing of the [ENTER] key when the string is filled.
This can be used to cause the od_edit_str() function
to finish inputting as soon as a valid string is
entered, instead of having to wait for the user to
press [ENTER] / [RETURN].
EDIT_FLAG_AUTO_DELETE - When set, along with the
EDIT_FLAG_EDIT_STRING flag, this flag will activate
the auto-delete feature of the od_edit_str() function.
When auto-delete is active, if the first key pressed
by the user is not an edit control key, the existing
text will automatically be deleted, and a totally new
string accepted from the user. This could be useful
when you are allowing the user to go back to edit a
previous input. If the user wishes to only change part
of the old string, they can move the cursor to the
location where they wish to make the change, and
perform their editing. However, if the user wishes to
completely replace the old string with a new one, they
can simply begin to type, and the old string will
automatically be deleted, and the new string accepted.
EDIT_FLAG_KEEP_BLANK - Normally, OpenDoors will only display the
input field background (as passed in the "character"
parameter) while the user is editing the string, and
will remove it when the od_edit_str() function exits.
However, you may wish to continue having this field
displayed after input has taken place, and the
od_edit_str() function has exited. In this case,
setting this flag will cause the background characters
to remain visible after input has finished.
===============================================================================
OpenDoors 6.00 Manual End of Page 75
EDIT_FLAG_PERMALITERAL - When the format string contains literal
characters (such as forcing a ':' character to be
added to a time input by using the format string
"##':'##':'##"), the od_edit_str() function can
operate in one of two modes. In the default mode, the
literal characters will only be displayed when they
have been automatically added to the string. For
instance, if you were inputting the current time using
the above format string, this mode would result in the
input field initially being blank. When the user types
the first digit of the time, that number would appear.
When the user types the second digit of the time, that
number will appear, and then the colon character will
automatically be added by OpenDoors. However, you can
also set the od_edit_str() function to operate in
"PermaLiteral" mode, by setting this flag. When the
EDIT_FLAG_PERMALITERAL flag is set, the input field
will initially contain the literal characters (ie, the
colons in our example), with the cursor still located
at the leftmost position in the input field. In this
mode, the literal character become a permanent part of
the input field, and can not be moved or deleted by
the user - instead the cursor simply skips over the
literal character's position.
EDIT_FLAG_LEAVE_BLANK - This flag applies to the special case
where the first character or characters of the format
string are literals. By default, the od_edit_str()
function will always return a string containing at
least these first literal characters. However, you can
alter this behaviors by setting this flag. When set,
if no non-literal characters have been entered in the
string, od_edit_str() will return an empty string.
EDIT_FLAG_SHOW_SIZE - Normally, od_edit() adds an extra blank to
the end of the input field, to give the cursor a space
to move into when the field is full. However, you may
prefer to have the input field be shown as exactly the
maximum size of input that is permitted. Setting
EDIT_FLAG_SHOW_SIZE does just this. In this case, the
cursor will be positioned immediately past the end of
the input field when the maximum number of characters
have been entered.
SEE ALSO od_input_str(), od_get_char(), od_clear_keybuffer()
EXAMPLE Below are several examples of typical uses of the od_edit_str()
function. For the sake of simplicity, all of these examples
perform their input beginning at the top, left hand corner of
the screen, and store the user's input in the string variable
===============================================================================
OpenDoors 6.00 Manual End of Page 76
named "string". For an example of the user of the od_edit_str()
function in a dialog-box / form entry application, see the
example accompanying the od_draw_box() function.
To input a name with a maximum of 25 characters, having the
first letter of each word automatically capitalized:
od_edit_str(string, "MMMMMMMMMMMMMMMMMMMMMMMMM", 1, 1,
0x03, 0x21, 176, EDIT_FLAG_NORMAL);
To input a North American style phone number, requiring that all
digits be filled, and running in "strict input" mode:
od_edit_str(string, "###'-'###'-'####",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_FILL_STRING|
EDIT_FLAG_STRICT_INPUT);
To allow the user to edit a previously entered 20 character
string, with auto-delete mode on. Any characters will be
permitted in the string. Remember that when the
EDIT_FLAG_EDIT_STRING flag is set, the string must be
initialized prior to calling the od_edit_str() function.
od_edit_str(string, "????????????????????",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_AUTO_DELETE);
To input a password of up to 16 characters from the user. Here,
the password will only be permitted to contain upper case
characters, and the od_edit_str() password mode is used, with a
small block displayed in place of any characters typed:
od_edit_str(string, "UUUUUUUUUUUUUUUU",
1, 1, 0x03, 0x21, 254,
EDIT_FLAG_PASSWORD_MODE);
To input a two-digit number from the user, requiring that both
digits be filled, and automatically accepting the input after
the two digits have been entered (not requiring the user to
press [ENTER]):
od_edit_str(string, "##", 1, 1, 0x03, 0x21, 176,
EDIT_FLAG_FILL_STRING|
EDIT_FLAG_AUTO_ENTER);
To input a filename to download, as a field in a dialog box.
Here, the filename will be permitted to contain valid filename
characters, and the od_input_str() function will operate in
field mode, with the cancel [ESCape] key enabled. Also, string
===============================================================================
OpenDoors 6.00 Manual End of Page 77
edit mode will be enabled, allowing the user to edit a
previously entered line, and the EDIT_FLAG_KEEP_BLANK flag will
be set, causing the field background to remain displayed after
the user exits. This time, however, auto-delete mode will not be
used. Note that this combination of parameters expects that the
field and it's contents will have already been displayed, prior
to calling the od_edit_str() function.
od_edit_str(string, "WWWWWWWWWWWW",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_FIELD_MODE|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_KEEP_BLANK);
To input a string without the field background and line
redrawing before and after input takes place:
od_edit_str(string, "******************************",
1, 1, 0x07, 0x07, ' ',
EDIT_FLAG_NO_REDRAW);
To input a date, using PermaLiteral mode. Here, the month is
entered by a three digit short form ("JAN", "FEB", etc.), and
the literal characters such as the '-' and the "19" are a
permanent part of the input field:
od_edit_str(string,"UUU'-'##'-19'##",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_PERMALITERAL|
EDIT_FLAG_FILL_STRING);
===============================================================================
OpenDoors 6.00 Manual End of Page 78
OD_EXIT()
-------------------------------------------------------------------------------
PURPOSE The OpenDoors program termination function
FORMAT void od_exit(INT nErrorLevel, BOOL bTermCall);
RETURNS N/A
DESCRIPTION You MUST USE THIS FUNCTION when you want your program to exit.
This function will close the serial port, re-write changed
information to the door information (drop), call your end-of-
program function (if any), and then exit with the errorlevel
specified in the first parameter.
Also, if the second parameter, bTermCall, is set to TRUE,
od_exit() will also log the user off (for options such as
logging off within the door - as shown in the example below).
This is accomplished by lowering the DTR line to the modem,
causing the modem to hangup. When control is returned to the
BBS, it will then detect that the user is no longer online, and
will carry out its own logoff processing.
If you wish for your program to always perform any activities
prior to exiting, such as updating or closing data files, you
should set a function to be executed from within the od_exit()
function. This is accomplished by using the od_control.
od_before_exit variable, as described in the section on the
OpenDoors control structure in chapter 5. Use of this variable
will allow your program to always carry out these activates,
even if OpenDoors decides to call the od_exit() function itself,
such as when a user hangs up on the door.
Note that in special cases, you may use the
od_control.od_disable variable to prevent the od_exit() function
from re-writing the door information file. Also, you may use the
od_control.od_noexit variable to shutdown door operations
without actually exiting your program. Both of these variables
are described in chapter 5.
SEE ALSO od_init()
EXAMPLE The example below demonstrates a function which a door could
execute when the user chooses to exit the door. This function
will ask the user whether they wish to exit the door and return
to the BBS, simply logoff of the BBS, or continue using the
door. The example function will then call od_exit() if the user
===============================================================================
OpenDoors 6.00 Manual End of Page 79
wishes to exit the door, or return control to the function which
called it, if the user does not wish to exit:
void goodbye(void)
{
char pressed;
/* Display choices to user */
od_disp_str("You have chosen to exit this door.\n\r");
od_disp_str("Do you wish to:\n\r");
od_disp_str(" [R]eturn to the BBS\n\r");
od_disp_str(" [L]ogoff of the BBS\n\r");
od_disp_str(" [C]ontinue using the door\n\r");
for(;;) /* loop until user makes valid choice */
{
pressed=od_get_key(TRUE); /* Get key from user */
/* If user selects R, exit without hanging up */
if(pressed=='R' || pressed=='r') od_exit(40,FALSE);
/* If user selects L, hangup and then exit */
if(pressed=='L' || pressed=='l') od_exit(41,TRUE);
/* If user selects C, return and allow door to continue */
if(pressed=='C' || pressed=='c') return;
}
}
===============================================================================
OpenDoors 6.00 Manual End of Page 80
OD_GET_ANSWER()
-------------------------------------------------------------------------------
PURPOSE Function to allow the user to respond to a prompt using only
certain keys.
FORMAT char od_get_answer(char *pszOptions);
RETURNS Character that user entered
DESCRIPTION This function can be used to get a response from the user, when
only particular responses should be accepted. The parameter to
the od_get_answer() function is simply a string listing the
valid responses. The function will wait until the user selects
one of the valid responses, and then return that response. The
function is case insensitive, and will return the character in
the same case that was supplied to it in the string.
SEE ALSO od_get_key(), od_hotkey_menu()
EXAMPLES od_get_answer("YN");
- If the user presses 'y', will return 'Y'.
od_get_answer("yn");
- If the user presses 'y', will return 'y'.
od_get_answer("ABC 123\n\rZ");
- Valid responses will be: [A], [B], [C], [SPACE],
[1], [2], [3], [ENTER], [Z]
===============================================================================
OpenDoors 6.00 Manual End of Page 81
OD_GET_INPUT()
-------------------------------------------------------------------------------
PURPOSE This function allows a single input event (e.g. keystroke) to be
retrieved, optionally translating extended key sequences such as
arrow keys and the insert key.
FORMAT BOOL od_get_input(tODInputEvent *pInputEvent,
tODMilliSec TimeToWait, WORD wFlags);
RETURNS TRUE on success, FALSE if no input event was retrieved.
DESCRIPTION Like od_get_key(), od_get_input() can be used to retrieve a
single key of input from the user. However, od_get_input() has
been designed to be easily extended in future versions of
OpenDoors. The information retrieved by this new function is
placed in a structure, which contains information on whether the
input event was generated by the remote user or the local
console, and what type of input event it was. This function also
has built-in the ability to recognize and translate the multiple-
character sequences that are generated when the user presses
extended keys such as arrow keys, insert, delete, etc.
The first parameter points to a tODInputEvent structure, which is
defined as follows:
typedef struct
{
tODInputEventType EventType;
BOOL bFromRemote;
char chKeyPress;
} tODInputEvent;
When od_get_input() successfully retrieves an input event, this
structure is filled with information about the input. The
EventType member can be either EVENT_CHARACTER (indicating a
single character keystroke) or EVENT_EXTENDED_KEY (indicating an
extended key, such as an arrow key). In the case of
EVENT_CHARACTER, chKeyPress is set to the character that was
received. In the case of EVENT_EXTENDED_KEY, chKeyPress is set to
one of the following values:
===============================================================================
OpenDoors 6.00 Manual End of Page 82
+------------------+---------------+-------------------------+
| chKeyPress Value | Meaning | Control Key Alternative |
+------------------+---------------+-------------------------+
| OD_KEY_F1 | [F1] | None |
| OD_KEY_F2 | [F2] | None |
| OD_KEY_F3 | [F3] | None |
| OD_KEY_F4 | [F4] | None |
| OD_KEY_F5 | [F5] | None |
| OD_KEY_F6 | [F6] | None |
| OD_KEY_F7 | [F7] | None |
| OD_KEY_F8 | [F8] | None |
| OD_KEY_F9 | [F9] | None |
| OD_KEY_F10 | [F10] | None |
| OD_KEY_UP | [UP ARROW] | [CTRL]-[E] |
| OD_KEY_DOWN | [DOWN ARROW] | [CTRL]-[X] |
| OD_KEY_LEFT | [LEFT ARROW] | [CTRL]-[S] |
| OD_KEY_RIGHT | [RIGHT ARROW] | [CTRL]-[D] |
| OD_KEY_INSERT | [INSERT] | [CTRL]-[V] |
| OD_KEY_DELETE | [DELETE] | [CTRL]-[G] |
| OD_KEY_HOME | [HOME] | None |
| OD_KEY_END | [END] | None |
| OD_KEY_PGUP | [PAGE UP] | None |
| OD_KEY_PGDN | [PAGE DOWN] | None |
| OD_KEY_SHIFTTAB | [SHIFT]-[TAB] | None |
+------------------+---------------+-------------------------+
The bFromRemote member of the tODInputEvent structure will be set
to TRUE if the input event originated from the remote system, or
FALSE if the event originated from the local system.
The second parameter, TimeToWait specifies how long the function
should wait for input before returning, in milliseconds. A value
of 0 causes the function to return immediately if no input is
waiting in OpenDoor's internal input buffer. The is equivalent to
a value of FALSE being passed to the od_get_key() function. A
value of OD_NO_TIMEOUT causes this function to wait and only
return after the next input event has been received. This is
equivalent to a value of TRUE being passed to the od_get_key()
function. An other value specifies the maximum number of
milliseconds that od_get_input() should wait for input. If input
is received before this time elapses, od_get_key() will return
immediately with a value of TRUE, and the tODInputEvent structure
will be fill accordingly. If no input is received before this
time elapses, od_get_key() will return FALSE. The number of
milliseconds to wait is rounded to the nearest 55 milliseconds in
the DOS version of OpenDoors.
The third parameter allows you to specify flags to further
control the behavior of od_get_input(). Normally, this parameter
will be set to GETIN_NORMAL. However, you can disable all
translation of extended keystrokes by setting this value to
GETIN_RAW. In this mode, od_get_input() works just like
===============================================================================
OpenDoors 6.00 Manual End of Page 83
od_get_key(), returning every individual character received from
the remote system.
Since extended keys are not directly supported by all terminal
programs, od_get_input() provides alternatives for some of the
extended keys, in the form of control-key combinations. The
control key combinations recognized by od_get_input() are listed
in the table above. However, these control key alternatives can
be ignored by setting the GETIN_RAWCTRL flag.
The od_get_input() function is used internally by
od_popup_menu(), od_edit_str() and od_multiline_edit().
SEE ALSO od_get_key(), od_clear_keybuffer()
EXAMPLE The following example shows the structure of how od_get_input()
might be used in your program:
tODInputEvent InputEvent;
od_get_input(&InputEvent, OD_NO_TIMEOUT, GETIN_NORMAL);
if(InputEvent.EventType == EVENT_EXTENDED_KEY)
{
switch(InputEvent.chKeyPress)
{
case OD_KEY_UP:
/* The up arrow key has been pressed. */
break;
case OD_KEY_DOWN:
/* The down arrow key has been pressed. */
break;
}
}
else if(InputEvent.EventType == EVENT_CHARACTER)
{
/* A single character key has been pressed, and is */
/* stored in InputEvent.chKeyPress. */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 84
OD_GET_KEY()
-------------------------------------------------------------------------------
PURPOSE Function to input a key from the user
FORMAT char od_get_key(BOOL bWait);
RETURNS The next key waiting from the keyboard, or 0 if none.
DESCRIPTION This function retrieves the next key waiting in the OpenDoors
keyboard buffer (see the description of the od_clear_keybuffer()
function, on page 53, for more information on the OpenDoors
keyboard buffer). The od_get_key() function allows your door to
retrieve both those keystrokes pressed by the user, and the
keystrokes pressed on the sysop keyboard (other than the sysop
function keys), in the sequence they were pressed. Since input
is accepted from both sources, it is possible for the sysop, as
well as the remote user, to make selections and control the
door.
Door input with OpenDoors can be accomplished with this
function, with the od_input_str() function or with the
od_edit_str() function. The od_input_str() and od_edit_str()
functions is used to input an entire sequence of characters from
the user (a string), and requires the user to press the [Enter]
key when they are finished typing their input. On the other
hand, the od_get_key() function is used to input a single
keystroke (one character) from the user, and allows the user to
make choices without having to press the enter key.
The od_get_key() function accepts a single parameter, which
determines whether or not it should wait for the user to press a
key, if they have not already done so. If you pass a FALSE value
to od_get_key(), then the function will not wait for a key to be
pressed at the keyboard, but instead return a 0 if there are no
keys waiting in the buffer. If you pass a TRUE value to
od_get_key(), then this function will instead wait for a key to
be pressed. Also, while waiting for the user to press a key, the
od_get_key() function will give up the processor to other
waiting programs, if you door is running under DesqView.
If you are waiting for the user to make a choice from a menu or
list of options, you will most likely pass a TRUE to the
od_get_key() function, indicating that you wish for it to wait
until a key is pressed. However, if you wish to continue other
processing if no key is yet available from the keyboard, you
should pass a FALSE to the od_get_key() function. For example,
if you are displaying a screen of text, and wish to allow the
user to pause or abort the display, you would simply call the
===============================================================================
OpenDoors 6.00 Manual End of Page 85
od_get_key() function every few moments, passing it a value of
FALSE. You would then be able to check if any control keys have
been pressed, and if not, continue displaying text.
The od_get_key() function returns the ASCII value representing
the keystroke that was made. If you are waiting for the user to
make a particular choice, perhaps from a menu, you will most
likely store the value returned by od_get_key() in a variable of
type char. For example:
char key;
...
key=od_get_key(TRUE);
You would then be able to determine which key the user pressed
by testing the value of key, either by comparing it's numerical
ASCII value, or by comparing it to a character constant. If you
are testing for a non-character key, such as [ESCape], [Tab] or
[Return], you may wish to use the ASCII value of that key. For
example, if you wished to take some action in the case that the
user presses the [Enter]/[Return] key, who's ASCII value is 13,
you could do:
key=od_get_key(TRUE); /* Get keypress from user */
if(key==13) /* If key was [Enter]/[Return] */
{
... /* Whatever you want to do */
}
If you wish, instead, to respond to the user pressing a
character key (perhaps as a choice from a menu), you can do so
by using character constants, such as 'c', '6', or 'F'. Also,
when testing for an alphabetical character, you will probably
want to check for the user pressing either the upper or lower-
case version of the letter. For example, if you wished to have
the user press the [Y] key to continue, you could test for
either an upper or lower-case Y as follows:
key=od_get_key(TRUE); /* Get keypress from user */
if(key=='y' || key=='Y') /* If key was [y]/[Y] */
{
... /* Whatever you want to do */
}
The charts on the following page lists the decimal value and corresponding
keystroke(s) of each of the ASCII values from 0 to 127.
===============================================================================
OpenDoors 6.00 Manual End of Page 86
ASCII KEYSTROKE | ASCII KEYSTROKE
----- ------------------------------ | ----- ----------------------
0 [Control]-[@] | 15 [Control]-[O]
1 [Control]-[A] | 16 [Control]-[P]
2 [Control]-[B] | 17 [Control]-[Q]
3 [Control]-[C] | 18 [Control]-[R]
4 [Control]-[D] | 19 [Control]-[S]
5 [Control]-[E] | 20 [Control]-[T]
6 [Control]-[F] | 21 [Control]-[U]
7 [Control]-[G] | 22 [Control]-[V]
8 [Control]-[H]/[Backspace] | 23 [Control]-[W]
9 [Control]-[I]/[Tab] | 24 [Control]-[X]
10 [Control]-[J] | 25 [Control]-[Y]
11 [Control]-[K] | 26 [Control]-[Z]
12 [Control]-[L] | 27 [ESCape]
13 [Control]-[M]/[Enter]/[Return] | 32 [SpaceBar]
14 [Control]-[N] |
ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE
----- --------- | ----- --------- | ----- --------- | ----- ---------
33 '!' | 57 '9' | 80 'P' | 104 'h'
34 '"' | 58 ':' | 81 'Q' | 105 'i'
35 '#' | 59 ';' | 82 'R' | 106 'j'
36 '$' | 60 '<' | 83 'S' | 107 'k'
37 '%' | 61 '=' | 84 'T' | 108 'l'
38 '&' | 62 '>' | 85 'U' | 109 'm'
39 '\'' (') | 63 '?' | 86 'V' | 110 'n'
40 '(' | 64 '@' | 87 'W' | 111 'o'
41 ')' | 65 'A' | 88 'X' | 112 'p'
42 '*' | 66 'B' | 89 'Y' | 113 'q'
43 '+' | 67 'C' | 90 'Z' | 114 'r'
44 ',' | 68 'D' | 91 '[' | 115 's'
45 '-' | 69 'E' | 92 '\\' (\) | 116 't'
46 '.' | 70 'F' | 93 ']' | 117 'u'
47 '/' | 71 'G' | 94 '^' | 118 'v'
48 '0' | 72 'H' | 95 '_' | 119 'w'
49 '1' | 73 'I' | 96 '`' | 120 'x'
50 '2' | 74 'J' | 98 'b' | 121 'y'
51 '3' | 75 'K' | 99 'c' | 122 'z'
52 '4' | 76 'L' | 100 'd' | 123 '{'
53 '5' | 77 'M' | 101 'e' | 124 '|'
54 '6' | 78 'N' | 102 'f' | 125 '}'
55 '7' | 79 'O' | 103 'g' | 126 '~'
56 '8' | | | 127 [DELete]
===============================================================================
OpenDoors 6.00 Manual End of Page 87
SEE ALSO od_get_input(), od_input_str(), od_edit_str(),
od_clear_keybuffer()
EXAMPLE For examples of the use of the od_get_key() function, see the
examples in the description portion, above, and the examples for
the od_exit() and od_clear_keybuffer() functions. For further
examples of this function, see the example program EX_VOTE.C,
described in the section beginning on page 38.
===============================================================================
OpenDoors 6.00 Manual End of Page 88
OD_GETTEXT()
-------------------------------------------------------------------------------
PURPOSE Stores a rectangular region of the screen in an array, to later
be redrawn using od_puttext(). Requires ANSI, AVATAR or RIP
modes.
FORMAT BOOL od_gettext(INT nLeft, INT nTop, INT nRight, INT nBottom,
void *pBlock);
RETURNS TRUE on success
FALSE on failure
DESCRIPTION This function stores the contents (both text and color
information) of the rectangular portion of the screen denoted by
the variables nLeft, nTop, nRight and nBottom into the buffer
pointed to by pBlock. The saved portion of the screen may then
be restored using od_puttext(). The buffer must be large enough
to store two bytes for every character in the specified
rectangle. In other words, the required size of the buffer, in
bytes, is:
length * width * 2
The parameters nLeft and nRight are column numbers from 1 to 80,
and the parameters nTop and nBottom are row numbers between 1
and 23.
This function has no effect on the current text color or cursor
position. ANSI, AVATAR or RIP mode is required for this
function. If you wish to save and restore the entire screen, you
may use the od_save_screen() and od_restore_screen() functions,
which can be used in all display modes.
If this function fails for any reason, a value of FALSE is
returned, and the od_control.od_error variable is set to
indicate the reason for the failure. For more information on the
od_control.od_error variable, see page 185.
SEE ALSO od_puttext(), od_save_screen(), od_restore_screen(),
od_scroll(), od_window_create(), od_window_remove()
===============================================================================
OpenDoors 6.00 Manual End of Page 89
OD_HOTKEY_MENU()
-------------------------------------------------------------------------------
PURPOSE Function to display a menu file with hotkeys
FORMAT char od_hotkey_menu(char *pszFileName, char *pszHotKeys, BOOL
bWait);
RETURNS Key pressed in response to menu, or '\0' if none.
DESCRIPTION This function can be used to display a menu from an ASCII, ANSI,
AVATAR or RIP file, allowing the user to select an option at any
time while the menu is being displayed. The od_hotkey_menu()
function is quite similar to the od_send_file() function, and
you should probably familiarize yourself with that function if
you are going to use od_hotkey_menu(). Like od_send_file(),
od_hotkey_menu() will display the file specified by pszFileName,
using the appropriate terminal emulation. If no extension is
provided for the filename, OpenDoors will automatically search
for matching files ending in .ASC, .ANS and .AVT extensions.
OpenDoors will the select the appropriate file to display, based
on the available files and available terminal emulation.
The second parameter, pszHotKeys, is a string specifying the
valid responses to the menu, in the same format as the string
passed to the od_get_answer() function. If any of the characters
listed in this string are pressed, either uppercase or lowercase
versions, OpenDoors will immediately stop displaying the menu,
and return with the value of the key pressed. The case (upper or
lower) returned will always be identical to the case used in the
hotkeys string. You can include the [ENTER] key as a valid hot
key by including the \n character in the hotkey string.
The third parameter passed to od_hotkey_menu(), bWait, specifies
whether OpenDoors should wait after displaying the menu for the
user to make a valid selection from the menu (TRUE), or if it
should exit immediately (FALSE). Normally, you will want to use
the TRUE value when calling this function. This will allow you
to use a single function call that will display the menu and
always return the user's selection. If you wish to gain control
as soon as OpenDoors has displayed the menu, you may specify
FALSE for this parameter. In this case, if the user does not
press any of the valid hot keys while the menu is being sent,
the function will return the character '\0'.
SEE ALSO od_send_file(), od_get_answer()
===============================================================================
OpenDoors 6.00 Manual End of Page 90
EXAMPLE As an example of the use of the od_hotkey_menu() function,
consider the following code fragment:
for(;;) /* Main program loop */
{ /* Display menu and get user's choice */
char choice=od_hotkey_menu("MAINMENU","123Q",TRUE");
switch(choice) /* Perform the appropriate action */
{
case '1':
od_printf("You selected one.\n\r");
break;
case '2':
od_printf("You selected two.\n\r");
break;
case '3':
od_printf("You selected three.\n\r");
break;
case 'Q':
od_exit(FALSE,10);
}
}
This is an example of the main menu loop of a simple door that
uses the od_hotkey_menu() function. The program will continue
executing the for(;;) loop until the user chooses to exit the
door. On each iteration of the loop, the od_hotkey_menu()
function is called, to display the door's menu from the file
MAINMENU.A??. The appropriate .ASC/.ANS/.AVT file will be chosen
and displayed as the menu. The possible choices that may be made
from the menu are specified by the string "123Q". Thus, whenever
the user presses one of the keys [1], [2], [3] or [Q], the
od_hotkey_menu() function will return immediately with the value
of the key pressed. If the menu is still being displayed at the
time when the key was pressed, menu display will cease at that
moment. The program then executes a case statement, to respond
to the user's key appropriately. If the user presses [1], [2] or
[3] this door will output a simple message to the screen. If the
user presses the [Q] key, the door will pass control back to the
BBS.
===============================================================================
OpenDoors 6.00 Manual End of Page 91
OD_INIT()
-------------------------------------------------------------------------------
PURPOSE To initialize OpenDoors activities
FORMAT void od_init(void);
RETURNS N/A
DESCRIPTION This function initializes OpenDoors. This function must be
called manually if you wish to access data about the user, etc.,
before you call any other OpenDoors functions. However, if you
do not explicitly call the od_init() function, it will be called
automatically on the first call to most other OpenDoors
functions. The only functions that should be called before
od_init() are od_add_personality() and od_parse_cmd_line(). The
od_init() function reads information from the door information
file, initializes communications with the modem, displays the
status line, and sets up OpenDoors' internal data structures.
For more information on what data is and is not available before
od_init() has been called, please refer to the chapter on the
OpenDoors control structure, which begins on page 148.
The od_init() function will read the door information file which
is located in the directory specified by the variable
od_control.info_path. If this variable has not been set prior to
calling the od_init() function, OpenDoors will expect to find
the door information file in the current directory. Thus, if you
wish your door to be able to be run in a directory other than
the BBS system directory, it would be a good idea to allow the
sysop using your door to specify the location of the door
information file. For an example of setting the
od_control.info_path variable, please see the example program
located on page 150.
Also note that you can prevent the od_init() function from
carrying out some of it's normal activities, such as attempting
to read a door information file, by the use of the
od_control.od_disable variable, as described in the section on
the OpenDoors control structure, which begins on page 148.
SEE ALSO od_exit()
EXAMPLE At times, you may wish to write a door program which will
require a maintenance utility to be run on a regular basis. For
example, a game door may have to have its system files updated
on a daily basis, by having a utility program run in a system
===============================================================================
OpenDoors 6.00 Manual End of Page 92
event each day at midnight. One way of accomplishing this would
be to have your door package include two .EXE files, one being
the actual door program, and the other being a utility program.
However, another option would be to have both the door and
maintenance functions to be accessible from a single .EXE file,
in order to simplify use of the door for the sysop. In this
case, you would want to test the command line to determine
whether your program should run in door mode or maintenance
mode. You would then only execute the od_init() function, along
with the rest of your door code, if you program were running in
"door mode".
The program below demonstrates one method of doing just this. In
this case, the program would include two functions, door(),
which would carry out all of the door-related activities, and
maint(), which would carry out all of the maintenance-related
activities. In this simple example, if the command line includes
a "-M" or "/M", the program will run in maintenance mode,
otherwise it will run in door mode. Also, if it is running in
door mode, the program will take the first command-line
parameter, if any, as a path to the location of the door
information file.
#include "opendoor.h"
void door(void);
void maint(void);
int main(int argc, char *argv[])
{
int counter;
/* Check any command line parameters for /M or -M */
for(counter=1;counter<argc;++counter)
{
if((argv[counter])[1]=='m' || (argv[counter])[1]=='M')
{
maint(); /* Then carry out maintenance */
exit(20); /* And exit */
}
}
/* If there was no -M or /M, then run in door mode */
/* If there are any command-line parameters take the first */
/* as the path to the door information file */
if(argc>1) strncpy(od_control.info_path,argv[1],59);
od_init(); /* call the od_init() function */
door(); /* Run the door portion of the program */
od_exit(30,FALSE); /* Shutdown the door */
===============================================================================
OpenDoors 6.00 Manual End of Page 93
}
void maint(void)
{
... /* Carry out maintenance activities here */
}
void door(void)
{
... /* Carry out door activities here */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 94
OD_INPUT_STR()
-------------------------------------------------------------------------------
PURPOSE Inputs a string from the user
FORMAT void od_input_str(char *pszInput, INT nMaxLength,
unsigned char chMin, unsigned char chMax);
RETURNS N/A
DESCRIPTION To perform string input within OpenDoors, one of two functions
can be used, od_input_str() and od_edit_str(). The first
function, od_input_str(), allows simple line input and editing,
and can be used in ASCII, ANSI, AVATAR and RIP modes. The second
function, od_edit_str(), allows many formatted input options,
advanced line editing, and other features, but requires the use
of ANSI, AVATAR or RIP graphics modes.
The od_input_str() function allows you to input a string from
the user. The string will be permitted to have up to the number
of characters specified by the max_len parameter, and all
characters must be between the values of the min_char and
max_char parameters. This function will wait until the user
presses the [Enter] key to finish inputting the string.
The first parameter passed to this function should be a pointer
to the string where the user's input should be stored. So, if
you wanted to store a string of up to 30 characters inputted by
the user, you might define this string as follows:
char input_string[31];
Notice here than the string must be long enough to hold the
thirty characters which can be entered by the user, along with
the additional "null" character which is used to indicate the
end of a string in C. Hence, the length of the string should
always be at least one greater than the total number of
characters the user is permitted to enter, passed in the
nMaxLength parameter.
The second parameter passed to the od_input_str() function
should be an integer value indicating the maximum number of
characters which can be input by the user. For example, if this
parameter had a value of 10, the user would be able to enter a
string containing any number of characters up to and including
10 characters. If this parameter had a value of 1, the user
would only be able to enter a single character. However, the
user would be able to backspace, change the character, and press
[Enter] when they were satisfied with their entry. Note that
===============================================================================
OpenDoors 6.00 Manual End of Page 95
even if you only ask the od_input_str() function to input a
single character, it will still expect a STRING to be passed to
it, and will return a string with either zero or one character,
followed by a null (string terminator) character.
The third and fourth parameters passed to this function allow
you to control what characters the user will be permitted to
enter as part of the string. For example, you could set the
minimum character to the '0' character and the maximum character
to the '9' character, permitting the user to only enter numeric
characters. On the other hand, you could permit the user to
enter all ASCII characters in the range from 32 to 127. The
od_input_str() function will permit characters in the range
beginning with the character passed as minchar, up to and
including the character passed as maxchar.
SEE ALSO od_edit_str(), od_get_key(), od_clear_keybuffer()
EXAMPLE Below are a number of examples of the use of the od_input_str()
function in various applications:
- To input a two character number (only digits from 0-9):
od_input_str(string, 2, '0', '9');
- To input a 35 character name (characters from Space to
ASCII 127):
od_input_str(string, 35, 32, 127);
===============================================================================
OpenDoors 6.00 Manual End of Page 96
OD_KERNEL()
-------------------------------------------------------------------------------
PURPOSE The OpenDoors Central Control function.
FORMAT void od_kernel(void);
RETURNS N/A
DESCRIPTION In the DOS version of OpenDoors, the od_kernel() function is
responsible for many vital OpenDoors tasks, such as monitoring
the carrier detect signal, monitoring the amount of time that
the user has remaining, updating the status line, responding to
sysop hotkeys, and reading characters which are received from
the modem. The od_kernel() function is automatically called on a
frequent basis by the other OpenDoors functions, so most often
you will not need to be concerned with this function. However,
in order that OpenDoors can carry out the activities mentioned
above with a quick response, it is important that od_kernel(),
or some other OpenDoors function be called at least once every
second. Thus, if your program will be carrying out some
processing, in which it will not be calling any OpenDoors
functions for more than a second or so, you should call the
od_kernel() function yourself. The example below demonstrates
one method of doing just this.
Note that if for some reason or other, it is not possible for
your program to call the od_kernel() function, or any other
OpenDoors functions for a period of several seconds, this will
not cause your door to crash or fail in any way. The only
problem will be that OpenDoors will not be able to respond to
any action, such as the sysop pressing a function key, or the
user dropping carrier, until such time as you next call
od_kernel(), or some OpenDoors function. Hence, use of the
od_kernel() function will improve the quality and response time
of your program, but calling it or some OpenDoors function on a
regular basis is not absolutely vital.
This function has no effect in the Win32 version of OpenDoors.
SEE ALSO od_sleep()
===============================================================================
OpenDoors 6.00 Manual End of Page 97
OD_LIST_FILES()
-------------------------------------------------------------------------------
PURPOSE Lists files in a particular file area (using FILES.BBS)
FORMAT BOOL od_list_files(char *pszFileSpec);
RETURNS TRUE if successful, FALSE if unsuccessful
DESCRIPTION This function allows you to display a list of files available
for download from a particular file area, as any BBS system
would. The file names and descriptions are taken from the
FILES.BBS located in the directory pointed to by pszFileSpec.
Thus, to list the files available for download in
C:\BBS\FILES\UPLOADS, simply:
od_list_files("C:\\BBS\\FILES\\UPLOADS");
OpenDoors uses a third-generation FILES.BBS format, that is
compatible with other FILES.BBS formats, but adds some
additional features. Each line in the FILES.BBS file lists a
filename, along with it's description. Thus, a typical FILES.BBS
file might look as follows:
PKZ110.EXE PKZip file compressor, version 1.10
ODOORS60.ZIP The newest version of OpenDoors
REC*.ZIP A Record file
C:\BBS\*.* All BBS files.
When displayed, OpenDoors will list the size of each file found
in the FILES.BBS file beside it's name, if the file is found. If
the file does not exist, then a "[OFFLINE]" string is displayed
in the file size column. Title lines may also be added to the
FILES.BBS, by indenting them one or more columns. Thus, you
could have something like:
NEWEST UPLOADS
~~~~~~~~~~~~~~
PKZ110.EXE PKZip file compressor, version 1.10
ODOORS60.ZIP The newest version of OpenDoors
REC*.ZIP A Record file
C:\BBS\*.* All BBS files.
In addition to this standard FILES.BBS format, OpenDoors will
also permit wildcards to be used in FILES.BBS filenames (ie
FNEWS???.*), or full directory paths to allow files from several
different directories to be included in the same files area.
===============================================================================
OpenDoors 6.00 Manual End of Page 98
You may alter the colors used to display the various portions of
the files list using the od_control variables:
od_control.od_list_title_col
od_control.od_list_name_col
od_control.od_list_size_col
od_control.od_list_comment_col
od_control.od_list_offline_col
which are documented in the OpenDoors control structure section
on this manual, which begins on page 148.
SEE ALSO od_send_file()
===============================================================================
OpenDoors 6.00 Manual End of Page 99
OD_LOG_WRITE()
-------------------------------------------------------------------------------
PURPOSE Function to write an entry to the log file
FORMAT BOOL od_log_write(char *pszMessage);
RETURNS TRUE on success, or FALSE on failure
DESCRIPTION This function can be used to write entries to the log file. If
the logfile has not already been opened when you call this
function for the first time, OpenDoors will automatically open
the log file at that time.
To create an entry in the log file, simply call the
od_log_write() function, passing to it the string of the text
you wish to write. You should not include any control characters
in this string, simply the text that should appear on the line.
OpenDoors will automatically format the log file, adding the
time information and other control characters. It is recommended
that the length of the string passed to od_log_write() not
exceed 67 characters, in order that logfile lines will all be
less than 80 characters in length.
Log file entries do not usually contain periods or other
punctuation at the end of the line. Also, log file entries are
usually written in the present tense. The first character of the
entry is usually upper-case, with all other entries in lower
case. Also, since excessive numbers or lengths of log file
entries can quickly use a lot of disk space, it is best to think
carefully about what events should be recorded in the log file.
It is also a good idea to minimize the number of words used in
the entry, without being too cryptic. As an example, "User
entering options menu" should be used instead of "user entered
the options menu."
SEE ALSO Page 224.
EXAMPLE Calling the od_log_write() function is as simple as follows:
od_log_write("Awarding user with 5 minutes more time");
===============================================================================
OpenDoors 6.00 Manual End of Page 100
OD_MULTILINE_EDIT()
-------------------------------------------------------------------------------
PURPOSE Provides a multiple line text editor which can be used for
entering editing any text that spans more than one line, such as
messages or text files.
FORMAT INT od_multiline_edit(char *pszBufferToEdit, UINT unBufferSize,
tODEditOptions *pEditOptions);
RETURNS OD_MULTIEDIT_SUCCESS on success, or OD_MULTIEDIT_ERROR on
failure
DESCRIPTION This function provides a text editor with optional word wrap
capabilities. This editor can be used for entering or editing
text files, messages or other information that spans multiple
lines. The editor can be configured to operate in full-screen
mode, or to occupy any smaller area of the screen that you
specify. It provides the navigation (home / end / page up / arrow
keys) features and editing features (insert / overwrite mode,
Ctrl-Y to delete a line, etc.) that you would expect.
The od_multiline_edit() function is designed to be both easy to
use and very flexible. To that end, the function only takes three
parameters. The first two parameters are required, and the third
parameter is an optional options structure. The first parameter,
pszBufferToEdit, is a pointer to the buffer of text to edit. This
buffer must always be a '\0'-terminated string. This buffer must
be initialized before calling od_multiline_edit(). The second
parameter, unBufferSize, indicates the size of the buffer that is
passed in pszBufferToEdit. Note that this should be the total
amount of space that is available in the buffer for text entered
by the user, not the length of data that is actually initially in
the buffer. If you do not wish to customize any of the
od_multiline_edit() options, then you may simply set the third
parameter to 0. Hence, a simple example of how to use
od_multiline_edit() is:
char szMyEditBuffer[4000] = "";
od_multiline_edit(szMyEditBuffer, sizeof(szMyEditBuffer),
NULL);
If you wish to customize od_multiline_edit(), you should pass a
pointer to a tODEditOptions structure as the third parameter. You
should initialize this entire structure to zeros before
attempting to use it. You can then set any values of this
structure which you wish to change from their default. Any values
that are left at 0 will automatically revert to their defaults.
For example, if you wanted to specify a text format other than
===============================================================================
OpenDoors 6.00 Manual End of Page 101
the default, you could create, initialize and pass in a
tODEditOptions structure as follows:
char szMyEditBuffer[4000] = "";
tODEditOptions MyEditOptions;
memset(&MyEditOptions, 0, sizeof(MyEditOptions));
MyEditOptions.TextFormat = FORMAT_LINE_BREAKS;
od_multiline_edit(szMyEditBuffer, sizeof(szMyEditBuffer),
&MyEditOptions);
The definition of the tODEditOptions structure is as follows:
typedef struct
{
INT nAreaLeft;
INT nAreaTop;
INT nAreaRight;
INT nAreaBottom;
tODEditTextFormat TextFormat;
tODEditMenuResult (*pfMenuCallback)(void *pUnused);
void * (*pfBufferRealloc)(void *pOriginalBuffer,
UINT unNewSize);
DWORD dwEditFlags;
char *pszFinalBuffer;
UINT unFinalBufferSize;
} tODEditOptions;
nAreaLeft, nAreaTop, nAreaRight, nAreaBottom allows you to
specify the portion of the screen that the text editor should
use. This defaults to 1, 1 - 80, 23.
TextFormat allows you to specify what format the text should be
stored in the buffer using. The default is
FORMAT_PARAGRAPH_BREAKS, which specifies that a line break only
appears at the end of each paragraph, and that the contents of a
paragraph are word wrapped. FORMAT_LINE_BREAKS specifies that a
line break appears at the end of each line of text on the screen,
and that newly entered text is word wrapped. FORMAT_NO_WORDWRAP
is equivalent to FORMAT_LINE_BREAKS, except that newly entered
text is not word wrapped. Instead, lines may be arbitrarily long.
For each of these text formats, od_multiline_edit() automatically
decides whether line breaks should take the form of a carriage
return ('\r'), line feed ('\n'), or some combination of these,
based on what it sees in the buffer that you supply. If no line
breaks are found in the buffer, then the default is to use just a
line feed ('\n') character. FORMAT_FTSC_MESSAGE specifies a FTSC-
compliant message, such as is used in a *.MSG message file. Among
other things, this specifies that carriage returns ('\r') end
paragraphs, and that line feeds ('\n') should be ignored.
pfMenuCallback allows you to provide a callback function that
will be called when the user presses the escape (or control-Z)
===============================================================================
OpenDoors 6.00 Manual End of Page 102
key. This allows you to provide a menu that can be accessed from
within the text editor. This function should return
EDIT_MENU_DO_NOTHING if the editor should continue normally, or
EDIT_MENU_EXIT_EDITOR if the od_multiline_edit() should return.
If no menu callback function is provided, then
od_multiline_edit() always returns when the escape or control-z
key is pressed.
pfBufferRealloc allows you to provide a function which will
attempt to reallocate a larger buffer if the user enters more
text than will fit in the originally supplied buffer. You should
only do this if you have dynamically allocated the buffer that
you initially passed into od_multiline_edit(). If you allocated
the buffer using malloc() or calloc(), then pfBufferRealloc can
be set to point to the realloc() function. If you allocated the
buffer using the C++ new operator, then you must write a your own
reallocation function which obeys the same semantics as the C
realloc() function. If no buffer reallocation function is
provided, then od_multiline_edit() will never allow the user to
enter more text than will fit in the buffer that you initially
supply. If you are using the buffer reallocation option, you can
obtain a pointer to the final buffer, and the size of the final
buffer, from the pszFinalBuffer and unFinalBufferSize members.
SEE ALSO od_input_str(), od_edit_str(), od_get_input()
===============================================================================
OpenDoors 6.00 Manual End of Page 103
OD_PAGE()
-------------------------------------------------------------------------------
PURPOSE Function to allow user to page the sysop
FORMAT void od_page(void);
RETURNS N/A
DESCRIPTION This function can be called to allow the user to page the sysop.
This function will ask the user why they wish to chat with the
sysop, and then page the sysop. The sysop will then be free to
break into chat at any time. Sysop paging will also be aborted
by the user, simply by pressing [Enter] when asked for a reason
for chat. When the user pages the sysop, the [Wants-Chat]
indicator will begin to flash on the main status line, and the
status line will switch to show the user's reason for wanting to
chat. Also, the user's total number of pages will be
incremented.
Depending upon the setting of the od_control.od_okaytopage
variable, this function will also optionally check sysop paging
hours, and only allow the user to page the sysop during valid
paging hours. For information on the variables containing the
user's total number of pages, the user's want-chat status, valid
sysop paging hours, and the od_control.od_okaytopage variable,
see the section on the OpenDoors control structure, which begins
on page 148.
EXAMPLE For an example of the use of the od_page() function, see the
EX_VOTE.C example program, which is described beginning on page
38.
===============================================================================
OpenDoors 6.00 Manual End of Page 104
OD_PARSE_CMD_LINE()
-------------------------------------------------------------------------------
PURPOSE Handles standard command line options.
FORMAT Under DOS Version:
void od_parse_cmd_line(INT nArgCount, char *papszArguments[]);
Under Win32 Version:
void od_parse_cmd_line(LPSTR pszCmdLine);
RETURNS N/A
DESCRIPTION This is the only OpenDoors function that uses a different
calling format in the DOS and Win32 versions of OpenDoors. The
reason for this is that od_parse_cmd_line() always allows you to
pass command line parameters in the same format that the
operating system passes them to you. Under the DOS version of
OpenDoors, you should pass the argc and argv values that were
passed to your main function as the two parameters to
od_parse_cmd_line(). Under the Win32 version of OpenDoors, you
should pass the pszCmdLine values that were passed to your
WinMain() function as the one parameter to od_parse_cmd_line().
The od_parse_cmd_line() function should be called before your
first call to any other OpenDoors function, with the possible
exception of the od_add_personality() function.
It is recommended that any program which uses OpenDoors call
od_parse_cmd_line() as part of its startup procedure. This
allows your program to automatically handle many common command
line options that will make it easier to setup and run your
program. Among the helpful command line options processed by
od_parse_cmd_line() are options to set serial port information
(including information on non-standard serial port setups),
specify the location of configuration and drop files, force the
program to run in silent mode (without no local display), pass
in user information, and the ability to start the program in
local mode without a drop file. For a complete list of the
options supported by od_parse_cmd_line(), run the example Vote
door that is included in the OpenDoors packages, specifying -
help on the command line.
If you wish to process your own command line parameters in
addition to those supported by OpenDoors, simply check the
command-line for your own parameters after calling
od_parse_cmd_line(). You can do this in the same way that you
would handle command line options if you weren't using
od_parse_cmd_line(). The od_parse_cmd_line() function does not
===============================================================================
OpenDoors 6.00 Manual End of Page 105
generate an error message if it encounters unrecognized command
line options. You can supply your own text to display when the
user chooses the /Help option by setting
od_control.od_cmd_line_help to point to your own string. Separate
lines in your string with the \n character, and align text using
the \t character.
SEE ALSO od_init()
EXAMPLE The following example shows how a program that uses
od_parse_cmd_line() should be structured in order to compile
under either DOS or Win32 versions of OpenDoors:
#include "opendoor.h"
/* main() or WinMain() function - Program begins here. */
#ifdef ODPLAT_WIN32
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpszCmdLine, int nCmdShow)
#else
int main(int argc, char *argv[])
#endif
{
#ifdef ODPLAT_WIN32
#endif
/* Set program's name for use by OpenDoors. */
#ifdef ODPLAT_WIN32
/* In Windows, pass in nCmdShow value to OpenDoors. */
od_control.od_cmd_show = nCmdShow;
/* Call od_parse_cmd_line. */
od_parse_cmd_line(lpszCmdLine);
#else
od_parse_cmd_line(argc, argv);
#endif
/* Start the rest of your program here. */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 106
OD_POPUP_MENU()
-------------------------------------------------------------------------------
PURPOSE Creates a popup menu which allows the user to make a selection
by pressing a single key, or selecting the item with a highlight
bar. After the user has made a selection, the menu may be
removed from the screen, restoring the original screen contents
"beneath" the window.
FORMAT INT od_popup_menu(char *pszTitle, char *pszText, INT nLeft,
INT nTop, INT nLevel, WORD uFlags);
RETURNS POPUP_ERROR On error (od_control.od_error is set to
indicate type of error).
POPUP_ESCAPE If user exited menu by pressing [ESCape].
POPUP_LEFT If user exited menu by pressing the left arrow
key.
POPUP_RIGHT If user exited menu by pressing the right arrow
key.
Or, a postive integer indicating the menu item that was chosen
if a selection was made.
DESCRIPTION od_popup_menu() creates a popup window with a menu of choices,
for use in ANSI/AVATAR/RIP modes. The user is able to choose an
item from the menu by moving the highlighted selection bar with
the arrow keys, or by pressing a key associated with a
particular menu item. The contents of the menu are defined by
the string pointed to by the pszText parameter. This menu
definition string contains each menu option, separated by a '|'
(pipe) character. Keys associated with each menu entry can be
defined by proceeding the letter with a '^' (carat) character.
For example, the string:
"^Save|^Load|E^xit"
would produce a menu with three options: Save, Load and Exit.
The user would be able to select the Save option by pressing the
[S] key, the Load option by pressing the [L] key, and the Exit
option by pressing the [X] key. Furthermore, the characters
corresponding to each menu item would be displayed in a
highlighted color.
Menus displayed with od_popup_menu() may optionally have a
title, as specified by the pszTitle parameter. If this parameter
is set to NULL, no title will be displayed. If this parameter is
not NULL, the specified string will be displayed as a title on
the window.
===============================================================================
OpenDoors 6.00 Manual End of Page 107
The nLeft and nTop parameters specify the left and top locations
of the menu window, were 1, 1 is the upper right corner of the
screen. The bottom and right corners of the menu are
automatically determined by the size and number of menu entries
in the menu definition string.
The nLevel parameter specifies the menu level, an integer from 0
to 10. Unless you are using the MENU_KEEP flag, this parameter
can always be 0.
The uFlags parameter specifies one or more of the following
options, joined by the bitwise-OR operator (|).
MENU_NORMAL Has no effect.
MENU_ALLOW_CANCEL Allow user to exit menu with [ESCape].
MENU_PULLDOWN Allow exit with arrow keys.
MENU_KEEP Leave menu active on selection.
MENU_DESTROY Remove a currently active menu.
If you are not using any of the other flags, you can use
MENU_NORMAL as a place-holder for this parameter. If you specify
MENU_ALLOW_CANCEL, the user will be able to exit the menu
without making a selection by pressing the [ESCape] key. If the
user presses [ESCape], od_popup_menu() returns POPUP_ESCAPE.
You can use the MENU_PULLDOWN option with od_popup_menu() to
implement a set of pulldown menus. In this case, if the user
presses the left arrow key or right arrow key while the menu is
being displayed, od_popup_menu() returns with POPUP_LEFT or
POPUP_RIGHT, allowing you to display a different menu.
Normally, od_popup_menu() will remove the menu from the screen
as soon as the user makes a selection. However, there may be
some cases when you want the menu to continue to be visible
after the user makes a selection. For example, you may want some
menu options to lead to further sub-menus, or you may wish to
display a popup window, and return to this menu after the user
has exited from the popup window. If the MENU_KEEP flag is
specified, the menu will remain active (on-screen) after the
user makes a selection. However, the menu will still be
destroyed if the user cancels out of the menu (this will only
happen if you have specified MENU_ALLOW_CANCEL), or if the user
moves to another menu by pressing the left or right arrow keys
(this will only happen if you have specified MENU_PULLDOWN). If
MENU_KEEP has been specified, and the user makes a selection,
you must eventually either return to the menu, or destroy it by
calling MENU_DESTROY. If you want to return to the menu, simply
call od_popup_menu() again with the same level value that was
used to originally create the menu. The user will now be able to
make another selection from the menu, and od_popup_menu() will
once again return that selection to you. If you want to destroy
the menu, simply call od_popup_menu() with the MENU_DESTROY flag
===============================================================================
OpenDoors 6.00 Manual End of Page 108
set, and the same level value that was used to create the
original menu. If you wish to create another popup menu while
the first one is still active, simply call od_popup_menu()
again, this time with a different level value. The colors used
by the od_popup_menu() function are set by the following
OpenDoors control structure settings:
char od_control.od_menu_title_col;
char od_control.od_menu_border_col;
char od_control.od_menu_text_col;
char od_control.od_menu_key_col;
char od_control.od_menu_highlight_col;
char od_control.od_menu_highkey_col;
SEE ALSO od_window_create(), od_window_remove(), od_draw_box(),
od_hotkey_menu()
EXAMPLE The following example shows the use of multiple-level menus:
#include <stdlib.h>
#include "opendoor.h"
main()
{
for(;;)
{
switch(od_popup_menu("Main Menu",
"^Files|^Electronic Mail|^News|E^xit",
20, 5, 0, MENU_NORMAL | MENU_KEEP))
{
case 1:
od_popup_menu("Files Menu",
"^Search For Files|^Download|^Upload",
30, 7, 2, MENU_NORMAL | MENU_ALLOW_CANCEL);
break;
case 2:
od_popup_menu("EMail Menu",
"Get ^New Mail|^Send Mail|Send ^Fax",
30, 8, 1, MENU_NORMAL | MENU_ALLOW_CANCEL);
break;
case 3:
od_popup_menu("News Menu",
"Choose News^Group|^Read News|^Post News",
30, 9, 1, MENU_NORMAL | MENU_ALLOW_CANCEL);
break;
case 4:
od_popup_menu(NULL, NULL, 0, 0, 0, MENU_DESTROY);
return(0);
}
}
}
===============================================================================
OpenDoors 6.00 Manual End of Page 109
OD_PRINTF()
-------------------------------------------------------------------------------
PURPOSE Performs formatted output (remote & local), with the ability to
change display colors.
FORMAT void od_printf(char * pszFormat,...);
RETURNS N/A
DESCRIPTION This is one of two OpenDoors function which allows you to
display a string of characters, the other being the
od_disp_str() function. For a complete comparison of the various
OpenDoors display function, see the description of the
od_disp_str() function, on page 63. Like the od_disp_str()
function, the od_printf() function will display its output both
on the local screen, and on the remote user's screen (if the
door is not operating in local mode). However, the od_printf()
function also allows for formatted output, just as the printf()
function does. In addition to providing all of the features of
the normal C printf() function, the od_printf() function allows
you to include codes to change the color of the display of text.
This unique feature allows you to display multi-colored text,
without having to use chains of alternating od_disp_str() and
od_set_color() calls.
As with the printf() function, the od_printf() function accepts
one or more parameters, the first parameter being the format
string to be displayed, and the additional parameters being data
to be displayed within the string. The OpenDoors od_printf()
function recognizes all of the control characters and options
recognized by the normal printf() function. For example, to
display the amount of time that a user has left online, the
following line would be a valid use of the od_printf() function:
od_printf("Time Left:%d\n\r", od_control.user_timelimit);
Note that a full discussion of the printf() function is beyond
the scope of this manual. For more information on using
printf(), please see your Turbo C(++) / Borland C++ manuals.
In addition to the normal control sequences, such as "%s", "%d",
or "%12.12s", the od_printf() function also allows you to
include special color-setting codes within the format string.
These color code sequences BEGIN and END with a delimiter
character, which is used to indicate that the sequence is a
color setting. Consider, for example, the following line of
code, which displays text in various colors:
===============================================================================
OpenDoors 6.00 Manual End of Page 110
od_printf("`blue`Blue `green`Green `red`Red \n\r");
In this case (assuming of course that a color monitor is being
used) the word "Blue" will be displayed in the color blue, the
word "Green" will be displayed in the color green, and the word
"Red" will be displayed in the color red. In this case, the
sequence `blue` sets the display color to dark blue on black.
Here, the back-quote (`) is the delimiter character which
indicates the beginning and end of the color sequence. Be sure
not to confuse the back-quote character (`) with the normal
forward quote ('). THIS IS THE MOST COMMON DIFFICULTY
EXPERIENCED WITH THE OD_PRINTF() FUNCTION. The text between the
back-quote characters indicates the color that should be set.
This text can include the name of the foreground color, the name
of the background color, the "bright" keyword and the "flashing"
keyword. The first color mentioned is taken to be the foreground
color, and the second the background color. Case is not
sensitive, additional words can be included for legibility.
Thus:
`bright white cyan`
is equivalent to:
`Bright white on a cyan background`.
The "bright" keyword indicates that the foreground color should
be displayed in high intensity, and the "flashing" keyword
indicates that the text should be flashing. If no background is
specified, the background color defaults to black. If no
foreground or background colors are specified, the color
defaults to white on black.
The od_printf() function will automatically determine whether
the user has ANSI, AVATAR or RIP graphics enabled, and will send
the appropriate color codes to change the color of displayed
text. If the user does not have either ANSI or AVATAR graphics
modes turned on, then the od_printf() function will not send any
color codes. Thus, a door program using color codes would work
just as well when ANSI/AVATAR/RIP graphics are not available,
except that all text will appear in the same color.
You may prefer to set colors by using the od_set_color() or
od_set_attrib() functions, instead of using these cryptic color
codes imbedded in od_printf() functions. In some cases, however,
it will be much more advantageous to place the color codes
within your od_printf() strings. As a case in point, consider
the single od_printf() statement in the example, above. To
accomplish the same result using the od_disp_str() and
od_set_color() functions, you would have to use the following
SIX function calls:
===============================================================================
OpenDoors 6.00 Manual End of Page 111
od_set_color(D_BLUE,D_BLACK);
od_disp_str("Blue ");
od_set_color(D_GREEN,D_BLACK);
od_disp_str("Green ");
od_set_color(D_RED,D_BLACK);
od_disp_str("Red \n\r");
While this method MAY be easier understand, it certainly
requires many more line of code to accomplish. However, either
method will work, and the choice is up to you as to which method
you prefer. Keep in mind, however, that if the color to be set
is stored in a variable, instead of always being the same color,
you must use either the od_set_color() or od_set_attrib()
function to set the display color.
While the back-quote (`) character is normally used to delimit a
color sequence in the od_printf() function, you may wish to be
able to print a back-quote character using the od_printf()
function. In this case, you may configure OpenDoors to use a
different character to represent color code sequences. To do
this, simply use the od_control.od_color_delimiter variable,
which is described in the OpenDoors control structure section,
beginning on page 148. For example, if you wished to use the
tilde (~) character instead of the back-quote character to
change colors, simply place the following line within your
program, at some point after having called od_init() or some
OpenDoors function:
od_control.od_color_delimiter='~';
Also, you may disable the color code interpretation within the
od_printf() function altogether, by setting the
od_control.od_color_delimiter variable to 0.
Note that the od_printf() function interprets the color codes
AFTER parsing the other control sequences, such as "%d" or "%s".
Thus, if you used the command:
od_printf("%s",string);
Any color codes contained in the string "string" would also be
interpreted. If you did not wish to have any color code
characters which might be contained in the string "string"
treated as such, you could again disable od_printf()'s color
code interpretation, by setting the od_control.od_color_char
variable to 0.
Note that the string to be displayed by od_printf() should not
exceed 511 characters in size, including the size of color
sequences and expanded % fields.
===============================================================================
OpenDoors 6.00 Manual End of Page 112
SEE ALSO od_disp_str(), od_disp(), od_putch(), od_repeat(), od_disp_emu()
EXAMPLE Below is a simple example of a user statistics door program,
which displays various pieces of information to the user, by
using the od_printf() function. Notice the use of color code
sequences in order to display the titles in a different color
from the information fields. Note that since the information
available to this door will depend on the BBS system under which
it is running, not all of the information displayed by this door
will be available under all BBS systems. For a description of
what information is available under what BBS systems, see the
OpenDoors control structure portion of this manual, which begins
on page 148.
#include "opendoor.h"
int main(int argc,char *argv[])
{
od_init(); /* Begin OpenDoors program */
od_printf("`bright white` YOUR STATISTICS\n\r"); /* Display title */
od_printf("---------------\n\r\n\r");
/* Display statistics */
od_printf("`red`NAME : `blue`%s\n\r",od_control.user_logintime);
od_printf("`red`LOCATION : `blue`%s\n\r",od_control.user_location);
od_printf("`red`PHONE NUMBER : `blue`%s\n\r",od_control.user_homephone);
od_printf("`red`LAST CALL : `blue`%s\n\r",od_control.user_lastdate);
od_printf("`red`NUMBER OF CALLS : `blue`%u\n\r",od_control.user_numcalls);
od_printf("`red`NUMBER OF PAGES : `blue`%u\n\r",od_control.user_numpages);
od_printf("`red`REMAINING TIME : `blue`%d\n\r",od_control.user_timelimit);
od_printf("`red`# OF DOWNLOADS : `blue`%u\n\r",od_control.user_downloads);
od_printf("`red`# OF UPLOADS : `blue`%u\n\r",od_control.user_uploads);
od_printf("`red`KBYTES DL TODAY : `blue`%u\n\r",od_control.user_todayk);
/* Ask user to press [Enter] */
od_printf("`bright green on green`Press [Enter] to return to BBS...\n\r");
while(od_get_key(TRUE)!=13); /* Wait for user to press [Enter] */
od_exit(20,FALSE); /* Return to BBS */
}
HELPFUL This section demonstrates use of the od_printf() color
HINT sequences imbedded directly in the printf() format string, such
as:
od_printf("Hello `bright green` there!");
===============================================================================
OpenDoors 6.00 Manual End of Page 113
However, there are also other ways that you can take advantage
of this feature. For example, the C programming language
concatenates string constants that are separated only by white
space or carriage returns. For instance,
"Hello " "`bright green`" " there!"
is equivalent to:
"Hello `bright green` there!"
For this reason, you can create macros for common color
sequences in your program, such as:
#define HIGHLIGHT "`bright green`"
You can then use such constants when calling the od_printf()
function, as follows:
od_printf("Hello " HIGHLIGHT " there!");
You may find this method of setting the display color to be
easier to read, and more easily configurable than including the
color sequence directly in the format string. Below another use
of the color sequences is describe, which allows the colors used
by od_printf() not be "hard-wired".
Since color control sequences are evaluated by od_printf() after
it evaluates all format sequences (such as "%d"). For this
reason, it is possible to change the display color using a
string variable, instead of using a fixed color in the string.
For example, if you program had the variable:
char highlight[40];
which was set at some point to be equal to:
"`bright green`"
you would be able to use od_printf() as follows:
od_printf("Hello %s there!", highlight);
The display color would then be changed at the location where
the "%s" appears in the od_printf() format string. The advantage
of using this method to change display colors is that unlike
other methods, the value of the highlight variable can be
changed. This could be used, for example, to allow the sysop to
configure the colors they wish your door to use. You would only
need to change the value of the highlight variable in order to
change the color set by od_printf().
===============================================================================
OpenDoors 6.00 Manual End of Page 114
OD_PUTCH()
-------------------------------------------------------------------------------
PURPOSE Function to display a single character.
FORMAT void od_putch(int chToDisplay);
RETURNS N/A
DESCRIPTION This function performs a similar function to the other OpenDoors
display functions. For information on the uses of the various
OpenDoors display functions, see the description of the
od_disp_str() function, on page 63. This function is most
similar to the od_disp() and od_disp_str() functions, except
that it only displays a single character at a time.
This function will display the character passed to it at the
cursor position in the output window, and then advance the
cursor to the next display position. If OpenDoors is not
operating in local mode, the character will also be sent to the
modem, and thus displayed on the user's screen in the same
manner that it is displayed on the local screen. If ANSI, AVATAR
or RIP graphics mode is activated the character will be
displayed in the current color.
SEE ALSO od_disp_str(), od_disp(), od_printf(), od_repeat(),
od_disp_emu()
EXAMPLE Below is an example of the use of the od_putch() function. This
example is a function which you could use in place of the
od_get_key() function. This function inputs a single character
from the keyboard, just as the od_get_key() function does.
However, if the character entered is a printable character, the
function will also echo the character to the local screen, using
the od_putch() function.
char get_key_with_echo(int wait)
{
char pressed=od_get_key(wait); /* Get key from user */
if(pressed>=32 && pressed<=126) /* If key is printable */
{
od_putch(pressed); /* Display the character */
}
return(pressed); /* Return key pressed by user */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 115
OD_PUTTEXT()
-------------------------------------------------------------------------------
PURPOSE Displays a rectangular region of text and color information, as
previously stored using od_gettext()
FORMAT BOOL od_puttext(INT nLeft, INT nTop, INT nRight, INT nBottom,
void *pBlock);
RETURNS TRUE on success
FALSE on failure
DESCRIPTION This function "pastes" a rectangular block of text and color
information that has been previously retrieved using
od_gettext(). The block is placed at the screen location
indicated by the variables nLeft, nTop, nRight and nBottom,
where nLeft and nRight are column numbers from 1 - 80, and nTop
and nBottom are row numbers from 1 - 23. The length and width of
the rectangle specified by nLeft, nTop, nRight and nBottom must
be the same as the length and width of the rectangle passed to
od_gettext() when storing the block of text.
This function attempts to display the pasted block as quickly as
possible, only transmitting information on portions of the block
that are different than the original screen contents. When this
function returns, it leaves the cursor at its original position,
and the display color at its original setting. This function
requires ANSI or AVATAR mode.
The control structure variable od_control.od_full_put may be set
to TRUE to force od_puttext() to always send all characters in
the block to be displayed, instead of only displaying the
portions of the block that differ from the original screen
contents. If you wish to save and restore the entire screen, you
can use od_save_screen() and od_restore_screen(), which work in
all display modes.
You may also use the od_puttext() to display a rectangular block
of text that you generate manually, instead of retrieving using
od_gettext(). To do this, you pass an array which contains the
text and color information for the rectangular area to be
painted, in the pBlock parameter. The array passed to
od_puttext() contains a two-byte sequence of information for
each character in the rectangle. The first byte contains the
ASCII code of the character to be displayed. The second byte
contains the color attribute value of the character, in the same
format as used by the od_set_attrib() function (described on
page 128). These two byte sequences are stored in the order in
which English is written; the array begins with the two byte
===============================================================================
OpenDoors 6.00 Manual End of Page 116
sequences for all of the characters on the first line, from left
to right, followed by the characters for the second line, and so
on. The length of each line must be exactly equal to the width
of the rectangular region to be painted.
SEE ALSO od_gettext(), od_save_screen(), od_restore_screen(),
od_scroll(), od_window_create(), od_window_remove()
===============================================================================
OpenDoors 6.00 Manual End of Page 117
OD_REPEAT()
-------------------------------------------------------------------------------
PURPOSE Repeatedly display the specified character any number of times,
using special graphics codes for greater speed, if possible.
FORMAT void od_repeat(char chValue, BYTE btTimes);
RETURNS N/A
DESCRIPTION This display function will repeatedly display the character
chValue, btTimes times. For a complete breakdown of the various
OpenDoors display functions, see the description of the
od_disp_str() function, located on page 63.
The advantage of using this function to display a series of
identical characters is that this function will use special
graphics-mode control sequences to display the repeated
character very efficiently, if the required graphics mode is
available. For example, in AVATAR mode, this function can
display an entire line of one character, by sending a control
sequence to the modem that is only three characters long. If
graphics mode is not turned on, then the od_disp_str() function
will simply send the specified character the appropriate number
of times. As with the other display functions, the output of
this function is sent to both the local and remote screens.
SEE ALSO od_putch(), od_disp_str(), od_disp(), od_printf(), od_disp_emu()
EXAMPLE The example function below demonstrates the use of the
od_repeat() function in drawing a window (a square box) on the
screen. This function is essentially a simplified version of the
od_draw_box() function, which is described on page 65. Unlike
this function, the od_draw_box() function allows the
customization of the characters used to draw the box's boarder,
and if possible uses additional AVATAR graphics codes to display
the window even faster than this function does. Thus, the
function below is really provided for demonstration purposes
only.
This function accepts four parameters, which indicate the
location of the upper left and lower right corners of the window
to be displayed. The function then displays the window with the
current color attribute settings. Since this function uses the
od_repeat() function, if AVATAR graphics are available, it can
display the entire window in a fraction of a second, even if it
is displaying a window the size of the entire screen at slow
===============================================================================
OpenDoors 6.00 Manual End of Page 118
baud rates. Note that this window display function requires that
the user has ANSI, AVATAR or RIP graphics mode enabled.
void draw_window(char left, char top, char right, char bottom)
{
char line_counter; /* Number of current line being drawn */
char between_size=(right-left)-1; /* X size of window */
od_set_cursor(top,left); /* move to top corner */
od_putch(218); /* display corner character */
od_repeat(196,between_size); /* display top line */
od_putch(191); /* display corner character */
/* loop through middle lines of window */
for(line_counter=top+1;line_counter<bottom;++line_counter)
{
od_set_cursor(line_counter,left); /* move to line start */
od_putch(179); /* display left line char */
od_repeat(' ',between_size); /* display blank area */
od_putch(179); /* display right line char */
}
od_set_cursor(bottom,left); /* move to bottom corner */
od_putch(192); /* display corner character */
od_repeat(196,between_size); /* display bottom line */
od_putch(217); /* display corner character */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 119
OD_RESTORE_SCREEN()
-------------------------------------------------------------------------------
PURPOSE Restores the screen contents as previous saved using the
od_save_screen() function. This function can be used in any
display mode.
FORMAT BOOL od_restore_screen(void *pBuffer);
RETURNS TRUE on success
FALSE on failure
DESCRIPTION This function restores the entire contents of the screen, along
with the current cursor position and display color, which was
previously stored using the od_save_screen() function. Unlike
the od_get_text() and od_put_text() functions, the
od_save_screen() and od_restore_screen() functions will work in
all display modes (ASCII, ANSI, AVATAR and RIP).
The pBuffer parameter must point to the buffer previously passed
to od_save_screen(). Note that the od_save_screen() and
od_restore_screen() functions save the stored information in
different formats than the od_getttext() and od_puttext()
functions. For this reason, you cannot save the screen contents
with od_gettext() and restore them with od_restore_screen(), or
visa-versa.
If this function fails for any reason, a value of FALSE is
returned, and the od_control.od_error variable is set to
indicate the reason for the failure. For more information on the
od_control.od_error variable, see page 185.
SEE ALSO od_save_screen(), od_gettext(), od_puttext(), od_clr_scr()
EXAMPLE For an example of how to use the od_restore_screen() function,
see the example which accompanies the od_save_screen() function,
on page 121.
===============================================================================
OpenDoors 6.00 Manual End of Page 120
OD_SAVE_SCREEN()
-------------------------------------------------------------------------------
PURPOSE Saves the contents of the screen, to later be restored using
od_restore_screen(). Can be used in any display mode.
FORMAT BOOL od_save_screen(void *pBuffer);
RETURNS TRUE on success
FALSE on failure
DESCRIPTION This function saves the entire contents of the screen, along
with the current cursor position and display color, to be later
restored using the od_restore_screen() function. Unlike the
od_get_text() and od_put_text() functions, the od_save_screen()
and od_restore_screen() functions will work in all display modes
(ASCII, ANSI, AVATAR and RIP).
The pBuffer parameter should point to a buffer where the current
screen information is to be stored. This buffer must be at least
4004 bytes in size.
Note that the od_save_screen() and od_restore_screen() functions
save the stored screen information in different formats than the
od_getttext() and od_puttext() functions. For this reason, you
cannot save the screen contents with od_save_screen() and
restore them with od_puttext(), or visa-versa.
Also, note that when used in RIP graphics mode, this function
only saves and restores textual information, and not bit-mapped
graphical information.
If this function fails for any reason, a value of FALSE is
returned, and the od_control.od_error variable is set to
indicate the reason for the failure. For more information on the
od_control.od_error variable, see page 185.
SEE ALSO od_restore_screen(), od_gettext(), od_puttext(), od_clr_scr()
EXAMPLE One case where you might wish to save and restore the contents
of the screen is when sysop chat mode is activated. This can be
accomplished by using the od_control.od_cbefore_chat and
od_control.od_cafter_chat variables. The following example
causes the screen contents to be saved and the entire screen
cleared, prior to entering sysop chat mode when the sysop
presses the "chat key". When the sysop ends chat mode, the
===============================================================================
OpenDoors 6.00 Manual End of Page 121
user's original screen is restored, and the user will be able to
continue working in the door as though nothing had happened.
Code to perform screen saving and restoring:
/* Function prototypes */
void before_chat_function(void);
void after_chat_function(void);
/* Buffer to hold contents of screen prior to chat */
char before_chat_buffer[4004];
/* Variable to store whether screen save was successful */
char before_chat_saved = FALSE;
/* Function which is called prior to entering chat mode */
void before_chat_function(void)
{
/* Store current screen contents */
before_chat_saved = od_save_screen(before_chat_buffer);
/* Present a blank screen for chat mode */
od_clr_scr();
}
/* Function which is called after exiting chat mode */
void after_chat_function(void)
{
/* If screen was successfully saved prior to chat */
if(before_chat_saved)
{
/* Restore original screen contents */
od_restore_screen(before_chat_buffer);
}
}
Code included in main() function to enable screen saving and
restoring code:
od_control.od_cbefore_chat = before_chat_function;
od_control.od_cafter_chat = after_chat_function;
===============================================================================
OpenDoors 6.00 Manual End of Page 122
OD_SCROLL()
-------------------------------------------------------------------------------
PURPOSE Scrolls any rectangular area of the screen a specified number of
lines upwards or downwards. Requires ANSI/AVATAR/RIP graphics
mode to be active.
FORMAT BOOL od_scroll(INT nLeft, INT nTop, INT nRight, INT nBottom,
INT nDistance, WORD nFlags);
RETURNS TRUE on success
FALSE on FAILURE
DESCRIPTION This function scrolls a rectangular area of the screen described
by the parameters nLeft, nTop, nRight and nBottom. The
parameters nLeft and nRight are column numbers from 1 - 80, and
the parameters nTop and nBottom are row numbers from 1 - 23.
The parameter nDistance indicates the direction and number of
lines to scroll the text in the specified area. Positive values
denote moving the text upwards, and negative values denote
moving the text downwards.
The new lines created by scrolling text will appear in the
current color. When this function returns, it leaves the cursor
at its original position, and the display color at its original
setting. This function requires ANSI or AVATAR modes. If ANSI
mode is active, this function is equivalent to calling
od_gettext(), od_puttext(), and then sending addition codes to
the modem clear the newly created lines. In ANSI mode, scrolling
can be accomplished more quickly if the area to be scrolled is
equal in width to the entire screen. This is because the
clearing of newly created lines is done by sending a simple
control sequence, instead of a line of space characters. If
AVATAR mode is active, scrolling of the window is accomplished
by sending a single 6-byte control sequence.
The last parameter to od_scroll(), nFlags, should normally be
set to SCROLL_NORMAL. However, if you set nFlags to
SCROLL_NO_CLEAR, the newly created lines at the top or bottom of
the screen are not cleared if it would take longer to do so.
SEE ALSO od_gettext(), od_puttext(), od_window_create(),
od_window_remove()
EXAMPLE For an example of a program which uses the od_scroll() function,
see the ex_chat.c example program, described on page 38.
===============================================================================
OpenDoors 6.00 Manual End of Page 123
OD_SEND_FILE()
-------------------------------------------------------------------------------
PURPOSE Sends an ASCII/ANSI/AVATAR/RIP file from disk, using terminal
emulation.
FORMAT BOOL od_send_file(char *pszFileName);
RETURNS TRUE if the file was successfully sent
FALSE if OpenDoors was unable to send the file
DESCRIPTION: This powerful function will display any ASCII, ANSI, AVATAR or
RIP file. The od_send_file() function can be used to display
existing BBS text files, such as a "logoff screen", before your
door hangs up on the user. You can also make use of the
od_send_file() function to build many of your door screens as
external files. This will allow you to easily create these
screens in an ANSI editor program, such as "TheDraw". It will
could also optionally allow sysops to customize your door for
use on their own BBS.
The od_send_file() function is called with the full path and
filename of the file you wish to have displayed. Thus, if you
wished to send the ANSI file MAINMENU.SCR, you would simply
call:
od_send_file("MAINMENU.SCR");
In many cases, instead of having just one file that you want
displayed in particular, you will have several different files,
and will want a different one displayed according to the user's
graphics mode. For example, you might have the four files,
MAINMENU.ASC, MAINMENU.ANS, MAINMENU.AVT and MAINMENU.RIP; the
.ASC file containing no special control codes, the .ANS file
containing ANSI control codes, the .AVT file containing AVATAR
control codes, and the .RIP file containing RIP graphics control
codes. In this case, you can have the od_send_file() function
automatically select the appropriate file according to the
user's current display mode, by omitting the extension
altogether. Thus, a call to:
od_send_file("MAINMENU");
would cause OpenDoors to automatically send the appropriate
file, according to the user's graphics mode settings. When the
od_send_file() function is used in this "automatic mode" (where
you do not specify a filename extension), it will look for one
of the four filename extensions listed below.
===============================================================================
OpenDoors 6.00 Manual End of Page 124
+----------------------------------------------------------+
| Extension| File type |
+----------+-----------------------------------------------|
| .ASC | Does not require any graphics mode to display |
| .ANS | Requires ANSI graphics mode to display |
| .AVT | Requires AVATAR graphics mode to display |
| .RIP | Requires RIP graphics mode to be displayed |
+----------------------------------------------------------+
If the user has RIP graphics enabled, od_send_file() will first
search for the .RIP file. If no file exists with the specified
filename and a .RIP extension, od_send_file() will then search
for .AVT, then .ANS, and if not found .ASC. If the user has only
ANSI graphics enabled, od_send_file() will attempt first to
display the .ANS file, and if not found will search for .ASC. In
the case that the user is using plain-ASCII mode, this function
will attempt only to display the .ASC file.
When displaying a .RIP file to the remote system, OpenDoors will
attempt to locate and display a corresponding .AVT/.ANS/.ASC
file on the local system. If no such file can be found, a window
will be displayed, indicating the name of the .RIP file that is
being sent to the remote system. When a .RIP file is being
displayed, page pausing is disabled.
When displaying .AVT/.ANS/.ASC files, od_send_file() will send
any ANSI or AVATAR codes in the file directly to the remote
terminal, and interpret them to display on the local screen
(regardless of the actual filename extension). This
interpretation is accomplished by OpenDoor's built in terminal
emulator. The terminal emulator fully supports all ANSI and
AVATAR level 0 and level 0+ control codes. The terminal emulator
will also translate Remote Access/QuickBBS style control codes,
if enabled by setting od_control.od_no_ra_codes to FALSE. The
control codes supported by OpenDoors are listed in the chart on
the following pages. When these control codes are inserted into
the file, OpenDoors will replace them with various pieces of
user or system information.
===============================================================================
OpenDoors 6.00 Manual End of Page 125
+-----------------------------------------------------+
| CONTROL | ASCII | |
| CODE | VALUE | DESCRIPTION |
+---------+-------+-----------------------------------|
| ^FA | 06,65 | Displays the user's full name |
| ^FB | 06,66 | Location the user is calling from |
| ^FC | 06,67 | Displays the user's password |
| ^FD | 06,68 | Business/data phone number |
| ^FE | 06,69 | Home/voice phone number |
| ^FF | 06,70 | Date of the user's last call |
| ^FG | 06,71 | Time of day of the last call |
| ^FH | 06,72 | The user's `A' flags settings |
| ^FI | 06,73 | The user's `B' flags settings |
| ^FJ | 06,74 | The user's `C' flags settings |
| ^FK | 06,75 | The user's `D' flags settings |
| ^FL | 06,76 | User's remaining netmail credit |
| ^FM | 06,77 | Number of messages posted by user |
| ^FN | 06,78 | Last read message number by user |
| ^FO | 06,79 | Displays security level of user |
| ^FP | 06,80 | Number of times user has called |
| ^FQ | 06,81 | Total # of uploads by user |
| ^FR | 06,82 | Total KBytes uploaded by user |
| ^FS | 06,83 | Total # of downloads by user |
| ^FT | 06,84 | Total Kbytes downloaded by user |
| ^FU | 06,85 | # of minute user has used today |
| ^FV | 06,86 | User's screen length setting |
| ^FW | 06,87 | User's first name only |
| ^FX | 06,88 | User's ANSI setting |
| ^FY | 06,89 | User's "continue?" prompt setting |
| ^FZ | 06,90 | Does user have screen clearing on |
| ^F0 | 06,48 | User's Full-screen editor setting |
| ^F1 | 06,49 | User's Quiet mode setting |
| ^F2 | 06,50 | User's hot-keys setting |
| ^F3 | 06,51 | Displays the user's alias |
| ^F4 | 06,52 | The date of the User's first call |
| ^F5 | 06,53 | The user's date of birth |
| ^F6 | 06,54 | User's subscription expiry date |
| ^F7 | 06,55 | Number of days until expiry |
| ^F8 | 06,56 | User's AVATAR setting |
| ^F9 | 06,57 | The user's upload:download ratio |
| ^F: | 06,58 | User's Upload K:download K ratio |
+-----------------------------------------------------+
===============================================================================
OpenDoors 6.00 Manual End of Page 126
+-----------------------------------------------------+
| CONTROL | ASCII | |
| CODE | VALUE | DESCRIPTION |
+---------+-------+-----------------------------------|
| ^F; | 06,59 | Full-screen message reader |
| ^KA | 11,65 | Total # of calls BBS has received |
| ^KB | 11,66 | Name of the last caller to BBS |
| ^KC | 11,67 | Total # of active messages on BBS |
| ^KD | 11,68 | Displays # of the first message |
| ^KE | 11,69 | Displays # of the last message |
| ^KF | 11,70 | # of times user has paged sysop |
| ^KG | 11,71 | Full name of the current weekday |
| ^KH | 11,72 | Displays total number of users |
| ^KI | 11,73 | Displays the current time |
| ^KJ | 11,74 | Displays the current date |
| ^KK | 11,75 | Minutes the user has been online |
| ^KL | 11,76 | Seconds the user has been online |
| ^KM | 11,77 | Minutes the user has used today |
| ^KN | 11,78 | Seconds the user has used today |
| ^KO | 11,79 | Minutes remaining for user today |
| ^KP | 11,80 | Seconds remaining for user today |
| ^KQ | 11,81 | The user's daily time limit |
| ^KR | 11,82 | Displays the current baud rate |
| ^KS | 11,83 | The current weekday in short-form |
| ^KT | 11,84 | The user's daily download limit |
| ^KU | 11,85 | # of minutes until the next event |
| ^KV | 11,86 | Time of the next system event |
| ^KW | 11,87 | # of node user is currently on |
| ^KX | 11,88 | Disconnects the user |
+-----------------------------------------------------+
SEE ALSO od_disp_emu(), od_list_files(), od_hotkey_menu()
EXAMPLE For an example of the use of the od_send_file() function in
displaying a custom door menu, see the EX_VOTE.C example
program, which is described beginning on page 38.
===============================================================================
OpenDoors 6.00 Manual End of Page 127
OD_SET_ATTRIB()
-------------------------------------------------------------------------------
PURPOSE Function to change the text color in ANSI or AVATAR mode, using
a single IBM-PC color attribute value.
FORMAT void od_set_attrib(INT nColor);
RETURNS N/A
DESCRIPTION od_set_attrib() is one of two functions which change the color
of the currently displayed text. This function allows you to set
the text color using a single IBM-PC style color attribute. On
the other hand, the od_set_color() function allows you to set
the display color by specifying a foreground and background text
color. Generally speaking, which of these two functions you use
will be only a matter of personal preference. You will, however,
most likely find it more convenient to use the od_set_color()
function for changing display color. However the od_set_attrib()
offers the advantage of allowing you to manipulate the color to
be displayed as a single value, instead of two separate values.
This could be convenient, for example, when displaying text in a
user configured color. Using a single byte to represent the
color will likely be easier than using two. An alternative
method of setting the color of displayed text is to include the
color codes within a string displayed by the od_printf()
function. The benefits of doing this, along with instructions on
how to do this, are described in the section on the od_printf()
function, which begins on page 110.
This function will only have an effect if the user has ANSI,
AVATAR or RIP modes enabled. As a result, you can use this
function within your door program, and have your text
automatically displayed in multiple colors if graphics mode is
available, and displayed without colors if graphics mode is not
available.
Note that the color to be set is passed to this function as an
IBM-style screen attribute. Hence, you can set the color of text
to be displayed by a single hexidecimal value, encoded as
follows:
+------------- Background color
|
0x7f
|
+------------ Foreground color
===============================================================================
OpenDoors 6.00 Manual End of Page 128
Where the left digit (most significant nibble) of the
hexidecimal number represents the background color, and the
right digit (least significant nibble) represents the foreground
color. Each of the possible colors, along with their
corresponding hexidecimal values, are listed in the charts,
below.
+-----------------------+ +--------------------------+
| Foreground colors | | Background | Flashing |
+-----------------------| +---------------+----------|
| 0 | Black | | 0 | Black | Off |
| 1 | Blue | | 1 | Blue | Off |
| 2 | Green | | 2 | Green | Off |
| 3 | Cyan | | 3 | Cyan | Off |
| 4 | Red | | 4 | Red | Off |
| 5 | Magenta | | 5 | Magenta | Off |
| 6 | Brown | | 6 | Brown | Off |
| 7 | White (grey) | | 7 | White | Off |
| 8 | Bright Black | | 8 | Black | On |
| 9 | Bright Blue | | 9 | Blue | On |
| a | Bright Green | | a | Green | On |
| b | Bright Cyan | | b | Cyan | On |
| c | Bright Red | | c | Red | On |
| d | Bright Magenta | | d | Magenta | On |
| e | Yellow | | e | Brown | On |
| f | White (bright) | | f | White | On |
+-----------------------+ +--------------------------+
SEE ALSO od_set_color(), od_disp_emu(), od_clr_scr(), od_clr_line(),
od_set_cursor()
EXAMPLE At times, you may wish to allow the user to select the color of
text they wish to have displayed, perhaps to configure your door
for the ideal colors to be displayed on their system. To
demonstrate the use of the od_set_attrib() function, we show
another function, which shows the user all 256 possible colors
that can be displayed, and allows the user to choose which color
they prefer. The function will then return the color attribute
value of the user's chosen color.
unsigned char choose_color(void)
{
register unsigned char counter; /* for displaying colors */
char string[4]; /* string input by user */
od_set_attrib(0x07); /* display title */
od_disp_str("Available colors:\n\r\n\r");
for(counter=0;counter<=255;) /* loop through all colors */
{
===============================================================================
OpenDoors 6.00 Manual End of Page 129
od_set_attrib(counter); /* set appropriate color */
od_printf("%03.3u",counter); /* display color's number */
if(((++counter)%16)==0) /* after every 16 colors ... */
{
od_set_attrib(0x07); /* ... reset display color ... */
od_disp_str("\n\r"); /* ... and start a new line */
}
}
od_set_attrib(0x07); /* Allow user to choose color */
od_disp_str("Which color do you prefer : ");
od_input_str(string,3,'0','9');
return(atoi(string)); /* Return chosen color */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 130
OD_SET_COLOR()
-------------------------------------------------------------------------------
PURPOSE Function to change the current display color in ANSI, AVATAR or
RIP modes, using foreground and background color values.
FORMAT void od_set_color(INT nForeground, INT nBackground);
RETURNS N/A
DESCRIPTION od_set_color() is one of two functions which change the color of
the currently displayed text. This function allows you to set
the text color using separate foreground an background text
colors, whereas od_set_attrib() allows you to set the text color
using a single IBM-PC style color attribute. Generally speaking,
which of these two functions you use is only a matter of
personal preference. An alternative method of setting the color
of displayed text is to include the color codes within a string
displayed by the od_printf() function. The benefits of doing
this, along with instructions on how to do this, are described
in the section on the od_printf() function, which begins on page
110.
This function will only have an effect if the user has ANSI,
AVATAR or RIP mode turned on. As a result, you can use this
function within your door program, and have your text
automatically displayed in multiple colors if graphics mode is
available, and displayed without colors if graphics mode is not
available.
The od_set_color() function accepts two parameters, the first
parameter being the foreground color to be used in displaying
text, and the second parameter being the background color to be
used in displaying text. For example,
od_set_color(L_WHITE,D_BLACK);
would set the current color to Light White on Dark Black. The
foreground and background text colors can be any one of the
color values listed on the following page.
===============================================================================
OpenDoors 6.00 Manual End of Page 131
+-------------------+-----------+
| Foreground Color | Value |
+-------------------+-----------+
| Dark Black | D_BLACK |
| Dark Blue | D_BLUE |
| Dark Green | D_GREEN |
| Dark Cyan | D_CYAN |
| Dark Red | D_RED |
| Dark Magenta | D_MAGENTA |
| Dark Brown | D_BROWN |
| Grey (Dark White) | D_GREY |
| Light Black (Grey)| L_BLACK |
| Light Blue | L_BLUE |
| Light Green | L_GREEN |
| Light Cyan | L_CYAN |
| Light Red | L_RED |
| Light Magenta | L_MAGENTA |
| Yellow | L_YELLOW |
| White | L_WHITE |
+-------------------+-----------+
+-------------------+-----------+
| Background Color | Value |
+-------------------+-----------+
| Black | D_BLACK |
| Blue | D_BLUE |
| Green | D_GREEN |
| Cyan | D_CYAN |
| Red | D_RED |
| Magenta | D_MAGENTA |
| Brown | D_BROWN |
| Grey | D_GREY |
| Blinking Black | B_BLACK |
| Blinking Blue | B_BLUE |
| Blinking Green | B_GREEN |
| Blinking Cyan | B_CYAN |
| Blinking Red | B_RED |
| Blinking Magenta | B_MAGENTA |
| Blinking Brown | B_BROWN |
| Blinking Grey | B_WHITE |
+-------------------+-----------+
SEE ALSO od_set_attrib(), od_disp_emu(), od_clr_scr(), od_clr_line(),
od_set_cursor()
EXAMPLE As an example of using the od_set_color() function to set the
color of displayed text, we show a pair of two functions. These
functions will allow a program to set the foreground OR
===============================================================================
OpenDoors 6.00 Manual End of Page 132
background color of text, without setting the other. In
contrast, the od_set_color() function sets both the foreground
and background color at the same time. These function presume
that they are the only functions used within the door to set the
color of displayed text, and that the original text color prior
to calling either of these functions is dark white on black.
These function must also have access to the two global variables
"current_foreground" and "current_background", as defined below.
void set_foreground(char foreground);
void set_background(char background);
unsigned char current_foreground=D_BLACK;
unsigned char current_background=D_GREY;
void set_foreground(char foreground)
{ /* set new text color */
od_set_color(foreground, current_background);
current_foreground=foreground; /* save new foreground */
}
void set_background(char background)
{ /* set new text color */
od_set_color(current_foreground, background);
current_background=background; /* save new background */
}
Using these functions, you would then be able to set just the
foreground text color by a function call like:
set_foreground(L_YELLOW);
Or set just the background text color by a function call like:
set_background(D_GREY);
===============================================================================
OpenDoors 6.00 Manual End of Page 133
OD_SET_CURSOR()
-------------------------------------------------------------------------------
PURPOSE Function to reposition the text cursor in ANSI, AVATAR or RIP
mode
FORMAT void od_set_cursor(INT nRow, INT nColumn);
RETURNS N/A
DESCRIPTION This function repositions the cursor to the specified row and
column on the screen. nRow can have a value of 1 to 23, and
nColumn can have a value of 1 to 80. ANSI, AVATAR or RIP mode
must be active.
SEE ALSO od_disp_emu(), od_clr_scr(), od_clr_line(), od_set_color(),
od_set_attrib()
EXAMPLE Below is a simple example that demonstrates the use of the
od_set_cursor() function. Note that this example detects whether
or not graphics mode is available, and if it is not, will carry
out the same task without the use of od_set_cursor().
od_init(); /* Initialize door operations */
od_clr_scr(); /* Clear the screen */
if(od_control.user_ansi || od_control.user_avatar)
{ /* If graphics mode is available */
od_set_cursor(1,1); /* Display demo */
od_disp_str("Top, Left Corner");
od_set_cursor(1,70);
od_disp_str("Top, Right Corner");
od_set_cursor(15,1);
od_disp_str("Fifteenth line\n\r");
}
else /* If graphics mode is not available */
{ /* Display demo */
od_disp_str("Top, Left Corner");
od_repeat(' ', 54);
od_disp_str("Top, Right Corner\n\r");
od_disp_str("\n\n\n\n\n\n\n\n\n\n\n\n\n");
od_disp_str("Fifteenth line\n\r");
}
od_get_key(TRUE); /* Wait for user to press key */
===============================================================================
OpenDoors 6.00 Manual End of Page 134
OD_SET_DTR()
-------------------------------------------------------------------------------
PURPOSE Controls the DTR (Data Terminal Ready) signal to the modem. Used
primarily to cause the modem to "hang up".
FORMAT void od_set_dtr(BOOL bHigh);
RETURNS N/A
DESCRIPTION In certain circumstances (such as call back verification doors),
you may wish to "hang up" the modem without exiting your door
program. This can be accomplished with most modems by
controlling the DTR (Data Terminal Ready) signal to the modem.
Passing a FALSE value to od_set_dtr() causes the DTR signal to
be set low, and passing a TRUE value causes the DTR signal to be
set high. Normally, OpenDoors maintains the DTR signal in its
high state. Since most (but not all) modems are configured to
disconnect from the remote modem when the DTR signal is set low,
calling od_set_dtr(FALSE) can be used to hangup the modem. When
hanging up by this method, you should be sure to set the DTR
signal high again, after the carrier detect signal has
disappeared. For more information on determining the state of
the carrier detect signal, see the od_carrier() function, which
is described on page 51. Note that not all modems will
disconnect from the remote user in response to your lowering the
DTR signal. If your software may be used with such modems, you
may wish to also provide the option of disconnecting the modem
by sending a "hang up" command sequence to the modem.
Since OpenDoors normally monitors the carrier detect signal, and
exits when this signal disappears, you will have to disable
OpenDoor's carrier detection if you wish your program to
continue executing after hanging up the modem. OpenDoor's
automatic carrier detection can be disabled using the
od_control.od_disable OpenDoors control structure variable, as
follows:
od_control.od_disable |= DIS_CARRIERDETECT;
SEE ALSO od_carrier(), od_exit()
EXAMPLE For an example of using the od_set_dtr() function to "hang up"
the modem, see the example that accompanies the od_carrier()
function, which is described on page 52.
===============================================================================
OpenDoors 6.00 Manual End of Page 135
OD_SET_PERSONALITY()
-------------------------------------------------------------------------------
PURPOSE Sets the current status line / sysop function key personality to
be used.
FORMAT BOOL od_set_personality(char *pszName);
RETURNS TRUE on success
FALSE on failure
DESCRIPTION This function changes the current status line / sysop function
key personality. The pszName parameter should contain the string
which uniquely identifies the personality to be set. This
function may only be used by OpenDoors programs which include
the OpenDoors "Multiple Personality System". To enable use of
the MPS, include the following line before your first call to
any OpenDoors function:
od_control.od_mps=INCLUDE_MPS;
OpenDoors includes a number of built-in personalities.
Additional personalities may be added using the
od_add_personality() function, which is described on page 47.
The following personalities are included with this version of
OpenDoors:
Name Description
-----------------------------------------------------------
Standard OpenDoors style, similar to RA 1.11
PCBoard Similar to PC-Board
RemoteAccess Similar to RemoteAccess 2.x
Wildcat Similar to Wildcat!
Personality names are not case sensitive. For more information
on the OpenDoors Multiple Personality System, see the section
which begins on page 233.
This function returns TRUE on success, or FALSE on failure. In
the case of a failure, the od_control.od_error variable is set
to indicate the nature of the failure. For more information on
the od_control.od_error variables, see page 185.
SEE ALSO od_add_personality(), od_set_statusline()
===============================================================================
OpenDoors 6.00 Manual End of Page 136
OD_SET_STATUSLINE()
-------------------------------------------------------------------------------
PURPOSE To set the currently displayed status line.
FORMAT void od_set_statusline(INT nSetting);
RETURNS N/A
DESCRIPTION If you have the OpenDoors status line enabled within your door
program (as is the default), the sysop will be able to control
the setting of the status line using the F1 - F10 keys on the
keyboard. These function keys are as follows:
[F1] - Display basic door and user information
[F2] - Display phone numbers and important dates
[F3] - Display security flags and up/download info
[F4] - Display system information and current time
[F5] - Display message info and user's settings
[F6] - Display chat reason and sysop's comment
[F9] - Display help information for sysop
[F10] - Turn off the status line
Using the od_set_statusline() function, you can manually set
which of these status line settings is currently selected. The
od_set_statusline() accepts a single parameter, which should be
one of the values listed below, which indicates which status
line you would like to have selected:
+---------------+---------------+------------------------------+
| | Corresponding | |
| Value | Function Key | Meaning |
+---------------+---------------+------------------------------+
| STATUS_NORMAL | [F1] | Basic door and user info |
| STATUS_NONE | [F10] | Turn off status line |
| STATUS_HELP | [F9] | Displays help for the sysop |
| STATUS_USER1 | [F2] | Phone Numbers and dates |
| STATUS_USER2 | [F3] | Security flags & up/downloads|
| STATUS_USER3 | [F5] | Message info & user settings |
| STATUS_USER4 | [F6] | Chat reason and sysop comment|
| STATUS_SYSTEM | [F4] | System info & current time |
+---------------+---------------+------------------------------+
(Note that these keys may be customized using variables in the
OpenDoors control structure.)
Keep in mind that the od_set_statusline() function only
temporarily changes the current status line setting, and that
the sysop will still be able to change the status line to any of
the other settings using the function keys. For instance, if you
===============================================================================
OpenDoors 6.00 Manual End of Page 137
wished to allow the sysop to normally see all 25 lines of text
displayed by your door, but at the same time to still allow the
sysop to turn on the status line at any time, you could place
the line
od_set_statusline(STATUS_NONE);
at the beginning of your program. Similarly, when the user pages
the sysop, OpenDoors itself calls
od_set_statusline(STATUS_USER4);
in order to display the status line which shows the user's
reason for chat, while still allowing the sysop to switch back
to any of the other status lines.
If you wish to permanently turn off the OpenDoor's status line,
without allowing the sysop to be able to turn it back on using
the sysop function keys, simply set the
"od_control.od_status_on" variable to FALSE. This variable is
described in the OpenDoors control structure section of this
manual, which begins on page 148.
===============================================================================
OpenDoors 6.00 Manual End of Page 138
OD_SLEEP()
-------------------------------------------------------------------------------
PURPOSE Suspends program execution, yielding control to other tasks in a
multitasking environment.
FORMAT void od_sleep(tODMilliSec Milliseconds);
RETURNS N/A
DESCRIPTION od_sleep() suspends execution of your program for the specified
number of milliseconds. Note that under the DOS version of
OpenDoors, this value is rounded to the nearest 55 milliseconds.
While the program's execution is suspended, od_sleep() yields
control of the processor to other tasks in a multitasking
environment.
Calling od_sleep() with a sleep time of 0 causes control to be
yielded to other waiting processes without imposing a minimum
sleep time. If no other processes are waiting to execute, the
function returns immediately. OpenDoors automatically calls
od_sleep(0) itself in most of the situations where there is a
need to do so. However, there may be circumstances under which
od_sleep(0) can be used to improve performance. In particular,
od_sleep(0) can be used to improve the performance of other
applications that are also running at the same time as yours. By
calling od_sleep(0), you are essentially telling the operating
system that your program doesn't currently need all of the
processing time that has been allocated to it. While appropriate
use of od_sleep(0) can improve overall system performance,
overusing od_sleep(0) can dramatically degrade the performance
of your own program. The only way to determine the optimal use
of od_sleep(0) is by trial and error.
The most common situation where you might want to use
od_sleep(0) is when your program cannot do anything useful until
you receive input from the user, but for some reason you cannot
call od_get_key(TRUE). Rather than sitting in a tight loop,
repeatedly checking where the user has pressed a key yet, it is
better to call od_sleep(0) to let other tasks run for a while
before checking again. OpenDoors calls od_sleep(0) itself under
any of the following circumstances:
- When transmitting characters, if the outbound serial
buffer is full, OpenDoors yields while waiting for some
of the characters in the buffer to be sent.
- During od_get_key(), if called with the wait parameter
set to TRUE.
===============================================================================
OpenDoors 6.00 Manual End of Page 139
- While waiting for input, during the execution of any of
the following input functions: od_get_answer(),
od_hotkey_menu() (after menu has been displayed),
od_popup_menu(), od_edit_str(), od_input_str().
- While pausing at the end of a screen during
od_send_file(), od_list_files(), od_hotkey_menu().
- During chat mode.
SEE ALSO od_kernel()
===============================================================================
OpenDoors 6.00 Manual End of Page 140
OD_SPAWN()
-------------------------------------------------------------------------------
PURPOSE To facilitate easy execution of child tasks from doors.
FORMAT BOOL od_spawn(char *pszCommandLine);
RETURNS TRUE on success,
FALSE on failure
DESCRIPTION This function allows you to easily run other programs from
within your door programs, such as external file transfer
utilities, compression utilities, and so on.
This function will attempt to swap OpenDoors and your entire
door to expanded memory or disk. OpenDoors swapping can be
controlled by the OpenDoors control structure variables,
od_swapping_disable, od_swapping_ems and od_swap_path. The
od_spawn...() functions first attempt to swap OpenDoors to EMS
memory. If enough EMS 3.2 or later memory is available, it will
be used. If not, OpenDoors will swap to a disk file in the
directory specified by the od_control.od_swap_path variable.
Unlike the other Turbo C(++) / Borland C++ library functions
such as system() or spawnf(), this function will automatically
store the door screen prior to executing the sub-program, and
will restore the screen upon return. This function will also
store the current drive and directory settings prior to
executing the program, and restore them after the program has
returned.
Normally, the user's time will continue to be decreased during
the execution of the od_spawn() function. However, you can
freeze the user's time during the spawn process by using the
OpenDoors control structure variable od_spawn_freeze_time.
SEE ALSO od_spawnvpe()
EXAMPLE Below are a few examples of various uses of the od_spawn()
function:
To run the command processor from within your door program, to
allow the sysop access to the DOS shell, simply use the
following line of code:
od_spawn(getenv("COMSPEC"));
===============================================================================
OpenDoors 6.00 Manual End of Page 141
The following function is an example of using the od_spawn()
function to call DSZ, allowing the user to download a file. You
pass the name of the file that you wish to send to the user.
This function will then ask the user what transfer protocol they
would like to use, generate the appropriate DSZ command line,
and then transmit the file to the user. Note that in order to
use a door which implements this function, the external file
transfer program "DSZ" must be available in the current search
path. As an alternative, you may want to allow the sysop to
specify the location of the DSZ file from within a configuration
program. If you wish to receive a file (allow the user to
upload), instead of sending one, simply change the "s" in the
command line to a "r".
char download(char *filename)
{
char commandline[80];/* string containing DSZ command line */
char protocol; /* character representing chosen protocol */
/* display protocol menu */
od_printf("Select File Transfer Protocol:\n\r");
od_printf(" [X] XModem\n\r");
od_printf(" [Y] YModem\n\r");
od_printf(" [Z] ZModem\n\r");
od_printf("or press [A] to abort transfer\n\r");
do /* loop until valid protocol has been chosen */
{
protocol=od_get_key(); /* get key */
/* abort if [A] key is pressed */
if(protocol=='a' || protocol=='A') return(FALSE);
} while(protocol!='x' && protocol!='y' && protocol!='z' &&
protocol!='X' && protocol!='Y' && protocol!='Z');
od_printf("Begin receiving file now or press [CTRL]-[X] to
abort\n\r");
/* generate DSZ command line */
sprintf(commandline,"dsz port %d s%c %s",
od_control.port+1,
protocol,
filename);
return(od_spawn(commandline)); /* spawn to DSZ */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 142
OD_SPAWNVPE()
-------------------------------------------------------------------------------
PURPOSE To facilitate easy execution of child tasks from doors. Allows
specification of child's environment, returns errorlevel
returned by child task, and searches path for the executable
file.
FORMAT INT16 od_spawnvpe(INT16 nModeFlag, char *pszPath,
char *papszArg[], char *papszEnv[]);
RETURNS -1 on failure
errorlevel returned by child process on success
DESCRIPTION This function behaves very similarly to the od_spawn() function.
Thus, to save space in the manual, I will not recapitulate what
is already said in the description of the od_spawn() function.
Instead, this description concentrates on the additional
features available through the od_spawnvpe() function. If you
are not already familiar with the od_spawn() function, take a
moment now to review the description of that function.
The od_spawn() function (the OpenDoors "quick-spawn" function)
is designed to be quick and easy to use, but does not have all
of the features available in the od_spawnvpe() function. In
addition to the features of the od_spawn() function, the
od_spawnvpe() function also provides the following features:
- od_spawnvpe() will search the "path" for the file
to be executed.
- od_spawnvpe() allows you to pass an altered
environment to the child process.
- od_spawnvpe() returns the errorlevel returned by
the child process.
The parameters passed to the od_spawnvpe() function are
identical to those passed to the C spawnvpe() function. The
first parameter should usually the be P_WAIT flag. The second
parameter is the name of the child program to execute. If a full
path to the child program is not specified, and the child
program does not exist in the current directory, OpenDoors will
search the directories listed by the PATH environment variable.
Also, if the .EXE or .COM extension is not provide, OpenDoors
will look first for a .COM file, and if not found, for a .EXE
file. The third parameter is an array of arguments to pass to
the child process, or NULL if no arguments are to be passed. The
===============================================================================
OpenDoors 6.00 Manual End of Page 143
fourth parameter is the environment to be passed to the child
process, or NULL if the a copy of the current environment should
be used.
SEE ALSO od_spawn()
EXAMPLE For an example of the use of the od_spawn...() functions, see
the example accompanying the od_spawn() function. As a specific
example of the od_spawnvpe function, consider the following code
which executes the "TEST.EXE" program.
od_spawnvpe(P_WAIT,"TEST.EXE",NULL,NULL);
===============================================================================
OpenDoors 6.00 Manual End of Page 144
OD_WINDOW_CREATE()
-------------------------------------------------------------------------------
PURPOSE Creates a popup window of the specified size and color, storing
the contents of the screen "under" the window. The window can
later be removed from the screen, restoring the original
contents of the screen "under" the window, using the
od_window_remove() function. Requires ANSI, AVATAR or RIP mode.
FORMAT void *od_window_create(INT nLeft, INT nTop, INT nRight, INT
nBottom,
char *pszTitle, BYTE btBorderCol, BYTE btTitleCol,
BYTE btInsideCol, INT nReserved);
RETURNS Pointer to newly allocated window structure on success
NULL on failure
DESCRIPTION This function creates a pop-up window on the remote and local
screens. The contents of the screen beneath the window are
stored, to allow the window to later be removed from the screen
using the od_window_remove() function. The window is drawn using
the boarder characters defined in the already existing
od_control.od_box_chars[] array. The boarder is displayed using
the color attribute specified in btBorderCol. The working area
of the window is created in the color specified in btInsideCol.
A title may optionally be displayed on the window by specifying
a string in pszTitle. This title will be displayed in the color
specified by btTitleCol. If you do not wish a title to be
displayed, pass an empty string or NULL pointer in pszTitle. On
success, od_window_create() will return a pointer to a buffer
which was allocated to store information on the window and the
contents of the screen "under" the window. This pointer should
at some point be passed in a call to od_window_remove().
This function requires ANSI, AVATAR or RIP graphics mode. If
AVATAR mode is active, this function will take advantage of
special AVATAR control sequences to display the window much
faster than is possible in ANSI mode. In ANSI mode, window
display will be slightly faster if btBorderCol and btTitleCol
are equal. Note that the nReserved parameter of this function is
not currently used. To preserve compatibility with future
versions of OpenDoors, this parameter should always be set to 0.
Currently, the size of the buffer allocated to store the window
information will be (length*width*2) + 4 bytes in size.
If od_window_create() fails for any reason, a value of NULL is
returned, and the od_control.od_error variable is set to
indicate the reason for the failure. For more information on the
od_control.od_error variable, see page 185.
===============================================================================
OpenDoors 6.00 Manual End of Page 145
SEE ALSO od_window_remove(), od_draw_box(), od_gettext(), od_puttext(),
od_save_screen(), od_restore_screen(), od_scroll()
EXAMPLE For an example of the use of the od_window_create() function,
see the included ex_chat.c example program.
===============================================================================
OpenDoors 6.00 Manual End of Page 146
OD_WINDOW_REMOVE()
-------------------------------------------------------------------------------
PURPOSE Removes a window previously created using od_window_create(),
restoring the original screen background.
FORMAT BOOL od_window_remove(void *pWinInfo);
RETURNS TRUE on success
FALSE on failure
DESCRIPTION The od_window_remove() function removes a window from the screen
which was previously created by od_window_create(), and
deallocates the memory which was allocated to store the window
information. The contents of the screen beneath the window is
restored to appear as it did prior to the call to
od_window_create(). pWinInfo must point to the value returned by
od_window_create().
Note that overlapping windows must be removed in the reverse
order from which they were created for proper display results.
The last window to be created must be the first window to be
removed.
If od_window_remove() fails for any reason, a value of FALSE is
returned, and the od_control.od_error variable is set to
indicate the reason for the failure. For more information on the
od_control.od_error variable, see page 185.
SEE ALSO od_window_create(), od_draw_box(), od_gettext(), od_puttext(),
od_save_screen(), od_restore_screen(), od_scroll()
EXAMPLE For an example of the use of the od_window_remove() function,
see the included ex_chat.c example program.
===============================================================================
OpenDoors 6.00 Manual End of Page 147
555555
55
55
55555
55
55
55555
-------------------------------------------------------------------------------
CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE
INTRODUCTION TO THE CONTROL STRUCTURE
-------------------------------------------------------------------------------
The OpenDoors "Control Structure" is used by OpenDoors in order
to provide you with a wide range of information about the system
on which you door is running, and the user who is currently
using the door, along with providing you a means by which to
customize much of OpenDoor's behavior. Using the OpenDoors
control structure, you can access or alter information about the
user who is online, information about the system on which your
door is running, and information about OpenDoors itself. You can
also use the control structure to customize all of the text
displayed by OpenDoors, the function keys to which it responds,
and many other aspects of OpenDoor's behavior.
The OpenDoors control structure is quite simply a normal C
"struct", named od_control, and is defined in the OPENDOOR.H
file. This "struct" contains many different variables, which
provide you access to the information provided by the control
structure. Hence, to access the contents of a control structure
variable, for example the variable "system_name" which contains
the name of the BBS the door is running under, you would use:
od_control.system_name
The following section of this chapter contains a complete
reference to all of the variables which make up the OpenDoors
control structure. This reference includes the name, type and
complete description of the use of each variable. The reference
is divided into the following categories of variables, with the
reference to the variables in each section beginning on the
listed page.
Door Information File Statistics..................150
Modem Settings....................................153
BBS and Caller Information........................158
Door Settings.....................................182
OpenDoors Behavior Customization..................187
Function Keys Customization.......................212
===============================================================================
OpenDoors 6.00 Manual End of Page 148
Color Customization...............................237
Text Customization................................217
Within each section, variables are listed alphabetically by
name.
Also, in order to make use of some of the variables in the
OpenDoors control structure, it is important to understand the
concepts of Boolean (TRUE/FALSE), and bit-mapped flag variables.
If you are not familiar with these two terms, they are described
in detail in the glossary, located towards the end of this
manual.
===============================================================================
OpenDoors 6.00 Manual End of Page 149
CONTROL STRUCTURE - DOOR INFO FILE STATS
-------------------------------------------------------------------------------
The following OpenDoors control structure variables provide your
program with information concerning the door information file
from which OpenDoors obtained the BBS and caller information
that is found elsewhere in the control structure. The following
control structure items are listed in this section:
info_path Sets the location and, optionally, the
name of the door information file
od_info_type Type of door information file that was
found
od_node Node number the door is running under
user_timeofcreation The time at which the door information
file was created
-------------------------------------------------------------------------------
info_path char od_control.info_path[60];
If used, this variable should be set prior to calling od_init()
or any other OpenDoors function. This variable allows you to
control where OpenDoors will look for the door information (drop
file). By default, OpenDoors searches for the door information
file in the current directory. If this variable is set to the
name of some other directory, OpenDoors will first search for
any door information files in that directory. If you only wish
OpenDoors to look for a particular type of door information file
(for instance, you want OpenDoors to only read a DORINFO1.DEF,
and ignore any DOOR.SYS file), you can specify the full path and
filename of the file you wish OpenDoors to use.
It is usually a good idea to design your door to allow the
system operator to set the location of the door information
file. This will allow the sysop to place your door in its own
directory, and will facilitate the use of your door on multi-
line BBS systems. If you are using the OpenDoors configuration
file system, then the system operator can set the door
information file location and/or name using the BBSDir keyword.
However, you may also wish to allow the location of the door
information file to be set on the command line. The following
example illustrates a method of reading and setting the location
of the door information file from the door's command line:
#include "opendoor.h"
===============================================================================
OpenDoors 6.00 Manual End of Page 150
main(int argc, char *argv[])
{
if(argc>1) strncpy(od_control.info_path,argv[1],59);
od_disp_str("This is a sample OpenDoors door.\n\r");
od_disp_str("Press any key to continue...\n\r");
od_get_key(TRUE);
od_exit(20);
}
-------------------------------------------------------------------------------
od_info_type char od_control.od_info_type;
This variable indicates the type of information file from which
OpenDoors has obtained the BBS and caller information that is
found elsewhere in the OpenDoors control structure. This
variable will have one of the following values, indicating that
the door information file was of the corresponding type:
+----------------+----------------------------+
| od_info_type | Door Information File Type |
| Value | |
+----------------+----------------------------+
| DORINFO1 | DORINFO?.DEF |
| EXITINFO | EXITINFO.BBS (Normal) |
| RA1EXITINFO | EXITINFO.BBS (Extended) |
| RA2EXITINFO | EXITINFO.BBS (RA 2.x) |
| QBBS275EXITINFO| EXITINFO.BBS (QuickBBS) |
| CHAINTXT | CHAIN.TXT |
| SFDOORSDAT | SFDOORS.DAT |
| CALLINFO | CALLINFO.BBS |
| DOORSYS_GAP | DOOR.SYS (GAP/PC-Board) |
| DOORSYS_DRWY | DOOR.SYS (Doorway style) |
| DOORSYS_WILDCAT| DOOR.SYS (WildCat standard)|
| CUSTOM | Custom door information |
| | file, defined in config |
| | file. |
| NO_DOOR_FILE | No drop file was found. |
+----------------+----------------------------+
The value of this variable is only valid AFTER od_init() or some
OpenDoors function has been called.
Note that this variable should be treated as a read-only
variable, and should not normally be altered by your program.
Altering this variable may cause OpenDoors to re-write a
different type of door information file upon exiting, than was
read upon startup.
===============================================================================
OpenDoors 6.00 Manual End of Page 151
-------------------------------------------------------------------------------
od_node char od_control.od_node;
This variable indicates the node number that the door is running
under. If this information is supplied by the BBS in the door
information file, the node number will be automatically by
OpenDoors. Specifically, the node number can be determined
automatically from systems that produce an SFDOORS.DAT, PC-
Board/GAP style DOOR.SYS or Wildcat style DOOR.SYS door
information file. If this information is not supplied in the
door information file, but is provided by the sysop in the
door's configuration file, OpenDoors will use the value found
there. Alternatively, you can set this variable manually.
On systems that produce a DORINFO?.DEF file, OpenDoors will use
this variable to determine which DORINFO?.DEF file to search
for. For instance, if od_control.od_node is set to 3, OpenDoors
will first search for a DORINFO3.DEF file. If this file is not
found, OpenDoors will then default to the DORINFO1.DEF filename.
-------------------------------------------------------------------------------
user char od_control.user_timeofcreation[6];
_timeof
creation This variable contains the time of day at which the door
information file was created. This variable is available only
when the door is running under a system that produces an
EXITINFO.BBS file. To determine what type of door information
file your door is running under, see the od_control.od_info_type
variable, below.
===============================================================================
OpenDoors 6.00 Manual End of Page 152
CONTROL STRUCTURE - SERIAL PORT SETTINGS
-------------------------------------------------------------------------------
The following OpenDoors control structure items store the
communications settings that OpenDoors uses to communicate with
the modem. These values are normally set upon the first call to
an OpenDoors function, during the od_init() procedure. However,
you may need to manual set this variables if:
- you wish to allow greater configurability of your door
- you are reading the door information file yourself
- you are using the OpenDoors to write a non-door
program
Some of these variables are always used by OpenDoors, while
others are only relevant if OpenDoor's built-in serial
communications code is being used instead of a FOSSIL driver.
Those that are only used when no FOSSIL driver is present are
denoted by an [*] in the list below.
The control structure variables controlling OpenDoor's serial
port settings are as follows:
od_control.baud Serial Port BPS rate
od_control.od_connect_sppedThe modem connection BPS rate
od_control.od_com_address Serial Port address [*]
" " .od_com_fifo_trigger 16550A FIFO trigger size
" " .od_com_flow_control Type of flow control to use.
od_control.od_com_irq Serial Port IRQ number [*}
od_control.od_com_method Is FOSSIL or built-in serial I/O
being used
od_control.od_com_no_fifo Disables use of 16550A FIFOs [*]
od_control.od_com_rx_buf Size of receive buffer [*]
od_control.od_com_tx_buf Size of transmit buffer [*]
od_control.od_no_fossil Prevents OpenDoors from using a
FOSSIL driver, even if one is
available.
od_control.od_open_handle Allows a live serial port handle to
be passed to OpenDoors.
od_control.port Serial port number, 0 based.
===============================================================================
OpenDoors 6.00 Manual End of Page 153
-------------------------------------------------------------------------------
baud unsigned long od_control.baud;
This variable contains the BPS rate at which the computer is
communicating with the modem, not to be confused with the BPS
rate at which the local modem is communicating with the remote
modem.
A value of 0 indicates that the program is operating in local
mode.
If a FOSSIL driver is being used for serial I/O, this value is
ignored if it does not correspond to one of the baud rates that
an application can directly set a FOSSIL driver to. The BPS
rates recognized by FOSSIL drivers are: 300, 600, 1200, 2400,
4800, 9600, 19200, 38400. If any other BPS rate is to be used,
the FOSSIL driver must be locked at that BPS from the FOSSIL
driver command-line. When locked, FOSSIL drivers ignore any
attempt by an application to change the BPS rate of the locked
port. For this reason, the od_control.baud setting has no effect
on the FOSSIL driver if it is locked.
-------------------------------------------------------------------------------
od_com_ int od_control.od_com_address;
address
This variable is only used when OpenDoors is NOT performing
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
used, the serial port address can be set from the FOSSIL driver
command line).
This variable may optionally be set to specify the base address
of the serial port to be used. For ports COM1: through COM4:,
OpenDoors can normally determine the serial port address
automatically. However, for other serial ports, the port address
must be specified using this variable. If you are not specifying
a serial port address with this variable, do not change it's
default value of 0.
-------------------------------------------------------------------------------
od_com_ char od_control.od_com_fifo_trigger;
fifo_trigger
This variable is only used when OpenDoors is NOT performing
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
used, the IRQ line can be set from the FOSSIL driver command
line).
===============================================================================
OpenDoors 6.00 Manual End of Page 154
This variable sets the number of bytes that will be placed in
the 16550A UART FIFO buffers before an interrupt is triggered,
if the 16550A UART FIFOs are used. Valid values are 1, 4, 8 and
14.
-------------------------------------------------------------------------------
od_com_ unsigned char od_control.od_com_flow_control;
flow_control
This variable sets the type of serial I/O flow control to use.
By default, this variable is set to COM_DEFAULT_FLOW, which
specifies the default mode of flow control. Most often, this
will be RTS/CTS flow control. A value of COM_RTSCTS_FLOW
explicitly enables RTS/CTS flow control. A value of COM_NO_FLOW
disables all flow control. If you are going to change the value
of this variable, it should be set prior to your first call to
any OpenDoors function.
-------------------------------------------------------------------------------
od_com_ unsigned char od_control.od_com_irq;
irq
This variable is only used when OpenDoors is NOT performing
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
used, the IRQ line can be set from the FOSSIL driver command
line).
This variable may optionally be set to specify the IRQ line to
be used for the serial port. By default, OpenDoors uses the
normal IRQ 4 line for ports COM1: and COM3:, and IRQ 3 for ports
COM2: and COM4:. To override this default, the IRQ line can be
set using this variable. If you are not specifying an IRQ line
with this variable, do not change it's default value of 0.
-------------------------------------------------------------------------------
od_com_ char od_control.od_com_method;
method
This read-only variable reports the method that OpenDoors is
using for serial I/O. This variable is set during od_init() or
the first call to an OpenDoors function. This variable can be
one of the following values:
COM_FOSSIL - Indicates that a FOSSIL driver is being
used
COM_INTERNAL - Indicates that OpenDoor's internal serial I/O
code is being used.
COM_WIN32 - Indicates that the Win32 communication system
===============================================================================
OpenDoors 6.00 Manual End of Page 155
is being used.
-------------------------------------------------------------------------------
od_com_ char od_control.od_com_no_fifo;
no_fifo
This variable is only used when OpenDoors is NOT performing
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
used, the receive buffer size can be set from the FOSSIL driver
command line).
Normally, OpenDoors will use a 16550A FIFO buffer if a 16550A
UART is installed. You can disable the use of the 16550A FIFO
buffer by setting this variable to TRUE.
-------------------------------------------------------------------------------
od_com_ unsigned int od_control.od_com_rx_buf;
rx_buf
This variable is only used when OpenDoors is NOT performing
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
used, the receive buffer size can be set from the FOSSIL driver
command line).
This variable allows you to set the size of OpenDoor's serial
I/O receive buffer. If you do not set this buffer size, a
default value of 256 characters is used. Normally, this buffer
size is more than large enough for door programs. However, if
you find that inbound characters are lost before they can be
processed by your program, you may wish to increase the size of
this buffer.
This variable should only be changed before your first call to
od_init() or any other OpenDoors function.
-------------------------------------------------------------------------------
od_com_ unsigned int od_control.od_com_tx_buf;
tx_buf
This variable is only used when OpenDoors is NOT performing
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
used, the receive buffer size can be set from the FOSSIL driver
command line).
This variable allows you to set the size of OpenDoor's serial
I/O transmit buffer. If you do not set this buffer size, a
default value of 1024 characters is used.
===============================================================================
OpenDoors 6.00 Manual End of Page 156
This variable should only be changed before your first call to
od_init() or any other OpenDoors function.
-------------------------------------------------------------------------------
od_connect_ DWORD od_control.od_connect_speed;
speed
This variable contains the best guess at the current modem
connection speed. This information is currently only accurate if
a DOOR.SYS file is being used. In other situations, it will
always be set to be equal to od_control.baud.
-------------------------------------------------------------------------------
od_open_ DWORD od_control.od_open_handle;
handle
Under platforms where this is supported (currently only the
Win32 version of OpenDoors), this variable can be used to pass a
live serial port handle to OpenDoors, which OpenDoors will use.
OpenDoors will not close this handle when it exits. If this
value is set to 0, OpenDoors will open and close the serial port
itself.
-------------------------------------------------------------------------------
port char od_control.port;
This variable contains the serial port number that the modem is
connected. This number is 0 based, so that a value of 0
corresponds to COM1:, a value of 1 corresponds to COM2:, and so
on. This value will normally be set by the od_init() function,
when the door information file is read, and should not be
changed after modem initialization has been carried out by the
od_init() function.
===============================================================================
OpenDoors 6.00 Manual End of Page 157
CONTROL STRUCTURE - BBS AND CALLER INFORMATION
-------------------------------------------------------------------------------
As we have already described, there are two types of variables
in the OpenDoors control structure. Some of the variables are
simply used to allow you to customize OpenDoor's various
features, such as altering colors, prompts, timeouts, etc. Other
variables in the OpenDoors control structure serve to provide
you with information about the user who is online and the BBS
system your door is running under. This section deals with those
variables that provide you with information about the BBS and
the user.
The information in these variables is read from the door
information file, a small file created by the BBS specifically
for the purpose of communicating with door programs. Depending
on what BBS system your door is running under, the type of door
information file will vary. Since different door information
files do not all provide the same pieces of information, some
variables in this section will only be available when your door
is running under particular BBS systems. Other variables will
be available with many or all BBS systems. In the description of
each variable in this section, we indicate under which door
information files the particular variable will be . So, if you
wish to access a variable that is only under certain door
information files, your program should test whether or not the
required information is available under the particular door
information file that was found. In order to determine which
door information file your door is running under, you should use
the od_control.od_info_type variable. This variable is described
in the section which begins on page 150. If you test the value
of the od_control.od_info_type variable, and find that the
required information is not available, you may wish to simply
use some sort of default value for the variable, or
alternatively, not allow your door to run under certain BBS
systems. Another possibility, if the required information is not
available, is imply to obtain this information from the user
yourself. For example, if you wished to know the length of the
user's screen, when this information is not available from the
door information file, you could simply prompt the user for
their screen length the first time they use your door. This
information could then be stored in your door's data files for
future reference.
As an example of testing what door information file your door is
running under, consider the case where you wanted to display the
user's birthday. The example below will display the user's
birthday if it is known, and otherwise, print the string
"unknown".
if(od_control.od_info_type == RA1EXITINFO
od_control.od_info_type == RA2EXITINFO)
===============================================================================
OpenDoors 6.00 Manual End of Page 158
{
od_disp_str(od_control.user_birthday);
}
else
{
od_disp_str("Unknown");
}
The chart below lists the door information file formats that
OpenDoors recognizes, along with example BBS systems that
produce these files and a reference letter for each type. Thus,
an OpenDoors door can run DIRECTLY under ANY BBS SYSTEM that
produces one of these files formats, and under ANY OTHER BBS
system when used in conjunction with a door information file
conversion utility.
+--------------------------+----------------------------------------+
| FILE FORMAT | EXAMPLE BBS SYSTEMS |
+--------------------------+----------------------------------------+
| CHAIN.TXT | WWIV |
+--------------------------+----------------------------------------+
| DORINFO1.DEF | RBBS-PC |
+--------------------------+----------------------------------------+
| DORINFO1.DEF | QuickBBS |
| & | Remote Access (versions 0.01-0.04) |
| EXITINFO.BBS (Std. Ver.) | |
+--------------------------+----------------------------------------+
| DOOR.SYS (DoorWay Style) | Remote Access |
+--------------------------+----------------------------------------+
| DOOR.SYS (PCB/GAP Style) | PC-Board |
| | GAP |
+--------------------------+----------------------------------------+
| DOOR.SYS (WildCat Style) | Wildcat 3.00 and above |
| | Telegard |
+--------------------------+----------------------------------------+
| SFDOORS.DAT | Spitfire |
| | TriBBS |
+--------------------------+----------------------------------------+
| CALLINFO.BBS | WildCat 2.xx |
+--------------------------+----------------------------------------+
| DORINFO1.DEF | Remote Access (versions 1.00 and later)|
| & | |
| EXITINFO.BBS (Ext. Ver.) | |
+--------------------------+----------------------------------------+
The chart on the following page lists all of the OpenDoors
control structure variables in this section, along with a brief
description of their use. The variables are then described in
detail, below.
===============================================================================
OpenDoors 6.00 Manual End of Page 159
+-----------------------+-----------------------------------------------+
| VARIABLE NAME | VARIABLE CONTENTS |
+-----------------------+-----------------------------------------------+
| EMSI INFORMATION | Information on current IEMSI session |
| event_status | The status of the next system event |
| event_starttime | The start time of the next system event |
| event_errorlevel | The errorlevel of the next system event |
| event_days | The days of the week to execute the event |
| event_force | Whether the next system event is forced |
| event_last_run | When the next system event was last run |
| sysop_name | The name of the BBS's sysop |
| system_calls | Total number of calls BBS has received |
| system_last_caller | The name of the last caller to the BBS |
| system_last_handle | The handle (alias) of the last caller |
| system_name | The name of the BBS |
| TIMELOG VARIABLES | The times at which the BBS has been most busy |
| user_ansi | Whether the user has ANSI graphics mode on |
| user_attribute | User attribute bit-mapped flags |
| user_attrib2 | Second set of user attribute bit-mapped flags |
| user_attrib3 | Third set of user attribute flags |
| user_avatar | Whether the user has AVATAR graphics mode on |
| user_birthday | The date the user was born |
| user_callsign | The user's amateur radio call sign |
| user_combinedrecord | The user's combined message areas settings |
| user_comment | Sysop's comment about the user |
| user_credit | Amount of NetMail credit the user has |
| user_dataphone | The user's data phone number |
| user_date_format | Format user wishes to have dates displayed in |
| user_deducted_time | Total time that has been subtracted from user |
| user_downk | Total Kilobytes downloaded by the user |
| user_downlimit | User's daily download limit |
| user_downloads | Total number of files downloaded by the user |
| user_echomailentered | Whether or not the user has entered EchoMail |
| user_error_free | Whether or not connection is error-free |
| user_file_area | The user's current file area |
| user_firstcall | Date of the user's first call to the BBS |
| user_flags | User's sysop-defined flag settings |
| user_forward_to | Name to forward user's mail to |
| user_group | User's group number |
| user_handle | User's alias |
| user_homephone | User's home telephone number |
| user_language | User's language setting |
| user_last_pwdchange | Total calls since last password change |
| user_lastdate | Date of the user's last call |
| user_lastread | Highest message number read by user |
| user_lasttime | Time of the user's last call |
| user_location | Name of the city where the user lives |
| user_logindate | Date on which the current call began |
+-----------------------+-----------------------------------------------+
===============================================================================
OpenDoors 6.00 Manual End of Page 160
+-----------------------+-----------------------------------------------+
| VARIABLE NAME | VARIABLE CONTENTS |
+-----------------------+-----------------------------------------------+
| user_loginsec | User's security at the beginning of this call |
| user_logintime | Time at which the current call began |
| user_logonpassword | User's password at the beginning of this call |
| user_menustack | Contents of the user's current menu stack |
| user_menustackpointer | Pointer to the top of the menu stack |
| user_messages | Total number of messages written by the user |
| user_msg_area | The user's current message area |
| user_name | The user's name |
| user_net_credit | The user's remaining netmail credit |
| user_netmailentered | Whether or not the user has entered NetMail |
| user_num | The user's record number in the user file |
| user_numcalls | Number of calls the user has made to the BBS |
| user_numpages | Number of times the user has paged the sysop |
| user_password | The user's current password |
| user_pending | The value of unsent NetMail written by user |
| user_reasonforchat | The reason the user wishes to chat with sysop |
| user_rip_ver | RIP protocol version being used |
| user_screen_length | The length of the user's screen |
| user_screenwidth | The width of the user's screen |
| user_security | The user's security access level |
| user_sex | The user's gender |
| user_subdate | The date the user's subscription expires |
| user_timelimit | The user's daily time limit |
| user_todayk | Kilobytes downloaded by the user today |
| user_upk | Total Kilobytes uploaded by the user |
| user_uploads | Total number of files uploaded by the user |
| user_wantchat | Whether or not the user wishes to chat |
| user_xi_record | The user's record in the USERSXI.BBS file |
+-----------------------+-----------------------------------------------+
-------------------------------------------------------------------------------
EMSI char od_control.ra_emsi_session;
INFORMATION char od_control.ra_emsi_crtdef[41];
char od_control.ra_emsi_protocols[41];
char od_control.ra_emsi_capabilities[41];
char od_control.ra_emsi_requests[41];
char od_control.ra_emsi_software[41];
char od_control.ra_hold_attr1;
char od_control.ra_hold_attr2;
char od_control.ra_hold_len;
These variables provide your door with information pertaining to
an interactive EMSI session that has been established. Note that
===============================================================================
OpenDoors 6.00 Manual End of Page 161
these variables are only available under systems that produce an
RA 1.00 and later style extended EXITINFO.BBS door information
file.
If an IEMSI session has been established, the Boolean variable
od_control.ra_emsi_session will be TRUE, and if no session has
not been established, this variable will be FALSE.
A full discussion of the IEMSI protocol is beyond the scope of
this manual. Specifications for the IEMSI protocol are available
from the OpenDoors support BBS.
-------------------------------------------------------------------------------
event_days unsigned char od_control.event_days;
This variable is a bit-mapped flag of the days of the week on
which the next system event is run. The bit-map bits are as
follows:
+-----+------+-----------+
| BIT | MASK | MEANING |
+-----+------+-----------+
| 0 | 0x01 | Sunday |
| 1 | 0x02 | Monday |
| 2 | 0x04 | Tuesday |
| 3 | 0x08 | Wednesday |
| 4 | 0x10 | Thursday |
| 5 | 0x20 | Friday |
| 6 | 0x40 | Saturday |
| 7 | 0x80 | All Days |
+-----+------+-----------+
For more information on bit-mapped flags, see the glossary item
entitled "BIT-MAPPED FLAGS".
This variable is only available under systems that produce an
EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
event_ unsigned char od_control.event_errorlevel;
errorlevel
This variable contains the ErrorLevel associated with the next
system event. This variable is only available under systems that
produce an EXITINFO.BBS door information file.
===============================================================================
OpenDoors 6.00 Manual End of Page 162
-------------------------------------------------------------------------------
event char od_control.event_force;
_force
This variable indicates whether the next system event should be
forced to run at a particular time. If this variable contains a
value of TRUE, then the user should be forced off-line in order
to accommodate the event, and if this variable is false, then
the event can wait until after the user logs off normally. This
variable is only available under systems that produce an
EXITINFO.BBS file.
-------------------------------------------------------------------------------
event char od_control.event_last_run[9];
_last_run
This variable contains a string representing the date on which
the next system event was last run, and is in the same format as
the user_lastdate variable. This variable is only available
under systems that produce an EXITINFO.BBS file.
-------------------------------------------------------------------------------
event char od_control.event_starttime[6];
_starttime
This variable contains a string representing the time at which
the next system event is scheduled to start, in the same format
as the user_lasttime variable. This variable is only available
under systems that produce an EXITINFO.BBS or Wildcat style
DOOR.SYS door information file.
-------------------------------------------------------------------------------
event unsigned char od_control.event_status;
_status
This variable represents the status of the next system event,
and will be equal to the value
ES_ENABLED
if and only if the other event information contained in the
control structure is valid. This variable is only available
under systems that produce an EXITINFO.BBS file.
===============================================================================
OpenDoors 6.00 Manual End of Page 163
-------------------------------------------------------------------------------
sysop_name char od_control.sysop_name[40];
The od_control.sysop_name variable contains the name of the
sysop of the BBS under which your door is running. This variable
is available under any BBS system that produces a DORINFO?.DEF
(including RA & QBBS which process both DORINFO1.DEF and
EXITINFO.BBS files), or Wildcat style DOOR.SYS file.
-------------------------------------------------------------------------------
system_calls long od_control.system_calls;
This variable contains the total number of calls that have been
placed to the BBS, and is available under any BBS which produces
an EXITINFO.BBS file.
-------------------------------------------------------------------------------
system_last char od_control.system_last_caller[36];
_caller
This string contains the name of the previous caller to the BBS,
on any line, and is available under EXITINFO.BBS.
-------------------------------------------------------------------------------
system_last char od_control.system_last_handle[36];
_handle
This string contains the handle (alias) of the previous caller
to the BBS, on any line, and is available under EXITINFO.BBS.
-------------------------------------------------------------------------------
system_name char od_control.system_name[40];
The od_control.system_name variable contains the name of the BBS
under which your door is running. This variable is available
under any BBS system that produces a DORINFO?.DEF (including RA
& QBBS which process both DORINFO1.DEF and EXITINFO.BBS files).
-------------------------------------------------------------------------------
TIMELOG char od_control.timelog_start_date[9];
VARIABLES
This string contains the date of the beginning of the time
period for which the time log is recorded. This variable is
available under any system that produces an EXITINFO.BBS file.
===============================================================================
OpenDoors 6.00 Manual End of Page 164
int od_control.timelog_busyperhour[24];
This variable is an array of 24 elements, with each element
indicating the total number of times the BBS was in use during
each of the 24 hours of the day. Element 0 corresponds to the
time period of 0:00-1:00, element 1 corresponds to the time
period of 1:00-2:00, and so on. In order to determine the
frequency of system use during any hour as a percentage, simply
calculate the total of all 24 entries in the array, and divide
any given entry by the total, in order to come up with an
average. This variable is available under any system that
produces an EXITINFO.BBS file.
int od_control.timelog_busyperday[7];
This variable is an array of 7 elements, with each element
indicating the total number of times the BBS was in use during
each of the 7 days of the week. Here, elements 0 corresponds to
Sunday, element 1 to Monday, and so on. In order to calculate
the frequency of system use during any day of the week, use the
same method as for calculating the frequency of calls during
each hour, as described above. This is only available under
systems that produces an EXITINFO.BBS file. Note that at least
some, if not all, versions of RemoteAccess do not maintain this
variable correctly, and thus even with the presence of an
EXITINFO.BBS file, this array may contain all zero entries.
-------------------------------------------------------------------------------
user_ansi char od_control.user_ansi;
This variable contains a Boolean value, indicating whether or
not the user has ANSI mode turned on. If ANSI graphics mode is
enabled, this variable will contain a value of TRUE, and if ANSI
graphics mode is disabled, this variable will contain a value of
FALSE. Many of the OpenDoors functions test the setting of this
variable in order to determine whether or not they should send
ANSI-graphics control characters. Also, if this variable
contains a TRUE value, OpenDoors will display an "[ANSI]"
indicator on the status line.
You may change the value of this variable at any time after the
first call to od_init() or any other OpenDoors functions.
Depending upon what BBS system your door is running under,
changes to this variable may or may not result in changes to the
user's ANSI setting upon return to the BBS.
===============================================================================
OpenDoors 6.00 Manual End of Page 165
This variable is available under all door information file
formats.
-------------------------------------------------------------------------------
user_ unsigned char od_control.user_attribute;
attribute
This variable is a bitmap of eight flags, each of which
represent individual pieces of information pertaining to the
user that is currently online. These flags are as follows:
+-----+------+-----------------------+
| BIT | MASK | DESCRIPTION |
+-----+------+-----------------------+
| 0 | 0x01 | Is the user deleted |
| 1 | 0x02 | Is screen clearing on |
| 2 | 0x04 | Is "more" prompt on |
| 3 | 0x08 | Is ANSI mode on |
| 4 | 0x10 | User no-kill setting |
| 5 | 0x20 | Transfer-priority |
| 6 | 0x40 | Full screen editor |
| 7 | 0x80 | Quiet mode |
+-----+------+-----------------------+
For more information on using and setting bit-mapped flags,
please see the entry entitled "BITMAPED FLAGS" in the glossary
of this manual.
Note that this variable is only available under systems that
produce and EXITINFO.BBS format door information file.
-------------------------------------------------------------------------------
user_ unsigned char od_control.user_attrib2;
attrib2
See the user_attrib variable for more information. This variable
is like the user_attrib variable, except that it contains
different information. The bit-mapped flags for the
od_control.user_attrib2 variable are as follows:
+-----+------+-----------------------+
| BIT | MASK | DESCRIPTION |
+-----+------+-----------------------+
| 0 | 0x01 | User hot-keys setting |
| 1 | 0x02 | Is AVATAR graphics on |
| 2 | 0x04 | Full screen reader |
| 3 | 0x08 | Hidden from userlist |
+-----+------+-----------------------+
===============================================================================
OpenDoors 6.00 Manual End of Page 166
Note that this variable is only available under systems that
produce an EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user_ unsigned char od_control.user_attrib3;
attrib3
This variable contains user attribute flags when a RA 2.50 or
later EXITINFO.BBS file is used.
-------------------------------------------------------------------------------
user_avatar char od_control.user_avatar;
This variable is a Boolean value indicating whether or not
AVATAR graphics mode is on. If AVATAR graphics is available,
then many of the OpenDoors functions will make use of AVATAR
graphics codes for greater display speed. If AVATAR graphics
mode is on, a [AVT] indicator will appear on the status line. If
your door is running under a system which produces an RA 1.00+
style extended EXITINFO.BBS door information file, the
user_avatar variable is set automatically. If the extended
EXITINFO.BBS file is not available, this value will default to
FALSE. In this case, you may wish to ask the user whether or not
they wish to use AVATAR graphics, and thus set this variable
yourself.
-------------------------------------------------------------------------------
user char od_control.user_birthday[9];
_birthday
This variable is a string, in the same format as the
od_control.user_lastcall variable, which stores the date of the
user's birthday, if it is available. This variable is only
available under systems that produce an RA 1.00 and later style
extended EXITINFO.BBS or Wildcat style DOOR.SYS file.
-------------------------------------------------------------------------------
user char od_control.user_callsign[12];
_callsign
This variable is a string which contains the user's amateur
radio call sign, if any. This variable is only available under
systems that produce a CHAIN.TXT file.
===============================================================================
OpenDoors 6.00 Manual End of Page 167
-------------------------------------------------------------------------------
user_combined unsigned char od_control.user_combinedrecord[25];
record
This variable is an array of bit-mapped flags, with each flag
corresponding to an individual message area. In this case, the
first bit of od_control.ra_combinedrecord[0] corresponds to the
first message area, the second bit to the second message area,
and so on. If any given bit-flag is turned on, then the user has
corresponding message area enabled for combined access, and if
the bit is turned off, the user does not have the area enabled
for combined access. A detailed description of the combined
message access is beyond the scope of this manual. This variable
is only available under systems that produce an RA 1.00 or later
style extended EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user_comment char od_control.user_comment[81];
This variable is a string which contains the sysop's comment
about the user that is currently online. This comment may be
displayed on the OpenDoors status line, if this variable is
available. This variable is available under systems that produce
an RA 1.00 and later style extended EXITINFO.BBS or Wildcat
style DOOR.SYS file.
-------------------------------------------------------------------------------
user_credit unsigned int od_control.user_credit;
This variable contains the total amount of NetMail credit that
the caller has left. Changes to this variable will be by the BBS
when your door exits and control is returned to the BBS. This
variable is only available under systems that produce an
EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user_ char od_control.user_dataphone[13];
dataphone
This string contains the user's data or business phone number,
if available. This value is only available under system that
produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS and WildCat
DOOR.SYS format door information files.
===============================================================================
OpenDoors 6.00 Manual End of Page 168
-------------------------------------------------------------------------------
user int od_control.user_deducted_time;
_deducted
_time This variable contains a signed integer value, which indicates
the total amount of time that has been deducted from the user
during this call. This variable is only available under systems
that produce an RA 1.00 and later style extended EXITINFO.BBS
door information file.
-------------------------------------------------------------------------------
user_downk unsigned int od_control.user_downk;
This variable contains the total kilobytes of files that the
current user has downloaded from the BBS, and is available under
systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
SFDOORS.DAT format door information files.
-------------------------------------------------------------------------------
user unsigned int od_control.user_downlimit;
_downlimit
This variable contains the total number of kilobytes that the
caller is permitted to download during this call. If your door
allows files do be downloaded, you will probably want to compare
the value of this variable to the size of any file to be
transferred and the total kilobytes already downloaded, as
stored in the od_control.user_todayk variable. This variable is
only available under systems that produce an EXITINFO.BBS file.
-------------------------------------------------------------------------------
user unsigned int od_control.user_downloads;
_downloads
This variable contains the total number of files that the
current user has downloaded from the BBS, and is available under
systems that produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS,
WildCat style DOOR.SYS or SFDOORS.DAT format door information
files.
-------------------------------------------------------------------------------
user_echo char od_control.user_echomailentered;
mailentered
This variable is a Boolean value, indicating whether or not the
user has entered new EchoMail during this call. If this variable
has a value of TRUE, then EchoMail has been entered, and if it
has a value of FALSE, then EchoMail has not been entered. This
===============================================================================
OpenDoors 6.00 Manual End of Page 169
variable will contain a valid value only after od_init() or some
OpenDoors function has been called. Any changes made to this
variable will be reflected within the BBS software when control
is returned to the BBS. This variable is accessible only under
systems which produce an EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user_error char od_control.user_error_free;
_free
This variable contains a Boolean value indicating whether or not
the user is connected to the BBS via an error free connection
(eg. a V.42/MNP or similar modem protocol). This variable is
only available under systems that produce an SFDOORS.DAT,
Wildcat style DOOR.SYS or RA 1.00 or later style extended
EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user_first char od_control.user_firstcall[9];
call
This variable is a string which contains the date of the user's
first call, in the same format as the od_control. user_lastcall
variable. This variable is only available under systems which
produce an RA 1.00 and later style extended EXITINFO.BBS door
information file.
-------------------------------------------------------------------------------
user_ unsigned char od_control.user_flags[4];
flags
The od_control.user_flags variable is an array of four sysop
defined bit-mapped flags, which represent some sort of
information about the user. od_control.user_flags[0] stores
flags A1 - A8 in bits 0 through 7, respectively. Likewise,
od_control.user_flags[1] stores flags B1 - B8, and so on. This
variable is only available under systems that produce
EXITINFO.BBS format door information files.
-------------------------------------------------------------------------------
user_handle char od_control.user_handle[36];
This variable contains the user's alias or handle name, if any.
If the user does not have and alias or handle, this variable
will be blank. This variable is only available under systems
that produce a CHAIN.TXT, RA 1.00 and later extended
EXITINFO.BBS or Wildcat style DOOR.SYS door information file.
===============================================================================
OpenDoors 6.00 Manual End of Page 170
-------------------------------------------------------------------------------
user_ char od_control.user_homephone[13];
homephone
This string contains the user's home or data phone number, if
available. This value is only available under system that
produce one of the following door information files:
EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat style
DOOR.SYS or SFDOORS.DAT.
-------------------------------------------------------------------------------
user unsigned char od_control.user_last_pwdchange;
_last
_pwdchange This variable contains the number of calls that the user has
made since they last changed their password. This variable is
only available under EXITINFO.BBS files.
-------------------------------------------------------------------------------
user char od_control.user_lastdate[9];
_lastdate
This variable is a string containing the date of the user's last
call to the BBS, and should always be of the format:
"MM-DD-YY"
Where MM is two digits representing the number of the month of
the user's call, with 1 being January, 2 being February, and so
on. DD should be two digits representing the day of the month of
the user's last call, beginning with 1, and MM should be the
last two digits of the year of the user's last call.
This variable is only available under systems that produce one
of the following door information files: CHAIN.TXT,
EXITINFO.BBS, PC-Board/GAP style DOOR.SYS or WildCat style
DOOR.SYS files.
-------------------------------------------------------------------------------
user_ unsigned int od_control.user_lastread;
lastread
This variable contains the number of the highest message number
that the user has read, and is only available under EXITINFO.BBS
format door information files.
===============================================================================
OpenDoors 6.00 Manual End of Page 171
-------------------------------------------------------------------------------
user char od_control.user_lasttime[6];
_lasttime
This variable contains a string representing the time of the
user's last call to the BBS, and should always be of the format:
"HH:MM"
Where HH is two digits representing the 24-hour format hour of
the user's last call, and MM is two digits representing the
minute of the user's last call. Thus, the following strings
would be valid entries for this string:
"00:01" (12:01 am)
"03:47" (3:47 am)
"18:20" (6:20 pm)
This variable is only available under systems that produce an
EXITINFO.BBS or Wildcat style DOOR.SYS format door information
file.
-------------------------------------------------------------------------------
user char od_control.user_location[26];
_location
This string contains the name of the location from which the
current user is calling from. This will usually be the name of
the city, region (province, state, etc.) and sometimes country
where the user lives. The contents of this variable are
displayed on the OpenDoors status line. The value of this
variable is valid after od_init() or any other OpenDoors
function has been called. Also, you may change the value of this
variable if you wish. However, not that these changes may not
immediately be reflected in the status line, and may or may not
cause the setting to be changed after the user returns to the
BBS. This variable is available under systems that produce one
of the following door information files: DORINFO?.DEF,
EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat style
DOOR.SYS SFDOORS.DAT and CALLINFO.BBS, but is not available
under CHAIN.TXT or DoorWay style DOOR.SYS files.
-------------------------------------------------------------------------------
user char od_control.caller_logindate[9];
_logindate
This variable contains a string representing the date on which
the current call to the BBS began. This variable is in the same
format as the od_control.user_lastdate variable, described
===============================================================================
OpenDoors 6.00 Manual End of Page 172
below. This variable is only available under systems which
produce an EXITINFO.BBS file.
-------------------------------------------------------------------------------
user long od_control.user_loginsec;
_loginsec
This variable contains the user's security at login, and can be
used to detect changes by the sysop or other programs during the
course of the call, by comparing it's value with the
od_control.user_security variable. This variable is only
available under systems which produce an EXITINFO.BBS file.
-------------------------------------------------------------------------------
user char od_control.user_logintime[6];
_logintime
This variable contains a string representing the time of day at
which the current call to the BBS began. This variable is in the
same format as the od_control.user_lasttime variable, which is
also described below. This variable is available under systems
which produce an EXITINFO.BBS, a Wildcat style DOOR.SYS, or an
SFDOORS.DAT file.
-------------------------------------------------------------------------------
user char od_control.user_logonpassword[16];
_logon
password This variable is a string which contains the user's password
at the time at which the current call to the BBS began. This
variable can be used to detect changes by the sysop or other
programs to the user's password, which have taken place during
the course of the call. In order to detect such changes, simply
compare the contents of this string with the contents of the
od_control.user_password variable. This variable is only
available under systems which produce an EXITINFO.BBS format
door information file.
-------------------------------------------------------------------------------
user char od_control.user_menustack[50][9];
_menustack
This variable is an array of 50 strings, containing the stack of
BBS menus that have been executed, and is used to record the
current position of the user within the BBS's menu system. Each
string contains just the base portion of the filename of the
menu, without the extension. The od_control.ra_menustackpointer
variable points to the top of the menu stack. However, a
===============================================================================
OpenDoors 6.00 Manual End of Page 173
complete discussion of the menu stack is beyond the scope of
this manual. This variable is only available under systems that
produce an RA 1.00 and later style extended EXITINFO.BBS door
information file.
-------------------------------------------------------------------------------
user unsigned char od_control.user_menustackpointer;
_menustack
pointer This variable points to the top of the current menu stack. For
more information on the menu stack, please refer to the
od_control.ra_menustack variable, above. This variable is only
available under systems that produce an RA 1.00 and later style
extended EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user unsigned int od_control.user_messages;
_messages
This variable contains a value representing the total number of
messages that have been written by the user, and is available
under EXITINFO.BBS or Wildcat style DOOR.SYS format door
information files.
-------------------------------------------------------------------------------
user_name char od_control.user_name[36];
This string contains the name of the user that is currently on-
line, and is used by OpenDoors to display the current user name
on the status line, and will most likely be used by your door
for differentiating among different users. In most cases, you
should probably not change the value of this variable, as a
user's name does not usually change, and doing so could results
in problems when returning to some BBS systems. For an example
of using this variable, see the EX_VOTE.C example program. This
variable is available under all BBS systems.
-------------------------------------------------------------------------------
user_net_ unsigned int od_control.user_net_credit;
credit
This variable contains the amount of NetMail credit that the
current user has to his or her name. This variable is only
available under systems that produce an EXITINFO.BBS file.
===============================================================================
OpenDoors 6.00 Manual End of Page 174
Note that if you wish to change the value of the user's
remaining NetMail credit, you should use the od_control.
user_credit variable, instead of this variable.
-------------------------------------------------------------------------------
user_net char od_control.user_netmailentered;
mailentered
This variable is a Boolean value, indicating whether or not the
user has entered new NetMail or GroupMail during this call. If
this variable has a value of TRUE, then NetMail/GroupMail has
been entered, and if it has a value of FALSE, then
NetMail/GroupMail has not been entered. This variable will
contain a valid value only after od_init() or some OpenDoors
function has been called. Any changes made to this variable will
be reflected within the BBS software when control is returned to
the BBS. This variable is accessible only under systems which
produce an EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user_num unsigned int od_control.user_num;
This variable contains the number of the user's record in the
user database file, where 0 is the first record. This can be
useful for changing user settings that are not re-read by the
BBS, such as the user's phone number or security level which
might be altered by a call back verification door. However, the
value of this variable itself should not be altered.
This variable is available under systems which produce any of
the following door information file formats: CHAIN.TXT, PC-
Board/GAP style DOOR.SYS, Wildcat style DOOR.SYS SFDOORS.DAT and
EXITINFO.BBS.
-------------------------------------------------------------------------------
user_ unsigned int od_control.user_numcalls;
numcalls
This variable contains the total number of calls that the
current user has placed to the BBS, and is available under
systems that produce EXITINFO.BBS or PC-Board/GAP and Wildcat
style DOOR.SYS door information files.
===============================================================================
OpenDoors 6.00 Manual End of Page 175
-------------------------------------------------------------------------------
user unsigned int od_control.user_numpages;
_numpages
The value of this variable contains the total number of times
that the user has paged the sysop, and can be used to limit the
number of times that the user is permitted to page the sysop.
OpenDoors increments this variable every time that the user
pages the sysop, via the od_page() function. This variable is
used with all types of door information files. However, this
variable will only reflect the value within the BBS if an
EXITINFO.BBS file is produced. Otherwise, the variable will only
contain the number of times that the user has paged within the
door, but not the total number of times the user has paged.
Under EXITINFO.BBS systems, changes to the value of this
variable will be reflected within the BBS upon return by the
DOOR.
-------------------------------------------------------------------------------
user char od_control.user_password[16];
_password
This variable contains the user's password for accessing the
BBS. OpenDoors does not use this value itself. This variable
will contain a valid value only after od_init() or some
OpenDoors function has been called. You may change the value of
this variable. Note, however, that changes in this variable may
or may not cause the setting to be changed when control returns
to the BBS - this will depend upon the particular BBS system
your door is running under. This variable is only available
under systems that produce one of the following door information
files: EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS,
SFDOORS.DAT, and CALLINFO.BBS.
-------------------------------------------------------------------------------
user_pending unsigned int od_control.user_pending;
This variable represents the total value of NetMail that has
been written by the current user, but not yet exported from the
message base. This variable is only available under systems that
produce an EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user_reason char od_control.user_reasonforchat[78];
forchat
This variable is a string, containing the reason for which the
user wishes to chat with the sysop, as they entered at the time
of paging the sysop. This variable will contain an empty string
===============================================================================
OpenDoors 6.00 Manual End of Page 176
if the user has not paged the sysop, or if the reason the user
wishes to chat is unknown. See also the od_control.user_wantchat
variable. This variable is available under all BBS systems,
regardless of what style of door information file they produce.
However, this variable will not be passed between the door and
BBS, and thus the user's reason for chat within the door will
not necessarily correspond to their reason for chat outside the
door.
-------------------------------------------------------------------------------
user_rip char user_rip;
This variable is set to TRUE if the user has RIP (Remote Imaging
Protocol) graphics enabled, and FALSE if they do not. This
setting can be determined from the door information (drop) file
in many cases. In other cases, you can automatically determine
whether or not the user's system supports RIP graphics using the
od_autodetect() function (see page 48).
-------------------------------------------------------------------------------
user_rip_ver BYTE user_rip_ver;
This variable contains the version of the RIP protocol that is
in use. This variable is only available under a RemoteAccess
2.50 EXITINFO.BBS file.
-------------------------------------------------------------------------------
user unsigned int od_control.user_screen_length;
_screen
_length This value of this variable represents the total number of
lines that can be displayed on the user's screen at once, and is
usually either 24 or 25. You may wish to make use of this
variable to allow your door to pause the display of long pieces
of text after every screen length, in order to allow the user to
read this information before it passes off of their screen. In
this case, you would simply maintain a counter of the total
number of lines displayed, and when this value reaches one less
than the length of the user screen, display a prompt asking the
user to whether or not they wish to continue.
This variable is set to the user's setting within the BBS under
systems that produce any of the following door information file
formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
DOOR.SYS and CALLINFO.BBS files.
===============================================================================
OpenDoors 6.00 Manual End of Page 177
This variable is used by the OpenDoors function,
od_list_files(). If this variable contains a valid value,
OpenDoors will pause the listing of files after every screen,
and give the user the option of continuing, aborting, or
disabling the "Continue?" prompt for the rest of the file
listing. Thus, if you are using the od_list_files() under a
system that does not produce one of the door information files
listed above, you may wish to obtain the user's screen length
from the user themselves. If the screen length is not available
from the particular type of door information file that is found,
and you do not set this value yourself, this variable will
default to 23. If you are going to set the value of this
variable yourself, you should do so after having called
od_init() or some OpenDoors function.
-------------------------------------------------------------------------------
user_ unsigned char od_control.user_screenwidth;
screenwidth
This variable contains a value representing the width of the
user's screen, and will most often be equal to 80. This variable
is only available under systems that produce a CHAIN.TXT or RA
1.00 and later style extended EXITINFO.BBS door information
file.
-------------------------------------------------------------------------------
user unsigned int od_control.user_security;
_security
This variable contains a numerical value representing the user's
security access level on the BBS. You may wish to use this value
to determine whether or not the current user of your door should
have access to certain sysop-only functions. In this case, you
may wish to have a configuration file used by your door, in
which the sysop may define the minimum security level for sysop
access. You would then be able to compare this configuration
setting to the security level stored in this variable, in order
to determine whether or not sysop function should be available.
An alternative method, used by the EX_VOTE.C sample door, of
determining whether or not the current user is the sysop is to
compare the user's name with the value of the
od_control.sysop_name variable. This method has the advantage of
not requiring a configuration program, but the disadvantage that
the door will not function correctly under all BBS systems, as
the od_control.sysop_name variable is not available under all
BBS systems.
The od_control.user_security variable is available under BBS
systems that produce any of the following door information file
===============================================================================
OpenDoors 6.00 Manual End of Page 178
formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
DOOR.SYS, SFDOORS.DAT or CALLINFO.BBS.
-------------------------------------------------------------------------------
user_sex char od_control.user_sex;
This variable contains a single character representing the
gender of the user that is currently online. This variable will
contain an upper-case 'F' if the user is female, and an upper-
case 'M' if the user is male. This variable is available under
systems that produce a CHAIN.TXT or RA 2.x style EXITINFO.BBS
file.
-------------------------------------------------------------------------------
user_subdate char od_control.user_subdate[9];
This variable is a string, in the same format as the
od_control.user_lastdate variable, which stores the date of
expiry of the user's subscription to the BBS. This variable is
only available under systems which produce a PC-Board/GAP and
Wildcat style DOOR.SYS or RA 1.00 and later style extended
EXITINFO.BBS door information file.
-------------------------------------------------------------------------------
user int od_control.user_timelimit;
_timelimit
This variable contains the amount of time, in minutes, that the
user has left in the door. Note that this value may or may not
be equal to the total amount of time that the user has left on
the BBS, depending upon whether the BBS or a third-party door
manager program only allows a limited amount of time in this
door. This variable contains a valid value after od_init() or
some OpenDoors function has been called. OpenDoors uses this
variable to keep track of how much time the user has left in the
door, and will automatically warn the user when nearly all of
his or her time has been used up. OpenDoors will also force the
user out of the door when their time in the door has expired.
OpenDoors automatically subtracts one minute from this variable
every minute that OpenDoors is active, unless chat mode has been
activated (in which case the user's time will freeze), and also
adjusts the value of this variable when the sysop uses the time
adjustment function keys. Hence, you will not normally have any
need to alter the value of this variable yourself. However,
there may be some cases in which you wish to subtract a penalty
or add a bonus to the user's time, such as in a "timebank" door
or a door game that permits the user to "gamble time".
===============================================================================
OpenDoors 6.00 Manual End of Page 179
Depending on which BBS system your door is running under, the
value of this variable may or may not effect the user's time
left upon return to the BBS. The BBS system will either reset
the user's time to the value re-written to the door information
file (this variable), or will always subtract the amount of time
spent in the door from the user's remaining time.
This variable is available under all door information file
formats.
-------------------------------------------------------------------------------
user unsigned int od_control.user_todayk;
_todayk
This variable contains the total kilobytes of files that the
current user has downloaded from the BBS during the current day,
and is available under systems that produce EXITINFO.BBS, PC-
Board/GAP and Wildcat style DOOR.SYS, or SFDOORS.DAT format door
information files.
-------------------------------------------------------------------------------
user_upk unsigned int od_control.user_upk;
This variable contains the total kilobytes of files that the
current user has uploaded to the BBS, and is available under
systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
SFDOORS.DAT files.
-------------------------------------------------------------------------------
user_uploads unsigned int od_control.user_uploads;
This variable contains the total number of files that the
current user has uploaded to the BBS, and is available under
systems that produce EXITINFO.BBS, PC-Board/GAP and Wildcat
style DOOR.SYS, or SFDOORS.DAT format door information files.
-------------------------------------------------------------------------------
user char od_control.user_wantchat;
_wantchat
This variable is a Boolean value which indicates whether or not
the user wishes to chat with the sysop (ie, the user has paged
the sysop, but has yet to receive a chat with the sysop). This
variable is used under all door information file formats.
However, changes to this variable are only reflected on the BBS
===============================================================================
OpenDoors 6.00 Manual End of Page 180
when the door is running under a system that produces an
EXITINFO.BBS door information file.
This variable is automatically turned on (ie., set to TRUE),
when the user begins to page the sysop for chat, within the
od_page() function, and is automatically turned off (ie., set to
FALSE), when the sysop breaks in for chat via the chat function
key. Also, setting this variable to TRUE will turn on the
flashing want-chat indicator on the OpenDoors status line.
-------------------------------------------------------------------------------
user unsigned int od_control.user_xi_record;
_xi_record
This variable contains the number of the user's record in the
USERXI.BBS file, if any. This variable is only available under
system that produce a Remote Access 1.00 and later style
extended door information file.
===============================================================================
OpenDoors 6.00 Manual End of Page 181
CONTROL STRUCTURE - DOOR SETTINGS
-------------------------------------------------------------------------------
This section deals with those variables in the OpenDoors control
structure which reflect the current door settings. These
variables are as follows:
od_cur_attrib The current display attribute, or -1 if
unknown.
od_okaytopage Controls whether the user is currently
permitted to page the sysop.
od_pageendmin End of valid paging hours.
od_pagestartmin Start of valid paging hours.
od_silent_mode Turns off local user interface.
od_user_keyboard_on Controls whether OpenDoors will
currently accept input from the remote
user's keyboard.
od_update_status_now Forces immediate update of the status
line.
sysop_next Indicates whether or not the sysop has
reserved use of the system after the
current calls.
-------------------------------------------------------------------------------
od_cur int od_control.od_cur_attrib;
_attrib
This read-only values stores the current display color
attribute, or the value -1 if the current display color is
unknown (such as when the door first begins execution).
-------------------------------------------------------------------------------
od char od_control.od_okaytopage;
_okaytopage
This variable allows you to control whether or not the user is
currently permitted to page the sysop via the od_page()
function. A value of PAGE_ENABLE indicates that paging is
currently permitted, regardless of the sysop page hours setting.
A value of PAGE_DISABLE indicates that paging is not current
permitted. A value of PAGE_USE_HOURS indicates that the
od_page() function should check the values of the
===============================================================================
OpenDoors 6.00 Manual End of Page 182
od_pagestartmin and od_pageendmin variables in order to
determine whether or not paging should be permitted.
The od_okaytopage variable should only be set after you call
od_init() or some other OpenDoors function. The default value is
PAGE_USE_HOURS. For more information on the od_page() function
itself, see page 101.
-------------------------------------------------------------------------------
od unsigned int od_control.od_pageendmin;
_pageendmin
This variable can be used to set the beginning of valid sysop
paging hours within the od_page() function. If the
od_control.od_okaytopage variable (which is described above) is
set to MAYBE, then OpenDoors will check the value of this
variable prior to paging the sysop via the od_page() function.
This variable should contain the time at which the valid sysop
paging hours end, represented as the a number of minutes since
midnight. For more information on the od_page() function itself,
see page 101.
-------------------------------------------------------------------------------
od unsigned int od_control.od_pagestartmin;
_pagestartmin
This variable can be used to set the beginning of valid sysop
paging hours within the od_page() function. If the
od_control.od_okaytopage variable (which is described above) is
set to MAYBE, then OpenDoors will check the value of this
variable prior to paging the sysop via the od_page() function.
This variable should contain the time at which the valid sysop
paging hours begin, represented as the a number of minutes since
midnight. For more information on the od_page() function itself,
see page 101.
-------------------------------------------------------------------------------
od_silent BOOL od_control.od_silent_mode;
_mode
If this variable is set to TRUE prior to the first call to any
OpenDoors function, OpenDoors will operate in silent mode, where
the local display and sysop commands are not used. Silent mode
is automatically disabled if the program is running in local
mode.
===============================================================================
OpenDoors 6.00 Manual End of Page 183
-------------------------------------------------------------------------------
od_update char od_control.od_update_status_now;
_status_now
Setting this variable to TRUE forces OpenDoors to update the
status line during the next od_kernel() execution. When the
status line is updated, this variable is reset to its default
value of FALSE.
-------------------------------------------------------------------------------
od_user char od_control.od_user_keyboard_on;
_keyboard_on
This variable is a Boolean value, indicating whether OpenDoors
will currently accept input from a remote user. OpenDoors
provides a function key (usually [ALT]-[K], unless you have
changed the default), which will allow the sysop to temporarily
prevent the user from having any control over the door. When the
sysop activates this feature, a flashing [Keyboard-Off]
indicator will appear on the status line, and this variable will
be set to FALSE. When the sysop presses the [ALT]-[K]
combination a second time, to toggle the user's keyboard back
on, the flashing indicator will disappear, and this variable
will be set back to TRUE.
-------------------------------------------------------------------------------
sysop_next char od_control.sysop_next;
This variable is a Boolean value, indicating whether or not the
"sysop next" feature has been activated. The "sysop next"
feature, which reserves the system for the sysop after the call
has ended, can be toggled on and off within OpenDoors by use of
a function key (Alt-N by default). Also, when the "sysop next"
feature has been activated, an indicator will appear on the
OpenDoors status line. This variable is only available under
systems that produce an SFDOORS.DAT or RA 1.00 and later style
extended EXITINFO.BBS door information file. For more
information on testing the type of door information file
available, please see page 158.
===============================================================================
OpenDoors 6.00 Manual End of Page 184
CONTROL STRUCTURE - DIAGNOSTICS
-------------------------------------------------------------------------------
To help in diagnosing problems in your OpenDoors programs,
OpenDoors stores information on the most recent error which
occurred. When any of the OpenDoors functions return an "error"
or "failure" state, the reason for this failure is recorded.
The following OpenDoors control structure variable provides
diagnostics information:
od_error Stores a "reason code" for the last
failed OpenDoors API function call.
-------------------------------------------------------------------------------
od_error int od_control.od_error;
When any of the OpenDoors API functions return an "error" or
"failure" state (usually denoted by either of the values FALSE
or NULL), the reason for the failure is recorded in this
variable. Since successful function calls do not alter the value
of the od_control.od_error variable, you must be careful not
only to check the value of the od_control.od_error variable, but
also to check the OpenDoors function return codes, in order to
determine which function failed.
This variable will always store the reason for the most recent
function call failure, or ERR_NONE if no functions have failed.
od_error may take on any of the following values:
ERR_NONE Indicates that no error has occurred
yet.
ERR_MEMORY Function was unable to allocate
required memory. This usually indicates
that there is not enough available
memory. This failure may also be due to
memory corruption caused by your
program inadvertently overwriting heap
structures. If your program has been
compiled in either the small or the
medium memory model, try recompiling it
in the compact, large, or huge memory
models. If your program is already
compiled in the compact, large, or huge
memory models, try making more system
memory available to your program.
===============================================================================
OpenDoors 6.00 Manual End of Page 185
ERR_NOGRAPHICS This setting indicates that the
function called requires ANSI, AVATAR
or RIP graphics mode, but none of these
modes are active.
ERR_PARAMETER An invalid parameter was passed to an
OpenDoors functions. Check the
function's description in chapter four,
to determine the required values for
each function parameter.
ERR_FILEOPEN OpenDoors was unable to open a file.
This can be due to the specified
filename not existing, due to the file
being locked for exclusive access by
another process, or due to a hardware
failure.
ERR_FILEREAD OpenDoors was able to open the
specified file, but unable to read the
required data from the file. This error
may be due to an invalid file format,
due to a portion of the file being
locked by another process, or due to a
hardware failure.
ERR_LIMIT An internal function limit has been
exceeded. Refer to the function's
description in chapter four for
information on the function's
limitations.
ERR_NOREMOTE Indicates that a function has been
called which is not valid in local
mode, such as od_carrier() or
od_set_dtr().
===============================================================================
OpenDoors 6.00 Manual End of Page 186
CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION
-------------------------------------------------------------------------------
The OpenDoors control structure provides many variables which
allow you to customize OpenDoor's behavior and appearance. These
customization variables fit into one of the following
categories:
General Behavior Customization Variables
Sysop Function Keys Customization Variables
Color Customization Variables
Language-Specific Prompts Customization Variables
This section deals with those variables that fit into the first
category, "General Behavior Customization Variables". The other
categories are dealt with in the following sections of this
chapter.
Below is a brief overview of the variables grouped into this
section of the OpenDoors control structure. Following the
overview is a detailed description of each of these variables.
od_app_icon Program icon for Win32 version.
od_box_chars Array of characters used by the
od_draw_box() function.
od_before_exit Function to call prior to exiting.
od_cafter_chat Function to call after sysop chat.
od_cafter_shell Function to call after DOS shell.
od_cbefore_chat Function to call prior to sysop chat.
od_cbefore_shell Function to call prior to DOS shell.
od_cfg_lines Sets the configuration file's custom
door information file line keywords.
od_cfg_text Sets the built-in configuration file
keywords that OpenDoors will recognize.
od_chat_active Controls whether or not sysop chat mode
is active.
od_clear_on_exit Controls whether the screen is cleared
upon door exit.
===============================================================================
OpenDoors 6.00 Manual End of Page 187
od_color_delimiter Indicates what character should delimit
imbedded color codes for the
od_printf() function.
od_color_names Strings which OpenDoors recognizes as
the names of various text colors.
od_config_file Used to enable or disable the OpenDoors
configuration file system.
od_config_filename Sets the filename that will be read by
the configuration file system.
od_config_function The callback function that OpenDoors
will call to allow your program to
process custom configuration file
entries.
od_default_personality Sets the default personality to be used
with the OpenDoors Multiple Personality
System, and also sets the personality
to use when the MPS is not active.
od_default_rip_win Whether OpenDoors should use the
default 43-line RIP window for ANSI
text (TRUE), or a 23-line window
(FALSE).
od_disable Disable OpenDoors activities such as
reading door information file and
monitoring carrier detect / remaining
time.
od_disable_dtr Specifies the string that will be sent
to the modem to prevent the modem from
hanging up when DTR is lowered.
od_emu_simluate_modem Simulates modem display speed for
emulation functions such as
od_send_file(), od_disp_emu() and
od_hotkey_menu().
od_errorlevel Sets the errorlevel OpenDoors exits
with under various conditions.
od_force_local Forces door to operate in local mode,
ignoring any door information file and
using default user settings.
od_help_callback Allows you to provide a help menu item
under the Win32 version of OpenDoors
===============================================================================
OpenDoors 6.00 Manual End of Page 188
od_in_buf_size Sets size of OpenDoor's internal
local/remote inbound buffer.
od_inactive_warning Number of seconds before hanging up
that OpenDoors displays the inactivity
timeout warning.
od_inactivity Controls user inactivity timeout.
od_ker_exec Is called whenever od_kernel()
executes.
od_last_input Indicates whether the last input came
from the remote user (==0) or the local
sysop (==1).
od_list_pause Controls whether or not the user may
pause display within the
od_list_files() and od_send_file()
functions by using the [P] key.
od_list_stop Controls whether or not the user may
terminate display within the
od_list_files() and od_send_file()
functions using [S], [CTRL]-[K], etc.
od_logfile Enables or disables the OpenDoors log
file system.
od_logfile_disable Prevents the logfile from being opened,
even if the logfile is enabled by
od_logfile.
od_logfile_messages Array of message strings that OpenDoors
will use when writing log file entries.
od_logfile_name Contains the filename and possibly path
of the logfile.
od_maxtime Indicates the maximum length of time
any user is permitted to use the door.
od_maxtime_deduction Indicates the amount of time that has
temporarily been taken away from the
user's remaining time, as a result of
the maximum door time setting.
od_mps Enables or disables the OpenDoors
Multiple Personality System.
od_no_file_func Called when no door information file
can be read.
===============================================================================
OpenDoors 6.00 Manual End of Page 189
od_no_ra_codes Disables translation of RA/QBBS control
codes.
od_nocopyright Prevents OpenDoors from displaying it's
name and version number when a door
program begins execution.
od_noexit Prevents OpenDoors from exiting when
the od_exit() function is called.
od_page_len Controls length of the sysop page beep.
od_page_pausing Enables or disables page pausing in
od_send_file(), od_hotkey_menu() and
od_list_files() functions.
od_page_startmin Indicates the time of day at which
sysop paging is first enabled.
od_page_statusline Which status line (if any) is activated
when the user pages the sysop.
od_page_endmin Indicates the time of day at which
sysop paging is disabled.
od_prog_name Stores the name of your program.
od_prog_version Stores the version number of your
program.
od_prog_copyright Place your copyright information here.
od_reg_key Stores the registration key that you
receive when purchasing OpenDoors.
od_reg_name Stores your name or your companies name
when you have purchased an OpenDoors
license (registration).
od_spawn_freeze_time Indicates whether the user's time
remaining continues to be decreased
during the execution of the
od_spawn...() functions (FALSE), or if
the timer should be "frozen" (TRUE).
od_swapping_disable Disables swapping during DOS shell and
od_spawn...() functions.
od_swapping_noems Prevents swapping form being done to
EMS expanded memory.
===============================================================================
OpenDoors 6.00 Manual End of Page 190
od_swapping_path Location where disk swap file should be
created.
od_status_on Controls whether the status line sub-
system is active.
od_time_msg_func Called instead of displaying time limit
warning messages.
-------------------------------------------------------------------------------
od_app HICON od_control.od_app_icon;
_icon
Normally, the Win32 version of OpenDoors displays its own icon
on the application title bar, on the Windows taskbar, and in the
help|about dialog box. You can supply your own icon by setting
this variable to point to the handle of the icon, as returned by
LoadIcon();
-------------------------------------------------------------------------------
od_box char od_control.od_box_chars[8];
_chars
This variable allows you to specify which character the
od_draw_box() function uses in drawing the boarder of a window.
The elements of this array are as follows:
od_box_chars[BOX_UPPERLEFT] - Upper left corner of box
od_box_chars[BOX_TOP] - Top horizontal line
od_box_chars[BOX_UPPERRIGHT] - Upper right corner of box
od_box_chars[BOX_LEFT] - Left Vertical line
od_box_chars[BOX_LOWERLEFT] - Lower left corner of box
od_box_chars[BOX_LOWERRIGHT] - Lower right corner of box
od_box_chars[BOX_BOTTOM] - Bottom horizontal line
od_box_chars[BOX_RIGHT] - Right horizontal line
-------------------------------------------------------------------------------
od_before void (*od_control.od_before_exit)();
_exit
This variable contains a pointer to a function which OpenDoors
should call prior to exiting, or NULL if you do not wish to have
any function called at exit time. For an example of the use of
this variable, see the description of the EX_VOTE.C example
program, which begins on page 38.
===============================================================================
OpenDoors 6.00 Manual End of Page 191
-------------------------------------------------------------------------------
od_cafter void (*od_control.od_cafter_chat)();
_chat
The function pointed to by this variable will be called after
sysop chat mode has ended. This may be useful for allowing you
to save the user's screen contents prior to chat, and restoring
the afterwards. If this variable contains its default value of
NULL, no function will be called. To alter the string of text
which is displayed after sysop chat, see the
od_control.od_after_chat variable, which is described in the
section on the prompts customization portion of the control
structure.
-------------------------------------------------------------------------------
od_cafter void (*od_control.od_cafter_shell)();
_shell
The function pointed to by this variable will be called after
the sysop has returned from a DOS shell. If this variable
contains its default value of NULL, no function will be called.
To alter the string of text which is displayed after a DOS
shell, see the od_control.od_after_shell variable, which is
described in the section on the prompts customization portion of
the control structure.
-------------------------------------------------------------------------------
od_cbefore void (*od_control.od_cbefore_chat)();
_chat
The function pointed to by this variable will be called prior to
entering sysop chat mode. This may be useful for allowing you to
save the user's screen contents prior to chat, and restoring the
afterwards. If this variable contains its default value of NULL,
no function will be called. To alter the string of text which is
displayed prior to sysop chat, see the od_control.od_before_chat
variable, which is described in the section on the prompts
customization portion of the control structure. To replace the
OpenDoors sysop chat facility with your own, simply activate
your chat mode when this function is called. Your chat mode
facility should remain active until OpenDoors sets the
od_control.od_chat_active variable to FALSE. If you wish to
terminate chat mode prior to this variable being set to FALSE,
you should set this variable to FALSE yourself if you do not
wish OpenDoors to activate its own chat mode.
===============================================================================
OpenDoors 6.00 Manual End of Page 192
-------------------------------------------------------------------------------
od_cbefore void (*od_control.od_cbefore_shell)();
_shell
The function pointed to by this variable will be called prior to
executing a sysop DOS shell. If this variable contains its
default value of NULL, no function will be called. To alter the
string of text which is displayed before a DOS shell, see the
od_control.od_before_shell variable, which is described in the
section on the prompts customization portion of the control
structure.
-------------------------------------------------------------------------------
od_cfg_lines char od_control.cfg_lines[25][33];
This array contains the strings for the keywords that represent
various lines in the definition of a custom door information
file. Each keyword must be 32 character or less in length. These
keywords are not case sensitive. See page 230 for more
information on defining custom door information (drop) file
formats. The default values for this array are as follows:
[0] "Ignore"
[1] "ComPort"
[2] "FossilPort"
[3] "ModemBPS"
[4] "LocalMode"
[5] "UserName"
[6] "UserFirstName"
[7] "UserLastName"
[8] "Alias"
[9] "HoursLeft"
[10] "MinutesLeft"
[11] "SecondsLeft"
[12] "ANSI"
[13] "AVATAR"
[14] "PagePausing"
[15] "ScreenLength"
[16] "ScreenClearing"
[17] "Security"
[18] "City"
[19] "Node"
[20] "SysopName"
[21] "SysopFirstName"
[22] "SysopLastName"
[23] "SystemName"
[24] "RIP"
If you wish to change any of these variable, you must do so
before calling any OpenDoors functions.
===============================================================================
OpenDoors 6.00 Manual End of Page 193
-------------------------------------------------------------------------------
od_cfg_text char od_control.od_cfg_text[47][33];
This array of strings contains the built-in configuration file
keywords that are recognized by OpenDoors. These keywords may be
up to 32 characters in size, and are not case sensitive. If you
wish to change any of these settings, you must do so before
calling any OpenDoors functions. The default values for this
array are as follows:
[0] "Node"
[1] "BBSDir"
[2] "DoorDir"
[3] "LogFileName"
[4] "DisableLogging"
[5] "SundayPagingHours"
[6] "MondayPagingHours"
[7] "TuesdayPagingHours"
[8] "WednesdayPagingHours"
[9] "ThursdayPagingHours"
[10] "FridayPagingHours"
[11] "SaturdayPagingHours"
[12] "MaximumDoorTime"
[13] "SysopName"
[14] "SystemName"
[15] "SwappingDisable"
[16] "SwappingDir"
[17] "SwappingNoEMS"
[18] "LockedBPS"
[19] "SerialPort"
[20] "CustomFileName"
[21] "CustomFileLine"
[22] "InactivityTimeout"
[23] "PageDuration"
[24] "ChatUserColor"
[25] "ChatSysopColor"
[26] "FileListTitleColor"
[27] "FileListNameColor"
[28] "FileListSizeColor"
[29] "FileListDescriptionColor"
[30] "FileListOfflineColor"
[31] "Personality"
[32] "NoFossil"
[33] "PortAddress"
[34] "PortIRQ"
[35] "ReceiveBuffer"
[36] "TransmitBuffer"
[37] "PagePromptColor"
[38] "LocalMode"
[39] "PopupMenuTitleColor"
===============================================================================
OpenDoors 6.00 Manual End of Page 194
[40] "PopupMenuBorderColor"
[41] "PopupMenuTextColor"
[42] "PopupMenuKeyColor"
[43] "PopupMenuHighlightColor"
[44] "PopupMenuHighKeyColor"
[45] "NoFIFO"
[46] "FIFOTriggerSize"
[47] "DiableDTR"
[48] "NoDTRDisable"
-------------------------------------------------------------------------------
od_chat char od_control.od_chat_active;
_active
This variable is set to TRUE when sysop chat mode is active, and
is set to FALSE when sysop chat mode is not active. This
variable can be used to determine whether or not chat mode is
active, and to force chat mode to end. When the sysop presses
the chat mode key ([ALT]-[C] if the default personality is being
used) while chat mode is active, this variable is set to FALSE.
-------------------------------------------------------------------------------
od_clear char od_control.od_clear_on_exit;
_on_exit
This variable contains a Boolean value, which indicates whether
or not you wish OpenDoors to clear the screen prior to exiting.
This variable defaults to a value of TRUE, which causes the
screen to be cleared when a door program exits. However, you may
wish to set this variable to a value of FALSE, which will cause
the contents of the screen to remain unchanged when the door
exits. While setting this variable to FALSE will probably result
in a messy display if the door is to return control to a batch
file, if the door returns directly to the BBS, it will result in
a smoother transition from the door back to the BBS (as the
sysop is not left with a blank screen). If your door has a
configuration file or configuration program, you may wish to
have an option which will allow the individual sysop to
determine whether or not the screen should be cleared when the
door exits.
-------------------------------------------------------------------------------
od_color char od_control.od_color_delimiter;
_delimiter
This variable sets the character that is used to delimit color
codes in the od_printf() function, and defaults to the back-
quote (`) character. If you wish to be able to display the back-
quote (`) character using the od_printf() function, and thus
===============================================================================
OpenDoors 6.00 Manual End of Page 195
wish to use a different character to delimit color codes in the
od_printf() function, simply set this variable to the
alternative character you wish to use. If you wish to disable
the imbedded color codes feature of the od_printf() function,
simply set this variable to a value of zero. For more
information on od_printf() imbedded color codes, see the
description of the od_printf() function, which begins on page
110.
-------------------------------------------------------------------------------
od_color char od_control.od_color_names[12][33];
_names
This array sets the strings that OpenDoors will recognize as
color description keywords. These are the keywords that can be
imbedded in od_printf() format strings, and are also the
keywords that can be used to change color settings in the
OpenDoors configuration file. If you wish to change these
keywords, you will normally do so before calling any OpenDoors
functions. These keywords should always be supplied in upper-
case characters. The defaults values for this array are as
follows:
[0] "BLACK"
[1] "BLUE"
[2] "GREEN"
[3] "CYAN"
[4] "RED"
[5] "MAGENTA"
[6] "YELLOW"
[7] "WHITE"
[8] "BROWN"
[9] "GREY"
[10] "BRIGHT"
[11] "FLASHING"
-------------------------------------------------------------------------------
od_config void (*od_control.od_config_file)(void);
_file
Set this variable to INCLUDE_CONFIG_FILE to enable the OpenDoors
configuration file system, or set it to NO_CONFIG_FILE to
disable the configuration file system. This variable should only
be set prior to your first call to an OpenDoors function. For
more information on the OpenDoors configuration file system, see
page 224.
===============================================================================
OpenDoors 6.00 Manual End of Page 196
-------------------------------------------------------------------------------
od_config char *od_control.od_config_filename;
_filename
If set, this variable should point to a string containing the
filename that you wish the OpenDoors configuration file system
to read. If this variable has its default value of NULL, the
filename DOOR.CFG will be used by default.
-------------------------------------------------------------------------------
od_config void (*od_control.od_config_function)(char *keyword, char
_function *options);
If set, this variable should point to the function that
OpenDoors should call when lines with unrecognized keywords are
encountered in the configuration file. This allows you to add
your own configuration file keywords. The first parameter to
this function will be a pointer to a string containing the
unrecognized keywords, and the second parameter will be a
pointer to a string containing any options that were specified
after the keyword. If no options were specified after the
keyword, this string will have a length of 0.
-------------------------------------------------------------------------------
od_default void (*od_control.od_default_personality)(unsigned char
_personality operation);
This variable sets the default personality that OpenDoors will
use if the multiple personality system is active. If the
multiple personality system is not active, the personality set
by this variable will be the only personality available. This
variable should only be set prior to calling an OpenDoors
function. This variable can be set to point to your own
personality function, or it can be set to one of the manifest
constants that represent one of the built-in personalities:
PER_OPENDOORS
PER_PCBOARD
PER_RA
PER_WILDCAT
For more information on the OpenDoors Multiple Personality
System, see page 230.
===============================================================================
OpenDoors 6.00 Manual End of Page 197
-------------------------------------------------------------------------------
od_default char od_control.od_default_rip_win;
_rip_win
This variable defaults to FALSE. When set to FALSE, OpenDoors
resets the RIP text window to a 23-line window that is most
appropriate for doors that support both RIP-graphics and non-RIP
mode. When this variable is set to TRUE, OpenDoors will use the
default sized text output window, 43 lines in size.
-------------------------------------------------------------------------------
od_disable unsigned int od_control.od_disable;
This variable is a bit-mapped flag which can be used to disable
certain OpenDoors features which are normally active, in order
to allow for maximum customization of OpenDoors. Each bit of
this variable represents a different feature that can be
disabled. To DISABLE a feature, you set the bit that corresponds
to the particular feature. To ENABLE the feature, the bit is
reset. Each bit is represented by a keyword, as follows:
DIS_INFOFILE - Setting the DIS_INFOFILE bit of the
od_control.od_disable variable allows you to prevent
OpenDoors from reading or re-writing a door information
file. If you wish to disable OpenDoors' reading of the door
information file, you must do so prior to calling
od_init() or any other OpenDoors door-driver functions. At
the same time, you must also manually set any required
variables that are normally set by the information obtained
from the door information file, such as the comm port
number, baud rate, user name, and so on. You may wish to
disable reading of the door information file in a number of
cases. For example, you may wish to manually read another
format of door information file not supported by OpenDoors,
or to obtain the necessary door information from your
program's command line. Also, if you are using OpenDoors to
write a non-door communications program, such as a terminal
program, you want to prevent OpenDoors from attempting to
read a door information file on startup.
DIS_CARRIERDETECT - Setting this bit allows you to prevent
OpenDoors from exiting when it the carrier detect signal
from the modem disappears. This bit may be set or rest at
any time. If you use this bit to disable OpenDoors' carrier
detection, you will probably want to monitor the state of
the carrier detect signal yourself, using the od_carrier()
function, which is described on page 51.
DIS_TIMEOUT - This flag allows you to prevent OpenDoors from
exiting when the user runs out of time. As with the
DIS_CARRIERDETECT flag, you may set or reset this bit at
===============================================================================
OpenDoors 6.00 Manual End of Page 198
any time. You will most often want to use this setting when
writing a non-door program, which you would not want to
have exit after a particular amount of time has elapsed. Be
sure that you do not confuse this flag with the user's
inactivity timeout. To disable the inactivity timeout, set
the do_control.od_inactivity variable to 0.
DIS_LOCAL_OVERRIDE - This setting affects OpenDoors' behavior
when a locked BPS rate is specified in the configuration
file, and another BPS rate is specified in the door
information file. By default, OpenDoors will initialize the
modem at the BPS rate specified in the configuration file,
unless the BPS rate specified in the door information file
is 0. In this case, the 0 BPS rate is used to indicate that
the door is operating in local mode, and will override the
BPS rate specified in the configuration file. Setting this
flag disables the local mode override, causing the modem to
always be initialized at the locked BPS rate, even when the
door information file specifies that local mode should be
used.
DIS_BPS_SETTING - When used with a FOSSIL driver, OpenDoors
normally changes the BPS rate to that passed from the BBS
(if the BBS passes a valid FOSSIL BPS rate). Setting the
DIS_BPS_SETTING flag disables this BPS rate setting.
DIS_LOCAL_INPUT - The local keyboard may be disabled by setting
this bit. This only affects the sysop's input in
circumstances that input is also accepted from the remote
user; this setting has no effect on the sysop function
keys.
DIS_SYSOP_KEYS - This setting also disables the local keyboard.
However, unlike the DIS_LOCAL_INPUT, this function disables
both sysop function keys and door input from the local
keyboard.
DIS_DTR_DISABLE - This setting prevents OpenDoors from
disabiling DTR response from the modem. Even if not
specified, OpenDoors only disables DTR response in the when
exiting under the Win32 version if an open serial port
handle was not provided to OpenDoors at startup.
DIS_NAME_PROMPT - Prevents OpenDoors from prompting for a user
name when operating in automatic local mode (by setting
od_force_local to TRUE or specifying -local on the command
line).
Note that in order to disable the OpenDoors status line, the
od_control.od_status_on variable is used, instead of the
od_disable variable. You may also disable the user's inactivity
timeout by setting the od_control.od_inactivity variable to 0.
===============================================================================
OpenDoors 6.00 Manual End of Page 199
The od_control.od_status_on variable is described later in this
section.
-------------------------------------------------------------------------------
od_disable_ char od_control.od_disable_dtr[40];
dtr
Unles the DIS_DTR_DISABLE od_disable flag is set, the Win32
version of OpenDoors will attempt to disable DTR response by the
modem when closing the serial port, if the serial port was
opened by OpenDoors. This is done by sending a series of
commands to the modem, and possibly waiting for responses to the
command. The string format specifies each command, followed by
the required response. The command and response is separated by
a single space character. If no response is required between two
commands, then those commands may be separated by two space
characters. A '|' character is translated into a carriage
return, and a '~' character is translated into a one second
pause. The default value of this string is "~+++~ AT&D0 ATO".
-------------------------------------------------------------------------------
od_emu_ BOOL od_control.od_emu_simulate_modem;
simulate_modem
When this flag is set to its default value of FALSE, the
OpenDoors terminal emulator displays text at full speed. When
this flag is set to TRUE, the emulation functions will display
text at approximately the same speed as it would be displayed
when sent over the modem, based on the current connect speed. In
local mode, an average modem speed of 9600bps is assumed. This
allows animations to be displayed locally at the same speed as
they would appear on the remote system. This switch affects the
following functions:
od_disp_emu()
od_send_file()
od_hotkey_menu()
-------------------------------------------------------------------------------
od unsigned char od_control.od_errorlevel[8];
_errorlevel
Allows you to configure the errorlevel (program exit code) which
OpenDoors exits with under various circumstances. The elements
of this array are as follows:
===============================================================================
OpenDoors 6.00 Manual End of Page 200
[ERRORLEVEL_ENABLE] Enables or disables custom errorlevels
[ERRORLEVEL_CRITICAL] Critical error errorlevel
[ERRORLEVEL_NOCARRIER] Carrier lost errorlevel
[ERRORLEVEL_HANGUP] Sysop manually terminated call
[ERRORLEVEL_TIMEOUT] User time expired errorlevel
[ERRORLEVEL_INACTIVITY] Keyboard inactivity timeout errorlevel
[ERRORLEVEL_DROPTOBBS] Sysop returned user to BBS errorlevel
[ERRORLEVEL_NORMAL] Door has exited normally
If you wish to override the default errorlevels used by
OpenDoors, you should set element [ERRORLEVEL_ENABLE] of this
array to TRUE, and set the remaining array elements to the
appropriate errorlevels. Note that the settings in this array
only affect the errorlevels which OpenDoors uses when it causes
the door to exit for one of the reasons listed above. This
setting has no effect on the errorlevel returned when your
program explicitly exits by calling the od_exit() function, or
your program returns by calling exit() or returning from the
main() function.
-------------------------------------------------------------------------------
od char od_control.od_force_local;
_force_local
This variable defaults to FALSE, which causes OpenDoors to
behave normally. When this variable is set to TRUE prior to
calling od_init() or any other OpenDoors functions, OpenDoors
will operate in local mode. In this case, no door information
file will be read. Also, the user name will be used if
od_control.user_name has not been set prior to calling od_init()
or the first OpenDoors function.
The default OpenDoors settings when od_control.od_force_local is
set are as follows:
- ANSI mode is on
- Time limit is 60 minutes
- User's location is the name of the BBS, or "Unknown Location"
otherwise if BBS name is not known.
- User name is set to sysop's name ("Sysop" if no sysop name is
specified in the configuration file).
You may wish to add a "-local" type parameter to your program's
command line, which will permit the sysop to easily operate the
door in local mode, as an interface to the
od_control.od_force_local setting.
-------------------------------------------------------------------------------
od_help void (*od_control.od_help_callback)(void);
===============================================================================
OpenDoors 6.00 Manual End of Page 201
_callback
If this variable is set to a non-NULL value, the Win32 version
of OpenDoors will provide a Contents item on the help menu, and
call the function pointed to by this variable when the user
chooses the Contents menu item.
-------------------------------------------------------------------------------
od_in_buf unsigned int od_control.od_in_buf_size;
_size
Specifies the size, in characters, of the OpenDoor's internal
local/remote inbound buffer size. Two bytes of storage are
required for each character in this buffer. This variable should
only be changed prior to calling od_init() or the first
OpenDoors function. If not set, this variable defaults to a
value of 256.
The buffer corresponding to this variable should not be confused
with the FOSSIL or internal communications receive buffer (which
is set by od_control.od_com_rx_buf). Unlike the serial I/O
receive buffer, which is used only for characters received from
the remote system, this buffer serves as a queue for input from
both the remote system and the local keyboard. If you find that
characters are lost when information is being set to your door
from the user, you may wish to increase the size of this buffer.
-------------------------------------------------------------------------------
od unsigned int od_control.od_inactivity;
_inactivity
OpenDoors has a built in user-inactivity timeout facility, which
will automatically disconnect a user who appears .to be sleeping
at the keyboard. If the user has not pressed any keys on their
keyboard for to great a length of time, they will be warned that
they are about to be disconnected due to inactivity. If they
still do not respond after another few seconds, OpenDoors will
automatically disconnect the user and return control to the BBS
software. The od_control.od_inactivity variable allows you to
set the maximum length of time, in seconds, after which the user
will be disconnected for inactivity. This variable defaults to a
value of 200 seconds. You may disable OpenDoors' inactivity
timeout altogether, by setting the od_control.od_inactivity
variable to a value of 0.
===============================================================================
OpenDoors 6.00 Manual End of Page 202
-------------------------------------------------------------------------------
od_inactive int od_control.od_inactive_warning.
_warning
This variable sets the number of seconds prior to hanging up
that OpenDoors displays the inactivity timeout warning. This
variable should only be changed after your first call to an
OpenDoors API function. If not explicitly set by your program,
this setting defaults to 10 seconds.
-------------------------------------------------------------------------------
od_ker_exec void (*od_control.od_ker_exec)(void);
When od_control.od_ker_exec is set to point to a function,
OpenDoors will call this function whenever od_kernel() executes.
This provides any easy way for you to perform your own
processing on a regular basis during door execution. The
od_control.od_ker_exec variable defaults to NULL.
-------------------------------------------------------------------------------
od_last char od_control.od_last_input;
_input
Indicates whether the last key retrieved using the od_get_key()
function originated from the remote user, or the local sysop. If
the input originated from the remote, this variable is set to 0.
If the input originated from the local keyboard, this variables
is set to 1.
-------------------------------------------------------------------------------
od_list char od_control.od_list_pause;
_pause
This variable contains a Boolean value, which allows you to
control whether or not the user may pause displaying within the
od_list_files() and od_send_file() function. When this variable
is set to its default value of TRUE, the user will be able to
pause the display by pressing the [P] key, and resume display by
pressing any other key. However, the pause feature may be
disabled by setting this variable to FALSE.
-------------------------------------------------------------------------------
od_list char od_control.od_list_stop;
_stop
This variable contains a Boolean value, which allows you to
control whether or not the user may abort displaying within the
od_list_files() and od_send_file() function. When this variable
===============================================================================
OpenDoors 6.00 Manual End of Page 203
is set to its default value of TRUE, the user will be able to
pause the display by pressing the [S], [CTRL]-[K] or [CTRL]-[C]
keys. However, the stop feature may be disabled by setting this
variable to FALSE.
-------------------------------------------------------------------------------
od_local void (*od_control.od_local_input)(int);
_input
If set, this function is called whenever the sysop presses a
non-sysop-function key on the local keyboard. The key pressed is
passed to the function in the single int parameter that it
accepts.
-------------------------------------------------------------------------------
od_logfile void *(od_control.od_logfile)(void);
To make the OpenDoors log file system available in your program,
set this variable to INCLUDE_LOGFILE, prior to calling any
OpenDoors functions. If not set, or if set to NO_LOGFILE, the
OpenDoors log file system will not automatically be enabled.
-------------------------------------------------------------------------------
od_logfile char od_control.od_logfile_disable;
_disable
This variable defaults to the value of FALSE, unless the
"LogfileDisable" option is specified in the configuration file,
in which case the variable will be set to TRUE. If this variable
is set to TRUE, OpenDoors will not write to a logfile, even if
the logfile system is enabled using od_control.od_logfile.
-------------------------------------------------------------------------------
od_logfile char *od_control.od_logfile_messages[14];
_messages
This array of pointers to strings contains the messages that
OpenDoors will automatically write to the log file, if the log
file system is enabled. If you wish to change the settings of
this array, you should do so before calling any OpenDoors
functions. The default strings for this array are as follows:
[0] "Carrier lost, exiting door"
[1] "System operator terminating call, exiting door"
[2] "User's time limit expired, exiting door"
[3] "User keyboard inactivity time limit exceeded, exiting door"
[4] "System operator returning user to BBS, exiting door"
===============================================================================
OpenDoors 6.00 Manual End of Page 204
[5] "Exiting door with errorlevel %d,
[6] "Invoking operating system shell"
[7] "Returning from operating system shell"
[8] "User paging system operator"
[9] "Entering sysop chat mode"
[10] "Terminating sysop chat mode"
[11] "%s entering door"
[12] "Reason for chat: %s"
[13] "Exiting door"
-------------------------------------------------------------------------------
od_logfile char od_control.od_logfile_name[80];
_name
This variable specifies the filename, and optionally the full
path of the logfile where OpenDoors should perform logging. This
variable only has an effect when set prior to calling any
OpenDoors functions. If the log file name is specified in the
configuration file, that name will be stored in this variable.
If you do not set this variable, and the log file name is not
specified in the configuration file, the default name "DOOR.LOG"
will be used. If you wish to set this variable, you should do so
prior to calling od_init() or any OpenDoors function.
-------------------------------------------------------------------------------
od_ unsigned int od_control.od_maxtime;
maxtime
This variable specifies the maximum length of time that any user
is permitted to use the door, and is normally set from a
configuration file option. If upon entering the door, the user's
time remaining online is greater than the od_maxtime setting,
their time remaining is temporarily decreased to the maximum
value. Then upon exit of the door, the number of subtracted
minutes is added back onto the user's remaining time. If the
user's remaining time is less than this value, then the setting
has no effect. A value of 0 disables the maximum time setting
altogether.
-------------------------------------------------------------------------------
od_maxtime int od_control.od_maxtime_deduction;
_deduction
This variable store the amount of time that should be added to
the user's time upon exit of the door, as a result of the
maximum time deduction, described above. If the maximum time
feature is not used, this variable will be given a value of 0.
===============================================================================
OpenDoors 6.00 Manual End of Page 205
-------------------------------------------------------------------------------
od_mps void (*od_control.od_mps)(void);
To make the OpenDoors Multiple Personality system available in
your program, set this variable to INCLUDE_MPS before calling
any OpenDoors functions. If this variable is not set, or is set
to NO_MPS, the Multiple Personality System will be disabled. For
more information on the OpenDoors Multiple Personality System,
see page 233.
-------------------------------------------------------------------------------
od_no_ void (*od_control.od_no_file_func)();
file_func
If od_no_file_func is set to point to a function, that function
will be called whenever a door information (drop) file cannot be
located or read. This provides an easy mechanism to add your own
door information file reader, or to provide a local login prompt
when no drop file is present. If you wish the door to operate in
local mode, you should set od_control.od_force_local to TRUE
prior to returning from your function. If you have successfully
read your own door information file format, you should set
od_control.od_info_type to CUSTOM. If neither of these variables
are set by the od_no_file_function, OpenDoors will report that
it is unable to find or read a door information file and will
exit immediately.
-------------------------------------------------------------------------------
od_no_ra char od_control.od_no_ra_codes;
_codes
This variable defaults to FALSE. When set to TRUE, the
translation of the RemoteAccess/QuickBBS control codes by the
functions od_send_file(), od_hotkey_menu() and od_disp_emu() is
disabled.
-------------------------------------------------------------------------------
od_ char od_control.od_nocopyright;
nocopyright
This variable is a Boolean value that allows you to prevent
OpenDoors from displaying its name, version number, copyright
notice and registration information when the program begins
execution. Set this variable to TRUE to disable the display of
copyright and associated information. When this variable is set
to TRUE, OpenDoors also does not change the initial display
color on startup. For obvious reasons, this variable does not
take effect when OpenDoors is operating in unregistered mode.
===============================================================================
OpenDoors 6.00 Manual End of Page 206
-------------------------------------------------------------------------------
od_noexit char od_control.od_noexit;
This variable contains a Boolean value, which allows you to
prevent OpenDoors from exiting when shutting down. This may be
useful when you want to have your program to do more processing
after you have called the od_exit() function, or if you do not
wish to have your program exit automatically when the user drops
carrier. Normally, this variable will default to a value of
FALSE, indicating that OpenDoors will exit normally when the
od_exit() function is called. However, you may optionally set
this variable to TRUE after od_init() or some OpenDoors function
has been called. In this case, when the od_exit() function is
called, either by your program manually, or automatically by
OpenDoors in response to the user dropping carrier, etc.,
OpenDoors will not exit. However, the normal operations of
closing the serial port and re-writing the door information file
will be carried out. If you set the od_noexit variable to TRUE,
you will probably have to provide some mechanism to allow your
program to detect when OpenDoors shutdowns due to the loss of
carrier, etc. The best way of doing this is to provide a
function which is to be called at the beginning of the od_exit()
function, by setting the od_control.od_before_exit pointer,
described above.
-------------------------------------------------------------------------------
od_page char od_control.od_page_len;
_len
This variable allows you to control the length, in seconds, of
the sysop page beep produced when the user pages the sysop via
the od_page() function.
-------------------------------------------------------------------------------
od_page char od_control.od_page_pausing;
_pausing
This variable contains a Boolean value that indicates whether or
not page pausing is enabled in the od_send_file(),
od_hotkey_menu() and od_list_files() functions. The default
value of TRUE indicates that page pausing is enabled. A value of
FALSE indicates that page pausing is disabled.
===============================================================================
OpenDoors 6.00 Manual End of Page 207
-------------------------------------------------------------------------------
od_page int od_control.od_pagestartmin;
startmin int od_control.od_pageendmin;
od_page These variables indicate the start and end times for sysop
endmin paging, expressed as the number of minutes past midnight.
Sysop paging will be available through the od_page() function
from the start time, up to but not including the end time.
-------------------------------------------------------------------------------
od_page char od_control.od_page_statusline;
_statusline
This variable controls which status line, if any, is activated
when the user pages the system operator (via the od_page()
function). A value between 0 and 9 causes the corresponding
status line to be activated. A value of -1 prevents any change
from being made to the current status line setting. This
variable will normally be set by personality functions (see page
233).
-------------------------------------------------------------------------------
od_prog_ char od_control.od_prog_copyright[40];
copyright
This variable should contain your program's copyright notice,
such as "(C) Copyright 1996 by Your Name". This information is
used in the Help|about dialog box under the Win32 version of
OpenDoors, and may be used in other places in future versions of
OpenDoors.
-------------------------------------------------------------------------------
od_prog_name char od_control.od_prog_name[40];
This variable should contain the full name of your program, up
to 39 characters. If not set, OpenDoors will use the string
"OpenDoors" in place of this variable. If used, this variable
should be set prior to calling any OpenDoors functions, and
should not include your program's version number. This
information is used to write your program's name in the log file
and to indicate your program's name on various windows, among
other places.
===============================================================================
OpenDoors 6.00 Manual End of Page 208
-------------------------------------------------------------------------------
od_prog_version char od_control.od_prog_version[40];
This variable should contain the version information of your
program. If used, this variable should be set prior to calling
any OpenDoors functions. This information is used in the
Help|About dialog box under the Win32 version of OpenDoors,
among other places.
-------------------------------------------------------------------------------
od_reg_key unsigned log od_control.od_reg_key;
When you purchase an OpenDoors licence (registration), this
variable should be set to your registration key, prior to
calling any OpenDoors functions.
-------------------------------------------------------------------------------
od_reg_name char od_control.od_reg_name[36];
When you purchase an OpenDoors licence (registration), this
variable should be set to your name, or your company's name, as
is listed in your OpenDoors registration record.
-------------------------------------------------------------------------------
od_spawn char od_control.od_spawn_freeze_time;
_freeze_time
This variable is a Boolean value which indicates whether or not
the user's time remaining is frozen during the execution of one
of the od_spawn...() functions. If this variable is set to TRUE,
the user's time remaining will not decrease during the time that
the od_spawn...() function is executing. However, if this
variable is set to FALSE, the user's time remaining will
continue to be subtracted during the execution of the
od_spawn...() function. The default value of this variable is
FALSE.
-------------------------------------------------------------------------------
od_swapping char od_control.od_swapping_disable;
_disable
This variable is a Boolean value which specifies whether or not
OpenDoors will attempt to swap itself and your entire door upon
===============================================================================
OpenDoors 6.00 Manual End of Page 209
DOS shell or a call to one of the od_spawn...() functions. This
variable defaults to FALSE. If set to TRUE, OpenDoors will not
attempt to perform swapping activities.
-------------------------------------------------------------------------------
od_swapping char od_control.od_swapping_noems;
_noems
This variable is a Boolean value which can be used to prevent
OpenDoors from swapping to EMS memory. This variable defaults to
the value FALSE. If set to TRUE, OpenDoors will not attempt to
use EMS memory for swapping, and will only swap to disk.
-------------------------------------------------------------------------------
od_swapping char od_control.od_swapping_path;
_path
This variable specifies the drive and directory where OpenDoors
should create its disk swapping file, if applicable. More than
one path can be specified, by separating the paths with a semi-
colon (;) character.
-------------------------------------------------------------------------------
od_status char od_control.od_status_on;
_on
This variable is a Boolean value which allows your program to
completely disable the OpenDoors status line. The variable
defaults to a value of TRUE, which causes the OpenDoors status
line to be controllable by function keys, displayed and updated
as it would normally be. However, if this variable is set to
FALSE, then OpenDoors will not update the status line, nor will
it allow the status line to be re-displayed as a result of one
of the status line ([F1] through [F10]) keys being pressed. When
you change the value of this variable from FALSE to TRUE,
OpenDoors will automatically redisplay the status line. Note,
however, that the status line isn't automatically removed when
the value of this variable is changed from TRUE to FALSE. In
order to erase the status line after resetting the value of this
variable, you should reset the output window to the full screen,
by calling the function window(1,1,25,80). Then manually erase
the old status line either by clearing the bottom two lines of
the screen, or by clearing the entire screen.
It is important that you do not confuse the use of this variable
with the od_set_statusline() function, which is described on
page 137. When the status line is enabled, the sysop can change
which status line, if any, is being displayed, using the
function keys [F1] through [F10]. The od_set_statusline()
===============================================================================
OpenDoors 6.00 Manual End of Page 210
function allows your program to make the same changes to the
status line setting which the sysop can make by pressing one of
the function keys. The status line can be removed from the
screen, allowing a full 25 lines of text to be displayed, by
pressing the [F10] key, or by making the appropriate call to the
od_set_statusline() function. Note, however, than when this is
done, the status line is still enabled, and can be turned on by
pressing any of the other function keys. On the other hand, if
the status line is turned off using this variable
(od_control.od_status_on), the status line sub-system will be
disabled, and pressing function keys will not "bring it back".
So, if you were writing a program where a status line would be
undesirable - such as a non-door communications program, you
would use the od_control.od_status_on variable. On the other
hand, if you only wanted to temporarily remove the status line -
say in order that all 25 lines of a door program's output could
be viewed - while still allowing the status line to be turned on
with the sysop function keys, you would use the
od_set_statusline() function. For more information on the
od_set_statusline() function, see page 137.
-------------------------------------------------------------------------------
od_time void (*od_control.od_time_msg_func)(char *string)
_msg_func
This variable defaults to a value of NULL. If set to point to a
function, OpenDoors will call this function INSTEAD OF
displaying time limit warning messages to the user. The messages
redirected to this function are:
- Inactivity timeout warning
- Inactivity timeout expired
- Less than 4 minutes left today
- Daily time limit expired
===============================================================================
OpenDoors 6.00 Manual End of Page 211
CONTROL STRUCTURE - FUNCTION KEYS
-------------------------------------------------------------------------------
Within OpenDoors, as with most BBS software and doors, the sysop
has access to a number of function keys, which permits the sysop
to carry out various functions such as entering chat mode,
hanging up on the user, shelling to DOS, and so on. The
variables in this section allow you to customize which keys
carry out the standard sysop functions, allowing you to
customize your door's interface to mimic any BBS package. By
default, OpenDoors emulates the function keys used by the Remote
Access BBS package, but you may choose, for example, to have
your door use the key combinations used by PC-Board. In
addition, OpenDoors provides an interface which allows you to
add your own function keys which will be accepted by the door.
This could allow you to add additional features, such as giving
the sysop access to a status screen which displays information
about your door.
Many of the variables in this section are unsigned ints, which
represent a sysop key combination such as [ALT]-[H], [F8], or
[CTRL]-[P]. These values are in the same format as is returned
by the Turbo C(++) / Borland C++ bioskey() function. The high-
order byte represents the scan code of the key, and the low-
order byte represents the ASCII value, if any, of the key
combination. Note that a complete tutorial on these key codes is
beyond the scope of this manual. For more information on these
key codes, you should see the documentation on the bioskey()
function, which accompanies your compiler. If you wish to
determine the key code which corresponds to a particular
keystroke, there is a simple program, listed below, which you
can compile and use. This program will simply display the key
code for any key pressed, until you press the [ESCape] key. So,
in order to determine the code for [SHIFT]-[F8], you would
simply run this program, press the [SHIFT]-[F8] key combination
on your keyboard, and record the value displayed on your screen.
#include <stdio.h>
#include <bios.h>
main()
{
int nKey;
do
{
nKey = bioskey(0);
printf("%d (from: %x, %x)\n",
nKey, nKey>>8, nKey&0xff);
} while((nKey & 0xff) != 27);
}
===============================================================================
OpenDoors 6.00 Manual End of Page 212
-------------------------------------------------------------------------------
BUILT IN These variable allow you to customize the sysop function keys
FUNCTION which control functions such as hanging up on the user, shelling
KEYS to DOS, and so on. All of these variable will be assigned
default values, which correspond to the same function keys used
by the RemoteAccess BBS package. However, you may change the
values of these variables in order to customize the key
combinations which carry out these functions in your own door
program. Remember that if you wish to change the value of any of
these variables, you must do so after having called od_init() or
some OpenDoors function. Each of these variables contain a scan-
code / ASCII-code combination representing a keystroke, as is
described above. These variables are as follows:
+---------------------+----------------------------------------+
| VARIABLE | CORRESPONDING FUNCTION |
+---------------------+----------------------------------------+
| od_control. | Enter sysop chat mode |
| key_chat | (Normally [ALT]-[C] |
| | |
| od_control. | Invoke sysop DOS shell |
| key_dosshell | (Normally [ALT]-[J] |
| | |
| od_control. | Return to the BBS without hanging up |
| key_drop2bbs | (Normally [ALT]-[D]) |
| | |
| od_control. | Hangup on the user |
| key_hangup | (Normally [ALT]-[H]) |
| | |
| od_control. | Turn off the user's keyboard |
| key_keyboardoff | (Normally [ALT]-[K]) |
| | |
| od_control. | Decreases the user's remaining time |
| key_lesstime | (Normally [DOWN-ARROW]) |
| | |
| od_control. | Lock the user out of the BBS system |
| key_lockout | (Normally [ALT]-[L]) |
| | |
| od_control. | Increases the user's remaining time |
| key_moretime | (Normally [UP-ARROW]) |
| | |
| od_control. | Array of eight function keys to set the|
| key_status[8] | current status line. |
| | (Normally [F1], [F2], [F3], [F4], [F5],|
| | [F6], [F9], [F10]) |
| | |
| od_control. | "Sysop next" toggle key |
| key_sysopnext | (Normally [ALT]-[N]) |
+---------------------+----------------------------------------+
===============================================================================
OpenDoors 6.00 Manual End of Page 213
-------------------------------------------------------------------------------
CUSTOM In addition to the sysop function keys built into OpenDoors, you
FUNCTION may wish to add your own function keys to your door. For
KEYS example, you might wish to have the [ALT]-[Z] combination
display a window of information about your door, or you may wish
to add your own user editor to your door, accessible through the
[ALT]-[E] combination. The four variables:
unsigned char od_control.od_num_keys;
unsigned int od_control.od_hot_key[16];
unsigned int od_control.od_last_hot;
void (*od_control.od_hot_function[16])(void);
provide your program with an interface to add your own sysop
function keys (not accessible by the remote user) to the door
you have written.
OpenDoors allows you to define up to sixteen custom sysop
function keys. The key codes (as described at the beginning of
this section) are stored in the od_control.od_hot_key[] array,
and the od_control.od_num_keys variable records the number of
keys which have been defined. The od_control.od_num_keys
variable defaults to a value of 0. So, in order to add your own
function keys, simply place the key codes for these keys in the
first n elements of the od_control.od_hot_key[] array, and set
the od_control.od_num_keys variable to the number of keys you
have defined. OpenDoors will then watch the keyboard for any of
your predefined sysop function keys being pressed. If one of
these keys is pressed, OpenDoors will place the key code of the
pressed key in the od_control.od_last_hot variable. Your program
will then be able to respond to one of your custom function keys
being pressed by checking the value of the
od_control.od_last_hot variable. At any time this variable
contains a non-zero value. If this is the case, you will then be
able to determine which of your function keys has been pressed
by checking the key code contained in this variable. After
taking the appropriate action for the key pressed, you should be
sure to reset the value of the od_control.od_last_hot variable
back to zero, which will indicate to OpenDoors that your program
has received and responded to the function key which was
pressed.
As an alternative to testing the contents of the
od_control.od_last_hot variable, you can also have your program
respond to custom sysop function keys by providing a callback
function in the array: void
(*od_control.od_hot_function[16])(void);
The Nth element in this array corresponds to the Nth element in
the od_control.od_hot_key array. To use this mechanism, simply
set the appropriate element of this array to point to the
===============================================================================
OpenDoors 6.00 Manual End of Page 214
function that you wish to have OpenDoors call when the sysop
presses the corresponding function key. For instance, assume
that the following function is included in your program's source
code:
void addPoints(void)
{
/* add ten points to the user's score */
currentUser->points += 10;
}
If you wanted to have this function called when the sysop
presses the [Page Up] key, you could do the following:
/* get number of new sysop function key, and increment */
/* total number of keys */
int new_key = od_control.od_num_keys++;
/* Set next sysop hotkey to Page Up */
od_control.od_hot_key[new_key] = 0x4900;
/* Set corresponding function to addPoints() */
od_control.od_hot_function[new_key] = addPoints;
===============================================================================
OpenDoors 6.00 Manual End of Page 215
CONTROL STRUCTURE - COLOR CUSTOMIZATION
-------------------------------------------------------------------------------
These variables allow you to customize the color of text
displayed by OpenDoors. Each of these variables are assigned
color attributes, in the format used by od_set_attrib()
(described on page 128). These variables are as follows:
+---------------------+----------------------------------------+
| VARIABLE | WHERE COLOR IS USED |
+---------------------+----------------------------------------+
| od_control. | Text typed by the sysop and user in |
| od_chat_color1 & 2 | chat mode. |
| | |
| od_control. | File description fields in FILES.BBS |
| od_list_comment_col | listings |
| | |
| od_control. | Color of page pausing prompt that is |
| od_continue_col | displayed at the end of each page |
| | |
| od_control. | Filename fields in FILES.BBS listings |
| od_list_name_col | |
| | |
| od_control. | "Missing" string in FILES.BBS listings |
| od_list_offline_col | |
| | |
| od_control. | File size fields in FILES.BBS listings |
| od_list_size_col | |
| | |
| od_control. | Title fields in FILES.BBS listings |
| od_list_title_col | |
| | |
| od_control. | Color of the window title as displayed |
| od_menu_title_col | by od_popup_menu() |
| | |
| od_control. | Color of the window border as |
| od_menu_border_col | displayed by od_popup_menu() |
| | |
| od_control. | Color of the normal text displayed |
| od_menu_text_col | by od_popup_menu() |
| | |
| od_control. | Color of the shortcut keys displayed |
| od_menu_key_col | by od_popup_menu() |
| | |
| od_control. | Color of the selection bar as |
| od_menu_highlight_ | displayed by od_popup_menu() |
| col | |
| | |
| od_control. | Color of the shortcut keys displayed |
| od_menu_highkey_col | on the selected line by od_popup_menu()|
+---------------------+----------------------------------------+
===============================================================================
OpenDoors 6.00 Manual End of Page 216
CONTROL STRUCTURE - TEXT CUSTOMIZATION
-------------------------------------------------------------------------------
In addition to the other aspects of OpenDoors which may be
customized by use of the OpenDoors control structure, all of the
text displayed by OpenDoors may also be customized. This may be
done either to create doors with OpenDoors that use languages
other than English, or to simply give your doors a "personal
touch". The variables described in this section allow you to
define what text you want to have displayed by OpenDoors at any
time. All of these variables are pointers to strings, and are
set to default values in the od_init() function. Thus, if you
wish to change the string pointed to by any of these variables,
you must do so after od_init() or some OpenDoors API function
has been called. To set any of these variables, you can simply
set them to point to a string-constant in your program. For
example, to set the text displayed by OpenDoors prior to a DOS
shell, you could:
od_control.od_before_shell=(char *)"\n\rJust a moment...\n\r";
The chart below lists each of the text customization variables
(without the "od_control." prefix, for the sake of brevity),
along with their default strings.
Note that some of these strings MUST always be the same length
as their default string. You may not display longer text within
these strings, and if you wish to display shorter text, you must
pad the remaining space in the string with spaces, in order to
preserve its length. Those string which must be of fixed length
also have their length listed in the chart below. Any strings
which have an asterisk (*) in their length column may be any
length.
Also keep in mind that any string with "printf-style" formatting
sequences, such as "%s", must retain the same sequences in the
same order.
In addition, four of these pointers - od_after_chat,
od_after_shell, od_before_chat and od_before_shell - can be set
to a value of NULL. In this case, OpenDoors will not display any
string where this variable's string is normally displayed.
+-----------------------+-----+----------------------------------------------+
| VARIABLE NAME | LEN | DEFAULT VALUE |
+-----------------------+-----+----------------------------------------------+
| od_after_chat | * | "\n\rChat mode ended...\n\r\n\r" |
| | | |
| od_after_shell | * | "\n\r...Thanks for waiting\n\r\n\r" |
| | | |
| od_before_chat | * | "\n\rSysop breaking in for chat...\n\r\n\r" |
| | | |
===============================================================================
OpenDoors 6.00 Manual End of Page 217
| od_before_shell | * | "\n\rPlease wait a moment...\n\r" |
| | | |
| od_chat_reason | * | " Why would you " |
| | | "like to chat?\n\r" |
| | | |
| od_continue | * | "Continue? [Y/n/=]" |
| | | |
| od_continue_no | char| 'N' |
| | | |
| od_continue_nonstop | char| '=' |
| | | |
| od_continue_yes | char| 'Y' |
| | | |
| od_day[0] | 3 | "Sun" |
| | | |
| od_day[1] | 3 | "Mon" |
| | | |
| od_day[2] | 3 | "Tue" |
| | | |
| od_day[3] | 3 | "Wed" |
| | | |
| od_day[4] | 3 | "Thu" |
| | | |
| od_day[5] | 3 | "Fri" |
| | | |
| od_day[6] | 3 | "Sat" |
| | | |
| od_hanging_up | * | "Terminating Call" |
| | | |
| od_help_text | 80 | " Alt: [C]hat [H]angup [L]ockout [J]Dos " |
| | | "[K]eyboard-Off [D]rop to BBS " |
| | | |
| od_help_text2 | 79 | " OpenDoors 6.00 - (C)Copyright 1992, " |
| | | "Brian Pirie - Registered Version " |
| | | |
| od_inactivity_timeout | * | "User sleeping at keyboard, inactivity " |
| | | "timeout...\n\r\n\r" |
| | | |
| od_inactivity_warning | * | "Warning, only %d minute(s) remaining " |
| | | "today...\n\r\n\r" |
| | | |
| od_month[0] | 3 | "Jan" |
| | | |
| od_month[1] | 3 | "Feb" |
| | | |
| od_month[2] | 3 | "Mar" |
| | | |
| od_month[3] | 3 | "Apr" |
| | | |
| od_month[4] | 3 | "May" |
| | | |
| od_month[5] | 3 | "Jun" |
===============================================================================
OpenDoors 6.00 Manual End of Page 218
| | | |
| od_month[6] | 3 | "Jul" |
| | | |
| od_month[7] | 3 | "Aug" |
| | | |
| od_month[8] | 3 | "Sep" |
| | | |
| od_month[9] | 3 | "Oct" |
| | | |
| od_month[10] | 3 | "Nov" |
| | | |
| od_month[11] | 3 | "Dec" |
| | | |
| od_no_keyboard | 10 | "[Keyboard]" |
| | | |
| od_no_sysop | * | "\n\rI'm afraid the sysop is not available " |
| | | "at this time.\n\r" |
| | | |
| od_no_response | * | " No response.\n\r\n\r" |
| | | |
| od_no_time | * | "Sorry, you have used up your time for " |
| | | "today...\n\r\n\r" |
| | | |
| od_offline | 10 | "[OFFLINE] " |
| | | |
| od_paging | * | "\n\rPaging Sysop for Chat" |
| | | |
| od_press_key | * | "Press [Enter] to continue..." |
| | | |
| od_sending_rip | * | "\xb4 Sending RIP File \xc3" |
| | | |
| od_status_line[0] | 80 | " " |
| | | " [Node: " |
| | | |
| od_status_line[1] | * | "%s of %s at %u BPS" |
| | | |
| od_status_line[2] | 79 | "Security: Time: " |
| | | " [F9]=Help " |
| | | |
| od_sysop_next | 5 | "[SN] " |
| | | |
| od_time_left | 10 | "%d mins " |
| | | |
| od_time_warning | * | "Warning, only %d minute(s) remaining tod" |
| | | "ay...\n\r\n\r" |
| | | |
| od_want_chat | 11 | "[Want-Chat]" |
+-----------------------+-----+----------------------------------------------+
===============================================================================
OpenDoors 6.00 Manual End of Page 219
66
66
66
66666
66 66
66 66
6666
-------------------------------------------------------------------------------
CHAPTER 6 - SPECIAL TOPICS
ADDITIONAL INFORMATION ON THE WIN32 VERSION
-------------------------------------------------------------------------------
This section provides additional information on the Win32
version of OpenDoors that isn't found elsewhere in this manual.
If you are working with the Win32 version of OpenDoors, you
should take the time to read this entire section. You should
also read the sections in chapter 3 that describe how to compile
and run Win32 programs that use OpenDoors.
The Win32 version of OpenDoors has been designed to be as
similar as possible to the DOS version of OpenDoors. This means
that where possible, you can compile the same source code to
produce both a DOS and a Windows program. However, if you are
porting an existing DOS OpenDoors-based program to the Win32
platform, there are some important things to keep in mind.
The first thing to note is that under DOS, the program's
execution begins in the main() function, whereas under Windows,
it begins in the WinMain() function. To allow the same source
file to build both DOS and Windows versions you can use
conditional compilation. OpenDoor.h defines a constant of the
form ODPLAT_xxx, indicating which version of OpenDoors is being
used. Currently, this will be either ODPLAT_DOS, or
ODPLAT_WIN32. However, if a OS/2 or Unix version of OpenDoors
were created, they would use definitions such as ODPLAT_OS2, or
ODPLAT_UNIX. Under the Win32 version, you should pass the
nCmdShow parameter that is passed to WinMain into OpenDoors,
through od_control.od_cmd_show. If you do not do this, the
program will always start with the main window maximized,
regardless of what the user has requested. Also, you will
probably want to use the new od_parse_cmd_line() function in
both DOS and Windows programs, to allow standard command-line
options to be processed. The od_parse_cmd_line() function
accepts command line information in the same format as it is
passed to the main or WinMain() function. So, the general
structure of an OpenDoors program that can be compiled under
either DOS or Win32 now becomes:
===============================================================================
OpenDoors 6.00 Manual End of Page 220
/* Add your own #includes here. */
#include "opendoor.h"
#ifdef ODPLAT_WIN32
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpszCmdLine, int nCmdShow)
#else
int main(int argc, char *argv[])
#endif
{
/* Add local variables here. */
#ifdef ODPLAT_WIN32
od_control.od_cmd_show = nCmdShow;
od_parse_cmd_line(lpszCmdLine);
#else
od_parse_cmd_line(argc, argv);
#endif
/* Add the rest of your program after this point. */
}
If you are porting existing OpenDoors programs over to the Win32
version of OpenDoors, another issue that you will have to pay
careful attention to is the fact that you are now working in the
32-bit world. While 32-bit programming under a flat memory model
has many advantages (no more 64K segments and related
limitations, for example), you must be aware that the size of
basic data types that you are used to using may have changed.
For example, an int is now 32-bits wide instead of 16-bits wide.
One of the places where this difference becomes very important
is if you are performing file-I/O by directly dumping a
structure to or from disk using functions such as fread() and
fwrite(). In this case, you must declare your structures using
types that are of the same size between the 16-bit and 32-bit
worlds, in order for your file formats to be compatible between
the DOS and Win32 versions of your program. For example, the
EX_VOTE.C example program declares its structure using fixed-
sized types that are always available to any program including
"opendoor.h". These types are the following size, regardless of
what platform you are compiling under:
INT8 - 8-bit signed integer.
INT16 - 16-bit signed integer.
INT32 - 32-bit signed integer.
BYTE - 8-bit unsigned integer.
WORD - 16-bit unsigned integer.
DWORD - 32-bit unsigned integer.
===============================================================================
OpenDoors 6.00 Manual End of Page 221
(NOTE: Obviously, the many details of 32-bit programming and
Windows programming are beyond the scope of this document. For
more information on the issues discussed here, you will probably
wish to consult other sources of information on Win32
programming.)
As you are probably aware, the Win32 edition of OpenDoors makes
extensive use of multithreading. The number of threads will
depend on what mode OpenDoors is operating in. In some
situations, all of the following threads may exist:
- The client thread(s), which executes the code that you write
in your program, along with the OpenDoors API functions.
- The local screen thread, which is responsible for drawing
your program's output on the screen, and receiving input from
the local keyboard.
- The frame window thread, which handles the OpenDoors menus,
toolbar, status bar and sysop function keys.
- The remote input thread, which receives input from the serial
port and adds it to OpenDoors common local/remote input
queue.
- The carrier detection thread, which blocks and only executes
if the carrier detect signal goes low.
- The time update thread, which updates the user's time
remaining online, and monitors user timeouts.
Since most of these threads only execute when the operating
system determines that there is actually something for them to
do, the Win32 version of OpenDoors provides very high
performance and responsiveness.
You may also want to make use of multithreading directly within
your program. If you do this, please note that while you may use
threads to perform background processing, OpenDoors requires
that you only call OpenDoors API functions from one thread.
If you wish to customize the information that is displayed in
the Help|About dialog box (including your program's name and
copyright information), provide your own application icon, or
add online help to the help menu, refer to the sections in the
manual on the following od_control variables:
od_control.od_app_icon
od_control.od_help_callback
od_control.od_prog_name
od_control.od_prog_version
od_control.od_prog_copyright
The section that describes how to run Windows based door
programs under DOS-based BBS package indicates that
COM<n>AutoAssign=0 should be set in the system.ini file. The
explanation for this is as follows: The default value for this
===============================================================================
OpenDoors 6.00 Manual End of Page 222
setting in Windows 95 is -1, which prevents any Windows-based
program from accessing a serial port which has previously been
used by a non-Windows-based program, until the window that
program was running in is closed. By setting this value to 0,
you are allowing the Windows-based door program to immediately
use the modem, even while the MS-DOS session (VM) is still
active. A value of <x> greater than 0 will allow Windows-based
programs to access the serial port, only if the DOS-based
program has not accessed the serial port for at least <x>
seconds. For example, the default setting in Windows 3.1 was
COM1AutoAssign=2, which allowed Windows-based programs to access
the serial port if no DOS program had used it for at least 2
seconds.
The section that describes how to run Windows based door
programs under DOS-based BBS package also indicates that the
DTRON utility should be run after the start command returns. The
reason for this is that when a Windows program exits and closes
the serial port (by calling the CloseHandle() function), Windows
95 lowers the DTR line on the serial port. Most modems are
configured to respond to this by hanging up on the remote user.
From talking to other people, it seems that this "feature" (or
fundamental design flaw, depending on how you want to look at
it) is unique to Windows 95, and won't effect OpenDoors when
running under Windows NT. However, the majority of people will
undoubtedly be using the Win32 version of OpenDoors under
Windows 95. This is unfortunate, since the Win32 communications
facilities are otherwise _very_ well designed. There is a rumor
that Microsoft's next upgrade to Windows 95 will fix this
problem. However, I must stress that this is only a rumor, and
that I haven't received any confirmation about this from
Microsoft.
OpenDoors currently provides two solutions to this problem.
First of all, OpenDoors has the ability to use an already open
serial port handle, if that information is supplied to it.
Hopefully, all Windows 95-based BBS software will provide the
option of running a door program with the serial port still
open, and allow you to pass that serial port handle on the door
program's command line. OpenDoors allows the serial port handle
to be passed on the command line, or set directly in the
od_control structure, as is described later in this manual. On
BBS systems where this form of hot sharing of the serial port is
supported, the serial port can remain open at all times, and so
the CloseHandle() problem is avoided.
This means that the only situation where the CloseHandle()
problem still has to be dealt with is when OpenDoors is running
on a Windows 95 system and OpenDoors has to open the serial port
itself (and so must close the serial port before exiting). This
would be the case for most MS-DOS based BBS systems running
===============================================================================
OpenDoors 6.00 Manual End of Page 223
under Windows 95, unless some intermediate layer is provided. By
default, in this situation OpenDoors will disable DTR response
by the modem just before it closes the serial port, by sending
the AT&D0 command to the modem. The exact sequence of commands
used by OpenDoors to do this is specified by the
od_control.od_disable_dtr string. This DTR response disabling
may be turned off by setting the DIS_DTR_DISABLE
od_control.od_disable flag. Since many programs (OpenDoors
included) assume that they can hangup the modem by lowering the
DTR signal, a small utility will usually be run after the door,
which first raises the DTR signal again, and then re-enables DTR
response by the modem. Such a utility is included in this
package, named DTRON.EXE. I wrote the DTRON utility so that you
can freely redistributed it with your programs.
So, to summarize, the DTR disabling by OpenDoors and subsequent
reenabling by DTRON is only required for the Win32 version of
OpenDoors running under Windows 95 when the modem is configured
to hangup if the DTR signal is lowered, and the BBS software
does not have the ability to pass a live serial port handle to a
door program. Setting COM<n>AutoAssign in system.ini is only
required for the Win32 version of OpenDoors when it is being
called from an MS-DOS session that has previously accessed the
serial port.
Note that the Win32 version of OpenDoors requires Windows 95 or
Windows NT. It will not run under Windows 3.x, even with Win32s.
This is because OpenDoors makes use of the Windows 95/NT
multitasking and multithreading services that are not available
under Win32s.
===============================================================================
OpenDoors 6.00 Manual End of Page 224
CONFIGURATION FILE SYSTEM
-------------------------------------------------------------------------------
One of the most useful OpenDoors features that you can
optionally choose to include in your programs is the OpenDoors
configuration file system. All that is required to enable the
configuration file system is to include the following line
before your first call to any OpenDoors function:
od_control.od_config_file = INCLUDE_CONFIG_FILE;
OpenDoors will now search for and read an OpenDoors
configuration file. If you do not specify the name of this file,
the default name of DOOR.CFG will be used. Using this
configuration file, the sysop can set a wide variety of options,
such as modem and system configuration information, maximum time
limits for the door, and even define custom door information
(drop) file formats. The example DOOR.CFG file included in your
OpenDoors package shows the format and all options that are
automatically supported by the configuration file system. This
configuration file format is designed to be easy to use, and the
example configuration file contains comments which provide a
complete description of each option. Feel free to redistribute
DOOR.CFG or a modified version of this file with your door
programs. In addition to the many configuration file settings
already supported, you can add your own settings that are
specific to your particular program.
To specify your own filename for the configuration file, use the
od_config_filename control structure variable. For example, the
following line:
od_control.od_config_filename = "MYDOOR.CFG"
causes OpenDoors to look for the configuration file MYDOOR.CFG
instead of the default DOOR.CFG.
OpenDoors fill first search for the configuration file in the
directory specified in the od_config_filename variable, if a
specific directory name was supplied. If not found, it will then
search the current directory. If the configuration file system
is unable to locate a configuration file, or if any settings are
omitted from the file, the default values for these settings
will be used automatically. This means that the configuration
file is always optional, unless your program has custom settings
that it requires in order to run.
The format for the configuration file is as follows. Blank lines
and any text following the semi-colon (;) character are ignored.
Configuration options are specified using a keyword, possibly
followed by one or more options. The keywords are not case
sensitive, but some of the options are. The order of options in
===============================================================================
OpenDoors 6.00 Manual End of Page 225
the configuration file is not significant, with the exception of
the "CustomFileLine" option. For more information on the
"CustomFileLine" setting, see the section that begins on page
230. The built-in configuration options are as follow:
BBSDir - BBS System directory. Indicates where the door
information file (drop file) can be found.
DoorDir - The door's working directory. This is where the door's
system files are located. OpenDoors will automatically
perform a chdir into this directory at initialization, and
will return to the original directory on exit.
LogFileName - Specifies the filename (path optional) where the
door should record log information.
DisableLogging - Prevents door from writing to a log file.
Node - BBS node number that the door is running on. Only used if
OpenDoors is unable to determine the node number by some
other means.
???dayPagingHours - Specifies sysop paging hours. Sysop paging
will be permitted beginning at the start time, up until,
but not including, the end time. Times should be in the 24-
hour format. To disable paging on a particular day, set the
paging start and end times to the same time. ???day can be
one of Sunday, Monday, Tuesday, Wednesday, Thursday, Friday
or Saturday.
PageDuration - Duration of sysop page. Value indicates the
number of beeps that compose the sysop page alarm.
MaximumDoorTime - Maximum length of time a user is permitted to
access the door. If the user's total remaining time on the
BBS is less than this value, the user will only be
permitted to access the door for this shorter length of
time. This option is disabled by commenting out the line.
InactivityTimeout - Specifies the maximum number of seconds that
may elapse without the user pressing a key, before the user
will automatically be disconnected. A value of 0 disables
inactivity timeouts.
SysopName - Name of the sysop. OpenDoors can usually determine
the sysop's name from the door information (drop) file.
How3ever, some BBS packages do not supply this information.
In such cases, if the sysop's name is required by the door,
it may be supplied here.
===============================================================================
OpenDoors 6.00 Manual End of Page 226
SystemName - Like the sysop's name, this option can usually be
determined from the door information file. If it is not
available, the sysop my supply the information here.
ChatUserColor - Specifies the color of text typed by the user in
sysop chat mode. The format of the color name is included
in the description of the od_color_config() function.
ChatSysopColor - Specifies the color of test typed by the sysop
in chat mode.
FileListTitleColor - Files.BBS listing colors.
FileListNameColor
FileListSizeColor
FileListDescriptionColor
FileListOfflineColor
SwappingDir - Directory where disk swapping will be done.
SwappingNoEMS - Disables swapping to EMS memory.
SwappingDisable - Disables swapping entirely.
LockedBPS - BPS rate at which door should communicate with the
modem. Valid rates are 300, 600, 1200, 2400, 4800, 9600,
19200 and 38400. A value of 0 forces the door to always
operate in local mode. This option is not normally needed,
as the information is usually available from the door
information file.
FossilPort - Specifies the FOSSIL driver port number that the
modem is connected to. FOSSIL port 0 usually corresponds to
COM1, port 1 to COM2, and so on. This option is not
normally needed, as the information is usually available
from the door information file.
CustomFileName - Specifies the filename used by the custom door
information file format. Described in more detail below.
CustomFileLine - Specifies the contents of a particular line in
the custom door information file format.
The last two configuration file options, "CustomFileName" and
"CustomFileLine" allow you or the system operator using your
program to define your own door information (drop) file formats.
For more information on this topic, see the section which begins
on page 230.
You can also extend OpenDoor's configuration file format to add
your own options, by supplying a callback function that will be
called whenever OpenDoors encounters an unrecognized
===============================================================================
OpenDoors 6.00 Manual End of Page 227
configuration file keyword. The prototype of this function
should be as follows:
custom_line_function(char *keyword, char *options)
To cause OpenDoors to use your function, you would include the
following line before your first call to any OpenDoors function:
od_control.od_config_function = custom_line_function;
(You can use a different function name if you wish.) When
OpenDoors encounters unrecognized keyword, it will now call your
function, passing a pointer to an upper case version the keyword
string in the first parameter, and a pointer to any options that
follow the keyword in the second parameter. For instance, if the
following line were encountered in the configuration file:
RegisteredTo John Smith ; Sysop's name
The parameters passed to your function would be:
char *keyword = "REGISTEREDTO"
char *options = "John Smith"
Your custom line function should be written in such a way that
if OpenDoors passes a configuration option to your function that
your function does not recognize, that option would simply be
ignored.
The example program below demonstrates how to use the custom
line function to add your own configuration file options. This
program looks for three custom configuration file options,
"RegistrationKey", "DefaultColor" and "DisplayWinners". If the
"RegistrationKey" option is present, the numerical value
following this option is stored in the global variable "key". If
the "DefaultColor" option is present, the color description
(such as "Bright Red on Black") is translated to an
od_set_attr() color code using od_color_config(). This color
setting is stored in the global variable default_color. Since
this variable is initialized to 0x07 (the value for dark white
on black), if this option is omitted, that color is used by
default. If the "DisplayWinners" option is included in the
configuration file, the global variable display_winners is set
to TRUE, regardless of any options that may follow this keyword.
#include "opendoor.h" /* Include opendooor.h */
/* Prototype for custom line function */
void custom_line_function(char *keyword, char *options);
unsigned long key=0L; /* Variables for our own config option */
unsigned char default_color=0x07;
===============================================================================
OpenDoors 6.00 Manual End of Page 228
char display_winners=FALSE;
main() /* Program's execution begins here */
{ /* Begin door operations, reading config file */
od_control.od_config_file = INCLUDE_CONFIG_FILE;
/* Tell OpenDoors to use custom line function */
od_control.od_config_function = custom_line_function;
od_init();
/* Main program's operations go here */
od_exit(10, FALSE); /* Exit program */
}
/* Code for custom line function */
void custom_line_function(char *keyword, char *options)
{ /* If option is registration key */
if(stricmp(keyword,"REGISTRATIONKEY")==0)
{
key=atol(options); /* Store key in variable */
} /* If option is text color */
else if(stricmp(keyword,"DEFAULTCOLOR")==0)
{ /* Get color value using od_color_config() */
default_color=od_color_config(options);
} /* Example of option enabled by just the keyword */
else if(stricmp(keyword,"DISPLAYWINNERS")==0)
{ /* If keyword is present, turn on option */
display_winners=TRUE;
}
}
===============================================================================
OpenDoors 6.00 Manual End of Page 229
DEFINING CUSTOM DOOR INFORMATION FILE FORMATS
-------------------------------------------------------------------------------
As is mentioned in the previous section, the OpenDoors
configuration file system provides two settings which allow the
sysop to define a custom door information file format. This
permits OpenDoors doors to operate directly on any BBS system
that produces a door information file format not directly
supported by OpenDoors. A custom door information file format is
defined using the "CustomFileName" option, followed by one or
more lines beginning with the "CustomFileLine" option.
The "CustomFileName" option specifies the filename used to
distinguish this file format from other file formats. This
filename should not include a path. To specify the path where
the door information file is located, the sysop should use the
BBSDir configuration file setting. If the filename of the custom
format is the same as that of one of the built-in formats, the
custom format will override the built-in format.
The actual format of the custom file is specified using a number
of lines that begin with the keyword "CustomFileLine". Each of
these lines will correspond to a single line in the door
information file, with the option following the "CustomFileLine"
keyword specifying the information that can be found on that
line. This can be one of the following keywords:
Ignore - Causes the next line in the door information file
to be ignored. Use on lines for which none of the
options below apply.
COMPORT - COM? port the modem is connected to (0 indicates
local mode)
FOSSILPORT - Fossil port number the modem is connected to
MODEMBPS - BPS rate at which to communicate with modem (0
or non-numerical value indicates local mode)
LOCALMODE - 1, T or Y if door is operating in local mode
USERNAME - Full name of the user
USERFIRSTNAME - First name(s) of the user
USERLASTNAME - Last name of the user
ALIAS - The user's pseudonym / handle
HOURSLEFT - Hours user has left online
===============================================================================
OpenDoors 6.00 Manual End of Page 230
MINUTESLEFT - Minutes user has left online, or time left
online in format hh:mm
SECONDSLEFT - Seconds user has left online, or time left
online in format hh:mm:ss or format mm:ss (If more
than one of the above time options are used, the user
time left is taken to be the total of all of these
values.)
ANSI - 1, T, Y or G for ANSI graphics mode
AVATAR - 1, T or Y for AVATAR graphics mode
PAGEPAUSING - 1, T or Y if user wishes a pause at end of
screen
SCREENLENGTH - Number of lines on user's screen
SCREENCLEARING - 1, T or Y if screen clearing mode is on
SECURITY - The user's security level / access level
CITY - City the user is calling from
NODE - Node number user is connected to
SYSOPNAME - Full name of the sysop
SYSOPFIRSTNAME - The sysop's first name(s)
SYSOPLASTNAME - The sysop's last name
SYSTEMNAME - Name of the BBS
As an example of how to define custom door information file
formats, consider the following imaginary file format, which we
will name DROPINFO.TXT:
Brian Pirie <-- User name
0 <-- Local mode
COM1: <-- Serial port to use
9600 <-- BPS rate
22:30:15 05-08-95 <-- File creation time
35 <-- Time remaining (in minutes)
1 <-- ANSI mode
Ottawa, Canada <-- Location
This format would be defined in an OpenDoors configuration file
as follows:
===============================================================================
OpenDoors 6.00 Manual End of Page 231
CustomFileName DROPINFO.TXT
CustomFileLine USERNAME
CustomFileLine LOCALMODE
CustomFileLine COMPORT
CustomFileLine MODEMBPS
CustomFileLine IGNORE
CustomFileLine MINUTESLEFT
CustomFileLine ANSI
CustomFileLine CITY
Notice that the first "CustomFileLine" keyword in the
configuration file corresponds to the first line in our
DROPINFO.TXT file, the second "CustomFileLine" to the second
line, and so on. Also notice that the keyword "IGNORE" is used
for the line that contains the file creation time, since there
is no CustomFileLine keyword that allows you to read this
information.
===============================================================================
OpenDoors 6.00 Manual End of Page 232
MULTIPLE PERSONALITY SYSTEM
-------------------------------------------------------------------------------
The OpenDoors Multiple Personality System allows the DOS
version of OpenDoors to support multiple sysop function key /
status line "personalities". Most commonly, you will use this
feature in conjunction with the "Personality" setting in the
OpenDoors configuration file, to allow the sysop to choose one
of the built-in personalities that most closely mimics the BBS
software they are using. OpenDoors includes the following
personalities:
Configuration Keyword Manifest constant
-----------------------------------------------------------
Standard PER_OPENDOORS
PCBoard PER_PCBOARD
RemoteAccess PER_RA
Wildcat PER_WILDCAT
The PCBoard, RemoteAccess and Wildcat personalities mimic the
status lines and function keys used by the BBS packages with
those names. The Standard personality, which is the personality
used by default, is a trimmed down version of the status lines
provided by OpenDoors 4.10 and earlier.
In addition to using the personalities supplied with OpenDoors,
you can create your own personalities. This simply involves
writing a function which OpenDoors will call to setup the sysop
function keys and to display the status line.
Include the following line before your first call to any
OpenDoors function:
od_control.od_mps = INCLUDE_MPS;
to include the multiple personality system in your program. This
also enables the Personality setting in the configuration file,
if you are using the configuration file system.
You can set the default personality to be used by OpenDoors by
setting od_control.od_default_personality to one of the manifest
constants listed in the table above. If you have included the
multiple personality system in your program, this setting will
determine the personality to use if the "Personality" option is
not set in the configuration file, and your program does not
later change the personality using the od_set_personality()
function. If you do not include the multiple personality system
in your program, this setting will determine the personality
that will always be used.
Creating your own personality involves writing a single
function.. Whenever OpenDoors needs to perform an operation that
===============================================================================
OpenDoors 6.00 Manual End of Page 233
involves the personality, it will call this function, passing
one of the following message values:
PEROP_INITIALIZE Initialize the personality, installing any
custom function keys.
PEROP_DEINITIALIZE Deinitialize the personality, returning any
changed settings to their original values.
PEROP_CUSTOMKEY Indicates that a custom function key has
been pressed.
PEROP_DISPLAYx Where x is a number from 1 to 10. Indicates
that the specified status line should be
drawn from scratch.
PEROP_UPDATEx Where x is a number from 1 to 10. Indicates
that the specified status line should be
updated to reflect any changes.
If you have enabled the multiple personality system by setting
od_control.od_mps to INCLUDE_MPS, you can install your
personality function into OpenDoors by calling
od_add_personality(). When you call od_add_personality(), you
supply a string containing the name of the personality, along
with the top and bottom output line numbers to use. These line
numbers specify the portion of the screen to use for door
output, leaving the remainder of the screen available for
displaying the personality's status line. Once the personality
has been installed into OpenDoors, it can be selected by the
sysop using the "Personality" configuration file option, or
manually activated using the od_set_personality() function. For
more information on the od_add_personality() function, see page
47.
You can make your personality function the default personality
by setting od_control.od_default_personality to point to your
personality function. As is the case with the built-in
personalities, this setting will be used as the default
personality if you have enabled the multiple personality system
by setting od_control.od_mps to INCLUDE_MPS. If you have not
enabled the multiple personality system in this manner, your
personality function will become the one and only personality
used within your program. When creating your own personality,
you can use the od_control.od_page_statusline variable to set
which status line (if any) will be activated when the user pages
the system operator.
===============================================================================
OpenDoors 6.00 Manual End of Page 234
LOG FILE SYSTEM
-------------------------------------------------------------------------------
In order for the system operator to monitor system activity and
diagnose problems that have occurred while the system was
unattended, it is common for BBS software and door programs to
record major events in a log file. This log file typically
records the date and time of evens such as a user logging on or
off, transferring files, sending messages, paging the system
operator, and similar activities. Sometimes the system operator
will configure all of the pieces of software running on a
particular node to write to a single log file. In other cases,
the system operator will prefer to have each program write to
its own log file. However, software serving one line of a multi-
node BBS system should never attempt to write to the same log
file that is used by another node.
OpenDoors uses the "FrontDoor format" log file standard. This
was chosen as it is a clearly documented format that is quickly
becoming the standard for bulletin board software log files. A
segment from a log file produced by OpenDoors is listed below.
---------- Thu 25 Feb 93, Vote 6.00
> 19:42:23 Brian Pirie entering door
> 19:50:55 User paging system operator
> 19:51:02 Entering sysop chat mode
> 20:05:41 Terminating sysop chat mode
> 20:18:32 User time expired, exiting door
To enable the OpenDoors log file system, simply include the
following line before your first call to any OpenDoors function:
od_control.od_logfile = INCLUDE_LOGFILE;
When OpenDoors is initialized, it will open the log file and
begin logging activities, unless logging has been disabled with
the od_control.od_logfile_disable variable. The log file name
will be taken from the od_control.od_logfile_name variable,
which is usually set by the configuration file. If no logfile
name has been set, OpenDoors will use the logfile named
DOOR.LOG. Upon opening the log file, OpenDoors will write an
entry indicating the time at which the use entered the door.
The od_control.od_prog_name variable sets the program name that
is written to the log file immediately after the current date
information. If this variable is not set, OpenDoors will write
its own name and version information in this place.
When the OpenDoors log file system is enabled, OpenDoors will
automatically produce logfile entries for the following events:
- User paging sysop, beginning of chat, end of chat
===============================================================================
OpenDoors 6.00 Manual End of Page 235
- Sysop entering or returning from DOS shell
- User inactivity timeout or user time expired
- Sysop dropping user back to BBS
- Sysop hanging up on user, sysop locking out user
- User hanging up on BBS
- Your program calling the od_exit() function
===============================================================================
OpenDoors 6.00 Manual End of Page 236
MAKING DOORS MULTI-NODE-AWARE
-------------------------------------------------------------------------------
While the majority of BBS systems have only a single phone line,
allowing only one user to access the system at a time, there are
also many multi-node BBS systems. On such systems, it is quite
possible that more than one user may be using your door program
simultaneously. OpenDoors itself is designed for both single-
node and multi-node operation. However, if you want your program
to operate correctly on multi-node systems, there are a number
of concurrency issues that you must keep in mind when writing
your own code.
Some door programs are designed to behave on multi-node systems
just as they would on single-line BBSes. Others add special
features only possible in multi-node environments. For instance,
you may want to permit users to interact or chat with one
another in "real time". Many simple doors may not require any
special attention to multi-node capabilities. However, if your
door must access any data files or other resources that are to
be shared among nodes, it is necessary to carefully coordinate
access to these resources.
There are two primary issues that are often of concern when
creating door programs for multi-node systems. The first issue
discussed below is how to coordinate concurrent file access
between multiple node. The second topic we will deal with is the
installation of door programs on multi-node systems.
CONCURRENT FILE ACCESS
-------------------------------------------------------------------------------
One of the most important issues that arises when writing door
programs for multi-node systems is how to coordinate
simultaneous access to a single data file by multiple instances
of your program. While it is generally safe to have multiple
nodes reading simultaneously from a single file, having multiple
nodes updating a file without any coordination can lead to lost
updates and other problems. Consider, for example, the EX_VOTE.C
example program that is included in your OpenDoors package. When
the user votes on a poll, EX_VOTE.C must update the total number
of votes for the user's answer. Such a program that is only
intended for single node operation could do this by simply
reading the current number of votes for the appropriate option,
adding one to this total, and writing the updated total back to
the file. However, if this approach where to be used on a multi-
node system, it is quite possible that two users would vote on
the same poll after both nodes have read the poll record into
memory. In this situation, one node would add one to the total
number of votes for the poll record that it has in memory, and
===============================================================================
OpenDoors 6.00 Manual End of Page 237
write the updated information to the file. The second node would
then add one to its total, without reading the updated
information written by the first node. When the second node then
writes this information to the file, it overwrites the first
node's total with its own. The final effect is that the second
user's vote overwrites the first, and so the first user's vote
is lost.
The solution to this problem is to lock a file unit for the
entire update operation, to prevent other nodes from accessing
the unit at the same time. This unit could be the entire file,
or only a single record in the file. EX_VOTE.C locks its entire
file when performing an update operation, but in other cases it
may be more appropriate to only lock a single record in the
file. The important thing to understand is that when one node
locks a file unit, other nodes much wait until the first node is
finished the update operation. This means that if one node is
updating information that other nodes could possibly need access
to, it should always perform the lock, read, write and unlock
cycle as quickly as possible.
Let's look again at the approach taken by EX_VOTE.C. After the
user has indicated which option he/she wishes to vote on, Vote
attempts to open the file for exclusive access. By doing this,
EX_VOTE.C in effect locks the entire file for the duration that
it has the file open. If another node attempts to open the file
while one node has it locked, the open operation will fail, and
the C runtime library will set the errno variable to EACCES.
This, in effect, tells you that another node is currently
working on the file, and that you must wait your turn. In this
case, EX_VOTE.C continues to retry the open operation until the
other node is finished its update, at which time the open
operation will succeed. This approach will even work when there
are many nodes that are attempting to update the file at the
same time. Whichever node first attempts to open the file will
gain exclusive access to the file, and any additional nodes are
forced to wait for access to the file. When one node finishes
with the file, another node will gain access to the file
(whichever happens to be the next node to re-attempt the open
operation). This process continues until all waiting nodes have
had a chance to perform their update. EX_VOTE.C will repeatedly
try to open the file for up to 20 seconds, after which time it
will give up, reporting an error which indicate that it is
unable to access the file. During this waiting process,
EX_VOTE.C repeatedly calls od_kernel(), so that sysop function
keys, carrier detection and other essential door operations can
continue to be performed.
After EX_VOTE.C has successfully secured exclusive access to the
file, it first reads the record that it is going to update. It
is important that this be done after the file unit is locked, in
order to ensure that the copy of the record in memory matches
===============================================================================
OpenDoors 6.00 Manual End of Page 238
what is stored in the file. EX_VOTE.C then updates the record
based on the question on which the user has voted, writes this
information back to the file. EX_VOTE.C then immediately closes
the file, allowing other nodes to also access the file.
EX_VOTE.C is very carefully designed so that the file update
operation can never be interrupted (for instance, no OpenDoors
functions are called, which could detect a time-out and
terminate the program while a file update operation is in
progress), or delayed until the user makes a response. As such,
the file unit is always unlocked (in this case, closed) within a
fraction of a second after it was locked, or order that other
nodes will never have to wait long for access to the file.
Here I have presented a detailed account of how EX_VOTE.C
handles multi-node file access. While all of the details
involved in coordinating multiple file access can be
overwhelming at first, they will begin to come naturally to you,
as you begin to always think in terms of multi-node scenarios.
To summarize, the important elements that are typically involved
in multi-node file access are:
A. Decide on an appropriate file unit to lock for your
application. In simple cases, this can be the entire file.
In other cases, you may wish to lock individual file
records, using the appropriate runtime library functions.
B. Always perform update operations in lock, read, update,
write, unlock cycles on individual file units. If there is a
chance that other nodes will also need to access the file
unit, ensure that the update operation cannot be interrupted
or delayed until a user makes a response.
After you have designed your program for concurrent file access,
how can you test it? If you don't have a multi-node BBS system
that you have access to, you can perform most of your testing
under a multitasking environment, with multiple copies of your
program running in different windows.
===============================================================================
OpenDoors 6.00 Manual End of Page 239
MULTI-NODE CONFIGURATION
-------------------------------------------------------------------------------
A second issue that you may want to bear in mind is how door
programs are typically setup on multi-node systems.
Unfortunately, this may differ considerable depending upon which
BBS software is being used. However, some of the issues that you
may have to consider discussed below:
A. Your program must be able to locate the correct door
information file for the appropriate node. Most BBS systems
make separate door information files available to each node
by one of the following means:
- By naming each node's door information file
uniquely. (e.g. DORINFO1.DEF, DORINFO2.DEF.)
- By having a separate directory for each node's door
information file. (e.g. \NODE1\DOOR.SYS,
\NODE2\DOOR.SYS, etc.)
In the first case, OpenDoors can automatically select the
correct door information file, assuming that it knows which
node it is running on (see item C, below). In the later
case, you must tell OpenDoors which directory it must look
in to find the appropriate door information file. You may do
this by any of the following means:
- By specifying the location of the file on the
command line, if od_parse_cmd_line() is used.
- By providing a configuration file keyword to set
the door information file location for each node.
- By providing a different configuration file for
each node (See item B, below).
B. If you are using the OpenDoors configuration file system,
node-specific options should not be used if each node is
accessing the same configuration file. While it is possible
to have a different configuration file for each node (the
filename can be specified on the command line if
od_parse_cmd_line() is used), in most cases the same
configuration file will be used for all nodes. In this case,
the node number, serial port information, and possible door
information file location operations should not be used. If
you are basing your configuration file on the example
DOOR.CFG file that is included in the OpenDoors package, you
may want to remove these options from the file.
C. In many cases, your program must also be able to determine
which node it is running under. If this information is
===============================================================================
OpenDoors 6.00 Manual End of Page 240
available in the door information file, or is stored in a
TASK environment variable, OpenDoors will automatically set
the appropriate node number in od_control.od_node.
Otherwise, if your program requires this information, it
should be specified on the program's command line. The
od_parse_cmd_line() function supports this option. Reasons
that your program might need to know the current node number
include:
- In order for OpenDoors to display this information
correctly on the status line.
- In order to determine which configuration file to
read or which node directory in which to look for
the door information file.
- In order for OpenDoors to know which door
information file to read (e.g. DORINFO1.DEF,
DORINFO2.DEF. etc.)
- In order to provide any form of real-time
interaction between nodes, such as inter-node chat.
D. If your program is running under MS-DOS, and multi-node file
access is being coordinated by locking part or all of a
file, the SHARE.EXE utility must be installed.
===============================================================================
OpenDoors 6.00 Manual End of Page 241
7777777
77
77
77
77
77
77
-------------------------------------------------------------------------------
CHAPTER 7 - TROUBLESHOOTING AND GETTING ASSISTANCE WITH OPENDOORS
ABOUT THIS CHAPTER
-------------------------------------------------------------------------------
This chapter is perhaps the most important section of this
entire manual. Here, we provide detailed instructions to help
you in tracing the source of problems in programs written with
OpenDoors. Included in this chapter is a step-by-step OpenDoors
troubleshooting guide and a chart listing common problems and
their solutions. Also included in this chapter is information on
the many means available to you for getting more help with
OpenDoors, including the OpenDoors support BBS, the OpenDoors
EchoMail conference, and how to get in touch with me. It is
strongly encouraged that you take the time to read through this
chapter.
TROUBLESHOOTING PROBLEMS
-------------------------------------------------------------------------------
If you are experiencing difficulty with a program that you are
writing using OpenDoors, it is suggested that you follow the
steps listed below in order to quickly solve your problem. Also,
be sure to check to "solutions to common problems" section of
this manual. There are many common difficulties which people
have with OpenDoors, that can easily be fixed using the
instructions in the "common solutions" section. Also, if you are
having difficulty solving a problem yourself, do not hesitate to
get in touch with me, as I am always happy to help with any
problems. In addition, you may find the other means of OpenDoors
support (described latter in this chapter), invaluable in
solving difficulties with OpenDoors.
Keep in mind that most programs you write will have some "bugs"
to begin with, and you should expect to spend at least 50% of
any programming project tracing down and solving errors and
bugs. While it would be nice if every program written worked
correctly the first time, it is a fact of life that debugging is
and always has been an important part of the software life-
===============================================================================
OpenDoors 6.00 Manual End of Page 242
cycle. In fact, what most often separates the good programs from
the bad is the amount of time their programmer's spend debugging
and improving them. Unfortunately, it is difficult, if not
impossible, to come up with a "magic formula" for debugging
software. Debugging software is really more of an art than a
science. However, there are some basic guidelines, which if
followed, can greatly ease the task of software debugging.
As with all problem solving, the secret to software debugging
lies in obtaining as much information about the problem as
possible. While it is sometimes possible to solve a bug by
making intuitive changes in your program, or in re-writing a
piece of code to solve the problem by a different means,
debugging most often requires more of a "planned attack". This
planned attack generally involves little more than learning as
much about what is going wrong as possible. The first step in
solving a bug usually lies in locating the source of the
problem. Once you have located the problem, solving it is often
a relatively simple procedure. In locating the source of your
bug, the use of a software debugger, such as the one built into
the Turbo C(++) / Borland C++ integrated development
environment, can be invaluable.
When debugging programs written with OpenDoors, you should also
follow the steps listed below, in order to obtain more
information related to the problem you are trying to solve:
1.) Re-read the section(s) of this manual, your Turbo C(++) /
Borland C++ manuals and your program's source code, which
apply to the problem you are experiencing.
2.) Check the solutions to common problems section below. The
most common problems with OpenDoors can be solved using
this simple chart.
3.) Check the value in the od_errno variable, which will often
provide vital clues as to the source of the problem. Use of
the od_errno variable is described in the section below.
4.) If you are still stuck, please feel more than free to get
in touch with me! (see the end of this chapter for
information on reaching me) I am always more than happy to
help with any OpenDoors or general programming problems!
===============================================================================
OpenDoors 6.00 Manual End of Page 243
SOLUTIONS TO COMMON PROBLEMS
-------------------------------------------------------------------------------
Below, several common difficulties with OpenDoors are listed,
along with suggested solutions to these problems. If you are
experiencing any difficulty with a program that you have written
with OpenDoors, we would suggest that you read this section
thoroughly. Here, the common problem is listed in the left
margin, and the solutions listed on the right portion of the
page.
-------------------------------------------------------------------------------
PROGRAM 1.) Check that the compiler is able to locate the OpenDoors
WON'T header file, "OPENDOOR.H". This can be accomplished either by
COMPILE placing this header file in the same directory as your other
header files (such as STDIO.H, etc.), or by placing the header
file in the current directory.
2.) Be sure that you are linking your program with the correct
library for the memory model you are using. (See the section on
compiling with OpenDoors). Also be sure that both the source
code file for your program (such as EX_VOTE.C) and the library
file are listed in your project file, and that the project file
is loaded. For more information on compiling programs written
with OpenDoors, see page 22.
3.) If you have tried the above solutions, and your program
still won't compile, then the problem is most likely an error in
your source code file. If you are unable to resolve your
problem, feel free to get in touch with me.
-------------------------------------------------------------------------------
SCREEN If you are using the od_clr_scr() function to clear the screen,
WILL NOT but are not getting any results, this is likely because the user
CLEAR online has screen clearing turned off. If you wish to force
screen clearing regardless of the user's screen clearing
settings (this is probably not a good idea), use the function
call od_disp_emu("\xc", TRUE);
-------------------------------------------------------------------------------
FIXUP This problem was probably caused by a mismatch between your
OVERFLOW memory model selection in your compiler, and the memory model
ERROR library you are using. See the section on compiling programs
with OpenDoors for more information on the correct library you
should be using for your memory model selection.
===============================================================================
OpenDoors 6.00 Manual End of Page 244
OPENDOORS SUPPORT
-------------------------------------------------------------------------------
The powerful and easy to use door toolkit and this comprehensive
manual are only two portions of how OpenDoors helps you to write
BBS door and similar programs. The third element of OpenDoors is
the extensive OpenDoors support mechanisms. The OpenDoors email
conference and support BBS each give you a chance to share ideas
and source code with other OpenDoors programmers. A lot of
information concerning OpenDoors, along with the newest version
and online registration, is available through the OpenDoors
World Wide Web site. In addition to these sources, I am also
more than happy to answer any of your questions, or hear any
suggestions for future versions of OpenDoors. The remainder of
this chapter provides more information on the various sources of
OpenDoors support. Also keep your eyes open for the "OpenDoors
Tech Journal", that is produced on a regular basis by the users
of OpenDoors. Included in this newsletter is information on
OpenDoors and future versions, questions and answers about
OpenDoors and BBS door / utility programming in general, sample
source code, and much more.
THE OPENDOORS SUPPORT BBS
-------------------------------------------------------------------------------
One means of receiving OpenDoors support is via the OpenDoors
BBS. Below is an outline of some of what is available from the
OpenDoors BBS:
- The newest version of this package is always available
for download.
- Also available for download is example source code and
other files which you may find helpful when writing
programs with OpenDoors.
- Access to the OpenDoors conference where OpenDoors
programmers can share ideas, source code, and receive
help with difficulties or with learning OpenDoors.
- Get in touch with me with any questions, comments,
suggestions or bug reports.
- Other files by yours truly, which may be of use in you
programming, such as a registration key system, and so
on.
All users receive full access upon their first call to the
OpenDoors BBS. The North American phone number for the support
BBS is:
===============================================================================
OpenDoors 6.00 Manual End of Page 245
+1 (613) 599-5554
The OpenDoors support BBS also has a FidoNet address, 1:243/8.
If you are interested in a list of files available from the
support BBS, simply file-request "FILES". To receive the newest
version of OpenDoors, you can file-request "ODOORS".
THE OPENDOORS WORD WIDE WEB SITE
-------------------------------------------------------------------------------
The OpenDoors World Wide Web site has been setup to provide up-
to-date information on OpenDoors. This includes news concerning
OpenDoors, OpenDoors tips and techniques, pointers to other
sources of OpenDoors support, online registration and access to
the newest version of OpenDoors.
The current URL (address) of the OpenDoors Web site is:
http://omega.scs.carleton.ca/~ug930227/opendoor.html
However, I plan on moving this to a new location some time this
year. If you are unable to reach the OpenDoors Web site through
the above URL, please get in touch with me, and I will be able
to tell you where it has moved to.
THE OPENDOORS CONFERENCE
-------------------------------------------------------------------------------
The OpenDoors conference is devoted to OpenDoors and BBS / door
/ BBS utility programming in general. The OpenDoors conference
serves as a place where people working with OpenDoors can share
ideas, source code examples, and other tricks and techniques.
Through the OpenDoors conference you can receive help with
OpenDoors and programming in general. Also available through the
OpenDoors conference is information on future versions of
OpenDoors and recent developments of concern to BBS door and
utility programmers. The OpenDoors conference is also a place
for suggestions for future versions of OpenDoors, OpenDoors bug
reports, a place to announce the availability of your programs,
and much more information of interest to programmers working
with OpenDoors.
You can become involved in the OpenDoors Conference by the
following means:
- The OpenDoors conference is available as an Internet mailing
list. to subscribe, send email to listserv@hms.com and put
===============================================================================
OpenDoors 6.00 Manual End of Page 246
SUBSCRIBE OPENDOOR in the message body. For help on using the
listserver you can send email to listserv@hms.com and put
HELP in the message body.
- The OpenDoors conference is available on the FidoNet North
America echo backbone, and so is available to a large number
of BBS systems. FidoNet capable systems may also obtain an
OpenDoors feed directly from the moderator, Brian Pirie.
GETTING IN TOUCH WITH ME
-------------------------------------------------------------------------------
If you have any questions about OpenDoors, would like help with
any programs that your are writing, or have any suggestions for
future versions of OpenDoors, please feel free to get in touch
with me. You can get in touch with me by any of the following
means:
- The best way to contact me is by Internet email. My primary
email address is:
pirie@msn.com
If you have difficulty contacting me through this address, I
may also be reached through the address:
aa522@freenet.carleton.ca
- By writing a message to me in the OpenDoors support
conference. For more information on the OpenDoors conference,
see the previous section of this chapter.
- By calling the OpenDoors support BBS. Information on the
support BBS is provided earlier on in this chapter.
- By sending your question or comment by Fax. My fax number is:
+1 (613) 599-5554
- By FidoNet NetMail. My address is:
1:243/8
While I would like to be able to reply to all NetMail
messages by CrashMail, I am afraid I simply can not afford to
do this. So, if you choose to send NetMail, please indicate
whether you would like me to reply by routed NetMail (this
may not work, if routed NetMail is not available in your
area), or to place the message on hold for you to poll and
pick up.
===============================================================================
OpenDoors 6.00 Manual End of Page 247
- By conventional mail. My postal address is:
Brian Pirie
117 Cedarock Drive
Kanata ON K2M 2H5
Canada
I try to respond to all correspondences as soon as possible.
If you are having some sort of difficulty with OpenDoors, the
more detailed information you supply (such as source code to the
program that is causing the problem, how to duplicate the
problem, and so on), the more quickly I will be able to
determine the source of your problem. Also, before you write
about a problem with OpenDoors, you may wish to be sure that you
have read and followed the instructions in the section on
troubleshooting, found on page 242. While I do not mind taking
the time to answer any questions related to OpenDoors, you may
be able to save yourself the time of writing and waiting for a
response - simply by following the instructions in the
troubleshooting section. More often than not, the answer to
questions I receive is already in this manual.
===============================================================================
OpenDoors 6.00 Manual End of Page 248
A
AAA
AA AA
AAAAAAA
AA AA
AA AA
AA AA
-------------------------------------------------------------------------------
APPENDIX A - CONTENTS OF PACKAGE
The main OpenDoors package is distributed in the form of a
single, compressed archive file. Thus, you should have received
this version of OpenDoors in a file whose name began with
ODOORS60. The files listed below should be included in your
OpenDoors package. If any of these files are missing, you will
probably want to look for the most recent version of OpenDoors
from another source. Note that the medium and compact memory
model libraries are now distributed separately from the main
OpenDoors package.
MISCALENEOUS FILES
FILE_ID.DIZ Description of the OpenDoors package
DORINFO1.DEF Sample door info file for testing programs
DOOR.CFG Sample OpenDoors configuration file
EXAMPLE PROGRAMS
EX_HELLO.C A simple program using OpenDoors
EX_CHAT.C Split-screen sysop chat program
EX_MUSIC.C Example of ANSI music in OpenDoors
EX_SKI.C Simple slalom skiing action game
EX_VOTE.C Example of an online voting program
VOTEDOS.EXE Compiled version of EX_VOTE.C - DOS version
VOTEWIN.EXE EX_VOTE.C compiled - Windows version
DTRON.EXE Free utility for running Win 95 doors
THE LIBRARY FILES
ODOORS.LIB DOS, Small memory model library
ODOORL.LIB DOS, Large memory model library
ODOORH.LIB DOS, Huge memory model library
ODOORW.LIB Win32 import library (Microsoft version)
ODOORS60.DLL The OpenDoors Win32 DLL
THE HEADER FILE
OPENDOOR.H OpenDoors header file
OPENDOORS DOCUMENATION
ORDER.TXT Easy-to-print order form
OPENDOOR.TXT OpenDoors programmer's manual (this file)
===============================================================================
OpenDoors 6.00 Manual End of Page 249
BBBBBB
BB BB
BB BB
BBBBBB
BB BB
BB BB
BBBBBB
-------------------------------------------------------------------------------
APPENDIX B - CHANGES FOR THIS VERSION
Since version 5.00, a lot of work has gone into OpenDoors. Many
months were spent cleaning up and restructuring the OpenDoors
code in a process that has touched nearly every line of the
OpenDoors code. As well as making the OpenDoors source code
easier to maintain, this has also involved making OpenDoors more
easily portable to 32-bit multithreaded platforms.
After this effort was completed, I began work on a Win32 port of
OpenDoors. The OpenDoors package now includes both DOS and Win32
versions of the library, giving you the option of developing for
one, the other, or both platforms. The Win32 version of
OpenDoors is highly multithreaded to give you the best possible
performance. With some exciting new BBS packages that are
designed specifically for Windows 95/NT in the works, the Win32
version of OpenDoors gives you a head start on developing
applications that will integrate smoothly with these new BBS
packages. Even if your programs will only be used with DOS-based
BBS packages, the Win32 version of OpenDoors allows you to take
advantage of the Windows 95 GUI, multithreading capabilities and
flat 32-bit memory model (no more DOS 64K limitations and
different memory models to worry about!). It also allows you to
access services that are only available to Windows based
programs, such as ODBC for easy database access, and MAPI for
email, fax and other messaging.
While this internal restructuring of OpenDoors and the Win32
port of the package would be enough alone to count as a major
new version, version 6.00 also includes many exciting new
features, enhancements and bug fixes:
- A new option, "silent mode", has been added. When operating
in silent mode, OpenDoor's local sysop interface is disabled,
so that no output is displayed on the local screen, and no
input is accepted from the local keyboard. Silent mode can be
activated by setting od_control.od_silent_mode = TRUE prior
to the first call to any OpenDoors function, or by specifying
-SILENT on the command-line (if od_parse_cmd_line() is used).
===============================================================================
OpenDoors 6.00 Manual End of Page 250
- OpenDoors now fully supports RTS/CTS flow control, which is
enabled by default. To disable the use of the RTS/CTS lines
for flow control, use od_control.od_com_flow_control.
- In version 5.00, the built-in serial I/O module would be
unable to initialize the serial port if the "Uses Serial
Ports" option was turned off in DesqView or other
multitasking environments. When this option is turned off,
multitasking environments typically remove the serial port
information from the BIOS data segment. However, it seems
that other serial I/O software commonly uses the default
address for each port if this information is not available
from the BIOS data area. OpenDoors 6.00 has been changed to
do the same thing.
- OpenDoors now provides a standard command-line processing
function, od_parse_cmd_line(). This function provides a one-
step method of adding support for many common command-line
options to your program. This function handles options such
as serial port information (including non-standard serial
port configurations), node number information, user
information, drop file and configuration file locations,
silent mode (turns off the local interface for efficiency and
privacy), one step local login without a drop file, and more.
For details, run the included example program (votedos.exe or
votewin.exe) with the -help command line option. The
od_parse_cmd_line() function is particularly helpful in
several situations:
- When your program is being used on a multi-node
system.
- Allows potential users to try your program in local
mode by just specifying -local on the command line.
- Allows door information to be specified on the
command line, rather than through a drop file, as
supported by some BBS systems
- Allows serial port handle to be directly passed to
the program under Windows-based BBS systems that
support this.
- Provides customizable command-line help (in a
window in the Win32 version of OpenDoors).
- A new function, od_sleep(), allows you to suspend program
execution for the specified number of milliseconds, releasing
time to other processes in a multitasking environment. A call
of od_sleep(0) will yield control to any other processes
without forcing program execution to be suspended if no other
processes are waiting.
- The sysop page timing mechanism has been reworked. By
default, od_control.od_okaytopage is set to PAGE_USE_HOURS,
only allowing the sysop to be paged during the paging hours
===============================================================================
OpenDoors 6.00 Manual End of Page 251
set by od_pagestartmin and od_pageendmin. Rather than
allowing the sysop to be paged at any time of the day or
night, the default now only permits sysop paging from 8:00am
to 10:00pm. Setting paging start and end time to the same
value now correctly permits paging 24 hours a day.
- OpenDoors now provides a multi-line editor function,
od_multiline_edit(). This editor allows the user to enter or
edit any information that spans multiple lines, such as email
messages or text files. The editor can be configured to
operate in full screen mode, or in any smaller area of the
screen that you specify. The editor is designed to be both
easy to use, and highly customizable.
- One new feature of OpenDoors 5.00 was somehow omitted from
the manual. Since version 5.00, it has been possible to set
the name of the drop file to use by including both a path and
filename in the od_control.info_path variable.
- All known inaccuracies and missing information from the
version 5.00 manual have been corrected.
- The example program, ex_chat.c, has been expanded to
demonstrate how OpenDoor's standard chat mode can be replaced
with the split-screen chat mode within your own programs.
- The multiple ex_vote?.c example files have been combined and
simplified into a single example program, as it was prior to
version 5.00.
- A memory leak in the od_popup_menu() function has been fixed.
- od_control.od_open_handle can be used to provide OpenDoors
with an already open serial port handle on platforms that
support it. Currently, this only applies to the Win32 version
of OpenDoors. If this variable is not set to a non-zero value
prior to calling the first OpenDoors function (other than
od_parse_cmd_line()), then OpenDoors proceeds normally,
opening the serial port itself, and closing the serial port
before exiting.
- A new switch, od_emu_simulate_modem, has been added to
od_control. When this is set to its default value of FALSE,
the OpenDoors terminal emulator displays at full speed, as it
has always done. However, when this flag is set to TRUE, the
emulation functions will display text at approximately the
same speed as it would be displayed when sent over the modem,
based on the current connect speed. This allows animations to
be displayed locally at the same speed as they would appear
on the remote system. This switch affects the following
functions:
od_disp_emu()
===============================================================================
OpenDoors 6.00 Manual End of Page 252
od_send_file()
od_hotkey_menu()
- OpenDoors now distinguishes between the serial port BPS rate
(od_control.baud) and the connection BPS (a new variable,
od_control.od_connect_speed). In situations where a separate
value is available for the connect speed (e.g., this caller
has connected at 14400 bps), OpenDoors will now display that
value on the status line. Currently, a separate connect speed
is only obtained from the DOOR.SYS drop file format.
- The latest versions of the QBBS EXITINFO.BBS drop file is now
supported.
- A new od_edit_str() flag, EDIT_FLAG_SHOW_SIZE, has been
added. By default, the fields shown by od_edit_str() are one
character larger than the number of characters that may be
entered. This is for esthetic reasons, so that the cursor
remains within the highlighted field, even after a full
string has been entered. However, you may prefer that the
highlighted area reflect the exact number of characters that
are permitted. This can be accomplished by setting
EDIT_FLAG_SHOW_SIZE.
- Tab characters ('\t') are now expanded on the local display.
- The new RemoteAccess 2.50 EXITINFO.BBS fields are now
supported. This has included the addition of the following
new od_control members: user_rip_ver, user_attrib3 and
system_last_handle.
- When operating in "forced automatic local" mode (where no
door information file used), OpenDoors now displays a window
in which in prompts for the user's name at startup time. This
new feature can be disabled by specifying the DIS_NAME_PROMPT
od_control.od_disable flag.
- The latest version of the SFDOORS.DAT drop file is now
supported. SFMAIN.DAT, SFSYSOP.DAT, SFFILE.DAT and
SFMESS.DAT, which are in the same format as SFDOORS.DAT, are
also now recognized.
- A new function, od_get_input(), allows you to easily handle
extended keys in your program, such as arrow keys, insert and
function keys.
- The OpenDoors configuration file system will now display an
error and exit the program if a particular configuration file
name has been specified, and that configuration file cannot
be found.
===============================================================================
OpenDoors 6.00 Manual End of Page 253
CCCC
CC CC
CC
CC
CC
CC CC
CCCC
-------------------------------------------------------------------------------
APPENDIX C - FUTURE VERSIONS
While I cannot make any promises about what features and changes
will be seen in future versions of OpenDoors, I would like to
take a moment to tell you a bit about some of the features you
can expect to see in future versions of OpenDoors
As you are probably already aware, OpenDoors is a constantly
evolving package. To help meet the needs of programmers working
with OpenDoors, nearly every idea and change that is made to the
package results from the suggestions and comments I receive from
the people using OpenDoors. For this reason, I will most likely
continue to produce new versions of OpenDoors for as long as
there is a demand and ideas for upgrades. There certainly is no
shortage of either of this right now.
Some of the features that I am considering for upcoming versions
of OpenDoors include:
-Telnet support.
- HTML support.
- Direct interfacing with new Windows 95/NT BBS packages.
- Further features to help writing multi-node door
programs.
-Direct interfacing with more BBS systems.
-Additional RIP graphics support, including possible
display of RIP images on local screen.
-Possible support for additional programming languages and
operating systems.
- Improvements to existing OpenDoors features, such as more
configuration file options, multiple log file formats,
and many smaller changes.
===============================================================================
OpenDoors 6.00 Manual End of Page 254
DDDDD
DD DD
DD DD
DD DD
DD DD
DD DD
DDDDD
-------------------------------------------------------------------------------
APPENDIX D - SPECIAL THANKS
There are many people who I would like to thank, for their
suggestions, ideas and assistance in making OpenDoors what it is
today. Among those I would like to thank are:
- Everyone who has registered OpenDoors.
- All those who participate in the OpenDoors conference,
who provide many suggestions, bug reports and words of
encouragement.
- Those who on the OpenDoors beta team. Thank-you for
putting up with the problems along the way. You have
certainly helped to make OpenDoors a better package. The
people who have helped to beta test OpenDoors 6.00 are:
Robert Bouman
Doug Crone
Greg Diener
Patrick Dixon
Joel Downer
Mike Fenton
Les Howie
Vince Jacobs
Scott Jibben
Dean Mills
Jimmy Rose
Jim Woodward
Timothy Ward
Mark Williams
- Last but not least, I would like to thank my wife, Pearl,
for her support during the long hours that it has taken
to put OpenDoors together.
===============================================================================
OpenDoors 6.00 Manual End of Page 255
GGGG
GG GG
GG
GG GGGG
GG GG
GG GG
GGGG
-------------------------------------------------------------------------------
GLOSSARY
ANSI ANSI is an acronym for "American National Standards Institute".
One of the standards approved by ANSI is a terminal display
protocol which allows (in this case), BBS software to perform
certain display functions such as changing the color of
displayed text, or moving the location of the cursor on the
screen. The majority, though not all, BBS users use terminal
software with ANSI capabilities. Any users that do not have
graphics display capabilities, will be using ASCII mode,
instead. The ANSI terminal protocol is sometimes referred to as
"ANSI graphics". It is graphic in the sense that it provides
more visual control than an ASCII TTY terminal does, but does
not imply any support for bit-mapped nor vector graphics.
Compare ASCII and AVATAR.
API API is an acronym for "Application Program(er) Interface". An
API is a set of well documented functions, variables and data
types that you can use to access certain services from your
program. When you write any C program that uses standard C
library functions such as fopen() or strcpy(), you are using a
sort of API. When you use OpenDoors functions such as
od_printf() or od_get_key(), you are using functions that are
part of the OpenDoors API. Operating systems provide their own
APIs that allow programs to gain access to operating system
features such as screen display, file I/O and communications.
The API provided by Microsoft Windows 95 and Windows NT is
called the Win32 API.
ASCII ASCII (pronounced "ass-key") is an acronym for "American
Standard Code for Information Interchange", and is a definition
of a set of 128 letters, number and symbols, which can be
displayed by computer systems. Also, when used within the domain
of BBS software, ASCII mode is often used to refer to the lack
of any more advanced display capabilities, such as ANSI or
AVATAR. When ASCII mode is used, characters can only be
displayed in standard Teletype (TTY) fashion, one after another.
Also, color and cursor positioning functions are not available
in ASCII mode. Compare ANSI and AVATAR.
===============================================================================
OpenDoors 6.00 Manual End of Page 256
AVATAR AVATAR is an acronym for "Advanced Video Attribute Terminal
Assembler and Recreator". AVATAR is a graphics display protocol,
similar to ANSI. Like ANSI-graphics, AVATAR graphics allow
functions such as cursor positioning, and color changing.
However, AVATAR also offers many capabilities not available from
ANSI, and performs the same functions as ANSI much more quickly.
AVATAR graphics is less common than both ANSI or ASCII, but is
becoming more popular as time goes by. Compare ASCII and ANSI.
BAUD "baud" or "baud rate" are generally used as a synonym for "BPS".
BPS BPS is an acronym for "Bits Per Second", and refers to the rate
at which data is being sent over a communications medium. There
are two important BPS rates which are relevant to OpenDoors. The
serial port BPS rate (also called the DCE rate) is the speed at
which the computer is communicating with the local modem. The
connect speed, on the other hand, is the speed at which the
local modem is communicating with the remote modem. The serial
port speed must be at least as fast as the connection speed.
Often the serial port speed will be locked at a fixed speed that
is higher than the fastest possible connection speed of the
modem. For example, the serial port might be locked at a speed
of 38400 BPS, while the modem could be connected at 28,800,
14,400 or slower speeds. OpenDoors usually needs to know the
serial port BPS rate in order to function correctly (as stored
in od_control.baud). Under certain situations, OpenDoors will
also be able to report the connection speed to you (as stored in
od_control.od_connect_speed), although OpenDoors does never
requires this information to operate.
BIT-MAPPED As with Boolean values, described below, bit mapped flags
FLAGS are used to indicate whether or not various conditions exist.
(For example, whether or not a certain setting is enabled, or
whether or not a particular event has occurred.) However, unlike
Boolean variables, a single bit-mapped flag represents more than
one of these TRUE/FALSE values. In fact, each bit (BInary
Digit), which makes of the variable can be used to represent a
separate TRUE/FALSE state. (ie, each bit maps to a particular
piece of information, and hence the term "Bit Map").
For an example of using bit-mapped flags, let us take a case of
a single "unsigned char" which contains three independent
TRUE/FALSE values. We will call this variable user_info, and it
will indicate whether or not a user has ANSI graphics, whether
or not the user has screen clearing turned on, and whether or
not the user has end-of-page "more" prompts enabled. Internally,
the bits of the user_info variable will be as follows:
===============================================================================
OpenDoors 6.00 Manual End of Page 257
Bit: 7 6 5 4 3 2 1 0
| | |
| | +--- ANSI Graphics
| +----- Screen Clearing
+------- More prompts
In this case, we will have three constants which we define in
order to simplify access to these bit-mapped flags, as follows:
#define ANSI_GRAPHICS 0x01
#define SCREEN_CLEARING 0x02
#define MORE_PROMPTS 0x04
Note that normally within OpenDoors, these constants will be
defined for you, and you will have no need to know what their
values are, nor in which bit which piece of information is
stored.
Using bit-mapped flags, you are able to set or clear any of the
individual flags, and check whether any of the flags are set,
using these simple methods: (Not that a set flag is the
equivalent of a Boolean value of "True", and a cleared flag is
the equivalent of a Boolean value of "False".)
Set Flag: variable |= FLAG_CONSTANT;
Clear Flag: variable &=~ FLAG_CONSTANT;
Test Flag: variable & FLAG_CONSTANT
Where "variable" is the name of the bit-mapped flag variable,
and "FLAG_CONSTANT" is the pre-defined constant for the
individual setting. To return to our example, you could turn on
the user's ANSI graphics setting by using the line:
user_info |= ANSI_GRAPHICS;
and to turn off screen clearing you would:
user_info &=~ ANSI_GRAPHICS;
To perform an action (such as waiting for the user to press
[Return]/[Enter]) only if "More" prompts are enabled, you would:
if(user_info & MORE_PROMPTS)
{
... /* Whatever you want */
}
===============================================================================
OpenDoors 6.00 Manual End of Page 258
BOOLEAN Many of the variables used within OpenDoors contain a
VALUES "Boolean Value". A Boolean value is a two-state variable, who's
states are referred to as "True" and "False'. If the variable
contains a value of "True", it indicates that a certain
condition is so, and if it contains a value of "False", it
indicates that the condition is not so. For example, a Boolean
variable "wait" might be used to indicate whether or not
OpenDoors should wait for the user to press a key, or continue
without waiting. In this case, a value of "True" would indicate
that OpenDoors should wait, and a value of "False" would
indicate that it should not wait.
Note that in the C programming language, there is no actual
Boolean variable type - usually a char or an int are used to
store Boolean values.
The constants TRUE and FALSE, as defined in the OPENDOOR.H file,
are used to represent the two states of a Boolean value. Thus,
to set a Boolean variable "wait" to the value of "True", you
would use this line:
wait=TRUE;
and to set the variable "wait" to "False", you would:
wait=FALSE;
However, you SHOULD NOT test whether a Boolean variable is
"True" or "False" by using the C compare (==) operator, as the
value "True" will not always be the same numerical value.
(Actually, the TRUE constant represents just one of many
possible numerical values for "True"). Instead, to perform an
action of the "wait" Boolean variable is "True", you would:
if(wait)
{
... /* Whatever you want */
}
and to perform an action if the "wait" Boolean variable is
"False', you would:
if(!wait)
{
... /* Whatever you want */
}
For interest sake, Boolean values are named after the 19th
century English mathematician, who studied formal logic, and
created Boolean algebra - an algebra which deals with TRUE and
FALSE values.
===============================================================================
OpenDoors 6.00 Manual End of Page 259
BPS BPS is an acronym for "Bits Per Second". For our purposes here,
the terms BPS and BAUD refer to the same thing.
CARRIER The term "Carrier" or "Carrier Detect" refers to a signal which
DETECT most modems send to the computer, which indicates whether or not
the modem is currently connected to (communicating with) another
modem. The door driver module of OpenDoors, as with most other
BBS software, uses the status of this carrier detect signal in
order to know whether the user is still connected to the BBS
computer. Thus, if the user hangs up, or if something goes wrong
and the connection is lost, OpenDoors is able to detect this
state, and exit to the BBS. The BBS will then also detect that
the carrier signal has been "lost", and will reset itself, and
then again be ready to accept calls.
CHAT MODE The term "chat mode" refers to a means by which the sysop can
communicate with a user of the BBS / door. During sysop chat,
anything typed by the sysop will appear on the user's screen,
and likewise, anything typed by the user will appear on the
sysop's screen. Sysop chatting is available on both single and
multi-line systems. Sysop chatting is initiated by the sysop,
either at any time a user is online, or specifically in response
to a sysop page.
COMPILE "Compiling" refers to the process of converting the source code
that you write for your program, into an executable file (such
as a .EXE file) that an end user can use. The process of
building an executable file is generally divided into two
stages. In the first stage, called compiling, source files are
converted to object files, often named .OBJ. In the second
stage, called linking, one or more object files are combined,
along with any library files, to produce the final executable
file.
DLL DLL is an acronym for "Dynamic Link Library". A dynamic link
library is similar to a static library, in that it contains one
or more functions that an application program can use. Unlike a
static library, the code from a dynamic link library is not
added to the program's executable file at link time. Instead,
the dynamic link library exists as a separate file which must be
loaded when the program is run. The Win32 version of OpenDoors
resides in a DLL.
See also "Library".
===============================================================================
OpenDoors 6.00 Manual End of Page 260
DOOR A "door" is a program that runs as part of a BBS system, but
which is separate from the central BBS software (RemoteAccess,
Maximus, QuickBBS, PC-Board, etc.) itself. A door provides
additional features not built into the BBS software, such as on-
line games, on-line shopping services, voting booths, match
making systems, access to special files or messages, and much
much more. Since the user also communicates with the door
online, as they do with the BBS, it may not necessarily be
obvious to the user that the door is even a separate entity from
the central BBS software itself.
DOOR Also referred to as a "drop file", "exit file", or "chain
INFORMATION file". The door information file is a file passed from the
FILE central BBS software to a door program, providing it with
information about the user who is online, the BBS the door is
running under, and the current modem connection. The door
information file may also be used to pass changed information
back to the BBS, such as the amount of time that the user has
used in the door. OpenDoors takes care of all of the work
involved in reading and writing the door information file for
you, as described in the "Basics of Door Programming" section,
in chapter 4. Examples of door information files supported by
OpenDoors include: DOOR.SYS, EXITINFO.BBS, DORINFO?.DAT,
SFDOORS.DAT, CALLINFO.BBS and CHAIN.TXT.
DTR DTR is an acronym for "Data Terminal Ready". This is a signal
that the computer sends to the modem, indicating that the
computer is ready to send or receive information. Most modems
are configured to hangup if the DTR signal is lowered. This is a
convenient means of hanging up the modem, but cases problems
under Windows 95, where the DTR signal is always lowered when a
program closes the serial port.
ECHO See "Local Echo".
FOSSIL The FOSSIL driver, or simply FOSSIL, is a TSR program or
DRIVER device driver which OpenDoors can optionally make use of in
order to communicate with the modem. The FOSSIL driver is loaded
prior to starting up the BBS or your door, usually from the
AUTOEXEC.BAT or CONFIG.SYS files. The two most commonly used
FOSSIL drivers are X00 and BNU. (FOSSIL is an acronym for
"Fido/Opus/SEAdog Standard Interface Layer", although it has now
become the standard for nearly all BBS software.) FOSSIL drivers
are also available for other specialized serial port hardware,
such as the popular "DigiBoard" multi-port serial card.
IMPORT LIBRARY See "Library".
===============================================================================
OpenDoors 6.00 Manual End of Page 261
LIBRARY A "library" or "library file" is a collection of precompiled
functions and variables that can be used by other programs. All
of the features, capabilities and functions of OpenDoors that
you can make use of are contained within the OpenDoors library
files. (Likewise, the C runtime library, consisting of the
familiar functions such as fopen(), printf() and atoi(), is also
contained within a library file.) For more information on the
different OpenDoors library files, see the section that begins
on page 22.
There are several different kinds of library files. A static
library file is actually a collection of individual object
files. When you compile a program that makes use of a static
library file, only those portions of the library file that your
program actually uses are linked into your program's executable
(.EXE) file. Static library files can be identified by a .LIB
extension. The DOS version of OpenDoors resides in a static
library.
A dynamic link library, on the other hand, is not combined with
the program's executable file. Instead dynamic link libraries
exist in separate .DLL files that must also be present when the
program is executed. The Win32 version of OpenDoors resides in a
dynamic link library.
An import library is a small file that describes a dynamic link
library. The most common way for a program to call functions in
a dynamic link library requires that an import library be used a
program link time.
See also "DLL".
LINK "Linking" generally refers to the process of combining several
object files into a final executable file, during which
references to symbol names (such as od_printf()) are resolved to
the address of the corresponding object. See also "Compiling".
LOCAL MODE The term "local mode" refers to a mode in which a BBS system or
door program may operate. In local mode, the BBS/door behave as
they would if a user were connected via modem to the BBS, except
that all display and input is done simply on the BBS software,
but not through the modem. Local mode allows the sysop or
another person with direct access to the BBS computer to use the
BBS/door software, either for their own user, or for testing
that the software is running correctly. When programming door
software, local mode can be very useful in testing and debugging
the door, without requiring the door to be connected to a remote
system. All doors written with OpenDoors automatically support
local mode operation. Compare "Remote".
===============================================================================
OpenDoors 6.00 Manual End of Page 262
LOCAL ECHO The term "Local Echo" refers to a door displaying the same
characters which are sent to the modem on the local screen
("Output Window"). This allows the sysop to view the same
information that is sent to the user's system, in the same
manner that it will appear on the user's screen.
LOCKED (eg. "Locked Baud Rate", "Locked BPS Rate", "Locked Commport
Speed", etc.) Usually, the communication port to which a modem
is connected is set to transfer data at the same BPS rate as the
rate at which the modem is communicating. However, many high
speed modems allow very high speed data transfer by using built-
in data compression methods. In this case, the actual rate of
data transfer can easily exceed the true BPS rate of the
connection. As a result, the BPS rate of the port is kept a
single speed, faster than any of the true modem connections, in
order to increase modem speed performance. This is referred to
as locking the commport BPS rate. OpenDoors has full support for
the use of locked BPS rates.
LOG FILE A log file is a normal text file in which BBS software records
all major activities that have taken place. As such, the log
file permits the sysop, to review what activities have taken
place on the BBS during the time which they have been away from
the computer. A log file can be helpful in identifying system
errors or crashes that have occurred, in alerting the sysop in
the case that any users have been causing problems on the BBS,
or in simply letting the sysop know who has called recently, and
what when they did when they called.
MEMORY MODEL C and C++ programs can be compiled under a variety of different
memory models. Each memory model describes how data and program
code are addressed in memory. When writing MS-DOS programs, you
generally have the choice of six different memory models (named
tiny, small, compact, medium, large and huge), each of which
provides a different combination of the maximum sizes of data
and code that your program may have. When writing Win32
programs, there is a single, flat 32-bit memory model that all
programs use. This memory model allows a program to address (in
theory) up to 4 gigabytes of data and code.
MODEM A device connected to a computer which permits it to communicate
with other computers, usually over standard telephone lines.
===============================================================================
OpenDoors 6.00 Manual End of Page 263
OBJECT FILE An object file contains the compiled version of a source code
file of a program. The source code file may be a .C file, .CPP
file, .ASM file, .PAS file, .BAS file, or any number of other
extensions associated with other programming languages. When any
of these language's source code files are compiled, a .OBJ file
is created containing information such as the executable code,
and names of symbols (variables and functions) that are to be
shared with other .OBJ files. In order to produce a .EXE file
that may be executed, a process known as linking must be
performed. During the link process, one or more object files
composing your program are combined, along with the necessary
code from any library files being used, in order to produce the
final .EXE file.
ONLINE In the case of BBS software and BBS door programs, the term
online refers to the state of a user using the BBS. Usually, the
user will be connected to the BBS from a remote location, using
a modem. However, it is also possible that the user will be
using the actual BBS computer, with the software operating in
"local mode".
OUTPUT WINDOW The local screen of the BBS on which BBS software is running is
usually divided into two sections. At the bottom of the screen,
there is often a one or two line status line, which displays
information to the sysop about the BBS and the user who is
currently online. The rest of the screen is usually an "output
window", in which the information which is being displayed to
the user, is also displayed on the local screen. In some cases,
there will be no status line, in which case the entire screen
will be the output window. Usually, the upper 23 lines of the
screen in an OpenDoors door will be the output window, with the
bottom two lines being the status line. However, it is possible
to disable the OpenDoors status line, in which case the entire
screen will be the output window. See also "Status Line"
PAGE See "SYSOP PAGE"
PARAMETER In the C programming language, many tasks are accomplished by
calling functions. When a function is called, one or more pieces
of information may be passed to a function, in the form of
parameters. For example, a function used to set the foreground
and background color of displayed text might accept two
parameters, one for each of the two color settings. In this
example, a function such as od_set_color(), would be called as
follows:
od_set_color(D_GREEN,D_RED);
===============================================================================
OpenDoors 6.00 Manual End of Page 264
In this case, D_GREEN, the foreground color, is the first
parameter, and D_RED, the background color, is the second
parameter.
In C, parameters are enclosed in parentheses, ( and ), which are
located after the name of the function to be called. Each
parameter is then separated by a comma character. If a function
does not accept any parameters, the parentheses will have
nothing between them. (ie. od_clr_scr() ).
REGISTRATION This is a demonstration version of OpenDoors, which may only be
used under limited circumstances, for a limited period of time.
If you wish to continue using OpenDoors after this "evaluation
period", you must "register" it. For more information on
registering OpenDoors, please see chapter 2 of this manual.
REMOTE When used in reference to BBS software or door programs, the
term remote is used to refer to a user or computer that is
communicating with the BBS, for a distant location, by use of a
modem. Compare "Local Mode"
RIP "RIP", "RIPScrip" or "Remote Imaging Protocol" is a popular
graphical terminal standard that is used with BBS systems.
Unlike other terminal emulation standards, such as the ANSI and
AVATAR modes supported by OpenDoors, RIP operates in bit mapped
graphics mode, allowing features such as lines, circles and
icons to be drawn on the remote screen. OpenDoors provides
support for RIP graphics, although OpenDoors operates in text
mode itself.
STATUS LINE Usually, the bottom two lines of the screen, as displayed by an
OpenDoors door, is devoted to a status line (although this
status line may be turned off). This status line will display
information about the user who is online, along with information
about the current state of the BBS system, and a reference to
the sysop function keys. See also "Local Window".
SYSOP The term sysop is a short-form for "SYStem OPerator", and refers
to the individual who is responsible for running and maintaining
the BBS system. The sysop is usually the only person who has
direct access to the local keyboard and computer on which the
BBS, BBS utilities and BBS doors are running.
SYSOP CHAT See "CHAT MODE".
===============================================================================
OpenDoors 6.00 Manual End of Page 265
SOURCE CODE The term "source code" refers to the original file or files that
where used to produce a library or executable program. The
source code files contain the language statements or commands
that are directly written by the programmer. These source code
files are then compiled to produce an executable file that may
be "run".
SYSOP PAGE Sysop paging refers to the process whereby a user of the BBS
system may call or page for the sysop's attention, when they
wish to "chat" with the sysop, and can be thought of as being
similar to the ringing of a telephone. When a user pages the
sysop, the BBS system will produce some sort of sound, which the
sysop may elect to respond to if they are within hearing range
of the computer. The most common reasons for a user to page a
sysop include the case that they are having difficulty with some
aspect of the BBS, that they have a question, or if they are
simply interested in having a friendly conversation with the
sysop. Obviously, since the sysop may not wish to be disturbed
by users paging at certain times (such as when they are in bed),
most BBS software provides controls to allow you to control
paging. These features might include the ability to set hours
for each day of the week during which paging will be permitted,
and the ability to temporarily override the ability of some or
all callers to page the sysop.
USER When applied to computers in general, the term user simply
refers to any person using the computer hardware and software.
However, when applied particularly to BBSes, the term user
refers specifically to a person who calls the BBS, to carry out
activities such as communicating via messages or chatting,
uploading and downloading files, or using doors. Often, the term
user is used in contrast with the term sysop. In this case,
users are all of the people who call and user the BBS, other
than the sysop themselves.
WIN32 Win32 is the name of the API that programs written to run under
Microsoft Windows 95 and Microsoft Windows NT use to access
operating system services. Win32 programs use a flat, 32-bit
memory model and have access to advanced operating system
services such as multithreading. Win32 programs cannot run under
DOS nor OS/2. While some Win32 programs can run under Windows
3.x using the Win32s system, OpenDoors cannot since it requires
multithreading services that are not provided by Win32s.
===============================================================================
OpenDoors 6.00 Manual End of Page 266
IIIIII
II
II
II
II
II
IIIIII
-------------------------------------------------------------------------------
INDEX
A D
About This Manual ..................21 Debugging 21, 241
Access Level ......................178 Demo Version........................9
Alias .............................170 Display Functions..............42, 63
ANSI Graphics Displaying Text....30, 41, 42, 60, 62
Archive Contents ..................248 Door Driver Functions..............40
ASCII Chart ........................86 Door Driver Module..............6, 40
ASCII Mode ........................255 Door Functions.....................45
AVATAR Graphics ....118, 134, 167, 256 Door Information File30, 33, 150, 158
Door Settings.....................182
B DORINFOx.DEF File..................33
DOS Shell.........................192
Baud Rate .........................154 Download Limit....................169
BBS Information ...................158
BBS Name ..........................164 E
BBS Systems ........................30
Before Exit Function ..............191 Error Free Connection.............170
Box Characters ...............185, 191 Example Program - Changing Only
BPS Rate ..........................154 Foreground/Background Colour ....132
Built-In Function Keys ............212 Example Program - Choosing Text
Colour ..........................129
C Example Program - Clearing A Line..56
Example Program - Dialog Box.......66
Caller Information ................158 Example Program - Door And Utility In
Carrier Detect .................51, 97 One Program ......................92
Chat ..........................38, 104 Example Program - Drawing A Window118
Chat Mode ....................104, 259 Example Program - Exiting A Door...79
Colour Attribute Codes ............128 Example Program - First Door.......29
Colour Constants ..................132 Example Program - Hanging Up In CBV
Colour Customization215, 229, 232, 236 Door .............................51
Colour Functions ...................42 Example Program - Hotkeyed Menu....91
Colours .................110, 128, 131 Example Program - Input Key.......115
Common Problems ...................243 Example Program - Setting Door Info
Compiler Errors ...................243 File Location ...................150
Compiling With OpenDoors ...........22 Example Program - Shelling To DOS.141
Custom Function Keys ..............213 Example Program - Terminal Emu.....62
Example Program - Testing Available
Door Information ................158
===============================================================================
OpenDoors 6.00 Manual End of Page 267
Example Program - Testing Screen M
Clearing Capabilities 57
Example Program - Transferring A File Memory Models..................23, 24
Using DSZ........................142 Memory Swapping...................209
Example Program - User Statistics Modem Port........................157
Door.............................113 Modem Settings....................153
Example Program - Vote .............33
Example Program - Waiting For CR ...54 N
Exiting A Door Program .............79
New Version.......................249
F Node Number.......................152
Features ............................6 O
Feedback Form ......................19
File Display Functions .............44 Object File.......................263
FILES.BBS File .....................98 od_autodetect() Function...........48
Fossil Driver .....................260 od_carrier() Function..............51
FOSSIL port .......................157 od_chat() Function.................50
Function Keys .................97, 211 od_clear_keybuffer() Function......53
Future Versions ...................253 od_clr_line() Function.............55
od_clr_scr() Function.........57, 243
G od_colour_config() Function........59
od_control Structure..........31, 148
Getting In Touch With Us ..........246 od_disable Variable...............198
Graphics Mode ...........165, 167, 255 od_disp() Function.................60
od_disp_emu() Function.............62
H od_disp_str() Function.............63
od_draw_box() Function.............65
History ...........................249 od_edit_str() Function.............68
Hotkeys ............................90 od_exit() Function...31, 79, 191, 195
od_get_answer() Function...........81
I od_get_input() Function............82
od_get_key() Function......30, 53, 85
IBM Colour Attribute Codes ........128 od_gettext() Function..............89
IEMSI Session Information .........161 od_hotkey_menu() Function..........90
Inactivity Timeout ......199, 200, 202 od_init() Function.............31, 92
Input Functions ............44, 81, 85 od_input_str() Function........53, 95
od_kernal() Function...............31
K od_kernel() Function...............97
od_list_files() Function...........98
Keyboard Buffer ...........53, 97, 115 od_log_write() Function...........100
Keys ...............................97 od_multiline_edit() Function......101
od_page() Function...........104, 207
L od_parse_cmd_line() Function......105
od_popup_menu() Function..........107
Language Customization ............216 od_printf() Function.....29, 110, 195
Learning OpenDoors .................29 od_putch() Function...............115
Library ...........................261 od_puttext() Function.............116
LIBrary Files ......................24 od_repeat() Function..............118
Line Number .......................152 od_restore_screen() Function......120
Linking ............................23 od_save_screen() Function.........121
Local Mode ...............33, 200, 261 od_scroll() Function..............123
Locked ............................262 od_send_file() Function...........124
od_set_attrib() Function..........128
===============================================================================
OpenDoors 6.00 Manual End of Page 268
od_set_color() Function ...........131 Solutions To Problems.............243
od_set_cursor() Function ..........134 Source Code................10, 17, 20
od_set_dtr() Function .............135 Special Thanks....................254
od_set_personality() Function .....136 Status Line...104, 137, 209, 210, 264
od_set_statusline() Function ......137 Stop Key..........................203
od_sleep() Function ...............139 Support...........................244
od_spawn Function .................208 Support BBS.............244, 245, 246
od_spawn() Function ...............141 Swapping..........................209
od_spawnvpe() Function ............143 Sysop Chat...............38, 104, 192
od_window_create() Function .......145 Sysop Function Keys...............211
od_window_remove() Function ..147, 148 Sysop Keys.........................97
OPENDOOR.H File ............22, 29, 34 Sysop Name........................164
OpenDoors BBS ................244, 245 Sysop Next Setting................184
OpenDoors Customization ...........187 Sysop Page........................207
OPENDOORS Echo ....................245 Sysop Paging.................104, 265
OpenDoors History .................249 System Event......................162
Our Address .......................246 System Name.......................164
Output Functions ...................42
Output Window .................34, 263 T
P Terminal Emulator........62, 124, 125
Terminal Emulator Control Codes...126
Paging Hours .................182, 183 Text Customization................216
Paging The Sysop ..................104 Thank-yous........................254
Pause Key .........................203 Time Left.........................179
Phone Number ......................171 Timeout............................97
Printing ..30, 41, 60-63, 90, 110, 115 Troubleshooting....................21
Printing Manual ....................22
Problems ...........................21 U
Product Support ...................244
Project Files ......................23 User Handle (Alias)...............170
User Information..................158
R User Keyboard Off Key..............53
User Keyboard Setting.............184
Registration ..9, 10, 12, 18, 246, 264 User Name.........................174
Registration Form ..............15, 18 User Password.....................176
RIP ...............................264 User Timeout.......................97
RIPScrip ..........................264
V
S
Version History...................249
Screen Functions ...................42
Screen Length .....................177 W
Screen Width ......................178
Security Level ....................178 Want-Chat Setting.................180
Setting Colours .........110, 128, 131
===============================================================================
OpenDoors 6.00 Manual End of Page 269
Reference in New Issue Copy Permalink