Programmer 7500/MAX_PROGRAMMERS.iso/PROGRAMS/UTILS/COMMUNIC/SUBWAY21.ZIP/SUBWAY.DOC

Text File | 1988-02-24 | 9.0 KB | 244 lines

*** SUBWAY 2.1 Documentation File ***

(1) INTRODUCTION

What is SUBWAY ?

A simple communications program featuring :

* TTY emulation
* ASCII file capture

Is that all ?  Yes that's all *but* what makes it special is its ability to :

* stay resident
* run as a background task

Staying resident means that you can, from inside any application, pop up the
terminal and communicate at will with your favorite BBS, and flip back and
forth between your application screen and the terminal screen.

Running as a background task means that, once the ASCII file capture is
underway, you can leave the terminal and come back to your application : the
capture will go on, whatever you're doing as a foreground task.  Think of it
as something like the PRINT utility, except that here the data flow is from
the outside world to your disk.  Furthermore, if this data flow comes to a
stop while in background capture mode, SUBWAY will detect it and beep the
speaker to warn you, urging you to pop up the terminal and check what's going
on.


(2) INSTALLING SUBWAY

This program is made of two parts :

* a general purpose interrupt driven async communications driver (CDRV)
* a pop-up terminal emulator featuring background file capture (SUBWAY)

To install them, type CDRV [Enter], then SUBWAY [Enter].  If you want to
use SideKick (tm) too, load it *after* SUBWAY.  This way you can call SK
from inside SUBWAY or SUBWAY from inside SK (more about this later).

(3) USING SUBWAY

To activate SUBWAY, just press the [Alt]-[Esc] key combination.  The screen
is blanked and the cursor is homed.

The first thing to do is to "open" the com port (the default is COM1:, but
this can be changed).  To do this, use the Alt-T combination (T stands for
"take").  If CDRV succeeds in initializing the port, it will say so, and you
can start to communicate (presumably by sending an ATZ string to your modem).

To "close" the com port, just press Alt-R (R stands for "release").  This will
stop the IRQ driven mode, and drop RTS and DTR (forcing most modems to drop
the line as well).

The baud rate and data format can be changed anytime using the following key
combinations :

Alt-1 to set 1200 bps
Alt-2 to set 2400 bps
Alt-3 to set  300 bps

Alt-N to set NO parity, 8 data bits, 1 stop bit
Alt-O to set ODD parity, 7 data bits, 1 stop bit
Alt-E to set EVEN parity, 7 data bits, 1 stop bit

To send a BREAK signal, just type Alt-B.

Now for the best : background ASCII file capture.

To activate it, just type Alt-C.  To stop it, type Alt-C again, since this is
a toggle.

When you start it, you'll be prompted for a file pathname.  If the file does
not exist, it is created.  If it already exists, captured data will be
appended to the end of the file.  You should *always* specify a drive and full
pathname.  This is because, if you change your working directory while the
file capture is running in background mode, SUBWAY won't find the capture file
any longer, and many characters will be lost.

To exit terminal mode, just press Alt-X.  This will not drop the communication
or stop the capture : SUBWAY will keep on receiving characters, and write them
to disk if requested to do so.  Notice that the original screen contents are
restored.  To recall SUBWAY, just Alt-Esc again.


(4) WORKING WITH SIDEKICK (tm)

Loading SK after SUBWAY brings some interesting features : with the notepad,
you can upload small text files using the PASTE function (you might wish to
adjust the paste delay factor to a non-zero value).

A typical working session might be :

* load CDRV, then SUBWAY, then SIDEKICK
* activate SUBWAY (Alt-Esc)
* open com port (Alt-T)
* set speed to 2400 bps (Alt-2)
* connect to BIX (ATD...etc...)
* join your favorite conference... Gosh ! 100 new messages !
* turn capture on (Alt-C, enter pathname)
* type "all" to read all messages
* exit SUBWAY (Alt-X)
* play around with your favorite program (word processor, spreadsheet,
  compiler, CAD, etc...)
* a moment later, a gentle beep warns you
* activate SUBWAY again (Alt-Esc) : "no more unread messages, etc..."
* stop capture mode (Alt-C)
* disconnect from BIX (Alt-R)
* browse thru the messages
* find an interesting question
* pop up SK's notepad
* write the answer
* assign the whole text to a key
* exit SK's notepad
* reconnect to BIX (Alt-T, ATD..., join...)
* "comment" the question, and automatically paste the answer using the
  key you just assigned


(5) PATCHING SUBWAY

Several default parameters can be changed using DEBUG.  First, load SUBWAY,
using the command : DEBUG SUBWAY.COM [Enter]

* hot key combination : the scan code for the key is at offset 0103, the
  default value is 01 (Esc) - the shift status is at offset 0104, the
  default value is 08 (Alt) - both values can be changed, provided you
  avoid to interfere with otherwise used key combinations.

* com port used : the port number is a WORD at offset 0105, the default
  value is 0 (COM1:)

* initial settings : the control byte is at offset 0107, the default value
  is 83H, standing for 1200 bps, 8 data bits, no parity, 1 stop bit - the
  meaning of each bit in this byte adheres to the BIOS (INT 14H) convention.

* the "no more incoming data" alarm comes when a timer (reset at each capture
  file write) has elapsed.  The default value is a WORD at offset 0108.  This
  value is 550 decimal (226H).  Units are clock ticks, so 550 is about 30
  seconds.  This is well suited for a 1200 bps communication, but might be a
  bit short at 300 bps, or a bit long at 2400 bps.

When the required values are patched, just write the file back (using the "W"
debug command) to disk.

Changes will be effective the next time you load SUBWAY (don't load it twice
in a row, please reboot if it is already loaded).


(6) TECHNICAL ISSUES

How does SUBWAY work ?

* staying resident : nothing magic about it - INT 27H is used to install the
  program - INT 09H is hooked to detect the hot key combination.

* screen swapping : BIOS calls are used to read and write the screen - this
  may be somewhat slower than direct memory access, but this is much more
  portable.

* IRQ driven com port : this is CDRV's job - it just has to take care of the
  8250 (async chip) and 8259 (IRQ controller chip) and manage an 8 K-byte
  ring buffer.

* background file capture : a TSR is allowed to issue DOS calls as long as it
  doesn't interfere with foreground applications - fortunately the DOS opens
  two windows even though it looks as if it closed the door : it manages an
  internal "DOS busy flag" to tell us when it doesn't want to be disturbed,
  and it calls INT 28H whenever it has nothing special to do and agrees to be
  called.

* memory requirements : CDRV uses about 9800 bytes, including the 8192-byte
  ring buffer - SUBWAY uses about 8500 bytes, including the 4000-byte screen
  buffer and a 2048-byte capture buffer - this capture buffer is flushed to
  disk whenever it is full.

* flushing capture buffer to disk : the DOS calls sequence is as follows :

   - hide file
   - open file
   - go to end of file
   - write buffer to file
   - close file
   - unhide file

  the file is hidden to prevent another TSR coming up at the very same moment
  from finding the file and maybe open and modify it - it has to be closed and
  reopened at each call, because exiting a foreground application closes ALL
  files.

* critical errors : whenever a critical error occurs in this sequence, the DOS
  call is failed (this requires DOS 3.0 or later to work) - whenever a DOS
  call fails in this sequence, a low pitched sound comes out of the speaker,
  the infamous "Abort, Retry, Ignore ?" message won't appear on your screen,
  and the disk write is canceled (not retried).


(7) IN CASE OF PROBLEM

SUBWAY has been tested for a while, and it seems to work rather well.  It
works even with WINDOWS running in foreground (you can't pop up the terminal
while in WINDOWS, but the background file capture is still running).

In the event you meet any problem :

* FIRST try to find out by yourself where it comes from - it is good for the
  brain and might be very rewarding to your ego.

* THEN ask for help - my BIX emailbox is : lanc.


(8) FUTURE FEATURES

I'm working on the next version of SUBWAY.  Guess what it will do ?

* background Xmodem/Ymodem up- and down-loading (for sure !)

* sophisticated terminal emulation (maybe...)

* anything else you might suggest (why not ?)


(9) ENCLOSED FILES

* CDRV.COM : communications driver
* CDRV.DOC : technical documentation about CDRV

* SUBWAY.COM : the communications program the world has been waiting for
* SUBWAY.DOC : this file


(10) ????WARE

Freeware or shareware ?  Well, I might as well consider this program to be
nothing more than freeware.  I just wrote it for my personal use, and assumed
that it could, after all, be useful to someone else as well.  But, if you like
it so much that you feel a compulsive need to pay for it... just let me know.

BIX : lanc
CALVACOM : LA21 (this is a Frrrrrench BBS)