ComRdTerm

int ComRdTerm (int portNumber, char buffer[], size_t count, int terminationByte);

Purpose

Reads from the input queue until terminationByte occurs in buffer, count is met, or a timeout occurs. Returns integer value that indicates the number of bytes read from the queue.

Note  This function does not append a terminating ASCII NUL byte to the value in the buffer parameter.

ComRdTerm times out whenever the input queue remains empty during an entire timeout period. This occurs when no data has been received during one timeout period. On a timeout, ComRdTerm returns the number of bytes read and sets rs232err to -99. You can set the timeout period by calling SetComTime.

If the read terminates on the termination byte, ComRdTerm neither writes the byte to the buffer nor includes it in count.

If the termination character is a carriage return (CR or decimal 13) or a linefeed (LF or decimal 10), the function handles it as follows:

• If terminationByte = CR, and if the character immediately following CR is LF, ComRdTerm discards the LF in addition to the CR.
• If terminationByte = LF, and if the character immediately following LF is CR, ComRdTerm discards the CR in addition to the LF.

ComRdTerm includes in the return count only the bytes placed in buffer. If ComRdTerm discards CR or LF because it follows an LF or CR, the function does not count it toward satisfying count.

ComRdTerm returns an error if you have not opened the port or if you pass an invalid parameter value.

Note   When executing a less than 8 bits transfer, LabWindows/CVI does not guarantee the value of the invalid high bits. For a 7 bits transfer, the value of the 8th bit is undefined. 7 bit value "0x60" can be passed back as "0x60" or "0xE0"(0x60|0x80). This depends on the device driver. Most drivers set the value to 0.

Parameters

Input
Name	Type	Description
portNumber	int	A number that indicates the COM port on which to operate. This number maps to the COM port specified by deviceName in the call to OpenCom or OpenComConfig. The portNumber 1, for example, may not necessarily map to COM1. (Linux) The portNumber 1, for example, may not necessarily map to /dev/ttyS0. Valid Range: 1—1,000
count	size_t	The number of bytes to read from the selected port. An error is returned if you pass a value greater than INT_MAX.
terminationByte	int	The byte value used to terminate the read. If the termination character is a carriage return (CR or decimal 13) or a linefeed (LF or decimal 10), the function handles it as follows: If terminationByte = CR, and if the character immediately following CR is LF, ComRdTerm discards the LF in addition to the CR. If terminationByte = LF, and if the character immediately following LF is CR, ComRdTerm discards the CR in addition to the LF. ComRdTerm includes in the return count only the bytes placed in buffer. If ComRdTerm discards CR or LF because it follows an LF or CR, the function does not count it toward satisfying count. ComRdTerm returns an error if you have not opened the port or you pass an invalid parameter value.
Output
Name	Type	Description
buffer	char []	The variable in which to store the data that was read from the selected port. Note  This function does not append a terminating ASCII NUL byte to the value in this parameter.

Return Value

Name	Type	Description
BytesRead	int	Number of bytes read from the input queue. If an error occurs, the return value is a negative error code. Note   This count does not include the termination byte.

Additional Information

Library: RS-232 Library

Include file: rs232.h

LabWindows/CVI compatibility: LabWindows/CVI 3.0 and later