When you add a door to your bulletin board system you add functionality to your system. A door application can enable your users to play on-line games, access databases, and just about anything else you can imagine.

When a user opens a door they temporarily exit PCBoard and run a batch file called the door batch file. This batch file will then execute some other application – be it a game, utility or other program.

Usually the program that is being run is designed to be a door application, or is designed to accept input and output via the serial port so that the remote user can control the operation of the program. Programs that do not provide input and output through the serial port may not be able to run as a door unless you use a program like DOORWAY which redirects both text screen and keyboard i/o to the remote caller.

Probably the most popular type of door programs are games. However, there are utility type doors as well that may allow users to store additional time on the system, read off-line mail, etc. Virtually anything that communicates via a serial port can be considered a door application.

A door is nothing more than a program which is designed to communicate through the serial port rather than through normal means (i.e., the keyboard).

You may be asking yourself if there is anyway to run a non-door application as a door. You can but it means that you will have to have some sort of software that will monitor what is on the screen and output it to the remote users screen. DOORWAY by TriMark Engineering does exactly this. It will monitor any 80×25 text mode application and draw it on the remote users screen using ANSI codes. Using this program you could run virtually any text mode DOS application as a door.

For the most part most door applications are all character-mode based. That means that you cannot run Windows application or other graphical applications as a door. The primary reason you cannot run graphical applications as doors is because there is no standard way to send graphical data over the modem and have the majority of modem users be able to view that information.

If you load PCBSetup, and select a conference to edit you will see the following fields at the bottom of your display:

The two fields that relate to door operation are the following:

The following is a brief description of each of the files:

The number at the very left of each line is the door number. The rest of the fields are not always so intuitive. The following briefly describes each field in the DOORS.LST file:

With an auto-login door it will only open for the security level that is listed in the SEC field. If you want the door to open every time any user logs in, enter a security level of 0 in the sec field.

NOTE: If you have any conferences that are defined as auto-rejoin, be aware that if a user logged off of the BBS in one of these conferences, they will rejoin that conference on their next login. Consequently, you must make sure that the proper doors are defined in this conference because this is the conference that PCBoard will read the DOORS.LST from.

By far the easiest method to create or edit your DOOR batch files is while you are editing DOORS.LST. First of all you need to make sure that you have defined a text editor in System Manager. If you have, highlight the filename field in DOORS.LST and press 2. This will allow you to create or edit the batch file. If you want to edit the file manually, you will need to look at your entry in DOORS.LST to determine the name and location of the batch file.
The following is sample entry in DOORS.LST

                                   USER DOOR
  Filename    Password   Sec Login SYS  SYS  Shell    Path to DOOR Files
 ---------- ------------ --- ----- ---- ---- ----- --------------------- 
1) TESTDOOR                0   N    N    N     N   C:\PCB\DOORS\

      >                                                  >
      +-------------------------+                        >
                                                         >
                 C:\PCB\DOORS\TESTDOOR                   >
                       >                                 >
                       +---------------------------------+

You can see that PCBoard thinks that the DOOR batch file is C:\PCB\DOORS\TESTDOOR. Notice that there is no .BAT extension. Even though it sounds strange it will still execute properly.

If the door you are creating the batch file for has either an S or a Y in the Shell column, you do not need to add any lines to the batch file in order to return to PCBoard. Once the door batch file has completed, PCBoard will automatically reload.

If you answered N to the Shell column, you need to reload BOARD.BAT. The easiest way to do this is to add the following three lines to the end of your door batch file:

%PCBDRIVE%
CD %PCBDIR%
BOARD

These lines will first make sure that your system returns to the proper drive, then change to the proper directory to reload, and finally reload PCBoard using BOARD.BAT.

Debugging a door is an easy process. There are two commands designed for batch files that you may want to keep in mind – PAUSE, and ECHO ON. The PAUSE command can be used to delay further execution of the batch file. This is useful when trying to catch errors that might be displayed as your batch file is running. The pause command will ask you to strike a key when it runs. Therefore you could put a PAUSE command after every command until you find the offending line in the batch file.

In conjunction with the PAUSE command you can put a line that says ECHO ON at the beginning of the batch file. This will let you see each command of the batch file as it runs. This method is useful for checking to see if your environment variables are being correctly substituted, changing to the wrong directory, and for tracking other obvious errors.

Using these two commands together can really help you track down some of the problems you will incur as you are creating your door batch files. If you have used these techniques and you still are unable to track down the problem perhaps you should consider contacting the author of the door for further help.

This section discusses various techniques for installing door programs on a multi-node setup. All of the techniques in this section are designed to help save you time both in the present setup and in the future when you add more nodes. You may use these instructions for setting up door programs in a multitasking or network environment.

It is assumed that you already know how to setup a door under PCBoard. If you do not yet know how to setup a door please refer to the Creating a Door section. It is also assumed that you have a good grasp on how to create batch files and pass parameters inside of batch files.

You do not have to be a batch file wizard but you should be familiar with the following topics:

• What a batch file is
• How to create and edit a batch file
• Batch file commands (IF, GOTO, etc.)
• Using replaceable parameters in batch files (environment variables in particular)

If you are not familiar with batch files or any of the above topics, please consult your DOS manual's batch file section for more information.

Because door programs are written by different authors and the fact that there are so many door programs available, you will find that the methods required to setup a particular door program differ greatly. Some door authors may require you to pass specific information on the command line of the executable file while other door authors may store the information in a configuration file. Other door programs may use a combination of configuration files and command line parameters.

Because setting up door programs requires a comprehensive knowledge of creating batch files, setting up door programs in a multinode environment may prove tricky at first. However, your efforts will pay off in the long run especially if you plan on adding more nodes in the future. By using the methods discussed in this section you will learn how you will be able to use one batch file for each door on all of your nodes.

You can set up your system so that each node has a different DOORS.LST. However, this would mean that you would have to add your door configuration to each node rather than making the change on one node and spreading the change automatically through the entire system. It is strongly recommended that you stay with one single DOORS.LST for your entire system. See Using A Different DOORS.LST For Each Node for additional information.

The first step in setting up a door is to browse the documentation included with the door package. Look to see if the door requires any special hardware or software. If you are using a COM port other than COM1 or COM2, you should also check to see if the door will support non-standard COM port definitions. Likewise, if you are using the /M version of PCBoard, check and see if the program supports the FOSSIL interface. If the door program does not support your hardware configuration, you will not be able to run the door.

The next step is to install the door on your system as per the instructions provided by the author. If you have questions on the installation of the door, contact the author for further assistance.

Test the door program and make sure that it works on at least one node. Do not proceed until you have confirmed that the door operates properly.

If the door does not work correctly your best chance of getting the door program to operate correctly is to contact the author of the program directly since they know how their program functions. If the author of the program is no longer available, try contacting other SysOps to see if they might already have it up and running. The PCBoard technical support staff is very familiar with the PCBoard program but are not very familiar with the thousands of third party programs that are available for PCBoard.

Now that you know that the door works you should examine the batch file you use to run the door. When looking at this batch file you should search for anything that is specific to a particular node. Look at the following example:

C:
CD\DOORS\ABCGAME
ABCGAME C:\PCB\NODE2\
C:
CD\PCB
BOARD

Notice how this batch file explicitly uses C:\PCB\NODE2. This means that if you ran this door batch file on node 3, it would not work because the C:\PCB\NODE2\ is hard-coded into the batch file.

Not all of the node specific information is so easy to spot. Let's take a look at another example:

C:
CD\DOORS\NEATDOOR
NEATDOOR ND.CFG
C:
CD\PCB
BOARD

On the outside it appears this door does not reference any node-specific information. However, if you look in the configuration file for this door (ND.CFG) you will most likely find that it contains some node specific information. This node specific information might be where to find PCBOARD.SYS, DOOR.SYS, or even what serial port to use.

Once you have determined where the node specific information is, you will need to find a way around this problem so you can still use one batch file for all of your nodes. To help you with your door configuration, PCBoard will create four environment variables. They are as follows:

If you did not heed the previous warning regarding environment variables and how to use them in batch files, consult your DOS manual for that information at this time.

A batch file that does not use the environment variables PCBoard provides might look like the following:

C:
CD\DOORS\ABCGAME
ABCGAME C:\PCB\NODE2\
C:
CD\PCB
BOARD

The same batch file using the environment variables that PCBoard provides, would look like the following:

C:
CD\DOORS\ABCGAME
ABCGAME %PCBDRIVE%%PCBDIR%\
%PCBDRIVE%
CD %PCBDIR%
BOARD

The following describes each line in the above example. It will help you understand how and why the environment variable were used:

The variables (surrounded by % signs) will be replaced by the appropriate values as they are set for each node. At this point you may be asking yourself, if this makes my node configuration easier, why are the batch files larger? What you may not be aware of is that you can use this batch file for EVERY node in your system. This makes both your maintenance and system configuration less complex. A tradeoff that is well worth the results.

Consider the following two examples to really appreciate how using environment variables in your DOOR batch files can help you out:

• You add more nodes to your system.
• You change the location or delete the door from your system.

In the first example you do not really have to do anything to activate your new nodes on the system. In the second example, if you move the location of the door you only need to change the one batch file to reflect the new location (The first CD command in the batch file). Can you imagine running 19 nodes and having to change 19 different batch files? Having numerous batch files for one door also increases your chance of making a configuration mistake.

Some door programs use a configuration (config) file for normal operation. Some of these programs store node-specific information in these files. Remember, environment variables can only be used in the batch files themselves (i.e., not in config files). This may lead you to wonder how you can still use environment variables and create one batch file for all of your nodes. The answer is quite simple. Create multiple config files and then use the PCBNODE environment variable to load the proper one.

As an example lets say you have the following batch file:

C:
CD\DOORS\NEATDOOR
NEATDOOR ND.CFG
C:
CD\PCB
BOARD

Now, lets say in the ND.CFG file is the following:

C:\PCB\NODE3\PCBOARD.SYS    ;location of PCBOARD.SYS
5                           ;number of times game can be played per day
400                         ;points per win

If you could use environment variables in other files, the solution would be easy enough, you would replace the C:\PCB\NODE3\PCBOARD.SYS in the ND.CFG file to say %PCBDRIVE% %PCBDIR%\PCBOARD.SYS. However, you cannot do that because environment variables cannot be read in from configuration files. Therefore, you need another alternative.

At this point you need to create a configuration file for each node. You will want to come up with some sort of naming convention. Since the original config file was called ND.CFG you may want to simply tack on the node number to each config file (e.g. ND1.CFG, ND2.CFG, ND3.CFG). By naming them with the node numbers in the filename we will be able to use the PCBNODE environment variable. The most important thing to remember is that you should remain consistent in your naming conventions. If you do not, you will not be able to use environment variables.

Once you have created (or copied) a config file for each node you need to change the first line to reflect the location of the PCBOARD.SYS for each node. Next, you need to make the modification to the batch file. After you have added the environment variables, your batch file would look like this:

C:
CD\DOORS\NEATDOOR
NEATDOOR ND%PCBNODE%.CFG
%PCBDRIVE%
CD %PCBDIR%
BOARD

The following describes each line in the previous example:

And finally, a more complex batch file might look something like the following:

C:
CD\DOORS\PCBMAIL
PCBMAIL PCBM.CFG C:\PCB\NODE3\ /PORT:3E8:5
C:
CD \PCB\NODE2
BOARD

This batch file represents a door which points to a single config file which does not contain information specific to any node (maximum plays per day, points rewarded, etc.). Also passed on the command line is the location of this node and the final parameter passed on the command line is the base address and IRQ for the COM port (/PORT parameter).

Do not let the additional parameters worry you. Your goal should still be the same. Replace the node specific information with environment variables. What makes this problem just a little different is that PCBoard does not create environment variables for the base address and IRQ for COM port. However, you could easily enough create some environment variables in your BOARD.BAT file which would represent your base address and IRQ for each of your COM ports. If you wish to do this, add the following lines to your BOARD.BAT:

SET COMBASE=2f8
SET COMIRQ=5

Of course, your system may not use 2f8, with an IRQ of 5 so you should change that information to reflect your system configuration.

We have now assured ourselves that we have environment variables that we can use to replace all of the node specific information in the previous batch file we are ready to change the batch file. Your final batch file should resemble the following:

C:
CD\DOORS\PCBMAIL
PCBMAIL PCBM.CFG %PCBDRIVE%%PCBDIR%\ /PORT:%COMBASE%:%COMIRQ%
%PCBDRIVE%
CD %PCBDIR%
BOARD

One thing that you should note about the above batch file is that the door that was used for this example does use a configuration file called PCBM.CFG. However, this configuration file does not contain any node specific information and that is why we did not have to make any changes. All of the node specific information was passed on the command line therefore it would be pointless to create multiple configuration files. This batch is a little more difficult because it contains more node specific information on the command line. In reality however, the technique is the same as in the previous examples.

By now you should have noticed that for all intents and purposes most of the batch file looks the same, the only line that has changed is the line that calls the program. For the most part this is the way most of your door batch files will look. You will change to the directory where the door is located, run the program, change back to the PCBoard drive and directory, and finally reload the BBS.

Once you have replaced the node specific information with environment variables, you are now ready to test the door to make sure that, with the changes you have made, the door still works. If it works on one node, try it on another node and make sure everything still works correctly. As an extra precaution you should try it out on every node (especially when a door uses config files) to make sure that all nodes work correctly. If the door works correctly on all nodes, you have properly setup your door for use in a multi-node environment. If you have problems with any nodes, use the debugging information described previously to help locate the problem.

There are about as many ways to configure a door as there are door programs out there. The previous examples should be used to aid you in several of the more popular types of door configurations. Not all of the configurations could be covered in this section so remember that you may run into configurations that you may not recognize. If you do run into such a configuration identify the node specific information and use environment variables to create one batch file for all of your nodes

If you decided you do not want to go to the trouble of using environment variables in your door batch files, you can have each node use a different DOORS.LST file. By doing that, you can specify a different location for the door batch file. For example, instead of storing the batch file in C:\PCB\DOOR\, you may instead choose to locate the batch file in C:\PCB\DOOR\N1\ for node 1, and C:\PCB\DOOR\N2\ for node 2.

The problem with this type of setup though is that as the number of nodes on your system increases, the time it takes to change the batch files also increase. If you have two nodes you may only have to edit two batch files. However, if you have 20 nodes online then that means 20 files to edit and consequently more lost time.

If you decide that separate DOORS.LST files are the way for you, the setup can be accomplished very easily. Since all of your nodes likely share the same CNAMES file you can change the location of DOORS.LST to look like the following:

              Menu Listing                     Path/Name List File
Doors       : C:\PCB\GEN\DOORS             : DOORS.LST

Notice that only the filename DOORS.LST is in this field. That means that PCBoard will search the current directory to find the file instead of an absolute location like C:\PCB\GEN\DOORS.LST. Since you are in different directories on every node this means each node will have a DOORS.LST file in their default directory.

Because PCBoard creates DOOR.SYS and USERS.SYS before the door is run and deletes them when returning there may be some confusion as to where these files are created. These files will be located in the same location as PCBOARD.SYS for the nodes. The best way to determine the subdirectory is to log into that node locally and then press 5. The subdirectory you are in is the subdirectory where the files will be stored.

NOTE: This subdirectory is also the subdirectory that you were in when you loaded PCBOARD.EXE from. In addition, it is also the subdirectory that is specified by the PCBDRIVE and PCBDIR environment variables.

There are four methods with which a door may be opened via PCBoard:

• Using the OPEN command from the conference command prompt.
• Using the DOOR command from the conference command prompt.
• Typing the name of the door at the conference command prompt.
• If you are using an MNU file, one of your options in the MNU file can execute a door.

The third and forth methods provide the most interesting possibilities because you can make the door appear to be a more integrated function of your bulletin board system.

Any text that is entered after the door name or number will be passed as command line parameters. These command line parameters are available to the door application if they will read the PCBDOOR environment variable. If you open a door called MAIL by typing the following,

MAIL D;Y;G

PCBoard will store D;Y;G in the PCBDOOR environment variable. In order for the door to see these parameters, you will most likely have to modify the door batch file. For the MAIL door mentioned previously, the batch file may resemble the following:

@ECHO OFF
CD\DOORS\MAIL
MAIL
%PCBDRIVE%
CD %PCBDIR%
BOARD

You must only make one change to this batch file in order to pass the command line parameters to the door. The change you must make is the line that executes MAIL.

This line would change to read:

MAIL %PCBDOOR%

NOTE: For more information on accessing environment variables in batch files, please refer to your DOS manual.

When PCBoard returns from running a door, it will check to see if a file named PCBSTUFF.KBD exits in the current directory. If it does, the contents of this file will be stuffed into PCBoard's keyboard buffer.

Example

If you have a door which creates a file that you want to the user to download, you would want PCBoard to automatically download a specific filename. The first thing that you would need to do is to create a file that you want to stuff into the keyboard. For this example, the filename created by the door will be called DATA.ZIP.

In your PCBoard directory create a file named. DATA.STF. The contents of this file should be the following:

D;DATA.ZIP

The only change you will have to make to the door batch file is to add a line that will copy your DATA.STF file to the PCBSTUFF.KBD file. In your batch file, this line may appear as:

COPY C:\PCB\DATA.STF %PCBDRIVE%%PCBDIR%\PCBSTUFF.KBD

The %PCBDRIVE% and %PCBDIR% environment variables are used to insure the PCBSTUFF.KBD file is created in the proper directory. If it is not, PCBoard will not find it and nothing will be stuffed into the keyboard.

NOTE: Once the file has been read by PCBoard, it will be deleted.

When PCBoard returns from running a door, it will check to see if a file named PCBDOOR.TXT exists in the current directory. If it does, the contents of this file will be displayed on the local and remote screens.

Example

After you have installed a door, you may find it has a problem which will force you to take it temporarily off line. You could delete the definition of the door from the DOORS.LST file, but that will be more trouble than it is worth if you are taking it off-line temporarily.

Instead, try inserting a REM before each line in your door batch file except BOARD (if that line is in your door batch file). When you have done this, create a text file that you want to display to your callers. The next step is for you to add the following line to your door batch file (before BOARD (if that line exists in your batch file):

COPY C:\PCB\CLOSED.TXT %PCBDRIVE%%PCBDIR%\PCBDOOR.TXT

Assuming that you name you display file CLOSED.TXT and store it in C:\PCB, that file will be displayed to anyone who runs the door. What will happen is that DOS will skip all of the lines that begin with REM and then execute the line that you added to your batch file. Finally it will return to PCBoard which will find the PCBDOOR.TXT and display it on the screen.

NOTE: Once the file has been read by PCBoard, it will be deleted.

To disable doors in a particular conference, simply clear out the fields related to door configuration as shown in the following example:

              Menu Listing                     Path/Name List
File
Doors       :                              :

If you do this, when a user attempts to open a door they will be informed that no doors are presently available.

NOTE: Doors are always disabled for users who do not have established accounts on the system. The following lists the two possibilities for a user to not establish an account on your system:

The caller logged in as a new user on a node defined as a closed board and you have a NEWASK questionnaire defined.

A user calls for the first time. When asked if they want to register, they choose not to. In order for the user to remain online, you must give those that refuse to register a security level other than 0.

If doors are available in a conference, when a user types OPEN or DOOR from the conference command prompt they will be shown a file which lists all of the doors that are available on the system. This file is specified by the following field in the conference configuration:

              Menu Listing
Doors       : C:\PCB\GEN\DOORS

This file is commonly referred to as the DOORS file. You can edit this text file by pressing F2 or F3 as listed on the bottom of the screen. When you are creating this file, you should list either the door number or door name (filename in DOORS.LST) and a description of the door for your users. The user can open the door by typing the door name or door number.