home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 15 / CDACTUAL15.iso / cdactual / program / basic / QBFC100.ZIP / QBFCOMMS.DOC < prev    next >
Encoding:
Text File  |  1990-10-20  |  10.2 KB  |  316 lines
  1.  
  2.                     QuickBASIC FOSSIL Comms Routines
  3.                             by Tom Collins
  4.                               Version 1.0
  5.                                10-19-90
  6.  
  7.    Intro
  8.    -----
  9.  
  10.    With the introduction of the FOSSIL (Fido-Opus-SEADog standard interface
  11.    layer), the BBS community has ushered in a way to write fast
  12.    computer-independent communications routines for any computer that
  13.    supports a FOSSIL implementation.  FOSSILs provide a high-level
  14.    interface to the computer's RS-232 port via a series of assembly
  15.    language calls.
  16.  
  17.    Unfortunately, FOSSIL implementations are a rarity among QuickBASIC
  18.    programmers, as many either don't understand or don't want to get
  19.    involved in writing assembly-language routines.
  20.  
  21.    With the release of the X00 FOSSIL driver, version 1.20c, Ray Gwinn
  22.    included what's called a HLLAPI interface into releases of X00.  This
  23.    provides the QuickBASIC programmer with a good way to invoke FOSSIL
  24.    functions without using QB's CALL INTERRUPT routines.  Unfortunately,
  25.    the QuickBASIC programmer still had to write generic FOSSIL routines
  26.    using Gwinn's HLLAPI modules.  QBFCOMMS relives the programmer of this
  27.    hassle by providing simple, QB-callable routines for FOSSIL interface.
  28.  
  29.    Included
  30.    --------
  31.  
  32.    Included in this archive is:
  33.  
  34.       QBFCOMMS.DOC   - What you're reading now.
  35.  
  36.       QBFCOMMS.BAS   - Source code for the QuickBASIC FOSSIL interface
  37.                        routines.
  38.  
  39.       QBFCOMMS.BI    - Header file containing declarations for all of the
  40.                        QBFCOMMS functions, as well as some miscellaneous
  41.                        CONSTs.
  42.  
  43.       QBFCOMMS.OBJ   -
  44.       QBFCOMMS.LIB   - LINKable compiled versions of the above.
  45.  
  46.       QBFCDEMO.EXE   -
  47.       QBFCDEMO.BAS   - Demo illustrating how to call QBFCOMMS functions.
  48.  
  49.       DEMO.BAT       - Batch file to run QBFCDEMO.EXE.
  50.  
  51.       INQB.BAT       - Batch file illustrating how to invoke QB.EXE for the
  52.                        QBFCDEMO.BAS and QBFCOMMS.BAS files.
  53.  
  54.       QBFCDEMO.MAK   - Used by QB.EXE when running INQB.BAT.
  55.  
  56.    Not Included
  57.    ------------
  58.  
  59.    To make this package work, you'll need QBX00.OBJ from a recent X00
  60.    release, as well as QuickBASIC v4.5.  (v4.0 may work... dunno)
  61.  
  62.    Warranty
  63.    --------
  64.  
  65.    Yea, right.
  66.  
  67.    Shareware?
  68.    ----------
  69.  
  70.    QBFCOMMS isn't shareware.  It's free for all to use and learn from.  If,
  71.    however, you use QBFCOMMS in a program of yours, please give credit to
  72.    me for QBFCOMMS.
  73.  
  74.    Usage
  75.    -----
  76.  
  77.    1.  Get a recent X00 release (the version used for testing these
  78.    routines was v1.23j).  Included in the X00 archive (somewhere!) is
  79.    QBX00.OBJ.  Extract this file, the FOSSIL.DOC file and the FOSSIL.CHT
  80.    file.
  81.  
  82.    2.  If you plan to write and test applications using QB.EXE, the
  83.    QuickBASIC integrated environment, you'll need to create a .QLB and a
  84.    .LIB version of QBX00.OBJ.  If you're just going to use BC.EXE, the
  85.    command-line compiler, skip this step.
  86.  
  87.    To create QBX00.QLB from QBX00.OBJ, try:
  88.       LINK /Q QBX00,,,BQLB45.LIB
  89.  
  90.    To create QBX00.LIB from QBX00.OBJ, do this:
  91.       LIB QBX00 +QBX00;
  92.  
  93.    (LINK.EXE, LIB.EXE and BQLB45.LIB should be on your original QuickBASIC
  94.    diskettes)
  95.  
  96.    3.  Invoke a FOSSIL driver on your system.  The driver can be X00,
  97.    loaded as a TSR or a device driver, BNU or any other FOSSIL driver.  For
  98.    testing, it's best to use X00 until everything works.
  99.  
  100.    4.  Run DEMO.BAT.  This will illustrate most of the functions provided
  101.    in QBFCOMMS.  You should verify that the demo can transfer information
  102.    between two computers.  The computers should be connected via modem over
  103.    a phone line or with a cable and a NULL modem adapter.  On the computer
  104.    that's not running the demo, invoke Procomm or another terminal program.
  105.    Until the demo can transfer information between computers, there's no
  106.    point in writing applications using QBFCOMMS.
  107.  
  108.    5.  When you're satisfied that the demo can transfer information
  109.    properly, look at the demo source code, the QBFCOMMS source code, and
  110.    Gwinn's FOSSIL.DOC and FOSSIL.CHT to determine what functions you'll
  111.    need in your application.  Remember QBFCOMMS provides a simple,
  112.    QB-callable set of functions for interfacing to the FOSSIL, so don't
  113.    dwell on the assembly-language interface details in FOSSIL.DOC.  Just
  114.    make a note of the functionality of the FOSSIL.
  115.  
  116.    6.  Write and test your own applications using QBFCOMMS.
  117.  
  118.    Compiling and Linking
  119.    ---------------------
  120.  
  121.    If you're using BC.EXE for your QB work, you can link QBFCOMMS into your
  122.    routine (assumed to be called MYPROG.BAS) like this:
  123.  
  124.        BC myprog.bas /o;
  125.        LINK myprog.obj+qbfcomms.obj+qbx00.obj;
  126.  
  127.    If you're using QB.EXE to develop your programs, do this:
  128.  
  129.       a)  Create QBX00.QLB and QBX00.LIB, as outlined above.
  130.  
  131.       b)  Create a MYPROG.MAK file containing:
  132.  
  133.             MYPROG.BAS          (line 1)
  134.             QBFCOMMS.BAS        (line 2)
  135.  
  136.           and invoke QB.EXE like this:
  137.  
  138.             QB myprog /lqbx00.qlb
  139.  
  140.       With this setup, when you're done with MYPROG.BAS, just tell QB to
  141.       make a standalone EXE to create MYPROG.EXE.
  142.  
  143.    Functions Supplied
  144.    ------------------
  145.  
  146.    FossilAnsiPrint% (A$)
  147.  
  148.       Prints A$ on the screen using ANSI processing.
  149.  
  150.    FossilBIOSPrint% (A$)
  151.  
  152.       Prints A$ on the screen using the PC's BIOS functions.
  153.  
  154.    FossilBreak% (Port%, Ctrl%)
  155.  
  156.       Sends a BREAK signal to the modem.  If Ctrl% is a 1, it starts
  157.       sending the BREAK.  If it is 0, the function stops sending the BREAK.
  158.  
  159.    FossilCtrlKCtrlC% (Port%, Ctrl%)
  160.  
  161.       Enables or disables extended ^K and ^C FOSSIL checking.  See the
  162.       values in QBFCOMMS.BI for possible Ctrl% values.
  163.  
  164.       Returns:
  165.          1 - ^C or ^K has been received
  166.          0 - ^C or ^K hasn't been received
  167.  
  168.    FossilDTR% (Port%, Ctrl%)
  169.  
  170.       Sets or resets the DTR line of a port.  Ctrl% equal to 1 sets DTR,
  171.       Ctrl% equal to 0 resets it.
  172.  
  173.    FossilDeactivate% (Port%)
  174.  
  175.       Deinitializes the FOSSIL for a given port.
  176.  
  177.    FossilFlowControl% (Port%, Ctrl%)
  178.  
  179.       Sets up the flow control (XON/XOFF, etc) to be used on a port.  See
  180.       QBFCOMMS.BI for possible Ctrl% values.
  181.  
  182.    FossilFlush% (Port%)
  183.  
  184.       Forces pending output to be sent to the port.
  185.  
  186.    FossilGetb% (Port%, Buffer$, Length%)
  187.  
  188.       Gets a buffer of data from a port.
  189.  
  190.       Returns:
  191.          The number of characters actually received.
  192.  
  193.       Warning:
  194.          See the QBFCDEMO program for how to use this function.  Incorrect
  195.          use will cause string space corrupts and other nasties to occur.
  196.  
  197.    FossilGetch$ (Port%)
  198.  
  199.       Gets and returns a character from a port, or a null string if no data
  200.       is available.
  201.  
  202.    FossilInfo% (Port%, Rev%, Ver%, ID$, ISZ%, IFR%, OSZ%, OFR%, SW%, SH%, Baud&)
  203.  
  204.       Gets a bunch of information about the FOSSIL:
  205.  
  206.          Rev%  - FOSSIL revision this driver follows
  207.          Ver%  - FOSSIL version this driver follows
  208.          ID$   - ID string ("BNU Fossil Driver")
  209.          ISZ%  - Input buffer size
  210.          OSZ%  - Output buffer size
  211.          IFR%  - Input buffer bytes free
  212.          OFR%  - Output buffer bytes free
  213.          SW%   - Screen width
  214.          SH%   - Screen height
  215.          Baud& - FOSSIL current baud rate (300,1200...)
  216.  
  217.    FossilInit% (Port%)
  218.  
  219.       Initializes a port for communications.
  220.  
  221.       Returns:
  222.          0 - Success
  223.          1 - Couldn't initialize the port
  224.  
  225.    FossilInkey% ()
  226.  
  227.       Reads a key from the local keyboard and returns the scan code for the
  228.       key received.  If no key was available, -1 is returned.
  229.  
  230.    FossilInkeyWait% ()
  231.  
  232.       Just like FossilInkey(), 'cept this function will wait forever for a
  233.       keystroke before returning.
  234.  
  235.    FossilLocate% (Row%, Column%)
  236.  
  237.       Moves the cursor to a given screen row and column.  The coordinates
  238.       place (0,0) at the upper left corner of the screen.
  239.  
  240.    FossilPeek$ (Port%)
  241.  
  242.       Looks into the FOSSIL input buffer to see if a byte is available.  If
  243.       it is, that byte is returned (but not removed from the buffer).  If
  244.       nothing is available, the function returns "".  Use FossilGetch() to
  245.       remove the data from the input buffer.
  246.  
  247.    FossilPurgeInputBuf% (Port%)
  248.  
  249.       Purges all pending input from the FOSSIL input buffer.
  250.  
  251.    FossilPurgeOutputBuf% (Port%)
  252.  
  253.       Purges all pending data from the FOSSIL output buffer.
  254.  
  255.    FossilPutb% (Port%, Buffer$)
  256.  
  257.       Writes a string of data to a port and returns with the number of
  258.       characters actually written.  If this number is less than the length
  259.       of the string, the input buffer filled up as a result of the
  260.       FossilPutb() call.
  261.  
  262.    FossilPutch% (Port%, Char$)
  263.  
  264.       Writes a character to the output buffer.
  265.  
  266.       Returns:
  267.          1 - Success
  268.          0 - No room in output buffer for character
  269.  
  270.    FossilPutchWait% (Port%, Char$)
  271.  
  272.       Just like FossilPutch() except this function will wait forever until
  273.       it can send the requested character.
  274.  
  275.       Returns:
  276.          The port status (see FossilStatus())
  277.  
  278.    FossilReadCursor% (Row%, Column%)
  279.  
  280.       Gets the current screen cursor position.
  281.  
  282.    FossilReboot% (Ctrl%)
  283.  
  284.       Reboots the computer.  If Ctrl% is 1, a warm boot is invoked.  If
  285.       Ctrl% is 0, a cold boot is performed.
  286.  
  287.    FossilSetBaud% (Port%, BaudRate&)
  288.  
  289.       Sets the baud rate for a port.  The baud rate should be 300, 600,
  290.       1200, 2400, 4800, 9600, 19200 or 38400.
  291.  
  292.       Returns:
  293.          The port status (see FossilStatus())
  294.  
  295.    FossilStatus% (Port%)
  296.  
  297.       Gets the status of a port.  Various values are OR'd together, as
  298.       defined in the QBFCOMMS.BI file.  See the QBFCDEMO.BAS file for an
  299.       example.
  300.  
  301.    FossilWatchdog% (Port%, Ctrl%)
  302.  
  303.        Turns on (Ctrl% = 1) or off (Ctrl% = 0) the FOSSIL watchdog
  304.        function.  Watchdogs automatically reboot your computer if the
  305.        carrier drops.
  306.  
  307.    For more information on how the functions work, take a look at
  308.    FOSSIL.DOC.  To see examples of using the functions, see QBFCDEMO.BAS.
  309.    That's why it's included.
  310.  
  311.  
  312.    Good Luck!
  313.  
  314.    -- Tom Collins
  315.  
  316.