ComRead

Reads characters from a communication port. The characters are read from the communication port into a string buffer. If no characters have arrived after the specified timeout, the function returns with a timeout error. If the timeout is 0, the function gets any characters that have arrived from the last call, and returns immediately.

You use the iLength variable to specify the length of the buffer, or the maximum number of characters to read when ComRead() is called. When ComRead() returns, iLength is set to the actual number of characters read. Because iLength is modified by this function, you need to reset it before each call.

You should not treat the string buffer as a normal string - it has no string terminator. Use the StrGetChar() function to extract characters from the buffer.

It is strongly recommended not to call ComRead() while another ComRead() is still pending on the same port, because it can produce unexpected results.

This function is a blocking function. It blocks the calling Cicode task until the operation is complete. This function can only be called from an I/O Server.

Syntax

ComRead(hPort, sBuffer, iLength, iTimeOut)

hPort:

The communication port handle, returned from the ComOpen() function. This handle identifies the table where the data on the associated communication port is stored.

sBuffer:

The buffer into which to put the characters. The actual number of characters read is returned in iLength.

iLength:

The number of characters to read into the buffer. The maximum length you may read in one call is 128 characters. When the function returns, this variable is set to the actual number of characters read.

iTimeOut:

The timeout for the read to complete:

• If iTimeOut = 0 (zero), the function checks for characters in the buffer and returns.
• If iTimeOut > 0, the function returns after this number of seconds - if no characters have been received.
• If iTimeOut < 0, the function waits forever for characters.

Return Value

0 (zero) if the read is successful, otherwise an error is returned.

Related Functions

ComOpen, ComClose, ComWrite, StrGetChar

Example

See ComOpen

See Also

Communication Functions