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.

N

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 The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64 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. In binary modes, the following values are supported: 8, 16, 32, and 64. 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.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

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.