     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 N).

         <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

See Also: COM_INIT() COM_SEND()