(Engine-Level Function)
| Description: | Serial Port Receive With Escape. This function reads the receive buffer until a specified character (the 'escape' character) is encountered, incrementing an offset counter for each character read that is not the Escape character. It is assumed that, where the message contains the Escape character as part of the message, that character is 'escaped' by being doubled. |
| Returns: | Numeric |
Usage:  |
Script Only. |
| Function Groups: | Serial Port |
| Related to: | COMPort | MakeBuff | SerCheck | SerIn | StrLen | SerOut | SerRcv | SerRTS | SerSend | SerString | SerWait |
| Format: |
SerStrEsc(Buffer, Offset, Port, Escape) |
| Parameters: |
| Buffer |
| Required. Any text variable to write the received data. This text buffer must already exist. It could be created by another function such as MakeBuff, or by assignment of a text constant. |
| Offset |
| Required. Any numeric expression which gives the offset from zero where SerStrEsc will start writing data to Buffer. If Offset is negative, Offset is returned and nothing is done. |
| Port |
| Required. Either a numeric expression for the serial port number (opened with a ComPort function) or any stream value. |
| Escape |
| Required. Any numeric expression which gives the terminating character code. This must be in the range 0 to 255 to be valid. A value of -1 means that no such code exists. |
| Comments: | Data is read until the receive buffer is empty, Buffer is full, or an Escape value is encountered. If two successive Escape values are received, one is written to Buffer and reading continues normally. Otherwise, reading is terminated if the character following the Escape is not another Escape character. This is useful for reading the serial port receive buffer where the end of a message is signaled by a particular byte sequence. The byte following the final Escape is placed in the buffer. The value returned by the function increases with each character read. When a single instance of the Escape value is encountered, the return value is the negative of the final offset before reading in the Escape character (the Escape character is discarded). The return value can be used in successive SerStrEsc calls as the Offset parameter to fill Buffer until a Escape character is encountered. |
Example:
response = MakeBuff(1, 32) { Fill the buffer with spaces };
...
{ Read port until DLE encountered }
If (! Valid(pos) || pos >= 0) && SerWait(2, 1) { Variable becomes negative when <DLE> encountered };
[
pos = SerStrEsc(response { Buffer },
PickValid(pos, 0) { Start at pos or 0 },
2 { Port number },
0X10 { Data end code (<DLE> or decimal 16) });
]
{ DLE found, all done } If Pos < 0 ProcessResponse;
[
{ calculate the size of the response message }
RespSize = pos * -1;
]
ZText(10, 10, response, 0, 0);
This reads all characters from serial port 2 until a single byte 0x10 is encountered. The byte following the escape code will be the final character in response. When the escape is received, pos will become a pointer to where the last byte was written into the buffer, and the ZText statement will display the received message. Suppose the following (decimal) bytes were received by VTScada on serial port 2:
1, 2, 3, 16, 16, 4, 5, 16, 3, 6, 9, 8
The response would contain the following:
1, 2, 3, 16, 4, 5, 3
and the following bytes would be left in the receive buffer:
6, 9, 8
