home *** CD-ROM | disk | FTP | other *** search
/ Power CD-ROM!! 7 / POWERCD7.ISO / prgmming / qbserial / qbserial.doc < prev    next >
Text File  |  1993-09-07  |  47KB  |  953 lines
  1.  
  2.  
  3.  
  4.  
  5.                                  QBserial version 3.20
  6.  
  7.             Serial I/O Routines for QB 4.x, BC 7.x, VBDOS, & FOSSIL Drivers
  8.  
  9.           This library will provide you with serial I/O communications
  10.           routines for use in QuickBASIC 4.x (with or without PDQ), the
  11.           Microsoft Basic Compiler 7.x Professional Development System, and
  12.           Visual Basic for DOS 1.x. No longer are you forced to use the poor
  13.           communications support provided by QB.  This program will allow you
  14.           to control 8250 and 16450 type communications ports (UARTS) at
  15.           speeds of up to 115200 baud. Communication ports 1 - 4, and non-
  16.           standard addresses are supported. You will no longer have problems
  17.           with the DTR signal. DTR is left in the same state it was in when
  18.           before you called this driver, or it can be controlled by your
  19.           program. The serial driver includes XON/XOFF and CTS/RTS
  20.           handshaking. Serial input is interrupt driven, using any IRQ you
  21.           specify (1 - 15), with incoming XOFF flow control (if enabled), or
  22.           RTS flow control (if enabled) to prevent overrunning the input
  23.           buffer. This is referred to as "Normal" mode. 
  24.  
  25.           This driver also has a mode where it will operate with FOSSIL
  26.           drivers (INT 14h interface). Using FOSSIL mode allows you to use
  27.           virtually any type of communications hardware, since the type of
  28.           hardware accessed is dependant on the FOSSIL driver. This mode
  29.           requires that you have a FOSSIL driver loaded in advance. This is
  30.           referred to as "FOSSIL" mode.
  31.  
  32.           The driver was written with Microsoft's C, and compiled with
  33.           version 6.0a of that compiler. This driver is useable with
  34.           QuickBASIC version 4.x, and Basic Compiler 6.x & 7.x PDS  (With or
  35.           without PDQ), and Visual Basic for DOS version 1.x. Basic Compiler
  36.           1.x, QuickBASIC 2.x, and 3.x are not supported by this driver. The
  37.           reason is that versions of QuickBASIC prior to 4.0 do not support
  38.           the extensive multi-language interface that QB4.x has (via the
  39.           DECLARE statement and Microsoft language extensions). Throughout
  40.           this manual QB will be used to refer to both QuickBASIC, the Basic
  41.           Compilers (6.x & 7.x PDS), and Visual Basic for DOS.
  42.  
  43.           Before the driver can be used, the following INCLUDE statement must
  44.           be added to the beginning of your QB program:
  45.  
  46.           '    $INCLUDE: 'qbserial.dec'
  47.  
  48.           The declarations included by this statement specify all the entry
  49.           points into the serial driver. DO NOT change them or the driver
  50.           will not function.
  51.  
  52.           Refer to the included sample programs SIMPLE.BAS, PCBDOOR.BAS, and
  53.           OFFHOOK.BAS. they use most of the calls described below.
  54.  
  55.  
  56.  
  57.         QBSERIAL User Manual - V 3.20                              Page 1
  58.  
  59.  
  60.           Qbserial has two (2) modes of operation: Normal and FOSSIL. The
  61.           mode you operate in is specified in the OpenComm statement (The
  62.           FOS% parameter). In the following sections, where applicable, each
  63.           parameter will be explained as to how it operates in both Normal
  64.           and FOSSIL mode.
  65.  
  66.                                   Port Initialization
  67.  
  68.           OpenComm Port%, IRQ/Stat%, Wlen%, Parity%, Bits%, Baud&, HS%, FOS%
  69.  
  70.           Parameter:     Port%
  71.  
  72.           Normal:   If the specified port is 1 to 4, the driver opens that
  73.                     port. If you specify the port as ZERO (0) the driver
  74.                     enters "LOCAL" mode. This allows you to call the driver
  75.                     with data, but the driver won't send anything. This is
  76.                     useful when working with "doors". if you specify the port
  77.                     as any other value, QBserial will use that as the base
  78.                     address for the port. This allows you to work with non-
  79.                     standard I/O addresses. Note however that if you open a
  80.                     non-standard port, you must specify an IRQ value from 1
  81.                     to 15 - There is no default IRQ when used in this manner.
  82.  
  83.           FOSSIL:   Unlike normal mode, "port" does not necessarily relate to
  84.                     a specific communications port or address. Using a "1"
  85.                     for a port value does NOT necessarily mean COM1. Also
  86.                     unlike QBserial's normal mode, a value other than 1 - 4
  87.                     does NOT refer to a base address of a UART.
  88.  
  89.                     When using FOSSIL mode, "port" refers to a logical
  90.                     device. Port 0 is the first port of a FOSSIL device
  91.                     driver, Port 1 the second, and so on. When used with
  92.                     drivers such as X00.SYS (assuming you didn't remap the
  93.                     ports), port 0 refers to COM1, and port 1 refers to COM2.
  94.                     This will vary depending on the FOSSIL driver used and
  95.                     the device(s) referenced. In most cases it is determined
  96.                     when the FOSSIL driver is installed through some sort of
  97.                     configuration file (or command line options) that relates
  98.                     the physical devices to logical port numbers. However, in
  99.                     order to make the FOSSIL implementation as compatible as
  100.                     possible with "normal" mode, the port number passed will
  101.                     have a value of ONE (1) subtracted from it before
  102.                     referring to the actual FOSSIL port. Therefore to access
  103.                     the first port (port 0), you pass a 1 as you did with in
  104.                     normal mode. Internally, one (1) is subtracted so that
  105.                     port 0 is referenced. This makes the implementation or
  106.                     normal and FOSSIL modes totally transparent.
  107.  
  108.                     Specifying a value of ZERO (0) for the port puts the
  109.                     driver in "local" mode. This is identical to normal mode.
  110.  
  111.  
  112.  
  113.         QBSERIAL User Manual - V 3.20                              Page 2
  114.  
  115.  
  116.           Parameter:     IRQ/Stat%
  117.  
  118.           Normal:   Specifies which interrupt to use with this port. If the
  119.                     value of IRQ% is ZERO (0), then the default IRQ values
  120.                     are used (COM1 & COM3 use IRQ4, COM2 & COM4 use IRQ3).
  121.                     This is what most applications will use. Specify an IRQ
  122.                     value of 1 through 15 when you want to use an IRQ value
  123.                     other than the default. Such as when you want to use
  124.                     IRQ15 with COM3. NOTE: Be careful when choosing an IRQ
  125.                     value other than the default. Most machines use some of
  126.                     the other IRQ inputs for other machine functions such as
  127.                     the Hard drive and system clock. QBserial DOES NOT chain
  128.                     the interrupt, it takes it over entirely. If you choose
  129.                     an IRQ that is used for something already, your machine
  130.                     will most certainly operate improperly.
  131.  
  132.           FOSSIL:   No IRQ value is necessary in FOSSIL mode since all
  133.                     communications tasks are handled outside of QBserial. The
  134.                     IRQ used with a particular "port" will be determined at
  135.                     the time the FOSSIL driver is installed, probably through
  136.                     the same configuration method mentioned above.
  137.  
  138.                     When using FOSSIL mode, this field is now Status. This is
  139.                     a value RETURNED to the programmer when OpenComm has
  140.                     completed. It indicates whether or not the FOSSIL driver
  141.                     initialized properly and is ready to perform
  142.                     communications tasks. A value of 1954h (HEX) or 6484
  143.                     (DECIMAL) indicates a successful initialization. ANY
  144.                     OTHER value indicates a initialization failure. You
  145.                     should terminate your program and inform the user of your
  146.                     program of the problem. Failures could result from the
  147.                     FOSSIL driver not being installed, or not installed
  148.                     properly. If you pass an invalid baud rate (see below),
  149.                     Status will be returned as a ZERO. Otherwise Status will
  150.                     be the actual value returned from the FOSSIL driver in
  151.                     response to initialization. These values other than
  152.                     1954h/6484 may offer a clue as to why the driver did not
  153.                     initialize. These "possible" values would be documented
  154.                     in the documentation for the FOSSIL driver.
  155.  
  156.           Parameter:     Wlen%
  157.  
  158.                     An integer specifying the word length of the serial data.
  159.                     It has a value of 7 or 8. Identical in both normal and
  160.                     FOSSIL modes.
  161.  
  162.           Parameter:     Parity%
  163.  
  164.                     An integer, 0 = NONE, 1 = ODD, 2 = EVEN. Identical in
  165.                     both normal and FOSSIL modes.
  166.  
  167.  
  168.  
  169.         QBSERIAL User Manual - V 3.20                              Page 3
  170.  
  171.  
  172.           Parameter:     Bits%
  173.  
  174.                     Specifies the number of Stop Bits on each serial
  175.                     character. Valid entries are: "1" for 1 Stop Bit, and "2"
  176.                     for 2 Stop Bits per character. Any other value will give
  177.                     1 Stop Bit. Identical in both normal and FOSSIL modes.
  178.  
  179.           Parameter:     Baud&
  180.  
  181.           Normal:   This is a LONG INTEGER representing the desired baud
  182.                     rate. Valid numbers are 0, 300, 1200, 2400, 4800, 9600,
  183.                     19200, 38400, 57600, and 115200. The value you send is
  184.                     NOT checked and I assume you could generate crazy baud
  185.                     rates if desired. 115200 is the absolute maximum rate
  186.                     that can be generated. If you specify a baud rate of ZERO
  187.                     then the serial port is used AS-IS. The rate, word
  188.                     length, & parity are NOT changed. This is useful for door
  189.                     operation since the port is already initialized at the
  190.                     proper settings when you get control.
  191.  
  192.           FOSSIL:   Identical to normal mode with the exception being that
  193.                     the range of selectable baudrates is limited. This is
  194.                     limited by the current FOSSIL specification. The valid
  195.                     baud rates are: 0, 300, 1200, 2400, 4800, 9600, 19200,
  196.                     and 38400. If you pass a value other than one of these
  197.                     valid rates, the driver will not initialize and return a
  198.                     ZERO for status. In FOSSIL mode, if you specify a baud
  199.                     rate of ZERO (0), the Baudrate initialization call is not
  200.                     performed by OpenComm. This *SHOULD* have the same effect
  201.                     that normal mode does by not changing the baudrate, word
  202.                     length, & parity. However, since this is an undefined
  203.                     condition in the FOSSIL specification, there is no way of
  204.                     guaranteeing that the current settings will not be
  205.                     changed during initialization of the driver. If you want
  206.                     a 100% guarantee of the rate setting, you should provide
  207.                     a speed when you do an OpenComm. This is only being done
  208.                     for compatibility with Normal mode.
  209.  
  210.           Parameter:     HS%
  211.  
  212.                     An integer specifying the type of handshake you wish to
  213.                     use between the CPU and Modem (or destination device).
  214.                     Valid numbers are: 0 = NO handshake, 1 = XON/XOFF, 2 =
  215.                     CTS/RTS, 3 = XON/XOFF and CTS/RTS. Identical in both
  216.                     modes.
  217.  
  218.           Parameter:     FOS%
  219.  
  220.                     An integer that specifies which mode the driver will
  221.                     operate in. Zero (0) specifies "Normal" mode, and One (1)
  222.                     specifies "FOSSIL" mode.
  223.  
  224.  
  225.         QBSERIAL User Manual - V 3.20                              Page 4
  226.  
  227.  
  228.                                      Serial Output
  229.  
  230.           To send a string of data out the serial port, you use the
  231.           "Transmit" call as follows:
  232.  
  233.                Temp$ = "Transmit this..."
  234.                Transmit Temp$
  235.  
  236.                     or
  237.  
  238.                Transmit "Send this also...."
  239.  
  240.           If you want to transmit single characters, you can use the
  241.           "WriteChar" function. Transmit calls WriteChar to send the actual
  242.           characters to the port. If you wish to use WriteChar, it has the
  243.           following format:
  244.  
  245.                Status% = WriteChar(Char%)
  246.  
  247.           Char% is the integer value of the character you want to send, it is
  248.           not a string. Status% is an integer returned by WriteChar, it is
  249.           NON-ZERO if the character was actually sent to the port, and ZERO
  250.           if the character was not sent. WriteChar will loop indefinitely on
  251.           CTS hold, XOFF hold, or Transmit Buffer Busy. These loops will exit
  252.           if carrier is lost in FULL or PARTIAL modes and return a ZERO
  253.           status% (This occurs in normal mode ONLY. What happens in FOSSIL
  254.           mode is undefined). WriteChar gives you more low level control of
  255.           the sending of characters, but you must send each character
  256.           separately and monitor its status.
  257.  
  258.           The Transmit function monitors the status of its calls to WriteChar
  259.           and triggers QuickBASIC's User Event trap (UEVENT) if a carrier
  260.           loss occurs in FULL mode. The UEVENT trap (FULL mode) is used by
  261.           default. You can disable the use of this event trap in the event
  262.           you already use the UEVENT trap for something else (PARTIAL mode).
  263.           Therefore, by default, carrier loss detection in your program is
  264.           done with the ON UEVENT GOSUB/UEVENT ON statements. The example
  265.           programs show the use of this method. By default UEVENT is also
  266.           used for catching carrier loss on keyboard input. this is described
  267.           below.
  268.  
  269.  
  270.  
  271.                                       Serial Input
  272.  
  273.           Serial input is managed with three functions: DataWaiting,
  274.           ReadChar, & ClearInputBuffer. DataWaiting is used to test the input
  275.           buffer to see if any characters need to be read from it. ReadChar
  276.           is then called to get the characters. ClearInputBuffer flushes the
  277.           input buffer of any existing characters. Both example programs
  278.           contain a subroutine called "KeyboardInput" that demonstrates the
  279.           use of these calls. It also properly handles input from the local
  280.  
  281.         QBSERIAL User Manual - V 3.20                              Page 5
  282.  
  283.  
  284.           and remote keyboards, and can be the routine you use in your
  285.           programs if you wish. Basically the procedure for reading the
  286.           remote keyboard (serial input) is as follows:
  287.  
  288.                IF DataWaiting THEN
  289.                     C$ = CHR$(ReadChar)
  290.                END IF
  291.  
  292.           The DataWaiting function also monitors the state of the carrier
  293.           detect signal and triggers, in FULL mode, the user event trap
  294.           (UEVENT) if carrier is lost. As you can see a singular trap routine
  295.           catches carrier loss on output as well as input. You will notice
  296.           that the "KeyboardInput" subroutine (in SIMPLE.BAS) loops using
  297.           DataWaiting, and as such, carrier is constantly checked while
  298.           waiting for input. If the ReadChar function is called when no data
  299.           is available (as indicated by DataWaiting) a NULL character is
  300.           returned.
  301.  
  302.           In "Normal" mode, if XOFF/XON, CTS/RTS, or BOTH is enabled, then
  303.           the serial buffer will be protected from overfills. When the buffer
  304.           reaches 75% of capacity, an XOFF will be sent on the serial output
  305.           or RTS will be dropped. When the buffer empties out to 25% of
  306.           capacity, an XON will be sent or RTS raised. The capacity of the
  307.           input buffer is 2048 bytes. In FOSSIL mode, the threshold points
  308.           where flow control occurs and the buffer size, are determined by
  309.           the FOSSIL driver.
  310.  
  311.  
  312.                                  Carrier Detect Control
  313.  
  314.           There are three modes of carrier detection: Full, Partial, & None.
  315.           Each has it own distinct use for a particular purpose. The driver
  316.           defaults to FULL carrier detection unless you change it. The
  317.           following call is used to change control modes:
  318.  
  319.                CarrierDetect 0 [or] 1 [or] 2
  320.  
  321.           Specifying a TWO (2) sets carrier detection to FULL. This is the
  322.           default mode. When a loss of carrier occurs while transmitting,
  323.           polling for input data, or sitting in a wait loop (XOFF/XON or
  324.           CTS), the driver will return to the calling program and trip the
  325.           UEVENT flag. Tripping the UEVENT flag causes Basic to go to the
  326.           User Event trap routine (providing ON UEVENT GOSUB/UEVENT ON has
  327.           been set up in the user program). You should use this mode only if
  328.           you want to use the UEVENT trap for carrier loss detection. You
  329.           cannot transmit data (with the Transmit function) in this mode if
  330.           there is no carrier. You can send characters in this mode with the
  331.           WriteChar function.
  332.  
  333.           Specifying a ONE (1) sets carrier detection to PARTIAL. This mode
  334.           is similar to FULL with the exception that the UEVENT flag is not
  335.           tripped when carrier is lost. This mode should be used if UEVENT is
  336.  
  337.         QBSERIAL User Manual - V 3.20                              Page 6
  338.  
  339.  
  340.           used for something else in your program, or you don't wish to
  341.           utilize UEVENT.
  342.  
  343.           Specifying a ZERO (0) sets carrier detection to NONE. An example of
  344.           this mode would be where "plain Jane" serial I/O is required (such
  345.           as communicating with a "dumb" terminal). In this application there
  346.           are no modem handshake signals (3 wire EIA/RS-232). This mode can
  347.           also be used for talking to a modem when there is no carrier signal
  348.           present (such as dialing and initialization commands). The Transmit
  349.           and WriteChar routines will always transmit data in this mode with
  350.           or without carrier present. Carrier detection must be disabled in
  351.           this mode to prevent calls to Uevent and disable the no carrier
  352.           escape mechanisms built into the XON/XOFF loops. Important: If you
  353.           are using "Normal" mode, and you are using the XOFF/XON protocol,
  354.           with "CarrierDetect 0" set, and receive an XOFF while transmitting,
  355.           you will sit forever waiting for an XON. This is a normal
  356.           condition, with the exception that there is no escape from this
  357.           loop other than XON. If you are using "FOSSIL" mode, this action is
  358.           undefined.
  359.  
  360.  
  361.                            Carrier Loss Detection by Polling
  362.  
  363.           As mentioned above, by default, the UEVENT trap is used to detect
  364.           when a loss of carrier occurs. There is also a function that allows
  365.           you to detect loss of carrier without using the UEVENT trap. While
  366.           I feel that using UEVENT is the simplest way to catch a carrier
  367.           loss in a program, it is possible that UEVENT might need to be used
  368.           by something else. This function is:
  369.  
  370.                X% = CarrierLost
  371.  
  372.           This function call allows to you to 'poll' for the state of
  373.           carrier. CarrierLost returns a NON-ZERO value when there is NO
  374.           carrier, and a ZERO when there IS carrier. CarrierLost is a real
  375.           time function, it returns the current carrier condition at the time
  376.           of the call. This allows you to code simple IF or DO loops to
  377.           detect loss:
  378.  
  379.                IF CarrierLost THEN
  380.                     ..process carrier loss
  381.                END IF
  382.  
  383.  
  384.                                       Modem Status
  385.  
  386.           NOTE:     This function ONLY works in Normal mode. It has no
  387.                     functional equivalent in FOSSIL mode.
  388.  
  389.           The Modem Status register contains bits that convey information
  390.           about the Modem's current state, and what has happened since the
  391.           last status query. In most instances these bits will not be needed
  392.  
  393.         QBSERIAL User Manual - V 3.20                              Page 7
  394.  
  395.  
  396.           for normal serial operations. This was added to provide additional
  397.           information about the device in use.
  398.  
  399.           Normal Mode:
  400.  
  401.                Modem Status Register:
  402.  
  403.               7       6       5       4       3       2       1       0   Bit
  404.                                                                            
  405.              128     64      32      16       8       4       2       1    
  406.            Carrier  Ring   DataSet  Clear   Delta   Delta   Delta   Delta  
  407.            Detect  Signal   Ready  To Send   CD      RI      DSR     CTS   
  408.                                                                            
  409.  
  410.           Bits 0 - 3 of this register report a change in the state of their  
  411.           respective RS-232 (signal) pins. A "1" in any of these bits means
  412.           that it's input has changed since last status read. Reading this
  413.           register clears bits 0 - 3. Bits 4 - 7 report the absolute state of
  414.           their respective RS-232 inputs (These bits are "real time").
  415.  
  416.           To use this function, the Basic statement would be:
  417.  
  418.                value% = ModemStatus
  419.  
  420.           The value returned by ModemStatus depends on the particular bit(s)
  421.           set in the Modem Status register. The corresponding decimal weights
  422.           are listed in the boxes in the above figure. As an example, if you
  423.           were monitoring the register and looking for a Ring Indication, you
  424.           would be looking for a value of 64. NOTE: If you are looking for a
  425.           particular value, you must AND the value you wish to test against
  426.           what ModemStatus returns. So, if you were looking for a Ring
  427.           Indication, you would use:
  428.  
  429.                St% = ModemStatus
  430.                if St% AND 64 then
  431.                     ... Ring detected
  432.  
  433.  
  434.                                                                            
  435.                        Program Termination                      
  436.  
  437.           Since "OpenComm" seizes an interrupt vector, this vector needs to
  438.           be restored BEFORE your program ends. If you neglect to restore
  439.           this vector, you could be risking a crash. The routine used to
  440.           reset the vector is: CloseComm. Only use CloseComm if you specified
  441.           a port value in the OpenComm call (Normal or FOSSIL modes). If you
  442.           specified a port value of ZERO (Local mode) the interrupt vector is
  443.           NOT grabbed, and does not need to be reset. In Normal mode,
  444.           CloseComm resets any UART registers to their original value. In
  445.           FOSSIL mode, how the UART registers are left is undefined.
  446.  
  447.  
  448.  
  449.         QBSERIAL User Manual - V 3.20                              Page 8
  450.  
  451.  
  452.  
  453.                                Data Terminal Ready (DTR)
  454.  
  455.           Everybody that has used QuickBASIC's OPEN COMn statement is very
  456.           familiar with the problems of the DTR signal. Apparently Microsoft
  457.           felt that DTR would never be needed after a program terminates.
  458.           Anybody who has ever tried to write a door, or chain from one
  459.           program to another has cursed this decision at some time during
  460.           their programs development. This driver handles the DTR with a
  461.           different view. When you close the comm channel the DTR signal is
  462.           left in the same state it was when you opened the comm channel. For
  463.           door applications, this is a must. 
  464.  
  465.           A function call is provided however that allows your program to
  466.           control the DTR signal:
  467.  
  468.           DTRcontrol 1 [or] 0           ' 0 = DTR OFF, 1 = DTR ON
  469.  
  470.           Additionally when you use DTRcontrol to change the state of the DTR
  471.           signal it also instructs the driver to leave it this way when the
  472.           CloseComm function is called. Remember that the driver leaves DTR
  473.           the way it found it when OpenComm was called. If you used some
  474.           other method to change DTR after OpenComm was called, it would
  475.           automatically return to that original state when you called
  476.           CloseComm. Therefor only DTRcontrol should be used if you wish to
  477.           change the state of DTR. This appears to operate identically in
  478.           normal and FOSSIL modes.
  479.  
  480.  
  481.                                  Request To Send (RTS)
  482.  
  483.           NOTE:     This function ONLY works in Normal mode. It has no
  484.                     functional equivalent in FOSSIL mode.
  485.  
  486.           Request To Send (RTS) is a hardware flow control signal used to
  487.           tell the remote device to STOP sending data to us. Normally RTS is
  488.           set "on" and data will always flow (or the signal is ignored at the
  489.           remote end). With some communications programs RTS is used to
  490.           temporarily stop a modem from sending data while I/O is done to a
  491.           slow disk. This is especially true with high speed communications
  492.           where there is very little time between interrupts. This function
  493.           is independent of the automatic RTS flow control selected by
  494.           handshake 2 or 3 which tells the remote device to stop sending when
  495.           the input buffer is almost full. This function allows you to
  496.           manually control the state of RTS so you could, for instance, go
  497.           off and write the data somewhere without fear of loosing data.
  498.  
  499.           RTScontrol 1 [or] 0           ' 0 = RTS OFF, 1 = RTS ON
  500.  
  501.           When you use RTScontrol to change the state of the RTS signal it
  502.           also instructs the driver to leave it this way when the CloseComm
  503.           function is called. The driver leaves RTS the way it found it when
  504.  
  505.         QBSERIAL User Manual - V 3.20                              Page 9
  506.  
  507.  
  508.           OpenComm was called. If you used some other method to change RTS
  509.           after OpenComm was called, it will automatically return to that
  510.           original state when you call CloseComm. Therefor only RTScontrol
  511.           should be used if you wish to change the state of RTS. This is
  512.           similar in the way DTRcontrol works.
  513.  
  514.  
  515.                                      Break Control
  516.  
  517.           Some serial devices require a "Break" signal to tell them to "wake
  518.           up" from an idle state and begin communication. A Break is a
  519.           sustained serial low signal (or space) for a period longer than one
  520.           serial character time. To cause QBserial to send a Break signal,
  521.           use the following statement:
  522.  
  523.           BREAKcontrol [1] or [0]            ' 0 = Normal, 1 = Break
  524.  
  525.           Executing a "BREAKcontrol 1" statement causes the serial output
  526.           signal to enter the Break state. The output line will remain in
  527.           this state until a "BREAKcontrol 0" statement is executed. It is up
  528.           to the user to time the duration of the required break signal.
  529.           Using the following lines will give a Break signal of 1 second:
  530.  
  531.                BREAKcontrol 1
  532.                SLEEP 1
  533.                BREAKcontrol 0
  534.  
  535.  
  536.                               Driver Version and Copyright
  537.  
  538.           A function is available to access the drivers version and copyright
  539.           string. This would be used if you wish to display in your final
  540.           product the version of QBserial that your are using, and/or my
  541.           copyright along with yours. In order to access the copyright
  542.           string, the following lines should be added to your Basic program:
  543.  
  544.                     X& = DriverCopyright
  545.                     WHILE (PEEK(X&))
  546.                          CP$ = CP$ + CHR$(PEEK(X&))
  547.                          X& = X& + 1
  548.                     WEND
  549.  
  550.           This places the version/copyright string into string variable CP$.
  551.           This string may now be handled in whatever method you choose.
  552.  
  553.  
  554.                                  Crescent's PDQ Library
  555.  
  556.           An object module for use with PDQ is also included. PDQ does not
  557.           support UEVENT, so all references to UEVENT in the text should be
  558.           ignored. You will need to do carrier checking by polling with the
  559.           CarrierLost function. If you use FULL mode and carrier is lost it
  560.  
  561.         QBSERIAL User Manual - V 3.20                             Page 10
  562.  
  563.  
  564.           will operate the same way as PARTIAL mode. The only exception to
  565.           this is the Transmit function, which when in FULL or PARTIAL mode,
  566.           will not transmit data.
  567.  
  568.  
  569.  
  570.                                         Linking
  571.  
  572.           Since object modules are provided for QB4.x, BC7, VBDOS, and PDQ,
  573.           you will need to select the proper one to use for your program. The
  574.           file QBSER.OBJ should be used for programs compiled with
  575.           QuickBASIC. BC7SER.OBJ is to be used for programs compiled with BC7
  576.           PDS, and Visual Basic for DOS. QBSERPDQ.OBJ is for PDQ users.
  577.           Typical link command lines would look like this: (Please note that
  578.           your command lines will probably be different if you use additional
  579.           libraries to generate your code). The term "yourprog" is meant to
  580.           imply any code modules necessary for linking your project. This
  581.           could one .OBJ file, or many. Please note that compiling any
  582.           linking projects from within the QB/QBX/VBDOS development
  583.           environment(s) is not supported.
  584.  
  585.  
  586.           Link yourprog qbser;               (For QuickBASIC)
  587.  
  588.           Link yourprog bc7ser;              (For BC7 PDS and Visual Basic)
  589.  
  590.           Link yourprog qbserpdq acrtused;   (For PDQ)
  591.                                     ^
  592.                                           See note about acrtused.obj
  593.  
  594.           NOTE:     In the past the file ACRTUSED.OBJ was required to be
  595.                     linked in when using the PDQ replacement libraries. This
  596.                     was necessary to satisfy a dummy external call. It
  597.                     appears that it may no longer be necessary to link with
  598.                     this file anymore. You should try linking without
  599.                     acrtused, and see if a link error occurs. If no error
  600.                     occurs, then you do not need to specify it.
  601.  
  602.  
  603.  
  604.                                     Quick Libraries
  605.  
  606.           If you wish to develop programs from within the environment, you
  607.           will first need to create a Quick library using one of the object
  608.           modules QBSER.OBJ, BC7SER.OBJ, or QBSERPDQ.OBJ. To create a Quick
  609.           lib for QuickBASIC 4.x, use the following Link command:
  610.  
  611.                Link QBSER,,,BQLB4x/q
  612.  
  613.           Where "BQLB4x" is one of the following: BQLB40.LIB, BQLB41.LIB, or
  614.           BQLB45.LIB. Use the one that came with your compiler. If you use
  615.           the wrong BQLB file you might get an "Invalid Format" error when
  616.  
  617.         QBSERIAL User Manual - V 3.20                             Page 11
  618.  
  619.  
  620.           attempting to start QuickBASIC. QBSER.OBJ may also be added to
  621.           Quick Libraries containing other routines and OBJ's as well.
  622.  
  623.           To create a Quick Library for use within QBX (BC7's environment)
  624.           use the following link command (IMPORTANT: be sure to use Link
  625.           v5.xx that came with BC7 or you will receive linking errors):
  626.  
  627.                Link BC7SER,,,QBXQLB/q;
  628.  
  629.           To create a Quick Library for use within Visual Basic's environment
  630.           (VBDOS) use the following link command (IMPORTANT: be sure to use
  631.           Linker that came with VBDOS or you will receive linking errors):
  632.  
  633.                Link BC7SER,,,VBDOSQLB/q;
  634.  
  635.           For PDQ, use the method for QB4.x, since you will be using the
  636.           built in run time routines built into the environment. You ONLY use
  637.           QBSERPDQ.OBJ when you link the EXEcutable file.
  638.  
  639.           Remember too, that you can also add BC7SER.OBJ to Quicklibs
  640.           containing other routines.
  641.  
  642.                                      Specifications
  643.  
  644.           The following port addresses and default interrupts are used in
  645.           Normal mode:
  646.  
  647.                Comm      Base Address        IRQ (Default)
  648.  
  649.                 1          3F8 hex            4
  650.                 2          2F8 hex            3
  651.                 3          3E8 hex            4
  652.                 4          2E8 hex            3
  653.  
  654.           Please read the section explaining the OpenComm function for
  655.           information on how to use addresses or IRQ's other than the
  656.           defaults.
  657.  
  658.  
  659.                                 Registration and Support
  660.  
  661.           QBserial is distributed as shareware. You may copy and distribute
  662.           it freely, as long as you do NOT modify it or add (or remove) any
  663.           files to it.
  664.  
  665.           QBserial is not free software, and requires registration. There are
  666.           two classes of registration which are dependant upon use:
  667.           Commercial and Non-Commercial.
  668.  
  669.           Registration of QBserial is $25 for non-commercial use. Non-
  670.           commercial uses are: Personal use, or use in another shareware
  671.           product such as doors and utilities where you allows others to try
  672.  
  673.         QBSERIAL User Manual - V 3.20                             Page 12
  674.  
  675.  
  676.           the product first before buying and request a nominal registration
  677.           fee. Source code is available as an option for an additional $50.
  678.  
  679.           Registration of QBserial for commercial use is $75. Commercial uses
  680.           are: Inclusion of QBserial into ANY product that is to be sold for
  681.           profit, or any use of this program in a business environment. Any
  682.           program that must be paid for in advance before the product is
  683.           delivered, or use in a corporate environment fits this category.
  684.           Commercial registration includes the source code for QBserial in C
  685.           (Microsoft C), if desired.
  686.  
  687.           Please register your copy!
  688.  
  689.           Software and Shareware distribution houses may charge a nominal
  690.           distribution and copying fee not to exceed $5.00. They may not sell
  691.           this program outright or ask you for the registration fee directly,
  692.           they must tell you that registration is required by the author.
  693.  
  694.           If you have access to a BBS that is an ILink network member, you
  695.           can reach me in the respective Basic conferences. If you do not
  696.           have ILink access anywhere nearby, then you can always contact me
  697.           on the SailBoard BBS at the number listed below. I would prefer if
  698.           you contact me directly on the SailBoard however, as mail networks
  699.           aren't always as reliable as I'd like, and I have missed messages.
  700.           I'll do the best I can to help if you have questions. Bugs will be
  701.           tended to if required, and good suggestions tend to be implemented.
  702.  
  703.  
  704.                                       Source Code
  705.  
  706.           The source code for QBserial is available. The source is available
  707.           by signing at the appropriate place on the registration form. The
  708.           source may be used for you own internal uses only. The source may
  709.           not be distributed by you to any other person, even if you make
  710.           changes to it. Nor can the resulting object code be sold or
  711.           distributed. Modifications can only be used in your end product,
  712.           and without any type of royalty. The source is available only after
  713.           you register QBserial. The license fee for the QBserial source code
  714.           is $50.00 for Non-Commercial users. Commercial users receive the
  715.           source as part of their registration fee if they desire it.
  716.  
  717.                                       Jeff Sumberg
  718.                                Sysop of the SailBoard BBS
  719.                                Ringwood, NJ, 201-831-8152
  720.  
  721.                                         [ or ]
  722.  
  723.                                         Box 212
  724.                                   Ringwood, NJ, 07456
  725.  
  726.  
  727.  
  728.  
  729.         QBSERIAL User Manual - V 3.20                             Page 13
  730.  
  731.  
  732.                                     Acknowledgments
  733.  
  734.           Thanks go out to Mark "Sparky" Herring for using these routines in
  735.           his highly successful Qmail door.
  736.  
  737.           Thanks to Brent Yandell for using these routines in his PCBoard
  738.           File Viewer PCBFV and PCBFX programs.
  739.  
  740.           Thanks to Mark Wilson for some very good ideas in version 2.0.
  741.           Thanks to Michael Conley for finding a real time sensitive
  742.           interrupt problem and for providing very useful information.
  743.           Thanks to Jeffrey Morley (author of ZipLab) for testing.
  744.  
  745.  
  746.                                Distribution File Contents
  747.  
  748.            QBSER.OBJ     QBserial object module for use with QuickBASIC
  749.                          version 4.x.
  750.  
  751.            QBSERPDQ.OBJ  QBserial object module for use with PDQ and
  752.                          QuickBASIC 4.x or PDQ with Basic Compiler 7.x (NEAR
  753.                          string model).
  754.  
  755.            BC7SER.OBJ    QBserial object module for use with Basic Compiler
  756.                          6.x, Basic Compiler 7.x (NEAR or FAR string models),
  757.                          and Visual Basic for DOS.
  758.  
  759.            ACRTUSED.OBJ  Dummy object module to satisfy an external reference
  760.                          when linking with PDQ files. May no longer be
  761.                          necessary. See Text.
  762.  
  763.            OFFHOOK.BAS   Sample Basic program. Used to take modem off hook.
  764.                          References PCBoard data files for port info. Can
  765.                          also be used stand alone.
  766.  
  767.            PCBDOOR.BAS   Very simple frame for creating a door in PCBoard.
  768.                          Should be used ONLY as a guide.
  769.  
  770.            SIMPLE.BAS    Very simple "do nothing" program offering examples
  771.                          of how to call QBserial functions.
  772.  
  773.            QBSERIAL.DEC  Function declarations for QBserial.
  774.  
  775.            QBSERIAL.DOC  QBserial Documentation (this file).
  776.  
  777.            READ.ME       Latest changes to QBserial.
  778.  
  779.            REGISTER.FRM  QBserial Registration form. Please Register your
  780.                          copy.
  781.  
  782.            FILE_ID.DIZ
  783.            DESC.SDI      BBS description files.
  784.  
  785.         QBSERIAL User Manual - V 3.20                             Page 14
  786.  
  787.  
  788.  
  789.                                  Changes and Revisions
  790.  
  791.           06/09/89  1.0  Initial Release
  792.  
  793.           06/21/89  1.1  Added carrier detection control. Calling program can
  794.                          turn detection off and on as desired. Necessary if
  795.                          data sending/receiving required if carrier isn't
  796.                          present.
  797.  
  798.           09/01/89  1.2  Fixed a bug in Readchar where 'extended' characters
  799.                          (ASCII 128 to 255) were causing an Illegal Function
  800.                          Call in the CHR$() conversion (because they were
  801.                          being returned as negative numbers). Extended
  802.                          character may now be received properly. Added three
  803.                          new functions: CDtrap, CarrierLost, and DTRcontrol.
  804.  
  805.  
  806.           03/24/90  1.5  Added support for Basic Compiler 7.0 PDS and PDQ.
  807.                          Added sections to manual about Linking, Source code
  808.                          availability, and updated section on Quicklibs.
  809.                          Separate object files now supplied for QB, BC7, and
  810.                          PDQ.
  811.  
  812.           05/01/90  1.6  Oops! PDQ users found out fast that I forgot to
  813.                          compile the PDQ module with stack checking removed.
  814.                          I also forgot to include ACRTUSED.OBJ to satisfy
  815.                          linking requirements. Sorry 'bout that! Released
  816.                          only as beta to those that needed it.
  817.  
  818.           11/01/90  2.0  Added capability to specify non-standard port
  819.                          addresses and which IRQ to use when the port is
  820.                          opened. Removed CDtrap function. Created new carrier
  821.                          detection modes using the CarrierDetect function. (0
  822.                          = NONE, 1 = PARTIAL, 2 = FULL). Also added
  823.                          DriverCopyright function to allow program access to
  824.                          the driver version.
  825.  
  826.           02/08/92  2.10 Added RTS flow control support. RTS will be used to
  827.                          control data coming in to QBserial when the
  828.                          handshake is set to 2 (CTS/RTS). Removed necessity
  829.                          for SERIAL.LIB library file by adding inline
  830.                          assembler that performed the routines that were
  831.                          previously included in that library. QBserial is now
  832.                          compiled with Microsoft C 6.0 which will give
  833.                          smaller, faster, and more efficient code than QuickC
  834.                          could generate. This is especially true in the
  835.                          interrupt area. Added new function RTScontrol, to
  836.                          allow program to control RTS line directly.
  837.                          Increased size of input buffer from 1024 to 2048
  838.                          bytes. Changed method in which interrupt controller
  839.                          mask bits were set & cleared. Corrected error found
  840.  
  841.         QBSERIAL User Manual - V 3.20                             Page 15
  842.  
  843.  
  844.                          in documentation describing the function of
  845.                          CarrierDetect.
  846.  
  847.           06/20/92  2.20 Added support for extended IRQs. QBserial now
  848.                          supports IRQ 8 - 15. Added a new sample program to
  849.                          the QBserial distribution package (OFFHOOK.BAS) to
  850.                          demonstrate usage of QBserial.
  851.  
  852.           07/05/92  2.25 While experimenting with some programs of my own I
  853.                          found a some errors in the disabling of the IRQ
  854.                          masks on the Interrupt Controller when exiting from
  855.                          QBserial. The program has been changed so that if
  856.                          the IRQ you specify is already turned ON when
  857.                          OpenComm executes, QBserial will leave it ON when
  858.                          you do a CloseComm. In versions since 2.10, the IRQ
  859.                          mask was always turned OFF when CloseComm was
  860.                          executed. This caused other communications programs
  861.                          such as BBS's that don't reset the port when
  862.                          returning from QBserial to appear to "lock up" when
  863.                          they regained control.
  864.  
  865.           11/01/92  3.00 Added the ability for QBserial to use FOSSIL
  866.                          drivers. Modified the OpenComm call to allow the
  867.                          programmer to specify which mode to operate in. The
  868.                          QBSERIAL.DEC file has changed and the one provided
  869.                          with this version MUST be used when upgrading to
  870.                          this version. Added new function: ModemStatus, to
  871.                          read the Modem Status register of the UART. This is
  872.                          a normal mode function only.
  873.  
  874.           06/12/93  3.10 This version is a bug fix version. Several minor
  875.                          errors and omissions have been reported by users,
  876.                          and these have been corrected in this version. These
  877.                          include:
  878.                          - Modified the QBSERIAL.DEC file to allow Qbserial
  879.                          to work with Visual Basic for DOS. This is because
  880.                          of an unknown, undocumented change in the way
  881.                          DECLARE works in Visual Basic for DOS.
  882.                          - ClearInputBuffer did not work in FOSSIL mode.
  883.                          - Modified OpenComm to reset flow control flags,
  884.                          buffer pointers, etc. It was found that if a port
  885.                          was opened, used, closed, then opened again without
  886.                          program termination or chain from program to
  887.                          program, that the Flow Control mode would be wrong
  888.                          or inoperative. The input buffer also was not
  889.                          flushed when a port was opened. This was because
  890.                          initialization to these flags and pointers was only
  891.                          being done when the EXE was loaded, not during
  892.                          OpenComm. These are done within OpenComm.
  893.  
  894.           09/01/93  3.20 Modified the OpenComm call to allow the programmer
  895.                          to specify the number of Stop Bits required (1 or 2)
  896.  
  897.         QBSERIAL User Manual - V 3.20                             Page 16
  898.  
  899.  
  900.                          for communication. Important: The QBSERIAL.DEC file
  901.                          has changed and the one provided with this version
  902.                          MUST be used when upgrading to this version. Added a
  903.                          new function "BREAKcontrol" to allow the programmer
  904.                          to send Break signals to remote devices.
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.         QBSERIAL User Manual - V 3.20                             Page 17