     COM_SEND()
     Transmits data directly or in the background

     Syntax

         COM_SEND(<nComPort>,<cString>) --> nLength

         Tip:  An enhancement over previous versions is that there are no new
         parameters!

     Arguments

         <nComPort>  Designates the port (1 to N) from which transmission
         occurs.

         <cString>  Designates the string that is transmitted by the selected
         port.  If you only need to transmit a single character, then the second
         parameter can also be numeric and thereby pass the ASCII character code
         directly.

     Returns

         When transmission is successful, a 0 is returned.  If transmission is
         not successful, the number of characters that have not been transmitted
         or could not be placed in the sending buffer is returned.

     Description

         COM_SEND() transmits one or more characters from one of four ports.
         This transmission can be interrupt driven (i.e. occurs in the
         background).  The third parameter of COM_OPEN() determines whether or
         not the transmission is direct or occurs in the background.

         "Normal" Transmission
         During "normal" transmission, program execution can continue only when
         all of the characters have been sent to the port.  A unique situation
         presents itself when the hardware handshake is activated.  As soon as
         the receiving station deactivates the CTS signal from the sending
         station, any transmission is immediately stopped.  To prevent the
         CA-Clipper program from hanging, COM_SEND() is terminated and a numeric
         value representing the number of characters not yet sent is returned.
         COM_CTS() can determine if CTS input has been deactivated by the remote
         station.  The software handshake is not supported in this mode!

         Background Transmission
         The background mode supports software and hardware handshakes.  The
         handshake automatically occurs in the background.  Several new functions
         are available to help you maintain control of the transmission buffer in
         this situation.  For example, COM_SMODE() allows you to determine if the
         buffer is waiting for an XON character to release the software
         handshake.  Since this kind of wait can prove futile, you can use
         COM_FLUSH() from within the program to empty the transmission buffer.

     Notes

         ”  The handshake is only supported when the transmission buffer
            is sending in the background.  Use small packets during direct
            transmissions, and regularly query COM_SOFT_R().

         ”  Software and hardware handshakes are switched on using the
            COM_SOFT() and COM_HARD() functions.

     Examples

         ”  This is an example of "normal" transmission at port 1, with no
            transmission buffer open:

            COM_OPEN(1, 1000)                    // Receiving buffer only
            COM_HARD(.T.)                        // Hardware handshake
            ACCEPT "Please input name " TO cInput
            nRest := COM_SEND(1, cInput)         // 1st attempt to transmit

            DO WHILE nRest > 0
               cInput := RIGHT(cInput, nRest)    // Characters not yet sent
               nRest := COM_SEND(1, cInput)
            ENDDO

         ”  Here is an example for background or interrupt controlled
            transmission at port 1.  Everything else can proceed through "normal"
            transmission:

            COM_OPEN(1, 1000, 1000)           // 1000 byte transmission buffer
            nRest := COM_SEND(1, "Attempt")   // Place characters in buffer

See Also: COM_OPEN() COM_INIT() COM_HARD()