BuffToArray

(Engine-Level Function)

Description:	Reads an array from a formatted buffer containing numerical data and returns the number of elements read.
Returns:	Numeric
Usage:	Script or steady state.
Function Groups:	Array, String and Buffer
Related to:	ArrayToBuff \| BuffToParm \| BuffToPointer
Format:	BuffToArray(ArrayElem, N, Buffer, Offset, Option, Size, Skip)
Parameters:

ArrayElem

Required. Any array element giving the starting point in the destination array where the data is to be stored. The subscript for the array may be any numeric expression.

Required. Any numeric expression giving the number of array elements to read, starting at the element given by the first parameter. If N extends past the upper bound of the array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.

Buffer

Required. Any text or buffer expression to read. The data stored in the buffer must be numeric.

Offset

Required. Any numeric expression giving the starting buffer position for the read in characters (bytes), starting at 0.

Option

Required. Any numeric expression that specifies the format of the buffer read. This can be one of:

Option	Buffer format
0	Unsigned binary (low byte first)
1	Signed binary (low byte first)
2	BCD (binary coded decimal) (low byte first)
3	ASCII octal (high byte first)
4	ASCII decimal (high byte first)
5	ASCII hex (high byte first)
6	ASCII floating point (high byte first)
7	IEEE float/double (low byte first)
8	<obsolete>
9	Allen-Bradley® PLC/3 floating point
10	VAX single precision floating point

For Options 7 and 9, the data is read as appropriate binary format.

Size

Required. Any numeric expression giving the number of digits in each datum. It has a different meaning for each option, as indicated below.

Size	Size Meaning	Size Range
Binary types	Number of bits	1 - 32 bits
BCD	Number of 4-bit digits	1 - 8 digits
ASCII types	Number of bytes	1 - 32 bytes
Float types	Precision 1 for single precision, 2 for double precision.

Skip

Required. Any numeric expression giving the number of buffer units to skip after each element is read. Units are bits for Options 0 and 1, BCD digits for type 2, and characters or bytes for all others.

Comments:

BuffToArray may only be used with buffers containing numeric data.

Illegal characters embedded in the ASCII string stop further interpretation and are ignored. If an illegal character or the end of a buffer is encountered before a valid number, the remaining array elements are set to invalid.

The return value is the number of array elements read.

Example:

  BuffToArray(Data[0] { Starting array element },
              100 { No. of elements to read from buffer },
              Response { Text expression to read },
              0 { Starting offset in buffer, in chars },
              2 { Read BCD format },
              4 { 4 BCD characters is 2 bytes },
              0 { Don't skip anything });

This example reads 100 BCD format numbers into array elements 0 to 99. Each BCD number has 4 digits, which occupy 2 buffer bytes.