Rockwell Automation Allen-Bradley ControlLogix 1756-MVI Programming Reference Manual page 110

5-22 Serial Port API
Publication 1756-RM004B-EN-P - October 2000
MVIsp_Getch
Syntax:
int MVIsp_Getch(int comport, BYTE *ch, DWORD timeout);
Parameters:
comport port from which data is to be received
ch pointer to BYTE to receive character
timeout amount of time to wait to receive character
Description:
This function is used to receive a single character from a serial port.
comport must be previously opened with MVIsp_Open.
ch points to a BYTE that will receive the character.
All data received from a port is queued after reception from the serial
port. Therefore, some delay may occur between the time a character is
received across the serial line and the time the character is returned by
MVIsp_Getch. This function attempts to retrieve a character from the
reception queue, and return values correspond accordingly.
timeout specifies the amount of time in milliseconds to wait. If timeout
is TIMEOUT_ASAP, the function will return immediately if the queue is
empty. If timeout is TIMEOUT_FOREVER, the function will not return
until a character is retrieved from the reception queue successfully.
If the reception queue is not empty, the oldest character is retrieved
from the queue and MVIsp_Getch returns MVI_SUCCESS. If the queue
is empty, MVIsp_Getch tries to retrieve a character from the queue
until the timeout elapses. If the timeout elapses before a character can
be retrieved, MVI_ERR_TIMEOUT is returned.
Return Value:
MVI_SUCCESS
MVI_ERR_NOACCESS
MVI_ERR_BADPARAM
MVI_ERR_TIMEOUT
Example:
BYTE ch;
if (MVIsp_Getch(COM1, &ch, 1000L) = = MVI_SUCCESS)
putch((char)ch);
See Also:
MVIsp_PutCh
MVIsp_Gets
a character was retrieved successfully
comport has not been opened
invalid pointer
timeout elapsed before character retrieved