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.

ComRead should not be used if the port is in use by an existing driver.

For high speed transports like TCPIP, it is recommended that timeout be set to 0.

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. Must be a String type variable.

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. Must be a Long type variable.

iTimeOut:

The timeout for the read to complete in seconds:

• 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 in Port mode 0 (and sets error 7 which is the task timeout code), or as soon as bytes are read in Port mode 1. In mode 1 if the read occurred before the timeout, there will be no error.

• If iTimeOut < 0, the function waits forever for characters.

Return Value

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

Related Functions

ComOpen, ComClose, ComWrite, StrGetChar

Example

See ComOpen.

See Also

Communication Functions