ArrayToBuff

(Engine-Level Function)

Description:	Returns a buffer containing the numeric data from an array.
Returns:	Numeric Buffer
Usage:	Script or steady state.
Related to:	ArrayStart | ArraySize | BuffRead | BuffToArray | BuffToParm | BuffToPointer | BuffWrite | GetByte | MakeBuff | ParmToBuff | PointerToBuff | SetByte| Array Functions
Function Groups:	Array,  String and Buffer.
Format:	ArrayToBuff(ArrayElem, N, Option, Size, Skip [,BadData])
Parameters:

ArrayElem

Required. Any array element giving the starting point for the array conversion. The subscript for the array may be any numeric expression. If processing a multidimensional array, the usual rules apply to decide which dimension should be used. Note: The array must contain numeric data only.

N

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

Option

Required. Any numeric expression that specifies the format of the buffer write, using the following table of formats: Note: For Options 7 and 9, the data is written as appropriate binary format. (See: Bitwise Parameters & Operations) 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)See comment: *1* 4 ASCII decimal (high byte first)See comment: *2* 5 ASCII hex (high byte first)See comment: *1* 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

Size

Required. Any numeric expression giving the size that each element should consume in the output buffer, (not the size of the input). It has a different meaning for each option as follows: 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 bits/digits/bytes to skip after writing each non-floating point element. For floating point types, this parameter must be set to 0.

BadData

Optional. A parameter that designates how invalid data is to be handled, according to the following table. Defaults to 0 if missing or invalid. BadData Invalid Data Type 0 Output to buffer as valid 0s 1 Causes buffer to be invalid 2 Output to buffer as valid 0s

Comments:

This function may only be used with arrays containing numeric data. It is useful for writing I/O drivers and saving arrays of data in RAM efficiently.

Example 1:

In the following example, assume that array x is a one-dimensional array containing the values 4.5, invalid, and 200:

  If ! Valid(buff);
  [
    buff = ArrayToBuff(x[0] { Starting element },
                      3 { Number of elements to process  },
                      7  { Type - IEEE floating point },
                      1  { Single precision },
                      0  { Skip is ignored },
                      2  { Use 0 for each invalid value });
    BuffRead(buff   { Buffer to read },
             0 { Starting offset },
             "%3b%3b%3b" { Type IEEE floating point binary },
             a1, a2, a3 { Variables to hold the values });
  ]

This code produces a formatted buffer called buff that holds 3 float values (written in binary format), each corresponding to an element in the array. The second value in the array is invalid - in the buffer, it will be a valid 0. The values of a1, a2 and a3 then will be 4.5, 0 and 200 respectively.

Note 1: For ASCII octal and hex values, negative numbers are output as 32-bit, 2's complement values and hence need a size sufficient to accommodate that. (For example, 8 characters for hex.)

Note 2: For ASCII decimal values, undefined results will be returned when used with negative values

Example 2:

    ArrayOp1(Data[0], N, 0xFFFF, 15);
    Buff = ArrayToBuff(Data[0], N, 5, 4, 0);

If Data originally contains 16 bit signed integers, it will output them as 4-character ASCII hex representation of those signed values. Note that the contents of Data are modified by the first line such that they have been converted to 16 bit unsigned integers with the same hex representation, so if the original Data array is needed, this operation should be done with a copy.

Note: If Data contains any values outside the range of a 16 bit signed integer, it will write out the least significant 16 bits of those numbers. Therefore, this approach does not detect values out of the 16 bit signed integer range.