BiModem - Developer's Toolkit

BiModem was designed to be as easy as possible to interface with both bulletin
boards and telecommunication programs. This tool kit should provide you with all
the information necessary to accomplish the interface task. An example of the
extent BiModem goes through to make it easy is the fact that it can maintain 3
different log formats. This gives you the ability to interface it quickly with
just a few modifications to your existing interfaces, and later interfacing it
more completely.

There are some common practices for both telecommunications and BBS developers
to keep in mind. BiModems configuration file is at your disposal to alter. The
preferred method is to read the existing one, alter only the fields you need to
alter, and write it back out. This allows the user to maintain additional
control by modifying the fields you aren't concerned with using BiConfig. It
also allows for future enhancements to BiModem to be installed with little
intervention by you. We will NOT alter the BiModem configuration file other than
adding new fields to the end, so make sure you don't truncate the record or new
features will be disabled.

Telecommunications interfaces

We will allow authors of telecommunications programs to freely distribute our
unregistered version of BiModem. We only require 2 things. You must indicate
that BiModem is a separate cost item, is included for your users trial
evaluation, and if they use BiModem on a regular basis they must register it
with us. The other requirement is that you let us know of your intentions to
distribute the unregistered version. This gives us the opportunity to put you on
our first line of support and make sure you receive the latest versions as soon
as we release to betas.

We have encountered a large number of telecommunications program developers that
want to make BiModem appear as an internal protocol. The major problem we are
faced with is that all of the other file transfer protocols are uni-directional
and do not allow chat. This means that the transfer screen that you are
currently using is not sufficient to make BiModem 100% internal. You can however
make it appear very close. What we suggest is that you allow BiModem to remain a
separate program and shell to it. There are a number of files that a
telecommunications program could update prior to shelling, and look at after
BiModem completes. We will start with the pre-shell set.

Prior to shelling to BiModem a telecommunication program, may want to modify
BiModem's configuration file. As a matter of fact 99% of the information in it
is probably already in your configuration information. For example: You may wish
to make BiModem appear as internal as possible, so you could change the color
table. This would make the BiModem screen(s) appear with a similar color scheme
to your software. Also important would be things like: sending directory,
receiving directory, baud rate, and comm port. Of course, everything in the
configuration file can be altered prior to shelling to BiModem, thus eliminating
the need to run our configuration program. Our intentions with future versions
is to NEVER change the format of our configuration file, except to add new items
to the end, if needed. You are free to modify anything in it and you can expect
future versions to continue to work.







Note: Our sending directory entry in the configuration file can point to an
ascii list of sending directories to be searched. We also plan to have the same
thing available for receiving directories, so that files received can be
earmarked for 1 of many destinations.

The next consideration is what files does the user want to send and receive.
Since bidirectional file transfer is a new concept to all telecommunications
programs and bulletin boards, this is another (make it appear 100% internal)

problem. How does the user hit both PgUp and PgDn to tell you what files to send
AND receive? We have provided a number of ways for you to tell us what files to
send and receive, but let me tell you about some of our plans first, so that you
can make an intelligent decision here. Currently, in our registered version, we
have 4 different ways for the user to specify requests. BiMark allows the user
to tag files from his/her disk. BiList allows users to tag files from a list
that they previously downloaded from a BBS. BiHot is a hot key program that can
be invoked while browsing through a BBS' file list online, to mark files to
download from the screen display. Then there is BiPath, which is available even
in the unregistered version, that allows users to simply enter the file names.
We hope to continually expand these techniques and eventually get to the point
of having a database file containing what files are available where. There are a
lot of directions you could go here. You could collect the file requests
yourself, and write them out to our file (see paths file layout). You can also
place a list of files after /u (upload) and /d (download) in the command line
when you shell to BiModem. Or you can write them out to separate ascii files and
give us the name of the files on the command line (/u @upload_file_path, /d
@download_file_path). The other way to go would be to shell to BiPath when it's
time for the user to enter file names. From your standpoint, this may be the
best approach. It could be set up so the user can specify what program to invoke
to collect the upload/download file paths. This would allow future database
forms of request collection to be hooked up with ease. The other consideration
is what direction will the BBS authors take. We are pushing for remotely
generated lists. This allows the user to build requests prior connection and
possibly save some phone line charges. Plus it opens up a new market for file
tracking applications.

Now it's time to shell. Please review our documentation on BiModem's command
line arguments. In addition to the transfer list path arguments, you may also
want to concern yourself with the /E parameter. This parameter allows the
specification of an escaped character. PCPursuit, for instance, uses an @C/R to
escape to the pad. Since files may contain @C/R's, it is a good idea not to send
them during the file transmission. You can inform BiModem not to send @'s by
passing the parameter /E64. Other networks may use different characters for the
same purpose. If your telecommunication program knows whether or not this is a
PCPursuit connection, then you can intelligently control escaped characters.
Otherwise you should probably escape it all the time. We made this an option so
that non-network connections could get that extra 4-5% throughput on their file
transfers. Another consideration before shelling would be whether or not you
need statistics information. We have 3 different methods of logging. Probably
the easiest one for you to use would be the DSZ log. It is produced if BiModem
sees a DSZLOG=Path entry in the environment. It is designed to conform to the
standard DSZ log and uses a B for received files, a b for files that were sent,
an E for received files that had a problem, and an e for files that were sent
and had a problem. The log you'll see referred to in the configuration file, is
designed to be a historical record of transfers easily visible to users. You may







not want to use this, because most of the information in it is in ascii form.
The third log was designed specifically for programmatic interface. All the
fields in it are in binary. The records and fields are fixed length. Plus it
contains a status field which is more specific about what the cause of a problem
was. It is also the only file that contains descriptions. This log is available
by passing a /^p log_file_path argument.

Currently we are having most users set up a hot key shell to BiMenu. This gives
them the means to specify paths, invoke BiModem on the BBS, and have it
automatically invoke BiModem locally when it sees the BiModem handshake. You
could also detect BiModem was up on the BBS by: watching the incoming characters
for multiple space/backspace characters. We look for 3 pairs, but you may want
to look for more. Most BBS's send out backspace/space/backspace when the user
types a single backspace, so beware of using too few pairs. All it takes is for
the user to type space/backspace/space/backspace and all of a sudden you will
receive 4 pairs. You may want to go the BiMenu shell route. This allows a
uniform interface across all telecommunications programs, and when the user
upgrades to a registered BiModem, he/she will get a new BiMenu with all the
registered only marking programs in it.

BiModem will require approximately 115k of shell space (over and above
command.com, if you shell that way). BiMenu brings that requirement up to 125-
130k. Once it is done you can interrogate the logs for any information you
desire. That's all there is. We hope we have provided enough hooks to make your
job easy. If you have further questions, please feel free to call.

BBS interfaces

We will allow authors of bulletin boards to freely distribute our unregistered
version of BiModem. We only require 2 things. You must indicate that BiModem is
a separate cost item, is included for your users trial evaluation, and if they
use BiModem on a regular basis they must register it with us. The other
requirement is that you let us know of your intentions to distribute the
unregistered version. This gives us the opportunity to put you on our first line
of support and make sure you receive the latest versions as soon as we release
to betas.

Probably the best way to interface BiModem into a bulletin board is to write a
separate program devoted to the interface task. Once this program is up and
running and tested it becomes an easy process to bring the interface internal.
The interface program has the following responsibilities:

1. Determine the comm port and pass it to BiModem.
2. Determine any time or size limits and pass it to BiModem.
3. Based on the user's security level, it should build a list of the
download directories and update BiModem's configuration file with the
path to this list.
4. Determine the upload directory and update BiModem's configuration file
with its path.
5. Determine the abort directory (for partial transfers) and update
BiModem's configuration file with it's path.
6. Next it should shell to BiModem. When BiModem returns it should:
7. Read the intercommunications log for:
a. updating the appropriate file listing. (You may want to prompt for







unsupplied descriptions)
b. updating user statistics.
c. updating system statistics.
d. writing log entries into the BBS's log.

Keep in mind that the file names used for the upload directory, log, BiModem's
config file, etc. should probably contain some kind of node id. This allows the
interface to work on multi-node systems. Other considerations would be the
rejection list and the password file. There are 2 ways to implement these
features, either you can re-generate these files everytime BiModem runs, or you
may want to have seperate maintenance programs for these that can be run on as
as needed basis.

The most common problem we have encountered with BBS software is the same
problem we have had with telecommunications software: Nobody asks for files for
both directions of the transfer. This is understandable since it was never
required before. There are two possible methods of solving this problem. First
you could have your interface program ask for file names and descriptions. It
could then write the requests to our path file (see path file layout). It could
also write them out separately to an ascii list of uploads and an ascii list of
downloads. Then when it invokes BiModem, it could have (/U
@upload_file_list_path /D @download_file_list_path) as an argument. The method
we prefer is that the bulletin board not ask for anything. Let the user specify
it on his end. This gives the user the ability to create the transfer list
before he calls. Our eventual goal is to provide the user with a database method
of tracking what files are available where and generating lists based on what he
has that the board needs and what he needs that the board has. We feel this
method will provide a better flow of programs around the world. With the BBS
asking the question, this goal is very difficult to reach. We think that with
the interface controlling what directories are accessible, and our new password
protection scheme, files will still be as secure as they are now.

Configuration File

1 - 1 Short Int Max Time Hundredths
2 - 2 Short Int Max Time Seconds
3 - 3 Short Int Max Time Minutes
4 - 4 Short Int Max Time Hours
5 - 8 Long Int Max Size
9 - 10 Integer Baud rate of Modem Connection not computer (for estimating)
11 - 11 Short Int Active Port Number
12 - 13 Integer Port Address 1
14 - 14 Short Int Interrupt Request Number 1
15 - 16 Integer Port Address 1
17 - 17 Short Int Interrupt Request Number 2
18 - 19 Integer Port Address 2
20 - 20 Short Int Interrupt Request Number 3
21 - 22 Integer Port Address 3
23 - 23 Short Int Interrupt Request Number 4
24 - 25 Integer Port Address 4
26 - 26 Short Int Interrupt Request Number 5
27 - 28 Integer Port Address 5
29 - 29 Short Int Interrupt Request Number 6
30 - 31 Integer Port Address 6







32 - 32 Short Int Interrupt Request Number 7
33 - 34 Integer Port Address 7
35 - 35 Short Int Interrupt Request Number 8
36 - 37 Integer Port Address 8
38 - 38 Bit Map 0 - Half Duplex Modem
1 - Dual Standard Modem
2-3 Reserved
4 - Maintain original date
5 - Summary Statistics
6 - Full Statistics
7 - Simple Names only
39 - 39 Bit Map 0 - Reserved
1 - Never allow sub directories
2 - Never allow directories
3 - Delete abortions
4 - Never delete source
5 - Always verify when done
6 - Always rename collisions
7 - Reserved
40 - 40 Bit Map 0-6 Default Download Options
41 - 41 Bit Map 0-6 Default Upload Options
42 - 121 Character Default Send Directory
122 - 201 Character Default Recv Directory
202 - 281 Character Default Log File Path
282 - 361 Character Default Paths File Path
362 - 362 Character Remove Snow (Y/N)
363 - 363 Character Modem Type (F-Full Duplex, D-Dual Standard, H-Half
Duplex)
364 - 364 Character Use Bios Indicator (Y/N)
365 - 365 Character Test CTS Indicator (Y/N)
366 - 366 Character Test Carrier Detect (Y/N)
367 - 367 Character Test Data Set Ready (Y/N)
368 - 368 Character Replace Timer Interrupt (Y/N)
369 - 369 Character Replace Keyboard Interrupt (Y/N)
370 - 370 Short Int Prompt Color
371 - 371 Short Int Field Color
372 - 372 Short Int Chat Received Color
373 - 373 Short Int Chat Sent Color
374 - 374 Short Int Menu Item Current Color
375 - 375 Short Int Menu Item Not Current Color
376 - 377 Integer # of seconds to wait for connect
378 - 378 Short Int Start Page Minutes
379 - 379 Short Int Start Page Hours
380 - 380 Short Int End Page Minutes
381 - 381 Short Int End Page Hours
382 - 394 Character Phone Edit
395 - 474 Character Rejection List Path
475 - 554 Character Abort Directory Path
555 - 555 Character Allow current directory access (Y/N)
556 - 556 Character Allow remote file requests (Y/N)
557 - 557 Character Allow local file requests (Y/N)
558 - 559 Integer BiHot Activate key value
560 - 565 Character BiHot Activate key name
566 - 567 Integer BiHot unload key value







568 - 573 Character BiHot unload key name
574 - 653 Character Password file Path

Paths file layout

1 - 1 Character (U)pload or (D)ownload
2 - 2 Character (R)efresh
3 - 3 Character {Y| |N} Replace if existing override
4 - 4 Character {Y| |N} Verify when done override
5 - 5 Character {Y| |N} Delete source when done override
6 - 6 Character Unused
7 - 7 Character {Y| |N} Allow full directory override
8 - 8 Character {Y| |N} Include subdirectory override
9 - 88 Character Source Path
89 - 168 Character Destination Path
169 - 248 Character Description (Only used on Uploads)

User Log file layout

Connect Entry

1 - 13 Character "Connected to:"
15 - 74 Character Registered ID
76 - 88 Character Edited Registered Phone #
90 - 97 Character Date connected (MM/DD/YY)
99 - 106 Character Time connected (HH:MM:SS)
107 - 107 Character Carriage Return
108 - 108 Character Line Feed

Send/Receive Entry

3 - 10 Character Beginning Time (HH:MM:SS)
12 - 12 Character Direction/Success Indicator (S-Sent Normal, s-Sent Abnormal,
R-Received Normal, r-Received Abnormal)
14 - 21 Character File Size
23 - 30 Character Elapsed time (HH:MM:SS)
32 - 37 Character Characters per Second (ZZZZ.9)
39 - 41 Character "BPS"
43 - ?? Character Pathname[,Password]
??+1 Character Carriage Return
??+2 Character Line Feed

Disconnect Entry

1 - 14 Character "Disconnected @"
16 - 23 Character Disconnect Time (HH:MM:SS)
24 - 24 Character Carriage Return
25 - 25 Character Line Feed







Intercommunication Log

1 - 1 Short Int Day transfer completed
2 - 2 Short Int Month transfer completed
3 - 4 Integer Year transfer completed

5 - 5 Short Int Hundredths of seconds transfer completed
6 - 6 Short Int Second transfer completed
7 - 7 Short Int Minute transfer completed
8 - 8 Short Int Hour transfer completed
9 - 9 Character Direction (S=Send,R=Receive)
10 - 88 Character Path[,Password]
89 - 89 Character Status (Blank=Successful,D=Duplicate,A=Aborted)
90 - 169 Character Description
170 - 171 Integer Characters per Second
172 - 231 Character Registered ID
232 - 233 Integer Area Code part of registered phone #
234 - 236 3byte Int Remaining part of registered phone #

DSZ Log

1 - 1 Character Transfer Type (b=Send,B=Receive,e=Error Sending,E=Error
Receiving)
3 - 8 Character Byte Count
10 - 14 Character Baud Rate
16 - 18 Character "bps"
20 - 23 Character Characters per Second
25 - 27 Character "cps"
29 - 31 Character Error Count
33 - 38 Character "errors"
40 - 44 Character Flow Control Stoppages (not used, 0)
46 - 49 Character Packet Size
51 - 62 Character File Name
64 - 76 Character Registered Edited Phone #
77 - 77 Character Carriage Return
78 - 78 Character Line Feed