SerString

(Engine-Level Function)

Description:	Serial Port String Receive. This function reads the receive buffer until a string is encountered and returns the final offset in the buffer.
Returns:	Numeric
Usage:	Script Only.
Function Groups:	Serial Port,  String and Buffer
Related to:	COMPort | MakeBuff | SerCheck | SerIn | StrLen | SerOut | SerRcv | SerRTS | SerSend | SerStrEsc | SerWait
Format:	SerString(Buffer, Offset, Port, String)
Parameters:

Buffer

Required. Any text buffer to write the received data to. It must already exist - either by creating it with a function such as MakeBuff, or assignment of a text constant.

Offset

Required. Any numeric expression which gives the offset from 0 where SerString will start writing data to Buffer.

Port

Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.

String

Required. Any text expression which gives the terminating string.

Comments:

Data is read until the receive buffer is empty, Buffer is full, or String is encountered. This is useful for reading the serial port receive buffer where the end of a message is signaled by a particular byte sequence. The optional return value is the final offset after reading into Buffer, unless String was encountered, or Offset is negative. If String was encountered, the return value is the negative of the final offset after reading in the String sequence. If Offset is negative, Offset is returned and nothing is done. The return value can be used in successive SerString calls as the Offset parameter to fill Buffer until String is encountered.

Example:

If (! Valid(pos) || pos > 0) && SerWait(2, 1)
{ Pos is positive until "END" };
[
  pos = SerString(response { Buffer },
  Cond(Valid(pos), pos, 0) { Start at the
  beginning, do successive reads },
  2, "END" { Port no. & terminating string });
]

This reads from serial port 2 until the string "END" is encountered. As the message is read from the serial port, pos will be StrLen(response) and "END" will be the final character sequence in response - when it is received, pos will become -StrLen(response).