BuffWrite

(Engine-Level Function)

Description:	Writes formatted values to a buffer and returns the number of values not written.
Returns:	Numeric
Usage:	Script Only.
Function Groups:	String and Buffer
Related to:	BuffRead \| FWrite \| SetByte \| SWrite \| ArrayToBuff \| MakeBuff
Format:	BuffWrite( [N,] Buffer, Offset, Format, V1, V2, V3, …)
Parameters:

Buffer

Required. Any text or buffer expression to be written. The buffer must already exist.
Buffers are created by certain functions, such as ArrayToBuff or MakeBuff, or by assignment of a text string such as "Hello." BuffWrite writes to an existing buffer, which is faster than creating a new buffer.
Writing to an empty buffer has no effect.

Offset

Required. Any numeric expression giving the starting buffer position in characters or bytes for the write, starting at 0.

Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be written. This format is similar, but not identical, to the C language format string for the printf function, whereby each of the Vn parameters in the statement is assigned to a % format specification in the order in which each appears in the list.

Note that like a standard text string, these format specifiers must also be enclosed by double quotes.

If a format specification appears for which there are no remaining V parameters, the format specification characters themselves are output to the stream exactly as they appear in the Format.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

[-][+]%[SPACE][#][width][.precision]type

where

- (minus sign) (optional) causes the data to be left justified within the field (for binary types b and ASCII character types c, this option is ignored);

+ (plus sign) (optional) causes positive numbers to be prefaced with a + sign (negative numbers are unaffected). This allows easy alignment of positive and negative numbers in a printed column of numbers. For binary types b and non-numerical types, this option is ignored;

% (percent sign) is mandatory;

space represents the single space character, and is similar to the [ + ] option but places a single space rather than a plus sign in front of positive numbers (negative numbers are still unaffected). This allows alignment of a column of numbers without having to show all signs. For binary types b and non-numerical types, this option is ignored;

# (hash mark) When used with the o , x , or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

width is a number that specifies the minimum number of characters to output. Numbers that require more characters than specified by the width value are truncated on output. If the number of characters in the number or string is less than width, blanks will be added to the left or right, depending upon whether the output is left or right justified (i.e. whether the [ - ] option has been specified) until the width is reached. For binary types b and ASCII character types c, this option is ignored;

precision has a different meaning for each of the type options as follows:

Integer types d, l, u, o, x, and X precision specifies the minimum number of digits to output. If the number contains fewer digits, leading zeroes will be added to the left of the number. If precision is 0, omitted, or if the decimal point appears without a number following it, the precision defaults to 1. The number is not truncated.
Floating point types e and E precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision in this case is 6. If the precision is 0 or if the decimal point appears without a number following it, no decimal point appears in the output.
Floating point type f precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision is 0. If the precision is explicitly 0, no decimal point is output. If a decimal point is output, at least one digit will be placed before the decimal point.
Floating point types g and G precision specifies the maximum number of significant digits to be output. If no precision is specified, all significant digits are written.
String type s precision specifies the maximum number of characters of the string to be output. If the string contains more characters than specified by the precision, the string is truncated and only the first characters are written. If the precision is not specified, all of the string characters are output.
Byte type c The precision option is ignored.
Binary type b The precision option is ignored.

type is mandatory. The type specification must be one of those listed below.

Note: The case of the letter is important. Specifying a character for the type that is not in this list will result in all the characters following the % up to that point to be output exactly as they appear in the Format string.

Type	Meaning
nb	Binary format, where n is a number indicating the type of value (see below).
c	Single character (byte values from 0 to 255)
d	Signed decimal integer
e	Signed exponential; exponent key is "e".
E	Signed exponential; exponent key is "E".
f	Signed floating point.
g	e or f format, whichever is shorter.
G	E or f format, whichever is shorter.
h	Handle to a window.
i	Signed decimal integer.
o	Unsigned octal integer.
p	Pointer to a buffer.
s	Text string.
t	Writes a utf-8 string as used by OPC UA binary TCP: a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string
u	Unsigned decimal integer.
x	Unsigned hex integer using "abcdef". (See following note.)
X	Unsigned hex integer using "ABCDEF".

When writing negative values using either x or X format codes, the output will use a minimum of 32 bits because that is the smallest possible size to display the full information. Defining a format string such as "%4X" will not reduce this to 16 bit output for negative values.

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.

n	Value Type
0	Byte, unsigned
1	Signed short integer (2 bytes)
2	Signed long integer (4 bytes)
3	IEEE single precision float (4 bytes)
4	<obsolete>
5	IEEE double precision float (8 bytes)
6	<obsolete>
7	Unsigned short integer (2 bytes)
8	Unsigned long integer (4 bytes)
9	Writes a time in Microsoft FILETIME format, which contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).

Note: Other options such as width and precision do not apply to the b type.

c, Byte type: This type is not representative of a single character in a string, but rather, represents single bytes. Input values (the Vn parameter to which this format specification applies) must be integers in the range of 0 to 255. Strings are not acceptable input values. Note that the %c format specifier behaves differently when used in an output statement such as BuffWrite than when used in an input statement, such as BuffRead. Some UTF-8 characters can require multiple bytes. Values from 0-127 are consistent between the traditional ASCII encoding and the UTF-8 encoding.

d, Signed decimal integer:

e, Signed exponential: Exponent key is "e"

E, Signed exponential: Exponent key is "E"

f, Signed floating point

g, e or f formats: Whichever is shorter

G, E or F formats: Whichever is shorter

h, Window handle type: This type is used for building structures to be handed to DLLs and should be used by advanced users only.

p, Buffer pointer type: This type is also used for building structures to be handed to DLLs and should be used by advanced users only.

s, Text string type:

t, Writes a utf-8 string as used by OPC UA binary TCP:
a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string

u, Unsigned decimal integer,

x, Unsigned hex integer using "abcdef"

X, Unsigned hex integer using "ABCDEF"

SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Plain text Text in the Format parameter is written exactly as it appears, with three exceptions:

Percentage sign (%) Because format specifications for the Vn parameters are indicated by a percentage sign, to include an actual percentage sign as part of the Format parameter, precede it with a backslash character (i.e. \%).
Backslash character (\) Because this is used to indicate special control characters such as line feed, carriage return, and form feed, to write a backslash as part of the Format parameter, use two backslash characters (i.e. \\).
Quotation marks (") The entire test string is delimited by quotation marks, so to include a set of quotation marks as part of the Format parameter, use a set of quotations marks (i.e. "").

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 (notice that the letters must be lower case):

Code	Meaning
\b	Backspace
\f	Form feed
\n	Line feed
\r	Carriage return
\t	Horizontal tab
\v	Vertical tab

\nnn In addition to the above predefined codes, \nnn may be used, 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.

znnn Escape character where nnn is the 3-digit ASCII code
For example: SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Offset is any numeric expression giving the starting buffer position in bytes for the write, starting at 0.

Comments:

In early versions of VTS (WEB), there was a numeric leading parameter, N. This should not be included in any new code.

If one of the values to be written is outside of the range of the type indicated by the format specifier, a 0 is written. If the value to be written is invalid, nothing is written for most format specifiers, except for %nb, which will write a 0 in the place of the invalid. Invalidity of the output values does not preclude execution of this function.

This function returns the number of Vn parameters not written to the buffer. A 0 return value indicates success. Variables that contain invalid values that were not written due to their invalidity do not increment this count. An invalid return value indicates an error with one of the parameters.

This function can be used to format strings for display, or for message packets as part of the driver toolkit.

As of version 12.0, VTScada expects all strings to be encoded using UTF-8.

Do not attempt to access a buffer while it is being written. During that time, its contents are undefined.

Example:

  If ! Valid(Buff);
  [
    buff = MakeBuff(100, 0) { Create the buffer };
    BuffWrite(Buff { Buffer }, 
              0 { Starting offset }, 
              "A=%3.2d\r\nB=%6.2f\r\n%8.3s\r\n%c\r\n\033"  { Format string }, 
              2, 2/3, "finished", 33 { Values to be written }); 
]

This would set Buff as follows :

A= 02
B= 0.67
fin 
!
!