COM_OPEN()
 Opens the port and initializes the buffer
------------------------------------------------------------------------------
 Syntax

     COM_OPEN(<nComPort>,<nBufferIn>,<nBufferOut>,
        [<lTrapMode>]) --> lStatus

     Tip:  The new optional parameter is an enhancement over previous
     versions!

 Arguments

     <nComPort>  Designates the number of the port (1 to 4).

     <nBufferIn>  Designates the size of the receiving buffer up to 64
     kByte.  The default value is 100 bytes.

     <nBufferOut>  Designates the size of the sending buffer for
     background transmission up to 64 kByte.  The default specification is a
     no send buffer.

     <lTrapMode>  Designates when the port triggers an interrupt.  When
     this parameter is .T., the port only triggers an interrupt while
     receiving data, and not as a result of transmission failure.  The
     default value causes the port to trap all occurrences.

 Returns

     COM_OPEN() returns .T. when the port has been successfully opened and
     you can select the buffer.

 Description

     This function allows you to open a serial interface port from COM1 to
     COM4.  These ports have particular I/O addresses.  For example,
     CA-Clipper Tools uses 3F8H as a base address for COM1.  DOS or BIOS
     routines are not even involved; I/O addresses are not read from the BIOS
     data area.  The default values described in the Introduction to this
     chapter are applied, or the values are set using COM_SETIO().  The
     availability of a port is tested for these addresses before the port is
     opened.

     Receiving Data
     A buffer of up to 64 kByte can be reserved for each com port.  All
     arriving characters are saved here, even when the CA-Clipper program is
     active elsewhere with another process.  The number of characters in the
     buffer can be checked and partially read.

     Sending Data
     You can also reserve a sending buffer.  If you reserve a sending buffer,
     COM_SEND() controls the interrupt function for data transmission, which
     means that the interrupt occurs in the background.  Several functions
     are available to control the send buffer.

     Interrupts during Transmission Errors
     If <lTrapMode> is specified as .T., the UART port only triggers an
     interrupt when there is data incoming or interrupt driven data being
     sent.  Events connected with the MSR or the LSR are no longer taken into
     account.  This affects the status signal and particularly affects
     transmission errors.

     This capability was added as the result of research that indicated that
     some adapter ports seemed to trigger interrupts for no reason.  These
     interrupts are caused by "trash" on the lines; as a rule, serial port
     incoming lines were not terminated (electronically closed).  Overflowing
     interrupts can disturb program execution and lead to significant loss of
     performance.

 Notes

     Important!  In contrast to other programming languages, like Basic,
     COM_OPEN() and COM_INIT() do not affect any control signals.  If you
     want to address a modem at the serial interface through CA-Clipper, you
     must set the DTR and every other signal using the correct CA-Clipper
     Tools functions.

     .  Buffer size can be between 100 bytes and 64 kByte.  Settings
        too large or too small are corrected, increased or decreased,
        accordingly.

     .  To ensure compatibility with earlier versions of CA-Clipper
        Tools, the <nComPort>, <nBufferIn>, and <lTrapMode> parameters can be
        used without <nBufferOut> (see the example).

 Examples

     .  Open a port with monitoring:

        IF COM_NUM() > 0
           nBuffSize := 4000                     // 4000 byte buffer

           ComOk  :=  COM_OPEN(1, nBuffSize)     // Open COM1

           IF .NOT. ComOk
              ? "Port cannot be opened  !"
           ENDIF
        ENDIF

     .  Open COM3 with the corresponding send and receive buffer:

        ? COM_OPEN(3, 1000, 1000)           // .T. when successful

     .  Trigger interrupts for incoming data only, not for
        transmission failure (receiving buffer 1000 characters, normal
        transmission):

        ? COM_OPEN(3, 1000, .T.)            // .T. when successful