SERIAL I/O

Name

SERIAL I/O --  Functions for using communication over COM-ports.

Function

nTotalCharacters    COM_COUNT(<nComPort>)
lOldDTRStatus       COM_DTR(<nComPort>,[<lNewDTRStatus>])
lClear              COM_FLUSH(<nComPort>)
lOldHandshake       COM_HARD(<nComPort>,<lNewHandshake>,[<lDTR/DSR>])
lInitialized        COM_INIT(<nComPort>,[<nBaudRate>],[<cParity>], [<nDataLength>],[<nStopBits>])
nMaxCom             COM_NUM()
lStatus             COM_OPEN(<nComPort>,<notused>,<notused>,<notused>, [<lRTSCTS>],[<lXONXOFF>],[<lDebug>])
cData               COM_READ(<nComPort>,[<nLength>])
lOldRTSStatus       COM_RTS(<nComPort>,[<lNewRTSStatus>])
nLength             COM_SEND(<nComPort>,<cString>)
lDeleted            COM_SFLUSH(<nComPort>)
lOldHandshake       COM_SOFT(<nComPort>,[<lNewHandshake>],[<cXONchar>],[<cXOFFchar>])
nOldTimeout         COM_TIMEOUT(<nComPort>[,<nTimeout>])

Description

Category Serial I/O include description of functions for using communication over COM-ports. This function based on multiplatform library EZV24 http://libezV24.sourceforge.net/.

For using need linking clip-com library:

clip -e test.prg -lclip-com

Function COM_COUNT()

 COM_COUNT(<nComPort>) --> nTotalCharacters

This function allows you to determine the number of characters in recieve buffer. This lets you determine how many characters can be read with the COM_READ() function.

If an attempt is made to read the number of characters available in a closed port, the function returns a value of -1.

Function COM_DTR()

 COM_DTR(<nComPort>,[<lNewDTRStatus>]) --> lOldDTRStatus

COM_DTR() queries the DTR signal status. If the second parameter is not supplied, the signal status does not change.

The COM_CLOSE() function resets DTR (to inactive). By contrast, COM_OPEN does not automatically make DTR active!

Function COM_FLUSH()

 COM_FLUSH(<nComPort>) --> lClear

This function allows you to flush all the characters in a receiving buffer. This makes it unnecessary to tediously determine how many characters are currently in the buffer in order to remove them with a read procedure.

COM_FLUSH() guarantees a truly empty buffer. However, a new character can be received between the time that you call a COM_COUNT() and a COM_READ().

Function COM_HARD()

 COM_HARD(<nComPort>,<lNewHandshake>,[<lDTR/DSR>]) --> lOldHandshake

The size of a receiving buffer is always limited. To avoid overflow, and thereby a loss of characters, software or hardware handshakes are usually implemented. During a hardware handshake, the port monitors the RTS signal. If you use this function to switch this handshake on, the signal is activated as soon as the buffer is 75% full. As soon as the buffer content is once again reduced to 50% or less, the port (the RTS signal) is once again released. Some printers use the port signals, DTR (output like RTS) and DSR (entry like CTS) instead of RTS/ CTS, to avoid buffer overflow. In this case, <lDTR/DSR> can be passed with .T..

This function works for data input as well as output.

If you use a hardware handshake, then the RTS signal should no longer be affected by COM_RTS() or COM_MCR().

Function COM_INIT()

 COM_INIT(<nComPort>,[<nBaudRate>],[<cParity>],
 [<nDataLength>],[<nStopBits>]) --> lInitialized

In order to use the serial port after you open it, four operating parameters must have been passed to this function. These operating parameters are the transmission speed (baud rate), the data length, the parity, and the number of stop bits. Tht defaul configuration is "9600 baud, 8N1". This configuration means eight data bits, no parity, and one stop bit. What is important is that all these parameters can be changed while the port is closed. Neither the data buffer or the modem status register (DTR, etc.) are affected.

The port must have been opened previously. It is impossible to initialize a port prior to opening it.

If any or all of the four operating parameters are not designated, or are designated incorrectly, the standard arguments of 9600 baud, no parity, eight data bits, and one stop bit is used.

Function COM_NUM()

 COM_NUM() --> nMaxCom

This function returns the number of the serial interface port available. This is not to say that a return value of 3 necessarily means that ports 1 through 3 are available; for example, COM2 could be missing. Whether or not a serial port can actually be used can be tested using the COM_OPEN() or COM_INIT() functions.

Function COM_OPEN()

 COM_OPEN(<nComPort>,<notused>,<notused>,<notused>,
 [<lRTSCTS>],[<lXONXOFF>],[<lDebug>]) --> lStatus

This function allows you to open a serial interface port.

Function COM_READ()

 COM_READ(<nComPort>,[<nLength>]) --> cData

All characters arriving at the serial port are stored in the appropriate buffer under interrupt control. It is possible to determine the number of characters in the buffer and to read one, several, or all of the characters. If the <nLength> parameter is not specified, then all the characters in the buffer are read.

Remember that you can receive additional characters between calling COM_COUNT() and COM_READ().

Function COM_RTS()

 COM_RTS(<nComPort>,[<lNewRTSStatus>]) --> lOldRTSStatus

COM_RTS() queries the RTS signal status. If the second parameter is not supplied, the signal status does not change.

The COM_CLOSE() function resets RTS (to inactive). By contrast, COM_OPEN does not automatically make RTS active!

Function COM_SEND()

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

Transmits one or more characters from one of four ports.

Function COM_SFLUSH()

 COM_SFLUSH(<nComPort>) --> lDeleted

This function remove all characters from sending buffer not yet transmitted.

Function COM_SOFT()

 COM_SOFT(<nComPort>,[<lNewHandshake>],[<cXONchar>],[<cXOFFchar>]) -->  lOldHandshake

With modem connections, a hardware handshake is impossible, which is why we are making a software handshake available with this function. When a buffer is 75% full, an XOFF character (Ctrl-Q) is transmitted to the remote station. As soon as the buffer has again been emptied to 50% or less, the XON character (Ctrl-S) is transmitted. You can use characters other than Ctrl-S or Ctrl-Q for individual protocols, which would then be taken into account in the situations described above.

When you want to transmit binary data, the software handshake must always be turned off.

Function COM_TIMEOUT()

 COM_TIMEOUT(<nComPort>[,<nTimeout>]) --> nOldTimeout

All read functions may use a timeout mechanism while waiting for characters. If this time limit is exceeded the function abort reading.

The timeout duration is specified by the parameter TenthOfSeconds. This value is given as a multiple of a thenth of a second.