ftp.wwiv.com/ftp.wwiv.com.zip/ftp.wwiv.com/pub/GENUTIL/VFD055B.ZIP/VFD.DOC

Text File | 1994-05-15 | 14KB | 359 lines

                         ┌─╖    ┌─╖ ┌───────╖ ┌─────╖
                         │ ║    │ ║ │       ║ │     ╙╖
                         │ ║    │ ║ │ ╔═════╝ │ ╔══╕ ║
                         │ ║    │ ║ │ ║       │ ║  │ ╙╖
                         │ ║    │ ║ │ ║       │ ║  │  ║
                         │ ║    │ ║ │ ║       │ ║  ╘╕ ║
                         │ ║    │ ║ │ ║       │ ║   │ ║
                         │ ╙╖   │ ║ │ ╙───╖   │ ║   │ ║
                         ╘╕ ║   │ ║ │     ║   │ ║   │ ║
                          │ ╙╖  │ ║ │ ╔═══╝   │ ║   │ ║
                          ╘╕ ║  │ ║ │ ║       │ ║   │ ║
                           │ ╙╖ │ ║ │ ║       │ ║  ┌┘ ║
                           ╘╕ ║ │ ║ │ ║       │ ║  │  ║
                            │ ╙╖│ ║ │ ║       │ ║  │ ╔╝
                            ╘╕ ╙┘ ║ │ ║       │ ╙──┘ ║
                             │    ║ │ ║       │     ╔╝
                             ╘════╝ ╘═╝       ╘═════╝



                                     -----

            Virtual FOSSIL Driver - VFD - A FOSSIL driver for OS/2

                          Public Beta Version 0.55ß

           Copyright 1993 Joakim B. Hernberg;  All rights reserved.

                                     -----


   1 SOFTWARE LICENSE AGREEMENT

   The Virtual FOSSIL Driver computer software, information attached hereto,
   and any modifications made to the enclosed information, hereafter referred
   to as VFD, is protected by applicable copyright laws and international
   treaty provisions pertaining to intellectual property.  VFD is provided to
   you "as is", without warranty of any kind, promise of merchantability, or
   fitness for a particular purpose, either expressed or implied, all of
   which are hereby explicitly disclaimed.

   Joakim B. Hernberg only guarantees that VFD occupies disk space.

   You are hereby granted a non-exclusive license to use and test this beta
   version of VFD, provided you agree and abide to the following:

    1. You agree and acknowledge that VFD is a proprietary product of Joakim
    B. Hernberg, protected under international treaty provisions and other
    applicable copyright laws.  You further acknowledge and agree that all
    rights, title, and interest in and to VFD are and shall remain with
    Joakim B. Hernberg.

    2. In no event shall Joakim B. Hernberg be liable for any indirect,
    incidental, consequential, special, or exemplary damages or lost profits,
    even if Joakim B. Hernberg has been advised of the possibility of such
    damages.

    3. Joakim B. Hernberg's cumulative liability to you or any other party
    for any loss or damages resulting from any claims, demands, or action
    arising out of or relating to this agreement shall not exceed the license
    fee paid by you to Joakim B. Hernberg for VFD.

    4. You may not lease, rent, or sell VFD.  You may not disassemble,
    decompile, or reverse engineer VFD.


   2 AVAILABILITY

   If you need to contact me, use one of the following addresses.

   Joakim Hernberg
   240, rue de Luxembourg
   L-8077 Bertrange
   Luxembourg

   FAX#: [phone]

   Fidonet:  Joakim Hernberg, 2:270/3
   Internet: [e-mail]

   The fidonet echo VFD_BETA is available from most below listed support
   nodes.

   You can always get the latest version of VFD by requesting magic file
   name VFD from the following fidonet sites:

   1:222/10           - DogStar
   [phone]    - Mario Dulisse

   1:260/369          - The Blue Fox
   [phone]    - Bob Beilstein

   1:170/400          - The Truckstop BBS
   [phone]    - Bruce Bodger

   2:201/329          - FrontDoor Help Europe
   [phone]     - Mats Wallin

   2:243/5039         - WayForward BBS
   [phone]     - Tobias Burchhardt

   2:257/168          - Barnabas The Caring BBS [OS/2]
   [phone]    - john barton

   2:270/3            - The SourceTap
   [phone]       - Joakim Hernberg

   2:270/17           - Use your illusion
   [phone]       - joaquim homrighausen

   2:285/712          - Medusa BBS
   [phone]     - Winston van Oosterhout

   2:344/2            - Ostargi
   [phone]     - Eduardo Jacob

   3:712/704          - Eagle One BBS
   [phone]     - Terry Harvey

   3:774/10           - Global NetWork
   [phone]     - Barry Blackford


   VFD is also available for ftp from ftp.luth.se in the directory
   /pub/os2/2.x/dos/network.


   3 WHAT IT IS

   VFD is a Virtual Device Driver providing int 14h (FOSSIL) functionality
   to VDMs (Virtual DOS Machines) running under OS/2.  It does this by
   translating int 14h calls (from a VDM) into OS/2 file system calls.

   This technique allows for very efficient file transfers when the
   communication software uses FOSSIL block read/write calls.  Software
   which uses single character I/O should be avoided if at all possible,
   especially for file transfers.

   VFD should be compatible with all OS/2 serial communication solutions due
   to it's use of the OS/2 file system.  This will of course prove not true,
   and I am interested in any reports you have on exotic hardware like DMA
   capable boards, or network redirected serial devices.  I have run FD/RA
   and FD - Terminal on remote comm devices using IBM Lan Server 3.0.

   VFD opens the comm handle in "deny none sharing mode", this means that
   it should be possible to coordinate access to the com port with other
   programs that also use deny none sharing.  Some type of semaphore file
   scheme or a control program using named pipes might be used for this
   purpose.  Or, you might want to run some DOS doors under your OS/2 BBS
   program, just start a DOS sesion and run your door.

   VFD supports up to 8 com ports with the standard names COM1 - COM8.

   VFD adds a DOS property setting 'COM_FOSSIL' which is turned ON by
   default.  FOSSIL support can be turned off, by toggling this DOS setting
   for your program object, if it should prove necessary.

   It seems like it is very difficult to give precise settings for perfect
   communications under OS/2.  Settings seem to vary from system to
   system, and what works on one system might not work at all on another.
   You should read the files in FDTN-002.* compiled by john barton.  Inside
   of this archive you will find a couple of technotes on how to run FD & RA
   under OS/2, containing invaluable advice for using vfd.

   If you can not find FDTN-002.* where you got this archive, you can get it
   from the support sites.

   All the advice I can offer, is to try different comm drivers if you have
   a problem, and once you find a working solution, stick with it !  I am
   using all default DOS_SETTINGS...


   4 INSTALLATION

   Installation should prove straight forward.  Just add the line "device =
   x:\path\vfd.os2" to your config.sys together with the default com/vcom.sys
   device driver pair or a replacement (such as sio/vsio.sys).

   If you are using the IBM drivers, see FDTN-002 and IBM docs for parameters
   to com.sys.

   VFD does not require the virtual driver (vcom.sys) to be loaded, but it
   will coexist peacefully, and it is a good idea to leave this driver
   present if you intend to use DOS software that talks straight to the
   hardware, since VFD will not provide a virtual UART.

   The com.sys driver has to be initialized to the proper state by using
   the OS/2 mode command.  This is preferably done by using a mode statement
   in the bat/cmd file launching your bbs/terminal software.  It can also be
   done in config.sys by using the run command or in startup.cmd, but since
   some other application might clobber your settings, you might want to run
   mode before every application that is about to use the port.

   This is the mode command in use on my system:

   mode com1 38400,n,8,1,,to=on,xon=off,idsr=off,odsr=off,octs=on,dtr=on,
             rts=hs,buffer=on

   The SIO driver is locked in config.sys and works fine with default
   settings (no need for the mode statement) when used with VFD.  See the
   tech notes and the SIO documentation for more details.


   5 VFDU.EXE

   This is a small crude command line interface for communicating with VFD.
   Note that VFDU does no verification of the command line passed it, so
   anything can happen if you don't watch it.  This will of course be
   rectified in a future version. and I am open to suggestions as to the
   "look" and settings to be provided.

   Syntax is:  vfdu parm1 parm2 ...

   At the moment the following parameters are accepted:

   l#,ls - lock baudrate at port # (COM1 is 1...), lazy status
   u#,ls - unlock port #, lazy status
   pc,l  - change DOS session's priority (c = class, l = delta of level)
   b#,s  - single char read buffer (port #) block size s = 1 - 1024
   td    - tame, d = delay in milli seconds, 0 turns off tame
   r#,s  - port # restrict read block size, 0 = disable restriction
   w#,s  - port # restrict write block size, 0 = disable restriction
   h#,$  - set port # to os/2 handle $


   Port numbers start with 1, which means that 1 is COM1 !


   Lazy status means that the status byte returned by function 3 only is
   updated once per clock tick, this allows programs that do single char I/O
   instead of block I/O to run at full speed.  Very useful for SEAlink
   receive and terminal work in FD, just don't complain that you can't do
   3.000 cps in x-modem ;-)  To turn this option on, add ",ls" to the end of
   the lock/unlock option and to turn it off, leave it out.  Default is OFF.


   You should probably leave the priority settings on default, but the
   hook is there if you want to experiment.  I am interested in your results.

   I've seen recommendations to set a communication task to Foreground Server
   class with a delta of 10, this is accomplished by using 'vfdu p4,10'.
   You should set priority back by 'p2,-10' upon exiting to do other
   processing, only keep it at server priority while the mailer or bbs is
   running (A DOS application running at server priority and hogging the CPU,
   will severely slow down the rest of OS/2 !).  Your DOS session starts out
   at class 2, level 0.

   Note that delta of level represents a change not an absolute value !

   That means that if you change level by +10, you have to change by -10 in
   order to restore starting value...

   See IBM's Red Books (now available as *.inf files) for a discussion on
   priority levels.

   The following classes exist (and their corresponding 'c' parameter):

   Idle                = 1
   Regular             = 2
   Time Critical       = 3
   Foreground Server   = 4
   Simulated Interrupt = 5

   Each class has 31 levels.


   Single char read buffer, attempts to read up to block size chars in one
   block read if available.  It then portions these bytes out to subsequent
   single char read requests.  Default is 64 which yields a good compromise
   between smooth terminal and efficient (?) SEAlink recieve on my system.

   This setting can cause a problem on a bbs, since it will allow a terminal
   to send a lot of chars without the bbs echoing them.  Fix by setting to 1.


   The tame parameter is not the normal type of tame which forces a program
   to give up time slices, rather it does exactly the reverse.  I know I
   should have named this parameter differently, but I could just not come up
   with an appropriate name for it.  This is useful, because a lot of
   programs give up slices in the wrong place and can cause a slowdown under
   OS/2.

   The default value is ON with a 250 ms delay, which has been arrived at by
   trial and error on a few systems.  This value seems to be optimal, in as
   much as it stops most of the slow down of the offending programs without
   degrading system performance.


   The two switches for restricting read and write block size work by
   restricting the maximum size of the block that will used with FOSSIL
   functions 18h and 19h.  This is useful for stopping "choppy" behaviour of
   some bbs programs, and to make Hydra (a bidirectional protocoll) perform
   faster.  The default is DISABLED, which means that VFD will read or write
   as large a block as requested by the program.


   The parameter for setting a FOSSIL port to an OS/2 handle sets the file
   handle used internally by VFD to the handle passed to it.  This can be
   used to run DOS doors under an OS/2 BBS or a DOS BBS under an OS/2
   mailer.  Note that this hasn't been throughly tested, but I ran
   Global Wars under Maximus/2 with it.


   6 FOSSIL IMPLEMENTATION

   The following revision 5 calls are fully implemented:

    0:  Set line parameters
    1:  Transmit - wait
    2:  Receive - wait
    3:  Request status
    4:  Initialize driver
    5:  De-initialize driver
    6:  Toggle DTR

    8:  Flush output buffer
    9:  Purge output buffer
    A:  Purge input buffer
    B:  Transmit - no wait
    C:  Non-destructive read ahead
    D:  Keyboard read - no wait
    E:  Keyboard read - wait
    F:  Enable or disable flow control

   11:  Set current cursor location
   12:  Get current cursor location
   13:  Single char ANSI write to screen
   14:  Watchdog (closes DOS session on carrier loss)
   15:  Single char write to screen
   16:  Insert/Delete from timer chain
   17:  Reboot System (closes DOS session)
   18:  Read block
   19:  Write block
   1A:  Toggle Break
   1B:  Return driver info


   The following are partly implemented:

    7:  Returns dummy value 0A08 in ax
   10:  Transmit on/off (bug: transmit will start on receipt of an X-ON byte)


   The following are missing altogether:

   7E:  Install external function
   7F:  Remove external function


   7 KNOWN PROBLEMS

   VFD does not work under a Virtual Boot Machine emulation of MS or IBM
   DOS.  This is because real DOS wants to load itself over the data area
   that VFD has allocated.  This will be solved in a future version, but
   for right now you will have to set COM_FOSSIL to off (disabling VFD)
   when running REAL DOS under OS/2.