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 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 bits/digits/bytes to skip after writing each non-floating point element. In binary modes, the following values are supported: 8, 16, 32, and 64. 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. 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 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.