Category : BBS Programs+Doors
Archive   : TNCDR106.ZIP
Filename : TNC-DOOR.DOC

TNC-DOOR Documentation May 30, 1992 V1.06
--- ---- -------------

I. REGISTRATION

TNC-DOOR is SHAREWARE. This software is FULLY FUNCTIONAL in every way.
This is not "cripple-ware" or any other such nastiness. However,
TNC-DOOR is not FREE. You are permitted to use this software for thirty
days following the day on which you obtained it. If you decide that
TNC-DOOR is something that you want to continue using, REGISTER the
software by doing ths following:

Send a check or money order for TWENTY DOLLARS (U.S.) to:

Vincent Quaresima, K2NE | PLEASE NOTE THE NEW
332 Ridge Road | ADDRESS EFFECTIVE
Browns Mills, New Jersey 08015 | MAY 28, 1992!!

This is a one-time LIFETIME registration, which will entitle you to the
use of any future upgrade of the TNC-DOOR. Upon receipt of your registration
you will get a disk containing the latest version of the TNC-DOOR, along
with any updates to this documentation file. Please specify DISK SIZE and
FORMAT (360K, 1.2 meg and 1.44 meg, 3.5 inch or 5.25 inch) when you register.

THIS SOFTWARE IS NOT FOR USE IN COMMERCIAL INSTALLATIONS. Such use will be
construed as a VIOLATION of COPYRIGHT. It is illegal in the United States
to use Amateur Radio for commercial purposes. Please obey the law!

When you register TNC DOOR you will receive a REGISTRATION CODE NUMBER
by return mail. Along with this number, you will also receive detailed
instructions on how to REGISTER YOUR COPY of TNC-DOOR on your hard-disk.
REGISTRATION will eliminate those "Remember to REGISTER" announcements
and will also eliminate the "UNREGISTERED EVALUATION COPY" message
that appears to your online user and replace it with a "kinder,
gentler" sign-on note!

PLEASE NOTE: ALL functions of TNC DOOR are available during your 30 day
evaluation period. I truly want to continue this policy, but it all
depends on the willingness of you folks to REGISTER this work.


II. WHAT YOU SHOULD FIND IN TNCDRxxx.ZIP

a) The "xxx" in the filename corresponds to the version/release
number. For example, V1.06 would be TNCDR106.ZIP, etc.
b) The file TNC-DOOR.EXE is the actual software.
c) The file TNC-DOOR.DOC is this file you are reading right now.
d) REGISTER.TNC is a "self-mailer" registration sheet. Print it
on your printer in standard 80-col. mode for an "instant mailer."
e) A file called TNCPARMS.TXT which is explained later on in this
documentation file.
f) A brief READ.ME file which may contain special information.

IF YOU ARE A FIDONET SYSOP and you obtained your TNC-DOOR package
by File Requesting it, then you may have received a ZIPfile not
conforming to this "version naming convention." For example,
you can always F'req the latest version from Jersey Devil Citadel
at FIDO 1:266/33 by using the "magic name" TNC-DOOR, in which case
the FIDO mailer will send you TNC-DOOR.ZIP. I always make sure that
TNC-DOOR.ZIP is the most current version, but other sysops may not
be so careful.






III. HOW TO SET IT UP

a) Make a directory from which this door will run. The name of the
directory is NOT IMPORTANT.

b) Using an ordinary ASCII text editor, create a file called
HAMUSERS.DAT, which goes in this directory. The format of the
file is simple but CRITICAL.

1st line: YOUR CALLSIGN
2nd line: NAME OF FIRST AUTHORIZED USER
3rd line: HIS CALLSIGN
4th line: NAME OF NEXT AUTHORIZED USER
5th line: HIS CALLSIGN

ETC.

A sample file follows:

K2NE
vince quaresima
K2NE-1
terry rossi
N2LQH
brian riley
KA2BQE
jerry devine
KA2RRK
LAST ONE

IT IS VERY IMPORTANT THAT THERE BE NOTHING AFTER THE LAST LINE OF THE
FILE. THE LAST LINE OF THE FILE MUST BE TERMINATED WITH A CARRIAGE
RETURN! As you can see from the example, the names and callsigns are
NOT "case sensitive." The exception is the "LAST ONE" used as the
last line of the file. This is used by the software as a redundant
method to prevent reading beyond the end of the file.

If your BBS online user's name is in this file then he is an authorized
user of the TNC-DOOR. If not, he isn't and he will get a message
telling him to contact you if he believes he is qualified to use the
door. A user whose name is not in this file WILL NOT BE ABLE TO
ACCESS YOUR TNC!

When an authorized user elects to run the TNC-DOOR, the software will
check for his name, and match this to his ham call, and will issue a
MYCALL to your TNC using HIS call. That way, what he does "on the air"
will be his responsibility!

When the user ends his packet session, another MYCALL is issued to the
TNC setting it back to YOUR call (which appears on the first line of
HAMUSERS.DAT).

c) Use whatever is required to "tell your BBS" about the door. This varies
depending on your BBS software, so there is no point in going through
it here. Check your BBS documentation for assistance on this point.
You should be glad to know that the TNC-DOOR will automatically
recognize DORINFO1.DEF when it finds it IN the "TNC-DOOR" directory.
Use whatever "batch file magic" is needed to copy the DORINFO file that
your BBS generates into the TNC-DOOR's directory. If you are running
your BBS on something other than COM1 (and hence generating DORINFO2.DEF
or DORINFO3.DEF, etc.) then simply rename as you move it.





The TNC-DOOR will also recognize (and use) CTDLDOOR.DAT in place of
a DORINFO#.DEF file if it finds it. Thus, this software should be
compatible with RBBS, any other BBS generating a DORINFO#.DEF file,
Citadel:K2NE, any other BBS generating a Citadel:K2NE-compatible
CTDLDOOR.DAT file, or any other "door information" file that can be
modified to LOOK like either of those (yes, there are utilities out
there that will modify "door information files" to look like them!).


d) TNC-DOOR's COMMAND LINE PARAMETERS:

/? will show you the USAGE syntax. In general, you should set it up
like this:

TNC-DOOR bbs=1 tnc=2 tncbaud=2400 mycall=yourcall [local]

"bbs=1" tells the door that the BBS is on COM1. You may change this
to suit your situation.

"tnc=2" tells the door that the TNC is on COM2. You can change this.

"tncbaud=2400" tells the door that your TNC is communicating with
your computer at 2400 bps. You may change this. Allowable settings
are tncbaud=300, tncbaud=1200, tncbaud=2400, tncbaud=4800, and
tnc-baud=9600. NOTE THAT THIS HAS NOTHING TO DO WITH THE BAUDRATE
YOUR TNC USES WHILE TRANSMITTING "ON THE AIR." Some TNCs are more
efficient than others (meaning some TNCs are slow clunkers!). You
may have to fiddle with your TNCs baud setting (ABAUD is the command
on the KAM unit that was used for testing this software, yours may
differ so check your TNC instruction manual).

"local" tells the TNC DOOR that the "user" is on your keyboard
rather than on the BBS modem. See section VI below.

e) Grabbing control from your online user

You can terminate a user's TNC DOOR session by pressing CTRL D
or CTRL K from your system console. This can be done at ANY TIME
although common sense would dictate that there are times that
you should be patient and wait (while your user is in the
middle of typing a message to a packet BBS or something similar!).
When you do this, the TNC DOOR will type out a message to your user.
That message will be whatever you put in the file PRE-EMPT.TXT if you
create such a file. Otherwise, the message will be "Your TNC
session is being terminated by the Sysop."

f) OPTIONAL TNC Parameter Reset at end of session

Beginning with Version 1.06 TNC DOOR will look for a file called
TNCPARMS.DEF at the end of a packet session, whether by an online
caller or in the LOCAL mode. TNCPARMS.DEF should contain TNC
commands that are valid for YOUR TNC. Any line in TNCPARMS.DEF
that begins with a "#" symbol will be treated as a COMMENT line.
The file MUST END with a COMMENT LINE to make sure that the last
valid command is actually read by your TNC. A sample file called
TNCPARMS.TXT is included for your reference.

TNCPARMS.DEF is OPTIONAL. If you don't want to use this feature
simply do not create a TNCPARMS.DEF file.







g) OPTIONAL "Get TNC out of KISS mode before starting!"

Beginning with Version 1.06 TNC DOOR has the capability of
resetting your TNC from KISS to TERMINAL (AX.25) mode.

To use this, create a file called EXITKISS.DEF. TNC DOOR
simply checks for the existence of this file in the same
directory as the TNC DOOR program. The contents of the file
are absolutely irrelevant. If the file is there, TNC DOOR will
send the standard TCP/IP "leave KISS mode" command sequence
consisting of <$FF>. TNC DOOR will then wait
for your TNC to return to AX.25 command mode and when that
happens TNC DOOR will then issue a MYCALL to the TNC with
your online caller's callsign (or your own if in LOCAL mode).
This whole routine has shown signs of flakiness. The "kinks"
will be worked out of this, but for now just be "warned." If
your TNC tends toward being "finicky" this whole business just
might not work for you.

NOTE: As of this release, TNC DOOR is NOT "TCP/IP compliant."
While this may happen with a future release, it hasn't
happened yet! If you are running a TCP/IP system on
your TNC you are left to your own devices (for now).

Also - if your TNC is NOT being used in KISS mode, just
don't create EXITKISS.DEF. TNC DOOR runs just fine without
it, and it has only been added as a convenience for those
folks who use their TNC with any of the TCP/IP packages
"floating around out there" and who also want to use
the TNC DOOR. TNC DOOR is AX.25 stuff (for now). And
even if TCP/IP compliance is added later, AX.25 will
continue to be supported by the software.

h) STARTUP PROBLEMS, or "MYCALL isn't working correctly!"

Some folks have been reporting problems with their TNC "getting"
the initial MYCALL command that TNC DOOR sends in order to set the
callsign of the TNC to the callsign of the landline BBS user. These
problems can be prevented by setting MONITOR OFF on your TNC prior
to "making the decision" to use the TNC DOOR software on a regular
basis. If you fear that your user(s) are setting MONITOR ON while
using your TNC via the TNC DOOR, you can use the TNCPARMS.DEF option
discussed previously in order to reset this command after each use
of TNC DOOR.

i) How we Handle the Modem and the TNC:

IMPORTANT: TNC DOOR does NOT contain its own serial communications
routines. To use the TNC DOOR software you MUST have a FOSSIL
driver INSTALLED prior to running TNC-DOOR.EXE. Please consult
your FOSSIL documentation for instructions on how to set up your
FOSSIL for DUAL PORT OPERATION. They are all different!















IV. OPTIONAL FILES FOR YOUR USER

The following files are OPTIONAL. If they are present they will be used.
If they are not present, the system will chug right along!

a) APPLY.TXT - this is typed to your BBS user if he tries to access
the TNC-DOOR and is NOT in your HAMUSERS.DAT file.
b) TNC-HELP.TXT - this is typed to your user when he issues a CTRL I
command.
c) COMMANDS.TXT - this is typed to your user when he presses ? at any
time when your TNC is NOT CONNECTED to another packet
station. Note: this will create a problem if your TNC
does not support DCD and report DCD to your computer.
Please get back to me if this creates more hassles than
it is worth and I will either remove it or figure out
a better way of implementing it.
d) PRE-EMPT.TXT - this is the file that is typed to the user when you, as
Sysop, press CTRL D or CTRL K from your system console
keyboard. If this file is missing, a hard-coded message
is sent to the user instead. See above for more details.

In any case, you are left to your own creativity in writing these files.


V. The TNC logging file

The TNC-DOOR automatically creates (or appends if it already exists) a file
called TNC.LOG. This file will automatically record the date, time, username,
and amateur callsign of each user as the user begins his TNC-DOOR session.
This file can be read by pressing "!" while using TNC-DOOR (as long as the
TNC is not in a "connected" state).

WARNING: TNC.LOG will "grow without end" if you do not maintain it.
I recommend that you set up a weekly event in your main BBS
scheduler to back it up and then delete it so that TNC-DOOR
can restart it with a "fresh start." This can probably be
"stretched" to more than a week, depending on how active your
TNC-DOOR becomes (and how large a log file you are willing or
able to tolerate on your hard disk!). FCC regulations no longer
require a "written log of station activity" as in years past.
This facility is a "sentimental throwback" but some may find
it useful.

VI. The LOCAL mode (Packet Terminal Operation)

If you use the "local" parameter when activating TNC-DOOR, the following
happens:

1) The sysop callsign is grabbed from the command line rather than from
the HAMUSERS.DAT file.

2) The user's callsign is set to the same as the sysop's call.

3) The bbs= parameter is ignored since input will be expected from the
local console keyboard rather than from a user on a BBS modem.

4) TNC-DOOR will not check for any "door information file" since for
LOCAL use, none of the information which would be in such a file would
be needed. The software "knows" you are on the keyboard, and from the
setting of the MYCALL= parameter, the software "knows" who you are.







5) You can now directly access your TNC from the keyboard. Originally,
my intention was to provide a "very simple 'dumb' terminal" however,
like a good story, it "grew in the telling." The next few paragraphs
will explain to you exactly what terminal features are supported in this
release of the software. I am not guaranteeing that future versions
will add features, but...

6) You can CAPTURE your packet session to a disk file. To begin
the CAPTURE session, type CTRL B. You will be prompted for a filename
to call your CAPTURE file. The DEFAULT filename is TNCBUFF.TXT.
If you pick a file that already exists, your session will be APPENDED
to the existing file, even if it is the DEFAULT file. To end your
CAPTURE session, type CTRL B once again. It is a "toggle."

7) File "uploading" can be done by pressing CTRL F once you are connected
to another packet system (or another ham packet station). You will
be prompted for the filename to send. If it cannot be opened for sending
you will be informed of the error, otherwise the file will then IMMEDIATELY
be sent to your TNC for processing. XON/XOFF flow control is ACTIVE
while TNC DOOR is sending the file. You should set your TNCs "XFLOW"
parameter accordingly. TNC DOOR expects $11 and $13 for XON and XOFF
respectively. If your TNC can't be configured this way then you should
NOT use TNC DOOR for file-sending. Also, there is nothing in TNC DOOR
to "check" the file to be sure it only contains printable ASCII. Thus
you will have to resort to external means to "convert" binary files that
you may want to send to another packet station or packet BBS. Since you
are using a packet TNC, there is no error-checking in the software. You
can rely on AX.25 to handle that for you "automagically."

8) You can READ a file from your disk. To do this press CTRL R and the
TNC DOOR software will then prompt you for the name of the file you
want to read. While reading, press P or the SPACEBAR to pause the
display. Press any other key to resume the display. Press N or S
to abort the display and end the READ session.

9) To exit TNC-DOOR from the LOCAL mode, press CTRL D or CTRL K.

VII. CHATTING with your user

At the bottom of the screen (when the user is logged in) you will see
" toggles CHAT". Very simple. If you want to CHAT with your user,
press ESC and you put TNC-DOOR into a local chat mode. All TNC activity
will be IGNORED while in chat mode. To exit from chat mode back to the
TNC (release your user back to the packet session) just press ESC again.

This might be handy if you are a sysop that prefers being "polite" and
asking your user to exit the door "in person" rather than CTRL D or
CTRL K to simply send him a message and boot him back to the BBS.

Obviously, this would also be handy if you are running TNC-DOOR from
a system that does not support its own chat facility and you simply
want to "talk" to your user.

------------------------------------------------------------------------------












BUG FIXES and OTHER ADMINISTRIVIA:

a) Sometimes when there is "garbage" in the TNC buffer the MYCALL
parameter was not being properly set. This is fixed (V1.05).
b) TNC-to-HostComputer baudrate of 4800 Bps is now supported by the
"TNCBAUD=" command-line parameter. (V1.05).
c) Code handling the initial sending of MYCALL to the TNC tightened
to help "guarantee" that the TNC sees the command. See comments
in Section III.h for more information. (V1.06)

------------------------------------------------------------------------------

And that's about all there is to it! Please send any suggestions for
enhancements or improvements, along with any "bug reports" to:

Vincent Quaresima, K2NE | PLEASE NOTE THE NEW
332 Ridge Road | ADDRESS EFFECTIVE
Browns Mills, New Jersey 08015 | MAY 28, 1992!!

And PLEASE don't forget to REGISTER this software! Only by registering
do you help keep good and inexpensive software coming your way.

------------------------------------------------------------------------------

Acknowledgments:

My thanks to Jerry Devine, KA2RRK, who patiently tolerated the lengthy
testing sessions during the debugging of this software. Also, thanks go
to Gary Watts, N0OXV, for several valuable suggestions for improvement.
In addition, my thanks go to the many packet and landline sysops who
have passed messages concerning this software, and who have made copies
of this software available for online downloading.

------------------------------------------------------------------------------

TNC-DOOR is COPYRIGHT 1992 by Vince Quaresima, K2NE (t/a K2NE Software).
All rights are reserved. Uploading to electronic databases (free or
commercial) is both PERMITTED and ENCOURAGED. Swapping or giving the
software away is also permitted. You may NOT charge for this software
other than a minimal fee to cover the expense of duplicating your disk.

SHAREWARE VENDORS: You are asked to include this software in your collection
of programs. You are also authorized to sell this software at a price
NOT TO EXCEED FIVE DOLLARS (U.S. funds). Such a sale does NOT constitute
registration by the end user.