Shareware Overload/ShartewareOverload.cdr/comm/boyan2.zip/OZBEXT84.DOC

Text File | 1988-06-25 | 19KB | 343 lines

OZBEXT Documentation
====================

Version 8.4d (06/24/88)
Copyright (c) 1987,1988 Steve Sneed/Ozarks West Software  (71520,77)

No charge or request for renumeration is made for private, non-commercial use.
This program may be distributed by any means, magnetic or electronic, and
may be included with another program package, as long as the following
restrictions are met:

  1.  No charge is made for such distribution.  Bona-fide "User's Groups" and
      computer clubs may charge a copying/media fee not to exceed $5.00.
      Specific licence is given to FOG (the First Osborne Group) and The
      Public (Software) Library to distribute this package.  Specific license
      is also granted to CompuServe Inc. and its employees and assigns to use
      the program and include it with other products and services if proper
      credit is given.  Distribution via electronic Bulletin Board Systems
      is encouraged.

  2.  The program and its documentation are distributed unchanged in any way,
      and packaged together in original format.

  3.  Proper credit is given in other documentation referencing this work.

  4.  Commercial or business use requires a licence.  Contact the author at
      one of the addresses below for more information.

Portions of this program are copyrighted by CompuServe Inc., TurboPower Soft-
ware, Inc., and Borland International.  This program was written in Turbo
Pascal 4.0.  "GIF" and "Graphics Interchange Format" are registered trademarks
of CompuServe Incorporated, an H&R Block Company.


What it is
==========

OZBEXT is an external protocol module supporting the CompuServe "B" and "B-
Plus" (often known as "QuickB") protocols for transport layer communications
with error-correcting file transfer capability.  It also supports a subset
of the CIS "VidTex" (VT52) terminal emulation standard for screen and cursor
handling, and VT100 emulation for block graphics and screen colors.  While
there are currently no applications on CIS that use the actual "Transport
Layer" capability of BPlus, there are several planned; I intend to make
implementations of those applications available as they are documented and
released.  Also, as of the release date of this version of the program, the
full BPlus functionality for transfers is available only in Level 5 FILTRN
on CIS as a testing venue and is limited to the restricted implementation
("QuickB") elsewhere, including the forums.  This will change "any day now";
in the meanwhile this program supports the existing protocol implementation
as well as the enhanced version soon to be released.  There are a few minor
points of the protocol standard that are yet to be settled; updated versions
of this program will be released as those points solidify.

OZBEXT allows almost anyone with communications programs that either support
external protocol modules directly (such as Boyan, QModem, PibTerm or OzCom),
or provides a "drop to DOS" capability, to take advantage of the superior per-
formance of the "B" and "BPlus" (hereafter called BP) protocols for file
transfers on CIS.  Some programs (such as earlier versions of BitCom) have
problems with external modules; there are several exellent help files for
these programs on the IBMNEW SIG on CIS which explain how to use this and
other protocol modules with these "problem" programs.


Calling
=======

OZBEXT is totally command-line driven.  That is, the program is configured
from information provided on the command line when calling the program.
OZBEXT has been designed to default to a typical set of values, and if these
default values are acceptable no command line parameters are required.
Parameters are not required to be in any specific order, and capitalization
is not important.  The program automatically detects the current baud
rate and parity settings for the default or selected port so you typically
do not have to provide that information unless you want to change one or
more port settings.

Parameters consist of a slash (/) or dash (-), immediately followed by a
command letter, and optionally followed by a space and a qualifying value.
All parameters on the command line *must* be seperated by spaces.  The
adjustable parameters (and their command line calls) are:

Port: Defaults to COM1.  If you have the environment variable OZPORT or
      DSZPORT set (typically in your AUTOEXEC.BAT file), the default will
      be overridden with that setting.  If you supply the parameter "-C"
      followed by a space and a number (1 thru 4), the port will be set to
      that value.  NOTE: It has come to my attention that the new IBM PS/2
      machines have "non-standard" addresses for COMs 3 and 4.  A future
      release of this program will provide command-line parameters for linking
      to these odd base addresses.

BaudRate: Defaults to the existing baud rate for the port in question.  Can
      be overridden by the "-B" parameter followed by a space and a valid
      baud rate.  Available baud rates are: 300, 1200, 2400, 4800, 9600,
      19200, 38400.

Parity: Defaults to the existing parity setting for the port in question.
      Can be overridden by the "-P" parameter followed by a space and a
      valid character for the parity type wanted.  Valid parity types are:
      (N)one, (E)ven, (O)dd, (M)ark or (S)pace (characters in parenthesis
      are the calling characters.)  *NOTE* If the port is set to None parity
      and 8 data bits, and you call for a parity type other than None, the
      data bits setting is automatically reset to 7.  Likewise, if the port's
      existing setting is for something other than None parity and you call
      for None parity on the command line, the data bits setting is auto-
      matically set to 8.  This can be overridden via other parameters; see
      below.

DataBits: Defaults to the existing port setting.  Can be overridden by the
      "-W" parameter followed by a space and a valid databits value
      (5 thru 8.)  Note that if 5 databits is selected, the stopbits value
      is automatically set to 1.5 and cannot be overridden (this is built
      into the 8250 and 16450 UART chips.)

StopBits: Defaults to the existing port setting.  Can be overridden via the
      "-S" parameter followed by a space and a valid stopbits value
      (1 or 2.)  See the note in the DataBits section concerning this value.

Duplex: Defaults to Full Duplex transmission.  Can be set to half duplex by
      using the "-H" parameter.

Drop DTR on exit: Defaults to NO.  If you want the program to drop the modem
      DTR control line (hanging up any call in progress), use the "-D"
      parameter.  NOTE: some modems are finicky and do not drop a connection
      when DTR is dropped - you should test this function with your modem
      before totally relying on it to disconnect a call.

Exit on Transfer Completion: Defaults to NO.  If you want the program to auto-
      matically exit cleanly after the successful completion of a transfer,
      use this switch.  Setting this switch automatically overrides the state
      of the "Alarm" internal switch (the Alt-S command) so no keypress is
      required at xfer end.  This also can be controlled via the Alt-E command
      inside the program.  This functionality allows you to establish an
      automated script for your existing comm program that, on completion of
      a download, returns you to your comm program and then automatically
      logs off of CIS cleanly.

Clear screen on entry/exit: Defaults to YES.  If you do not want the program
      to clear the screen on entry and exit (just give you a notice that the
      program is loaded and operational), you can use this switch.  Using
      this switch allows you to continue to see the last screen of the
      calling program, and to see where you were when returning.

Parameters:

-C : Sets port.  Default is COM1.  Valids are 1 thru 4.
-B : Sets baudrate.  Default is port setting.  Valids are 300, 1200, 2400,
     4800, 9600, 19200, 38400.
-P : Sets parity.  Default is port setting.  Valids are N, E, O, M, S.
-W : Sets databits.  Default is port setting.  Valids are 8, 7, 6, 5.
-S : Sets stopbits.  Default is port setting.  Valids are 1 or 2.
-H : Sets half-duplex mode.  Default is full-duplex.
-D : Sets to drop DTR on exit.  Default is to leave DTR high so as not to
     disconnect a call in progress.
-X : Exit-on-transfer-completion.  Default is to return to OZBEXT's internal
     terminal emulation mode when the transfer is done.
-Z : Clear-Screen-on-entry/exit.  Default is to clear the screen.
-? : Display a help/info screen and exit.


Command line examples:

OZBEXT{enter}
   - calls OZBEXT for standard setting and default port and parameters.

OZBEXT /c 2{enter}
   - calls OZBEXT for COM2 with all other settings standard.

OZBEXT /p E /h{enter}
   - calls OZBEXT at Even parity, default port and speed, and sets half-duplex
     mode.

OZBEXT /c 1 /p e /w 7 /s 1 /b 2400{enter}
   - calls OZBEXT with all port parameters specifically defined.  Note that no
     special order is enforced on the parameters.  While this is perfectly
     legal for the program, it is typically overkill unless your comm program
     does something wacky to the port when exiting.

OZBEXT /d{enter}
   - calls OZBEXT with the "drop DTR on exit" flag set.  Never recommended un-
     less you are using OZBEXT as a "stand-alone" comm program and want to
     make sure the call is disconnected on exit.


Using
=====

OZBEXT is simple to use - consider it an extension of your existing comm pro-
gram.  OZBEXT knows how to talk to CIS about itself so that CIS automatically
takes advantage of the program's powers, with one exception: if you do not
have VIDTEX set with CIS as your default terminal emulation, CIS will not
"force" VidTex cursor controls on the system.  While I personally recommend
you use the VidTex capabilities, it will also depend on the emulation of
your main comm program - most general-use comm programs do not understand
the VidTex control sequences and would cause garbage to be displayed.  If
you want to use VidTex, do a "GO TERMINAL" at any CIS "!" prompt and follow
the prompts for "Setting your terminal type", or type "SET TERM VIDTEX" at
almost any "!" prompt.  The VidTex terminal emulation command set is very
close to the DEC VT52 emulation, so if your comm program supports VT52 you
can use that emulation with (usually) good success.  Many programs like the
VT100/ANSI emulation - OZBEXT fully supports the VT100 screen-handling
commands.  However, to use this program's VT100/ANSI support you must have
ANSI.SYS loaded via a call in your CONFIG.SYS file (see your DOS documentation
for more information.)  Also, if you use FANSIConsole (a multifeatured ANSI
replacement), be sure to turn off Fansi's fast-screen-updating capability as
it causes grief for this and many other programs that use DOS standard output
redirection for character-based display.


The following commands are available within OZBEXT:

  Alt-X: Exits the program.
  Alt-E: Toggles the state of the Exit_On_Transfer_End flag.
  Alt-S: Toggles the state of the Alarm_On_Transfer_End flag.  Note that this
         flag is overridden if the Exit_On_Transfer_End flag is set ON.
  Alt-R: If my OZRLE CIS graphics module is available in the same directory
         as this program, it will be loaded.  See the OZRLE docs for info.
  Alt-H: Toggles the Half-duplex/Full-duplex flag.
  Alt-D: Toggles the Drop_DTR_On_Exit flag.

When calling OZBEXT, be sure to call the program *prior* to telling CIS you
want a transfer.  CIS sends a special code to the remote program (you) asking
the remote if it does in fact support BP.  Most comm programs are much more
generic in nature and do not understand this special interrogation, so they
do not reply and CIS aborts the transfer.  OZBEXT must be loaded prior to
receiving this interrogation so that it properly responds and CIS allows the
transfer to take place.  (This special interrogation is done only when a BP
transfer is requested - it is not used and has no effect on any of the other
transfer types supported by CIS.)  Some programs that support certain CIS
capabilities, such as ProComm Plus, reply in their own way to this inter-
rogation, and these program's replies may or may not match OZBEXT's actual
capabilities - when using one of these programs, be sure to load OZBEXT
before CIS sends the interrogation.

Also, it is important to note that you do not have to change your comm
program's parameters in order to use this program.  It's come to my attention
that some users are logging on to CIS at 7/E/1 but calling OZBEXT with the
command-line switches set to 8/N/1 because they assume that they need 8/N/1
for the transfer.  You do need 8/N/1 for the transfer *itself*, but CIS
does not switch to 8/N/1 until it actually begins the protocol transfer -
all prompt answering, etc. is still done at the caller's original 7/E/1
parameters, including the interrogation/response sequence mentioned above.
OZBEXT automatically switches to 8/N/1 at the proper time to do the
transfer and then back as soon as the transfer is complete; the user is
not notified and never sees or notices the changes.  Therefore, unless
your comm software or system is unusual, you can best use this program by
passing it no command-line parameters except those absolutely nessessary
for operation or those flag settings you desire.  In other words, don't
use the -C, -B, -P, -W or -S command-line params unless you *have* to.  Oh,
yes:  there are some rather poorly-made modems and serial cards out there
that do not like to change parity/databits once a connection is established.
If you have problems trying to do a transfer when logged onto CIS at 7/E/1,
do a GO TERMINAL at almost any ! prompt and follow the menus to set your
default parity to NONE.  Be sure to save the new setting for future sessions
as you exit the TERMINAL area.  From then on, log onto CIS at 8/N/1 and you
should see no more problems.

If the comm program you are using does not restore keyboard control on
return from a shell out to OZBEXT (or any other external program), a
simple fix that often works is to go to that program's area for setting
the communications parameters and switch from the current parity setting
to some other setting and then back (example: if you are currently at
7/E/1, switch to 8/N/1 and then back to 7/E/1) - this will usually clear
the port and restore your keyboard functions.  Older versions of the BitCom
software included with many modems are known to demonstrate this problem.


What's new with 8.4
===================

CIS recently changed the programming in the User Profile Area (GO TERMINAL),
and these changes have caused some minor confusion because the host (CIS)
switches to 7/E/1 parameters at a time when most comm programs do not expect
it.  OZBEXT now maps all incomming characters at the port to 7 data bits
(except during a protocol transfer) to eliminate this problem.

The processing of the B+ transfer was changed slightly.  Previous versions of
this program did not display the transfer window until the actual file trans-
fer itself was initiated.  However, right after telling CIS to start the
transfer a negotiation packet (or series of packets) is processed between the
host and the remote.  During periods of high network traffic, this negotiation
process could take enough time to make a impatient user think the protocol
had died.  Therefore I changed the transfer window opening process to display
the transfer window while this negotiation is taking place so the user can
see what is going on.

All keyboard Alt-key toggles now display a small information window at the
top right corner of the screen.  For example, if you pressed Alt-D to toggle
the Drop_DTR_On_Exit flag, a small reverse-video blurb is displayed telling
the new state of the flag.


Kudos, congrats, karma enhancements
===================================

Many, many thanks to the CIS IBMNET sysops, Connie Kageyama, Don Watkins and
Chris Dunford, for their help with BETA testing and debugging.

Comm software can be very complex, even in a relatively small, single-purpose
package such as this.  Very, very seldom is a program of any size the total
work of one individual, especially in a comm program where so many areas of
expertise are required.  Nothing irks me more than to hear some programmer
say, "Yep, it's all mine!  Ain't it great?" when his code is peppered with
one person's async handler, another person's video handling code, etc., etc.,
ad infinitum ad nausium.  Here are some of the fine folks who's good honest
skull sweat has made this program possible:
   Kim Kokkonen and the folks at TurboPower Software: too many little handy
      routines thruout the code to mention.  Exellent work!  If you program
      in Turbo Pascal, and you don't use the Turbo Professional library,
      you're missing a bet!
   N. Arley Dealey: the majority of the timing routines.  Arley's timer code
      is as bulletproof as any available for Turbo Pascal.
   Russ Ranshaw, CIS: the overall implementation of the BPlus protocol.  Russ'
      code is the heart of this program, although I've tweaked here and there
      and implemented my comm routines.  The B series protocols are a very
      tricky coding job - Russ' good, clean code and understandable docs
      make it very easy.
   Chris Dunford, CIS:  several years ago Chris released a Turbo Pascal in-
      clude file called ASYNC.PAS - it is either the basis of, or the pattern
      for, most of the Turbo Pascal serial port handlers in use today.  I've
      modified the original code so many times it's almost unrecognizable, but
      I still thank Chris for the stable foundation on which to build, and I
      still defer to his deep expertise when I hit something I don't know.


Finally, thanks to all the users who have pointed out bugs and deficiencies
and provided exellent suggestions that have helped make the program what
it is.  If you like the program and its capabilities, thank them instead
of me.

This program is dedicated to my darling daughter Whitney.


Steve Sneed
Ozarks West Software
409 San Juanico
Santa Maria, CA.  93455
CIS ID  71520,77
  or
The C2G BBS  805-925-0378  300/1200/2400  24hrs.

<eof>