(Engine-Level Function)
| Description: | Reads values from a formatted buffer and returns the number of values not read. |
| Returns: | Numeric |
Usage:  |
Script Only. |
| Function Groups: | String and Buffer |
| Related to: | BuffOrder | BuffWrite | FRead | GetByte | SRead | SubStr |
| Format: |
BuffRead( Buffer, Offset, Format, V1, V2, V3, …) |
| Parameters: |
| Buffer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Required. Any text or buffer expression to read. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Offset | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Required. Any numeric expression giving the initial buffer position for the read, starting at 0. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Required. Any text expression giving the format of how the values (Vn parameters) are to be read.
%[*][width]type Where… % Is a mandatory character * The optional asterisk causes the read to occur as per the format specification, but suppresses any assignment to the Vn parameters. width Width is optional, specifying the maximum number of characters to read. type The specifications for type are listed in the following table: Note: Format strings are case insensitive. Additionally, specifying a character for a type that is not in this list results in all the characters following the % up to that point to be read exactly as they appear in the Format string and discarded.
nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.
c, ASCII character type: Unlike BuffWrite this type deals with characters in a string; each character being equal to one byte. Unlike the %s option, which reads only up to the first white-space character, the %c option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, a single character is read.
d, Signed decimal integer
e, Signed exponential
f, Signed floating point
g, e or f formats
i, Signed decimal integer type: This option normally reads a decimal integer; however, if a leading "0b" is encountered, the number will be interpreted as binary. If a leading "0" (zero only) is encountered, the number will be interpreted as octal. If a leading "0x" is encountered, the number will be interpreted as hexadecimal.
l, Line of characters: This option reads a line of characters terminated by a carriage return, a line feed, or both (in either order). The carriage return and line feed will be discarded, and the next character read will be the first character on the next line. The maximum number of characters read is 2GiB (2^30 bytes) or less if the width option is used.
n, Buffer offset: This option does not read a value, but returns the present offset in Buffer and can be useful in subsequent reads.
o, Unsigned Octal
s, Text string type: Text in the string is read up until a white-space character is encountered, or the specified width has been read, whichever is smaller. Square brackets enclosing a character, group of characters, or a caret and a group of characters used in the format string reads strings not delimited by spaces. This is a substitute for the %s format specification. The input is read up to the first character that does not appear inside the square brackets (note that this is case-sensitive). A dash may be used to specify a range of characters. For example, the following format specifier: % [A-Fa-f] will read a string up to the first which is not an A, B, C, D, E, or F both upper and lower case.
t, Counted string type A counted string is encoded as a sequence of UTF-8 characters without a null terminator and preceded by the length in bytes. The length in bytes is encoded as Int32, i.e. a "%2b". A value of −1 is used to indicate an invalid string, a value of 0 indicates a null ("") string. Do not apply width or precision modifiers to a "%t" counted string.
The caret symbol ^. If the first character inside the square brackets is a caret ( ^ ), the read progresses up to, but not including, the first character that appears inside the square brackets: %[^X-Z] This would read a string up to, but not including, the first X, Y or Z (upper-case only); if the string were terminated by an X, the next character read would be that X. Inside the square brackets, the backslash is used as an escape character - any character following a backslash (such as a caret, dash, or backslash) is taken as that character without special meaning. For example: %[^X-Z\^] would behave as described previously, except that the string would now be read up to but not including the first X, Y, Z, or ^. Because format specifications for the Vn parameters are indicated by a percentage sign, to read (and discard) an actual percentage sign as part of the text string, precede it with a backslash character (i.e. \%). Also, since the backslash character is used in this manner, as well as with special control characters such as line feed, carriage return and form feed, to read and discard a backslash, use two backslash characters (i.e. \\).
x, Hexadecimal characters: the %x option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, it will continue reading all bytes that can be recognized as hexadecimal characters. For example, given the string "…= 3D", %[^=]=%2x would read the hedadecimal value, 3D (decimal value, 61).
znnn, Escape characters: This specifies an escape character that will be thrown away when read, where nnn is a 3-digit number giving the ASCII character code of the escape character. This option is generally used as the sole format specifier that reads an entire string, spaces included, discarding every single occurrence of an escape character, or the first occurrence of every pair of escape characters. For example, if the string to be read looked like:
abXc dXXfghiXXXjXXXXkl mX Xn o
and the format specifier indicated that the ASCII code for 'X' (88) was to be the escape code:
%25z088
then the variable that this was read into would contain:
abc dXfghiXjXXkl m n o
Notice that for each occurrence of X, the character immediately following it is saved, even if it is itself an escape character. Then the next occurrence of the escape character is discarded, with the character following it being saved, regardless of what it is, and so on. The width field specifies the maximum number of bytes to place in the output string; if this number is smaller than the input string (less the offending escape characters), the string will be truncated. If no width is specified, a single character will be read.
Control characters: In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result. Please note that the letters must be lower case.
In addition to the predefined codes, an alternate form may be used:
\nnn: where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| V1, V2, … | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Required. Are the variables to be read in the form described by the Format parameter. Expressions are not allowed. Each of the Vn parameters is read in the order in which each appears in the parameter list. V1 has the format given by the first % sequence in the Format parameter, V2 has the second, and so on. |
Comments:
In early versions of VTScada (WEB), there was a numeric leading parameter, N. This should not be included in any new code.
The strings read by this function may be part of an I/O driver (such as a message packet), or entered from the keyboard (such as a command-line-interpreter interface). The return value is optional and is the number of Vn parameters not read, which can be used as an error flag.
Example:
If ! Valid(WellLevel);
[
BuffRead(FileData { Source buffer to read from },
0 { Starting offset, in characters },
"%f%d/%d/%d" { Format string },
WellLevel { First variable - read by %f },
SampleDay { Second variable - read by %d },
SampleMonth { Third variable - read by %d },
SampleYear { Fourth variable - read by %d });
]
The example shown above reads a floating point variable and 3 integers. The slash characters "/" must be present in the FileData buffer. If the slash characters "/" are missing, reading will be terminated when one is missed. All variables after that point will be set invalid. If FileData contained:
"12.3 28/09/92"
... WellLevel would be set to 12.3, SampleDay to 28, SampleMonth to 9, and SampleYear to 92. If it is desired to skip a single character, use the "%*c" option (read character and discard).
